# Paper trading (spot / futures simulator)

This document is the **single source of truth** for **paper trading** in Tradesteady Algo: simulated fills for crypto and Indian cash/F&O routes. It does **not** describe **Options Analytics** / **crypto options paper** (Short Straddle, `crypto_options_paper_trades`) — that is a separate product.

## What it is

- **Activation:** User enables paper mode via **Activate** on the dashboard (`POST /api/paper-trading/activate`). Sets `users.paper_trading_activated_at`.
- **Routes:** Create a route with **Paper trading (simulation)** checked (`routes.is_paper = true`). No exchange API keys are required for simulation; fills use the **price from the TradingView alert** when possible, otherwise an LTP fetch.
- **Supported destination types:** `binance_spot`, `binance_futures`, `bybit_spot`, `bybit_futures`, `delta_exchange`, `delta_exchange_india`, `fyers`, `dhan` (see `PAPER_DESTINATION_TYPES` in `app/services/paper_trading_service.py`).
- **Not included:** **MetaTrader (MT5)** is **live execution only**. There is no paper/simulation route type for MT5 in this product.

## Webhooks and entitlements

- Every account gets **at least one webhook** without a subscription. Activating paper trading does **not** add an extra webhook slot beyond that — it only unlocks creating **paper** routes.
- Paper routes do not count toward the per-webhook **live** route cap (3 live routes per webhook); paper routes are unlimited per webhook.
- Diagnostics: `GET /api/webhooks/can-create-info` reasons are **free first webhook**, **trial**, or **subscription limits** — not “paper trading” as a separate webhook grant.

## Virtual wallet and margin

- Virtual balance in `paper_wallets` (default starting capital in USDT).
- New positions and add-to-position calls **`lock_margin`**. By default (**strict**), if margin cannot be locked, the fill is **rejected** (no new row / no add).
- Set **`PAPER_TRADING_RELAXED_MARGIN=true`** (env) only if you need legacy behavior that records trades even when margin is insufficient (not recommended).

## Binance / Bybit paper and TP/SL

- Background TP/SL evaluation **excludes** Binance spot/futures paper routes to reduce exchange REST usage. Users should use **Refresh prices** on the Paper Trades tab (rate-limited, typically **3 minutes** between refreshes) to update marks and evaluate TP/SL for those venues.
- Include **`P={{close}}`** (or equivalent) in TradingView alert templates for reliable entry prices.

## Data retention

- Closed rows in `paper_trades` are purged by the **centralized data retention job** (`run_data_retention_cleanup`), default **30 days** for closed trades (`data_retention_policies`, migration `087_data_retention_policy.sql`). Open positions are never deleted by retention.
- The legacy midnight **72-hour** delete path has been removed; retention is aligned with this policy.

## Related code

| Area | Location |
|------|-----------|
| API | `app/routes/paper_trading.py` |
| Core logic | `app/services/paper_trading_service.py` |
| Wallet | `app/services/paper_wallet_service.py` |
| Alert → paper | `app/services/alert_service.py` → `record_paper_trade` |
| Route create rules | `app/services/route_service.py` |

## Options Paper (different product)

- **Options Analytics** / **crypto options paper** uses `crypto_options_paper_*` tables and the Options Analytics app. Do not confuse with this paper trading simulator.