Polytraders: a controlled trading-infrastructure layer for prediction markets.
The software layer between a trading strategy and a live prediction-market exchange. It handles safety checks, order routing, audit trail, and reporting — so every strategy author builds on the same guardrails instead of reinventing them. This guide documents 109 frozen bot specifications and the standards every one of them must meet.
All specs documented. None in production. This guide is the build plan.
platform mock · start here · demo-wired ≠ production-live Open the platform mock — watch one trade flow through all 11 stages → Registry → book → canonical state → signals → fair value → execution → decision → OMS → inventory → replay → monitoring. 300+ pages · 9 demo-wired bots · the full operator UX.The platform mock is the source of truth for what each stage exposes. The dev-guide pages below — stages, standards, pipelines — explain how to code what the mock shows.
What this is, in plain English
What is a prediction market?
A prediction market is a financial exchange where you buy and sell shares in the outcome of a future event — “Will X happen?” trades like a stock. If you think YES is underpriced at 30 cents, you buy; if it resolves YES, it pays $1.00. Polymarket is the largest on-chain prediction-market exchange. Polytraders is infrastructure for automated trading on Polymarket — not a product for users to gamble with, and not copy-trading.
What is Polytraders?
Polytraders is a layered software system that sits between a trading strategy and the Polymarket exchange. A strategy author writes the logic for when and why to trade. Polytraders handles everything else: scanning markets for quality, collecting signals, enforcing risk limits, signing and routing the order, recording the fill, and producing an audit trail. Nothing reaches the exchange unless every risk gate has cleared. The system targets Polymarket's CLOB V2 exchange and uses pUSD only.
Why build it in layers?
A single script that “does everything” is untestable, unauditable, and catastrophic when it fails. Layers separate concerns: a Discovery bot only finds markets; a Strategy bot only decides what to trade; a Risk guardrail only votes on whether to allow the trade. Each layer has a strict contract — it can only do what its class permits. If a Risk guardrail rejects an order, no downstream code can override it. Layers mean you can test, audit, and replace one component without touching the others.
Terms used on this page
- CLOB V2
- Central Limit Order Book, version 2. Polymarket's on-chain order matching engine. All Polytraders orders target CLOB V2 only — V1 is blocked.
- EIP-712 v2
- An Ethereum signing standard that encodes what you're signing in a structured, human-readable format. Every Polytraders order must be signed using the V2 domain separator. Wrong domain = hard reject.
- pUSD
- Polymarket's dollar-pegged stablecoin. The only currency used for orders in this system. Not USDC.e, not raw USDC — pUSD only.
- builderCode
- A tag attached to every Polytraders order that attributes fills to the Polytraders builder. Required for Polymarket's builder-rewards program and for the Governance layer's reconciliation checks.
- CTFExchangeV2
- The on-chain contract address for the Polymarket Conditional Token Framework exchange, V2. ContractAddressGuard enforces that every order targets this exact address.
- OrderIntent
- A structured internal object that Strategy emits when it wants to trade. It describes the market, direction (YES/NO), side (buy/sell), price, and size. Every Risk guardrail votes on an OrderIntent before it becomes a real order.
- ReportEnvelope
- The standard audit record that wraps every trade lifecycle event — from OrderIntent creation through fill confirmation. The Governance layer writes one per order. It is the primary artefact for reconciliation and compliance.
The operating loop: how one trade goes from raw data to fill
Every trade passes through the same eleven stages. Each stage has a single responsibility and a reference TypeScript implementation in packages/polytraders-*. Open the 11-stage index →
net_edge = p_hat − q_exec − fees − uncertainty_buffer. No stage may skip the one before it. That is what makes a trade explainable and safe enough to scale.If you only build the rails, build them in this order.
These are the infrastructure modules you build before any trading strategy goes near real capital. If you skip Tier 1, you have no kill switch, no audit trail, and no safety net.
- Tier 1 — Mandatory rails (14 modules): clean data, ReportEnvelope, KillSwitch, ComplianceGate, PortfolioGuard, StaleBookGuard, MarketHaltDetector, SmartRouter, OrderLifecycleManager, PnL Reporter, ConfigDriftDetector, ReplaySimulator, plus the ReasonCode registry. Build these before anything else. See the Plan →
- Tier 2 — First trading path (4 modules): Maker-Tight + Cross-Market Arb + Fee/Slippage Estimator + Anti-Toxic Fill. The path that proves the rails work end-to-end.
- Tier 3 — Alpha expansion: news, sports, social, ontology, resolution. Only after Tier 1 is at runtime-live.
Current readiness, honestly
| State | Count | What it actually means |
|---|---|---|
| docs-complete | 109 / 109 | Every spec page is filled out across all 29 sections. Documentation completeness only — no implementation guarantee. |
| demo-wired | 9 / 109 | Reference implementation runs against the synthetic feed in the browser demo and ships a complete fixture pack. Not production-live. No capital, no live adapter. |
| shadow-ready | 0 / 109 | Has fixture pack, has passed CI on all four readiness scores, ready for shadow mode. |
| runtime-live | 0 / 109 | Has run in shadow with clean telemetry; promoted through the modes ladder. |
| production-live | 0 / 109 | Running against production constraints. Nothing here yet. |
Synthetic backtests are not forecasts. Demo-wired ≠ production-live. See Definition of Done for the four readiness scores.
From spec library to running system.
v2 shipped 27/27 documentation for every bot — spec coverage, not running code. v3 separates documentation from implementation from runtime. The bot library is frozen at 109 frozen specifications — no new bots until the runtime rails (kill switch, reconciler, replay, envelopes) are at runtime-live with 24h of clean envelopes.
Nine bots wired into the synthetic replay stack.
These are reference implementations, not production-live. They run end-to-end against a deterministic synthetic feed with full order-book ladders, against the same TypeScript that compiles against @polytraders/contracts. They are demo-wired — they have not yet passed shadow-mode validation, fixture packs, or runtime promotion gates. Treat them as implementation references until the four readiness scores are complete. Click any chip to open its spec page; click Run in demo to watch it react in your browser. Synthetic backtests are not forecasts.
- risk.killswitchKillSwitchRun →
- risk.compliancegateComplianceGateRun →
- risk.markethaltguardMarketHaltDetectorRun →
- risk.stalebookguardStaleBookGuardRun →
- risk.marketqualityguardMarketQualityRankeralias of marketqualityrankerRun →
- risk.exposureguardSettlementExposureGuardalias of settlementexposureguardRun →
- risk.drawdownguardPortfolioGuardalias of portfolioguardRun →
- strat.maker_tightMaker-TightRun →
- exec.smartrouterSmartRouterRun →
All 109 bots by layer — click any to open its spec.
Seven layers. Data flows in from the left (Discovery, Intelligence), decisions happen in the middle (Strategy, Risk, Security), and orders flow out the right (Execution). Governance sits across all of it. 109 docs-complete · 9 demo-wired · 0 production-live
ReportEnvelope records flow back through Governance
Pick a class. Then a bot.
Functional classes. Each class is a contract — what authority a bot in that class is allowed to hold and what it must never do.
Guardrail
Bots that can block, downsize, quarantine, or pause an order. They vote on every OrderIntent. A guardrail must have at least one REJECT path — if it cannot reject, it is not a guardrail and should be reclassified.
- ComplianceGate · Risk demo-wired
- KillSwitch · Risk demo-wired
- MarketHaltDetector · Risk demo-wired
Execution Utility
Bots that shape an approved order — price, timing, order type, size within constraints. They never change direction or strategy intent and never override a Risk decision.
- SmartRouter · Execution demo-wired
- AntiToxicFill · Execution
- CancelReplaceOptimizer · Execution
Alpha Strategy
The only bots in the stack that take directional, spread, or liquidity intent. Each declares its risk envelope to Layer 1 at startup; mid-run parameter changes require re-validation.
- Maker-Tight · Strategy demo-wired
- BasisTrader · Strategy
- Breakout-Follower · Strategy
Signal Service
Read-only producers of typed signals. Every output carries a freshness timestamp and a provenance string. Signal services never submit orders.
- MarketScanner · Discovery ref
- AnomalyDetector · Intelligence
- ContradictionDetector · Intelligence
Governance Service
Bots that log, explain, reconcile, and audit. They sit across the top of everything else and produce the artefacts the team and users need to trust the system. Governance never blocks; it explains.
- BuilderAttribution · Governance ref
- AttributionRevenueReporter · Governance
- Backtester · Governance
Reference bots — fully specced
Eight bots authored end-to-end. Use these as the model when you author the next one.
Other ways to browse
By layer
Discovery → Intelligence → Strategy → Risk → Security → Execution → Governance.
By authority
Read-only · Recommend · Warn · Reshape · Reject · Pause · Trade · Explain.
By developer readiness
Idea only → Spec started → Parameters → Thresholds → Tests → Ready → Built → Shadow → Limited live → General live.
By Polymarket input
Group bots by which Polymarket API or feed they depend on. Use this view to map the blast radius if a feed degrades.
Principles & schemas
Locked rules, the six standard schemas, reason-code standards, default-value guidance.
Trade Report
The reporting layer. ReportEnvelope schema, six lifecycle groups, end-to-end trace, SLOs, routing matrix, replay modes, compliance export.
How to read a bot page
- Top: identity table, pills, and one-line purpose. If you only have ten seconds, you stop here.
- Inputs: what Polymarket data and what internal data the bot needs. If a required input is missing in production, the bot must safe-fail.
- Parameters: machine name, default, warning, hard, plain meaning. The detailed block below explains why each default matters.
- Decision logic: when it APPROVES, RESHAPES, REJECTS, or only WARNS.
- Output: the standard
RiskVote(or layer-equivalent) the bot returns. - Failure modes + acceptance tests + Ready-to-ship checklist. If the checklist isn’t green, the bot doesn’t ship.