Paper Mode Guide

Paper Mode Guide

Paper mode lets you run a fully functional grid bot against real-time market data without placing actual orders or risking capital. It is the essential bridge between backtesting historical data and deploying with real money. Understanding what the simulation covers and what it does not helps you interpret paper mode results correctly.

How Paper Mode Works Internally

When dry_run is set to true in your bot configuration, the entire simulation engine activates. The bot runs the same code path as a live bot with one critical difference: all order operations are routed through the simulation module instead of the exchange API.

The simulation engine includes:

• SimAccount: Tracks a virtual account balance, margin, and positions. It starts with the capital you configure and updates as simulated trades execute.
• FillModel: Determines when simulated orders would fill based on real-time price data. A limit buy order fills when the real market price drops to or below the order price.
• PriceFeedSim: Connects to the same real-time WebSocket price feed as the live bot. Paper mode uses actual market prices, not synthetic data.
• SendOrderSim: Intercepts order calls and routes them to the simulation engine instead of the exchange API.

The simulation runs the complete bot cycle: price checks, grid level evaluation, order placement decisions, fill detection, TP management, and reconciliation. Every decision the bot makes is identical to live mode; only the execution layer differs.

What Paper Mode Simulates Accurately

Price-based decisions: Since paper mode uses real-time market prices, all decisions about which grid levels to buy, when to place TP orders, and when grid break triggers are identical to live trading.

Bot logic and timing: The full cycle runs at the same interval. Reconciliation, bootstrap, grid break detection, and all safety guards operate exactly as they would in production.

Order placement logic: The bot decides to place orders using the same filters: grid locks, pending levels, in-flight tracking, and duplicate detection all function normally.

PnL calculation: Realized and unrealized PnL are calculated using the same formulas as live mode, based on simulated fill prices and current market prices.

What Paper Mode Cannot Simulate

Slippage: In real markets, especially during volatility spikes, your limit orders may fill at slightly different prices than specified. The simulation fills at the exact order price.

Partial fills: Real exchange orders can fill partially. The simulation always fills completely once the price condition is met.

Order queue position: On a real exchange, your limit order competes with other orders at the same price. You fill based on time priority. The simulation ignores order book depth and competition.

Funding rates: Perpetual futures charge funding every 8 hours based on the funding rate. Paper mode does not deduct these costs, which can be significant for positions held over multiple days.

Exchange latency: Real API calls take 50-500ms. The simulation responds instantly. This means the paper mode bot may appear to fill orders slightly faster than a live bot would.

Interpreting Paper Mode Results

Given the limitations above, paper mode results tend to be slightly optimistic compared to live performance. Expect your live results to be 10-20% lower than paper mode due to:

• Slippage reducing effective profit per trade
• Partial fills requiring additional cycles to complete
• Funding rate costs accumulating over time
• Occasional API timeouts causing missed opportunities

If your paper mode configuration is barely profitable (less than 1% over several days), it will likely be unprofitable live. Look for configurations that show clear, comfortable profitability in paper mode before deploying.

Running a Paper Mode Test

To activate paper mode, set dry_run: true in your bot configuration YAML:

execution:
  dry_run: true
  debug: false

Everything else in your configuration stays the same. The bot starts, connects to real price feeds, and begins its cycle. Monitor the dashboard and logs just as you would with a live bot.

Recommended test duration: Run paper mode for at least 3-5 days before going live. This gives you exposure to different market conditions including weekday volatility, weekend lulls, and at least one or two significant price moves.

Transitioning to Live Trading

When you are satisfied with paper mode performance, transitioning to live is straightforward:

1. Review your paper mode PnL and ensure it meets your expectations.
2. Verify your exchange account has sufficient balance for the configured grid.
3. Change dry_run: false in your configuration.
4. Start the bot. It will now place real orders on the exchange.

Important: Start live with the same configuration you tested. Do not change grid levels, order size, or leverage during the transition. You want your live behavior to match what you validated in paper mode.

After your first live session (24-48 hours), compare live results against your paper mode results. If live performance is significantly worse (more than 30% lower), investigate the cause before continuing. Common issues include higher-than-expected fees, slippage in thin markets, or funding rate costs that were not factored in.

Summary

• Paper mode runs the full bot logic against real-time prices but routes orders through a simulation engine instead of the exchange.
• Simulated results are slightly optimistic due to perfect fills, no slippage, and no funding costs; expect 10-20% lower performance when live.
• Run paper mode for 3-5 days minimum, then transition to live with identical configuration settings.

Next Step

Understand the complete bot architecture and internal cycle in How the Grid Bot Works.