Documentation

Paper Trading

Run your strategies on live market data with simulated execution. Same engine, same rules, zero capital at risk.

How It Works

Paper bots use the exact same strategy engine as live bots — the same condition engine, the same tick processing pipeline, the same lot sizing logic. The only difference is where orders go: live bots send orders to your MT5 broker via MetaApi, while paper bots send them to an in-memory PaperTradingService that simulates execution.

Paper bots subscribe to real price feeds from your MT5 broker — the same ticks your live bots receive. This means realistic spreads, real symbol availability, and accurate market behavior. No synthetic data.

Architecture

MetaApi price tick → EventEmitter('price.tick')

→ BotService.handlePriceTick()

→ Strategy evaluates conditions (same as live)

→ Strategy returns actions: OPEN, CLOSE_ALL, etc.

→ PaperTradingService executes simulated fill

→ Applies slippage (configurable)

→ Applies commission (per-lot)

→ Tracks position in memory

→ Trade recorded in TradeHistory (is_paper: true)

Simulated Execution

The PaperTradingService provides realistic execution simulation:

Slippage

Simulated slippage on open and close. Applied in the direction that hurts (buy fills higher, sell fills lower).

Commission

Entry-side and round-trip commission modeled per lot. Configurable per symbol.

SL/TP Stop Levels

Stop-loss and take-profit levels checked every tick. Positions close when breached, just like on a real broker.

Partial Closes

Supports closePartialPosition — close a fraction of a position's volume while keeping the rest open.

Trailing Stops

Trailing stop modification via modifyPosition(). ATR-based, percentage, and fixed distance types all work.

P&L per Tick

Floating P&L recalculated every tick. Direction-aware: uses bid for BUY positions, ask for SELL.

Virtual Capital Isolation

Each paper bot has its own assigned_capital, virtual_balance, and virtual_equity — completely isolated from other bots and from your real MT5 balance.

The same 3-layer margin guard applies to paper bots:

1. Hard floor — reject if virtual_equity ≤ 5% of assigned_capital

2. Margin check — requiredMargin = (volume × contractSize × price) / leverage

3. Exposure cap — total notional must not exceed assigned_capital × leverage

Leverage

Paper bots inherit leverage from the MT5 account they're attached to. This ensures margin calculations match what you'd experience on a live account with the same broker. The leverage is set automatically at bot creation — no manual configuration needed.

Paper vs Live — What's Identical

Feature

Paper

Live

Strategy engine

Real broker ticks

Virtual capital isolation

3-layer margin guard

Bot-level equity SL/TP

Trade history recording

Spread + slippage + commission

Real money at risk

Broker order execution

Position Recovery

Paper positions are held in memory. On engine restart, restorePosition() reconstructs in-memory positions from TradeHistory records in the database, so your paper bot resumes exactly where it left off.

Paper trades are recorded in TradeHistory with is_paper: true, making them easy to filter in queries and analysis.

Capital Allocation

Paper bots are excluded from capital allocation calculations. Their assigned_capital does not reduce the available balance on your MT5 account, so you can run paper bots with any amount without affecting your live bots' allocations.