Paper trading

Paper trading runs a strategy (or a multi-strategy book) against simulated execution — no real money — so you can watch a validated edge behave in real time before risking capital. The same registered strategy code runs here as in a backtest and live. Two venues:

Crypto sandbox (zero-setup default) — a fully local simulator (Nautilus’s sandbox execution client) that fills your orders against a live Kraken market-data feed (US-available, no key). Nothing leaves the machine; no money at risk.
IB paper — Interactive Brokers’ native paper account (a DU… id), through the Dockerized IB Gateway.

Starting a session from the app (no terminal)

The Paper tab’s guided start card walks you through it:

Choose a venue — Crypto sandbox (nothing to configure) or IB paper (shows an IB account preview).
Get IB ready (IB only) — a readiness strip shows the gateway state; a Start gateway / Restart (re-login) button runs docker compose for you (no terminal). The first start downloads the image (~2 min) and IB may ask for a 2FA tap on your phone.
Configure — a Single strategy / Book toggle. Single: strategy, symbol (searchable picker), timeframe, parameters. Book: Add strategy for as many sleeves (strategy + symbol) as you want — they run as one node on one account. Plus starting cash (sandbox), an optional auto-stop at HH:MM ET, and a label.
Start. The API spawns and supervises the runner; the card flips to the live status cards, controls, and event feed. Stop session flattens and stops gracefully. If a start fails, the log tail is shown in the UI.

A ready strategy’s Start paper button on the research ladder deep-links here, pre-filled.

IB Gateway — one-time setup

IB paper/live trade through the Dockerized gateway. In backend/.env set the container env (see configuration):

TWS_USERID / TWS_PASSWORD — your IBKR login (enable 2FA).
ATS_IB_ACCOUNT_ID — your paper account id (starts with DU).

Start the gateway from the Paper tab’s button, the header chip, or a shell:

docker compose -f infra/docker-compose.yml --profile ib up -d --wait

No paper account yet? “Paper Account Notice: the specified user does not have a Paper Trading user” means you must create one in IB Client Portal (Settings → Account Settings → Paper Trading Account), then put the DU… id in ATS_IB_ACCOUNT_ID and restart the gateway.

The command-line runners (power-user / automation)

The CLI runners are the automation path (cron, headless, scripting):

cd backend
# IB paper — foreground; Ctrl-C flattens and stops
uv run python -m ats.paper --strategy ibs_reversion --instrument QQQ.NASDAQ \
    --bar-spec 1-DAY-LAST --params '{"buy_threshold": 0.15, "exit_threshold": 0.7}'

# Crypto sandbox — crypto trades 24/7 (no market-hours gating)
uv run python -m ats.crypto_paper --strategy tsmom --instrument BTCUSD \
    --bar-spec 1-DAY-LAST --params '{"trade_size": 1}' --starting-cash 100000

For unattended sessions use scripts/run-paper.sh (relaunches after crashes, respects intentional stops). Add --until 16:05 for a clean market-close auto-stop, and cron it — see scheduling.

IB symbology vs catalog symbology: trading uses IB ids (QQQ.NASDAQ), distinct from catalog ids (QQQ.XNAS) on purpose, so a session states exactly which IB contract it trades. Run one paper session at a time — IB or crypto (they share the paper session namespace).

Running a book (multiple strategies, one account)

Pass --sleeves-json to run several strategies in one node — one feed, one heartbeat, one kill switch, one RiskEngine, all on the same account — and --label to name it:

uv run python -m ats.paper --label "QQQ book" \
    --sleeves-json '[{"strategy_key":"ibs_reversion","instrument":"QQQ.NASDAQ","params":{"buy_threshold":0.1}},
                     {"strategy_key":"turn_of_month","instrument":"HYG.NASDAQ"}]'

Each event/fill is attributed to its sleeve. A live/paper book can only contain order-placing registry strategies — the vectorized research engines (cross-sectional, pairs) have no live order path. See multi-instrument engines.

Session controls

While a session runs you have, from the UI or queued through Redis (each acknowledged in the feed and audited):

Pause — RiskEngine HALTED: new orders denied, positions held, indicators warm.
Resume — back to ACTIVE.
Flatten — REDUCING: cancel open orders, close all positions (closing orders only).
Kill — flatten, then shut the session process down.

What you see

Live telemetry — capital snapshot, per-position P&L, and a run-scoped event feed (orders, fills, connectivity) in Eastern time, streamed over WebSocket and persisted so it survives a page refresh.
Account metric cards — equity, available capital, unrealized/realized P&L, net exposure.
Account at rest — before a session, a read-only IB account probe (reqAccountSummary / reqPositions, never an order) shows equity, cash, buying power, exposure, and holdings, and explains why there’s no data (gateway down / logged out) rather than showing nothing.
Gateway health chip — the header shows separate Paper/Live state (OK / re-login needed / off), with copy-paste restart commands; a worker monitor probes each gateway ~every 15 min.
Performance — the session page aggregates the durable fill history (trades, win rate, realized P&L, fees) per strategy/instrument.

Sessions history

Every run is recorded as a session (opened/closed from the telemetry heartbeat). The Sessions tab lists them newest-first (label, kind, strategy/instrument or book, started/ended in ET, status, fills, round trips, realized P&L, fees); open a row for the per-sleeve breakdown and round-trips, and delete one or bulk-clear a kind. (Deleting a session also removes its fills from the Research “Paper” rung — the confirm says so.)

Safety even on paper

Paper runs behind the same machinery as live: the pre-trade risk engine (per-order notional

submit-rate caps), startup reconciliation, and gateway resilience — so what you exercise on paper is what protects you live.

Live trading — promoting paper to real money (gated). · Alerts · Scheduling.