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

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, 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):

# 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 creates a new record seeded with the full IOOK_CAPITAL amount:

# 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 (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.
• The _ensure_agent_cash function in 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}