6.5 Paper-Trade Runner

1. Bot Identity

2. Purpose

Paper-Trade Runner mirrors every live signal against a simulated paper account in real time (mode=paper). It subscribes to the live CLOB order book and signal streams, runs the strategy under test through the full execution path, and simulates fills against the current order book snapshot without submitting any real orders. It is the mandatory pre-promotion environment for all new strategies. Paper-Trade Runner emits OperationsReport records (and paper-tagged copies of any report kind it simulates) to polytraders.reports.operations, partitioned by bot_slug+epoch, retained for 1 year. A strategy may only be promoted to limited live when Paper-Trade Runner has accumulated at least min_paper_days of continuous paper trading with require_positive_risk_adj=true passing. Paper-Trade Runner never signs orders, never submits to the CLOB, and never touches on-chain state.

3. Why This Bot Matters

• Strategy promoted to live without paper trading

  Untested strategies can produce runaway losses on live capital. Paper trading is the mandatory governance gate. Skipping it removes the last safety check before real money is at risk.

• Paper-Trade Runner uses different signal path than live

  Paper P&L is not predictive of live performance. Governance evidence is invalid. The promotion gate is passed on false grounds.

• Simulated fills not marked paper-tagged

  Paper fills contaminate live P&L reports. PnLReporter may include hypothetical P&L in regulatory SettlementReports, which is a compliance violation.

• min_paper_days requirement not enforced

  A strategy may be promoted after insufficient observation. Edge cases and drawdown events that occur only after extended periods are never observed before live promotion.

No worked examples on this bot yet. Worked examples are optional but strongly recommended — they turn an abstract failure mode into something a developer can verify in a fixture.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "min_paper_days": 14 }

if (p.min_paper_days < p.hard) throw ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL')

{ "require_positive_risk_adj": true }

if (!p.require_positive_risk_adj) throw ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL')

{ "simulated_capital_usd": 10000 }

if (p.simulated_capital_usd > p.hard) throw ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL')

8. Default Configuration

{
  "bot_id": "gov.paper_trade_runner",
  "version": "2.0.0",
  "mode": "paper",
  "defaults": {
    "min_paper_days": 14,
    "require_positive_risk_adj": true,
    "simulated_capital_usd": 10000
  },
  "locked": {
    "mode": {
      "immutable": true,
      "value": "paper"
    },
    "require_positive_risk_adj": {
      "immutable": true
    }
  }
}

9. Implementation Flow

1. On startup, validate configuration: min_paper_days >= 3, simulated_capital_usd <= 500000, strategy in registry.
2. Assign a paper_run_id (ULID) for this paper trading session; all emitted reports for this session carry paper_run_id and mode=paper.
3. Subscribe to the live internal signal bus and CLOB WebSocket feed (ws_market) using the same subscription path as live strategies.
4. On each signal event, run the strategy under test in paper mode: evaluate intent, simulate risk guardrail votes (paper mode), shape the intent.
5. If a shaped intent would result in a simulated order: compute simulated fill against the current live order book snapshot (mid-price, depth). Denominate all amounts in pUSD.
6. Check KillSwitch; if active, suppress simulated fill emission and log KILL_SWITCH_ACTIVE.
7. Record simulated fill in the paper account ledger (Postgres): size_pusd, simulated_fill_price, simulated_slippage_bps, fee_pusd, pnl_pusd. Mark all records as paper_tagged=true.
8. Emit paper-tagged OperationsReport per simulated fill to polytraders.reports.operations, partitioned by bot_slug+epoch. Include paper_run_id and mode=paper on every record.
9. At each reporting cadence (batched-1/min), emit an aggregate OperationsReport summarising: total simulated fills, cumulative pUSD P&L, risk-adjusted P&L (Sharpe), days elapsed, and promotion gate status.
10. At min_paper_days boundary, evaluate the promotion gate: require_positive_risk_adj check. Emit PAPER_TRADE_RUNNER_GATE_PASSED or PAPER_TRADE_RUNNER_GATE_FAILED.
11. Retain all paper-tagged OperationsReport records for 1 year in polytraders.reports.operations.

10. Reference Implementation

Subscribes to the live signal bus and CLOB WebSocket feed, runs the strategy under test in paper mode through the full execution and risk guardrail stack, simulates fills against the current order book snapshot, emits paper-tagged OperationsReport per fill and an aggregate report at cadence. Evaluates promotion gate at min_paper_days boundary.

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. Translate to TS/Python/Go/Rust.

// ---- STARTUP ----
FUNCTION init(config):
  IF config.min_paper_days < 3:
    RAISE ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL')
  IF NOT config.require_positive_risk_adj:
    RAISE ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL')
  IF config.simulated_capital_usd > 500000:
    RAISE ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL')
  paper_run_id = generateULID()  // e.g. 'paper_01HX9KZQ7E8VR5'
  strategy = strategyRegistry.load(config.strategy, params=config.defaults)
  paper_account = { balance_pusd: toPusdUnits(config.simulated_capital_usd),
                    positions: {}, fills: [], start_ts: now() }

  // Subscribe to live feeds (same path as live strategies)
  ws_market.subscribe(onBookUpdate)
  internal_bus.subscribe(topics=['signals.*'], handler=onSignal)

