Paper trading

Paper trading is how a strategy earns its first taste of real-time conditions without risking a cent. Once a strategy survives the gauntlet, it enters the paper stage of the pipeline — the public site calls this stage a "candidate" — where it runs forward against the live price feed, fills trades against local prices, and records everything to your local database. No order ever reaches an exchange.

This page is for any beta user who has a strategy sitting at the paper stage and wants to watch it trade, read its session results, and understand why those results are not the same thing as live performance.

Forven is a research tool. Paper results describe how a strategy behaved in simulation; they do not predict live results and are not financial advice. Treat paper PnL as evidence of process, not a promise of profit.

What paper trading actually does

In paper mode the execution mode is paper, which is the default and — in beta builds — the only mode available. When a strategy in the paper stage produces a signal, Forven:

1. Checks the same risk gates a live trade would face (drawdown, daily loss, per-trade risk, position limit).
2. Records a trade in your local SQLite store, tagged execution_type='paper' (or 'paper_challenger' for a challenger run).
3. Fills the trade immediately at the local mid-price from the current candle — not at an exchange quote.
4. Accumulates the position inside an isolated paper session.

This behaviour is governed by paper_stage_local_execution_only, which defaults to true. Local fills are what let paper trading prove zero look-ahead: the strategy only ever sees prices it could have seen in real time, and it can't peek at exchange order-book depth it would never have had during research.

Paper vs. backtest vs. live

These three are easy to confuse. They are different things:

A backtest replays the past. Paper trading runs the strategy forward on live data but still fills locally. Only live trading sends real orders to the exchange.

Paper sessions

Every paper run lives in its own session — an isolated sandbox with independent starting capital, its own positions, and its own PnL. Sessions do not pool capital or share risk budget with each other or with the live wallet.

A few properties worth internalising:

• Sessions are per-session, not per-strategy. If you run the same strategy twice, you get two separate sessions, each with its own starting capital and position set. Rolling both into one "strategy summary" takes care.
• Per-session position limits come from paper_max_concurrent_positions (unlimited by default), distinct from the live max_concurrent_positions cap.
• Starting capital defaults to initial_capital (10000), used only for sizing and PnL math — there is no real balance behind it.

Running a paper session

The real UI page is /paper-trades. It runs and replays paper sessions, overlays paper trades and signal markers on a live chart, and shows a session summary plus execution history. The day-to-day controls for starting and stopping the paper service live on the operations side.

Steps

1. Promote a strategy into the paper stage from the strategy lab — a strategy must clear the gauntlet's paper-promotion gate first; the stage is not skippable.
2. Open /paper-trades to watch sessions, or start the paper trading service so the scanner begins emitting signals for paper-stage strategies.
3. Let the scanner run. As signals fire, paper trades open and close on the chart, filling at local prices.
4. Select a session to inspect its summary card, signal overlays, and execution history; use the replay controls to step through what happened.
5. Read the session PnL and close-reason breakdown. Compare across sessions, not against any exchange statement — there is nothing to reconcile against.

Starting and stopping the paper service uses these local endpoints (base URL http://127.0.0.1:8003):

# Start the paper trading service
curl.exe -X POST http://127.0.0.1:8003/api/paper/service/start

# Stop it
curl.exe -X POST http://127.0.0.1:8003/api/paper/service/stop

# List active sessions with cumulative PnL
curl.exe http://127.0.0.1:8003/api/paper/sessions

# Inspect one session's trades
curl.exe "http://127.0.0.1:8003/api/paper/sessions/$SessionId/trades"

# Aggregate PnL rollup + close-reason breakdown
curl.exe http://127.0.0.1:8003/api/paper/summary

What you'll see

On /paper-trades: a session summary header with cumulative PnL, a main chart workspace with paper-trade overlays and signal markers, a pending-signal view while a signal is being evaluated, and an execution-history list. The home operations dashboard also shows a paper trading summary panel, and /api/risk reports open_positions_paper (paper position count) separately from the live count.

How a paper trade opens and closes

When the scanner emits a signal for a paper-stage strategy, the payload carries the asset, direction, entry price, size, stop-loss, take-profit, and leverage. From there:

• The scanner calls can_open() to check drawdown, daily-loss, per-trade-risk, and position-limit gates. Oversized orders are rejected fails-closed with risk_limit_exceeded.
• If allowed, a local trade record is created (status='OPEN', signal_entry_price set) and filled at the current candle's mid-price. No order is sent to the exchange.
• On exit — a take-profit, a stop-loss, or a strategy exit rule — close_trade_record() runs with the signal_exit_price and a close_reason such as tp_hit or sl_hit.
• PnL is computed as (exit − entry) × size × sign × leverage, finalised as pnl_usd and pnl_pct, and rolled into the session's realized PnL.

Because the fill price is the signal price, paper trades carry no slippage and no exchange order ID.

Why paper trades don't reconcile with the exchange

This is the single most important caveat, and it is deliberate.

Paper trades fill against local OHLCV mid-prices, so they have no exchange order ID and cannot be reconciled by phantom recovery — the routine that matches live exchange positions against database records. A paper position exists only in your local store.

Practical consequences:

• Do not treat paper PnL as a proxy for live PnL. Real fills include slippage, partial fills, funding, and rejections that local mid-price fills never model. A strategy can look clean in paper and still bleed on real spreads.
• Paper sessions stay isolated. Live execution pools every active strategy into one shared wallet with global position limits; paper sessions never join that pool.
• The beta paper-lock is real. Even if a config file says execution_mode: live, beta builds return paper at the read site, so a stale live value can never take effect. See execution modes for the full lock behaviour.

The risk gates still apply

Paper trading is not a free-for-all — it runs the same risk machinery as live, just without real capital. The risk page and its gates govern paper trades too:

• max_drawdown_pct (default 10) arms the kill-switch.
• max_daily_loss_pct (default 5) can set the daily-loss halt.
• max_risk_per_trade_pct (default 2) caps per-trade exposure at submit time.

Running these gates in paper is the point: it lets you watch how a strategy behaves against your real risk budget before any of it is at stake. Risk limits are configured in Settings under the Trading section and persisted to the local KV store.

Caveats (beta)

• Paper fills assume the candle mid-price with zero slippage; they are optimistic relative to live execution by design. Read paper PnL as a behaviour test, not a forecast.
• A strategy run more than once produces multiple independent sessions. Aggregate them deliberately, not accidentally.
• The default and the only enforced mode during beta is paper. Switching to live is documented under execution modes and is gated behind the strict paper→live promotion gate plus FORVEN_ALLOW_MAINNET.

Forven is a research tool. Surviving paper trading is evidence of disciplined process, not a prediction of live returns, and nothing here is financial advice.

Related

• Execution modes: paper vs live — how the two modes differ and how to switch safely
• The pipeline — where the paper stage sits in the strategy lifecycle
• Live trading — what changes when real orders reach the exchange
• Risk & safety — the gates, kill-switch, and limits that apply in paper and live alike