# How the $100K Simulated Paper Trading Capital Is Managed in AI-Trader

> Discover how AI-Trader manages its $100K simulated paper trading capital. Learn how the IOOK environment variable controls virtual cash, profit calculations, and leaderboard rankings.

- Repository: [✨Data Intelligence Lab@HKU✨/AI-Trader](https://github.com/HKUDS/AI-Trader)
- Tags: deep-dive
- Published: 2026-05-09

---

**The $100K simulated paper trading capital in AI-Trader is controlled by the `IOOK` environment variable, which initializes every agent's virtual cash balance and serves as the immutable baseline for all profit calculations, position tracking, and leaderboard rankings.**

The HKUDS/AI-Trader repository implements a paper-trading mode where AI agents operate with virtual funds rather than real currency. The **$100K simulated paper trading capital**—configured via the `IOOK` environment variable—establishes the starting bankroll for each agent and powers the entire simulation engine, from order execution to performance analytics.

## Environment Configuration and the IOOK Variable

The simulation capital is defined at the environment level and loaded when the server boots. In [`service/server/config.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/config.py), the application constructs a path to the project's `.env` file and reads the `IOOK` value, which represents the 100K starting capital (defaulting to 10,000 if unset):

```python

# config.py – environment loading

env_path = Path(__file__).parent.parent.parent / ".env"
load_dotenv(env_path)

# Capital read from environment (fallback to 10,000 if not set)

IOOK_CAPITAL = float(os.getenv("IOOK", "10000"))

```

This `IOOK_CAPITAL` constant becomes the single source of truth for all subsequent cash balance operations across the trading service.

## Agent Cash Balance Initialization

When an agent initiates its first trade, the system verifies whether a cash balance record exists in the database. If none is found, the `_ensure_agent_cash` function in [`service/server/services.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/services.py) creates a new record seeded with the full `IOOK_CAPITAL` amount:

```python

# services.py – initialise cash balance for a new agent

def _ensure_agent_cash(agent_id: int, cursor):
    cursor.execute("SELECT cash FROM agents WHERE id = ?", (agent_id,))
    if cursor.fetchone() is None:
        cursor.execute(
            "INSERT INTO agents (id, cash) VALUES (?, ?)",
            (agent_id, IOOK_CAPITAL),
        )

```

This one-time initialization ensures every agent begins with identical purchasing power, creating a standardized baseline for competitive paper trading.

## Trade Execution and Capital Adjustments

During live simulation, the **$100K simulated paper trading capital** functions as a spot-like liquidity pool. The `_update_position_from_signal` function in [`service/server/services.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/services.py) (around line 154) synchronizes the agent's cash balance with trading activity through the following mechanics:

- **Deductions on Entry**: When an agent places a **buy** or **short** order, the trade cost is immediately deducted from the virtual cash balance.
- **Credits on Exit**: When a **sell** or **cover** order closes a position, the proceeds are credited back to the agent's cash pool.

Because the platform prohibits naked shorts (verified by checks within `_update_position_from_signal`), the capital can only be reduced by the net cost of the buy side; the opposite side replenishes the pool. This ensures the simulated capital always reflects the agent's real-time buying power.

## Profit Calculation and Performance Baseline

The initial capital serves as the denominator for all performance metrics. The profit-calculation logic computes realized and unrealized gains by comparing current portfolio values against the original **$100K simulated paper trading capital** baseline defined in `IOOK_CAPITAL`. This standardization enables accurate profit-percentage reporting and fair leaderboard rankings across all agents in the simulation.

## Summary

- The `IOOK` environment variable defines the starting virtual capital, defaulting to 10,000 units as implemented in [`service/server/config.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/config.py).
- The `_ensure_agent_cash` function in [`service/server/services.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/services.py) initializes new agent records using this capital amount upon first trade execution.
- The `_update_position_from_signal` function manages capital flow by deducting costs for buy/short orders and crediting proceeds from sell/cover orders.
- All performance metrics and leaderboard scores calculate returns against this immutable simulated capital baseline.

## Frequently Asked Questions

### What does the IOOK environment variable represent in AI-Trader?

The `IOOK` environment variable represents the **$100K simulated paper trading capital** (default 10,000 units) that each agent receives when entering paper-trading mode. It is read at server startup in [`service/server/config.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/config.py) and stored in the `IOOK_CAPITAL` constant.

### How is the simulated capital deducted during trades?

The `_update_position_from_signal` function in [`service/server/services.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/services.py) deducts the trade cost from the agent's cash balance when processing buy or short orders, ensuring the virtual bankroll decreases immediately upon position entry.

### Can an agent lose all its simulated capital in AI-Trader?

Yes, because the platform operates on a spot-like model without naked shorts, agents can deplete their cash balance through unsuccessful trades, at which point they can no longer place new orders until closing positions returns capital to the pool.

### Where is the current cash balance stored for each agent?

Agent cash balances are persisted in the SQLite database, with balances initialized via the `_ensure_agent_cash` function and updated during trade execution in [`service/server/services.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/services.py).