Execution
Paper Trading
Last updated April 20, 2026
Paper mode runs your strategy against real live market data with simulated order fills. No exchange account is required, no money moves, and all the same execution logic runs — including condition tracking, structured logs, and position management. It is the default mode for all new projects.
Overview
When a project is set to Paper mode, the runner uses a PaperBroker in place of the LiveBroker. The broker abstraction is identical — strategy code callsHP.buy() and HP.sell() exactly the same way in both modes. The difference is entirely in how those calls are resolved into fills.
| Paper mode | Live mode | |
|---|---|---|
| Fill price | Current mark price (latest close of primary timeframe) | Actual Binance MARKET order fill |
| Fees | Zero | Binance exchange fees (0.1% or lower) |
| Slippage | Zero | Real market slippage applies |
| Wallet required | No | Yes — encrypted API key |
| Position stored in DB | Yes | Yes |
| Logs written | Yes — full TRADE_TRIGGER + TRADE_EXECUTED | Yes — full TRADE_TRIGGER + TRADE_EXECUTED |
| Analytics available | Yes | Yes |
Everything above the broker layer — condition tracking, position state, log structure, analytics — behaves identically in both modes. Paper mode is not a "demo" — it uses the same execution pipeline as live mode.
How Fills Work
In paper mode, when HP.buy(usd) is called:
- The PaperBroker reads the current mark price — the most recent close of the primary timeframe kline series.
- It computes the quantity as
usd ÷ mark_price. - It creates a position row with
entry_price = mark_price,qty = computed_qty,fee = 0. - It logs a TRADE_EXECUTED entry with
fill_price = mark_price,slippage = 0.
When HP.sell(pct) is called:
- The PaperBroker reads the current mark price.
- It computes the USD proceeds as
qty × (pct/100) × mark_price. - It updates or closes the position row with
close_price = mark_price. - PnL is recorded as
(close_price − entry_price) × qty_sold.
What Is Real in Paper Mode
Despite being simulated at the fill level, many things in paper mode are completely real:
Your strategy evaluates against live Binance kline data on every tick. Conditions trigger on real price movements.
The same compiled JS, sandbox, indicator library, and condition tracking system that runs in live mode.
Full TRADE_TRIGGER condition tables and TRADE_EXECUTED fill records are written for every paper trade.
The same position tracking, PnL calculation, and analytics available on live mode positions.
This makes paper mode genuinely useful for validating that strategy logic is working correctly in a real market environment before committing capital.
Switching to Live
To switch a project from Paper to Live mode:
- Go to Settings inside the project.
- Under Mode, select Live.
- Under Wallet, select the wallet containing your Binance API credentials. If you haven't added one yet, go to Settings → Wallets first.
- Save settings. The change takes effect on the next scheduled tick.
Switching from Live back to Paper mid-run is safe — the change takes effect on the next tick. Any open positions in live mode will remain open (they are not automatically closed when you switch modes), and subsequent exits will use paper fills.
Paper Trading Limitations
Paper mode will produce better numbers than live mode on the same strategy. This is an inherent property of simulated execution, not a bug. The main gaps:
| Factor | Paper mode | Live reality |
|---|---|---|
| Fill price | Fills at the exact mark price at the moment of signal | MARKET fills at best available ask/bid, which can differ — especially on low-liquidity pairs or at high volatility moments |
| Fees | Zero | Binance charges 0.1% per trade by default (lower with BNB fee discount). On a $1,000 round trip: ~$2 in fees |
| Liquidity | Any order size fills instantly at mark price | Large orders may move the market or partially fill |
| Latency | Fill is instantaneous (computed locally) | Network latency between the runner and Binance affects the exact fill time |
For most retail-scale strategies on liquid pairs (BTCUSDT, ETHUSDT), the difference between paper and live performance is small on a per-trade basis. For high-frequency strategies or large position sizes, it can be material.