Paper-Trade Runner
Paper-Trade Runner mirrors every live signal against a simulated paper account in real time (mode=paper).
What it does
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.
Pipeline placement
Applies to: All strategies configured for paper mode; any strategy awaiting promotion to live must complete min_paper_days of paper
Why it matters
| If this fails | Consequence |
|---|---|
| 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. |
Inputs
Polymarket inputs
| Input | Source | Required | Use |
|---|---|---|---|
| Live CLOB order book snapshots (real-time mid-price, depth, spread) | clob_public | required | Primary signal for simulated fill computation. Paper fills are computed against the current live order book snapshot. |
| Live market metadata (negRisk flag, condition_id, market_type) | clob_public | required | Identify negative-risk markets for correct simulated payoff valuation. |
| Live WebSocket market feed (order book updates, trade events) | ws_market | required | Real-time signal stream fed into the paper strategy; same feed as live execution. |
Internal inputs
| Input | Source | Required | Use |
|---|---|---|---|
| Live signal stream from intelligence and discovery bots | internal | required | Paper-Trade Runner subscribes to the same internal signal bus as live strategies, ensuring paper results reflect live signal quality. |
| KillSwitch active flag | KillSwitch | optional | When KillSwitch is active, suppress all paper-trading simulated order emission. Paper-Trade Runner continues to record signal observations but stops simulating fills. |
| Risk guardrail stack (paper simulation) | internal | required | All risk guardrail votes are simulated in paper mode. Paper-Trade Runner must pass through the same guardrail logic as live strategies. |
Authority
What this bot is permitted to do
State
Readiness
Limited live
Status
beta
Class
Governance Service
Default mode
limited_live
Developer owner
Polytraders core — Governance pod
Capital impact
Indirect
Reason codes emitted
| Code | Severity | Meaning | Action |
|---|---|---|---|
| PAPER_TRADE_RUNNER_FILL_SIMULATED | INFO | A simulated fill was computed against the live order book snapshot and logged to the paper account ledger. | No action — routine paper trading event. |
| PAPER_TRADE_RUNNER_GATE_PASSED | INFO | The strategy has completed min_paper_days of continuous paper trading with positive risk-adjusted P&L. It is eligible for promotion to limited live. | No action — governance pod to review promotion evidence. |
| PAPER_TRADE_RUNNER_GATE_FAILED | WARN | The strategy completed min_paper_days but did not achieve positive risk-adjusted P&L (Sharpe ratio <= 0). | Emit alert; do not promote strategy; governance pod to review. |
| PAPER_TRADE_RUNNER_RISK_ADJ_FAIL | WARN | Sharpe ratio at promotion gate evaluation is <= 0; require_positive_risk_adj gate failed. | Block promotion gate; emit WARN; continue paper trading or revise strategy. |
| PAPER_TRADE_RUNNER_FEED_STALE | WARN | The live CLOB WebSocket feed has been disconnected for more than 30 minutes; fill simulation paused and promotion gate clock suspended. | Pause fill simulation; suspend promotion gate clock; emit alert; resume on feed recovery. |
| STALE_DATA | WARN | The order book snapshot used for fill simulation is stale (last updated > 30s ago). Fill simulation skipped for this signal. | Skip fill simulation for this tick; emit WARN; retry on next fresh snapshot. |
| KILL_SWITCH_ACTIVE | WARN | KillSwitch is active; simulated fill emission is suppressed. Paper trading timer continues. | Suppress simulated fills; emit WARN; paper timer continues. |
| PAPER_TRADE_RUNNER_INTENT_BLOCKED | INFO | A simulated intent was blocked by the paper-mode risk guardrail stack. | Log; no fill emitted; paper account unchanged. |
| PARAMETER_CHANGE_REQUIRES_APPROVAL | HARD_REJECT | min_paper_days below hard limit (3), require_positive_risk_adj set to false, or simulated_capital_usd above hard limit (500000) attempted. | Reject config change; emit alert. |
Related bots in Governance & Ops
Used by
Reverse index — strategies that currently reference gov.paper-trade-runner. If you change this bot's authority or reason codes, these strategies must re-pass shadow.
| Strategy | State | Activity |
|---|---|---|
| AI Frontier — release-day taker | frozen | last triggered 35m ago |
| NBA props — line-shop | demo-wired | last triggered 42m ago |
| Crypto Q2 — basket rebalance | frozen | last triggered 2m ago |
Showing 3 of 3 · demo-wired ≠ production-live
Why this matters
Governance & Ops bots does NOT propose, approve, or block trades; only observes and reports. Understanding the authority boundary prevents misuse and makes promotion-gate reviews faster and more reliable. View raw spec JSON →