// ---- SIGNAL HANDLER ----
FUNCTION onSignal(signal):
  ks = FETCH killswitch.status()
  IF ks.active:
    log.warn('KILL_SWITCH_ACTIVE', { paper_run_id: paper_run_id })
    RETURN

  // Evaluate strategy intent in paper mode (same logic as live)
  intent = strategy.evaluate(signal, paper_account, mode='paper')
  IF intent IS NULL:
    RETURN

  // Simulate risk guardrail stack in paper mode
  votes = riskStack.simulate(intent, context={
    paper_account: paper_account, mode: 'paper'
  })
  shaped_intent = applyVotes(intent, votes)
  IF shaped_intent IS NULL:
    EMIT OperationsReport(event_type='PAPER_TRADE_RUNNER_INTENT_BLOCKED',
                          paper_run_id=paper_run_id, mode='paper', ...)
    RETURN

  // Fetch current live order book snapshot for fill simulation
  book = FETCH clob_public.GET('/book?market_id=' + shaped_intent.market_id)
  IF book.last_updated_ms < now() - 30000:  // > 30s stale
    alerting.emit('STALE_DATA', { market_id: shaped_intent.market_id })
    RETURN  // Never simulate against stale book

  // Simulate fill against live book
  sim_fill = simulateFill(shaped_intent, book)
  sim_fill.size_pusd         = toPusdUnits(sim_fill.size_usd)
  sim_fill.fee_pusd          = sim_fill.size_pusd * sim_fill.fee_bps / 10_000
  sim_fill.pnl_pusd          = computeRealisedPnL(paper_account, sim_fill)
  sim_fill.paper_tagged      = true
  sim_fill.mode              = 'paper'
  sim_fill.paper_run_id      = paper_run_id

  // Check negRisk
  market = FETCH clob_public.getMarketByConditionId(shaped_intent.condition_id)
  IF market.negRisk:
    sim_fill.pnl_pusd = negRiskPayoff(paper_account, sim_fill, market)

  // Persist to paper ledger
  postgres.INSERT('paper_fills', sim_fill)
  paper_account.fills.append(sim_fill)
  paper_account.balance_pusd -= sim_fill.fee_pusd

  // Emit per-fill paper OperationsReport
  EMIT OperationsReport({
    report_id:              'ops_paper-trade-runner_' + paper_run_id + '_' + now(),
    bot_id:                 'gov.paper_trade_runner',
    event_type:             'PAPER_TRADE_RUNNER_FILL_SIMULATED',
    paper_run_id:           paper_run_id,
    mode:                   'paper',
    market_id:              shaped_intent.market_id,
    simulated_fill:         sim_fill,
    topic:                  'polytraders.reports.operations',
    partition:              'paper-trade-runner+' + epochBucket(now())
  })

// ---- CADENCE REPORT (batched-1/min) ----
FUNCTION onCadence():
  days_elapsed = (now() - paper_account.start_ts) / 86400
  sharpe = computeSharpe(paper_account.fills)

  EMIT OperationsReport({
    event_type:              'PAPER_TRADE_RUNNER_CADENCE_REPORT',
    paper_run_id:            paper_run_id,
    mode:                    'paper',
    paper_days_elapsed:      days_elapsed,
    simulated_fills:         len(paper_account.fills),
    simulated_pnl_pusd:      SUM(f.pnl_pusd FOR f IN paper_account.fills),
    simulated_sharpe_ratio:  sharpe,
    promotion_gate_eligible: days_elapsed >= config.min_paper_days
  })

// ---- PROMOTION GATE (at min_paper_days boundary) ----
FUNCTION evaluatePromotionGate():
  sharpe = computeSharpe(paper_account.fills)
  gate_passed = (sharpe > 0)
  IF gate_passed:
    EMIT OperationsReport(event_type='PAPER_TRADE_RUNNER_GATE_PASSED',
                          promotion_gate_passed=true, ...)
  ELSE:
    EMIT OperationsReport(event_type='PAPER_TRADE_RUNNER_GATE_FAILED',
                          promotion_gate_passed=false,
                          reason_code='PAPER_TRADE_RUNNER_RISK_ADJ_FAIL', ...)

SDK calls used

• clob_public.GET('/book?market_id=...')
• clob_public.getMarketByConditionId(condition_id)
• ws_market.subscribe(onBookUpdate)
• toPusdUnits(raw_usd)
• postgres.INSERT('paper_fills', sim_fill)
• alerting.emit('STALE_DATA', metadata)
• alerting.emit('PAPER_TRADE_RUNNER_GATE_FAILED', metadata)

Complexity: O(S) per signal event where S = signals/s from the live bus; O(F) per cadence report where F = cumulative simulated fill count

11. Wire Examples

Input — what arrives on the wire

{
  "label": "Live CLOB order book snapshot (ws_market update)",
  "source": "ws_market",
  "payload": {
    "market_id": "0x9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c",
    "condition_id": "0x3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f",
    "best_bid": 0.615,
    "best_ask": 0.625,
    "depth_pusd_bid_5pct": 38000,
    "depth_pusd_ask_5pct": 42000,
    "negRisk": false,
    "last_updated_ms": 1746792300000
  }
}

Output — what the bot emits

{
  "label": "OperationsReport — PAPER_TRADE_RUNNER_GATE_PASSED (14-day completion)",
  "payload": {
    "report_id": "ops_paper-trade-runner_paper_01HX9KZQ7E8VR5",
    "bot_id": "gov.paper_trade_runner",
    "event_type": "PAPER_TRADE_RUNNER_GATE_PASSED",
    "paper_run_id": "paper_01HX9KZQ7E8VR5",
    "strategy": "sum_to_one_arb",
    "mode": "paper",
    "paper_days_elapsed": 14,
    "simulated_fills": 312,
    "simulated_volume_pusd": 134200.0,
    "simulated_pnl_pusd": 1890.5,
    "simulated_sharpe_ratio": 1.42,
    "simulated_net_fees_pusd": 335.5,
    "promotion_gate_passed": true,
    "paper_tagged": true,
    "report_kind": "OperationsReport",
    "topic": "polytraders.reports.operations",
    "partition": "paper-trade-runner+2026-05-09T00:00Z",
    "retained_until": "2027-05-09"
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a OperationsReport object. See OperationsReport schema.

{
  "report_id": "ops_paper-trade-runner_paper_01HX9KZQ7E8VR5",
  "bot_id": "gov.paper_trade_runner",
  "event_type": "PAPER_TRADE_RUNNER_GATE_PASSED",
  "paper_run_id": "paper_01HX9KZQ7E8VR5",
  "strategy": "sum_to_one_arb",
  "mode": "paper",
  "paper_days_elapsed": 14,
  "simulated_fills": 312,
  "simulated_volume_pusd": 134200.0,
  "simulated_pnl_pusd": 1890.5,
  "simulated_sharpe_ratio": 1.42,
  "simulated_net_fees_pusd": 335.5,
  "promotion_gate_passed": true,
  "report_kind": "OperationsReport",
  "topic": "polytraders.reports.operations",
  "partition": "paper-trade-runner+2026-05-09T00:00Z",
  "retained_until": "2027-05-09"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Governance / Paper-Trade Runner session dashboard (P&L, Sharpe, days elapsed)
• Grafana — Governance / Promotion gate history and pass rate by strategy

16. Developer Reporting

{
  "bot_id": "gov.paper_trade_runner",
  "event_type": "PAPER_TRADE_RUNNER_FILL_SIMULATED",
  "paper_run_id": "paper_01HX9KZQ7E8VR5",
  "market_id": "0x9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c",
  "simulated_fill_price": 0.618,
  "simulated_fill_size_pusd": 640.0,
  "simulated_slippage_bps": 1.2,
  "fee_pusd": 16.0,
  "pnl_pusd": 0.0,
  "paper_tagged": true,
  "mode": "paper",
  "tick_ts_ms": 1746792300000
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On restart, the paper_session record is reloaded from Postgres and the paper trading session resumes. In-flight signal processing is restarted from the next WebSocket event; no missed signals are retroactively replayed.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Sibling bots (same OrderIntent)

External services

23. Security Surfaces

Abuse vectors considered

• Setting require_positive_risk_adj=false to bypass the promotion gate risk-adjustment check
• Reducing min_paper_days below the hard limit to fast-track a strategy to live promotion
• Mixing paper_tagged=true fills with live fills to inflate live P&L reports

Mitigations

• require_positive_risk_adj is locked immutable in default_config; any attempt to set false raises PARAMETER_CHANGE_REQUIRES_APPROVAL
• min_paper_days hard limit of 3 enforced at config load; cannot be overridden without approval
• All paper fills carry paper_tagged=true; PnLReporter checks this flag before including in live SettlementReports
• Paper-Trade Runner has no clob_auth or onchain access — it can never submit real orders

24. Polymarket V2 Compatibility

API surfaces declared

Networks supported

25. Versioning & Migration

Migration history

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

Paper-Trade Runner incidents involve feed staleness (fill simulation paused), failed promotion gates (strategy underperformed), or configuration lock violations (bypass attempts). Feed staleness is the most common operational issue during WebSocket instability.

On-call actions

Manual overrides

• polytraders gov paper reset-gate --paper-run-id <id> --reviewed-by <operator> — After a gate fails due to a known data quality issue (e.g. stale feed during gate evaluation), reset the gate clock with governance pod sign-off.

Healthcheck

Endpoint: /internal/health/paper-trade-runner | Green: Active paper session running; WebSocket feed connected; last simulated fill < 300s ago during active trading; Postgres paper_fills writable. | Red: No active paper session; WebSocket disconnected for > 30 minutes; Postgres write failure; fill simulation suspended.

28. Promotion Gates

A bot does not advance to the next readiness state until every gate below is green. Gates are observable from production data — no subjective sign-off.

Promote to Shadow

Promote to Limited live

Promote to General live

29. Developer Checklist

Ready-to-ship score: 27/27 sections complete · 100%