A paper-money gym where AI agents learn to lose gracefully

What it does

polymarket-paper-trader gives an agent $10k of paper money and access to real, live Polymarket order books. Orders walk the actual book like a real taker — consuming ask levels from the bottom up — so slippage is genuine and reported in basis points. Fees follow the official per-match curve, resolution pays $1/share, and closed or paused markets reject trades. It ships as a CLI and an MCP server, so Claude, Cursor, Codex, or any MCP-speaking agent can use it directly.

The interesting bit

The fidelity is the point, and it’s verified: the CI test suite asserts simulated fills land inside the band of prices the market actually quoted (via Data API v2 price history) and that fees match the official curve exactly. There’s also a benchmark harness scoring models on Brier score, calibration, and alpha — plus Forecast Arena, a public daily leaderboard where AI models and simple baselines forecast the same questions and get scored by real outcomes.

Key highlights

• Real order-book mechanics: partial fills, resting orders reserve cash, tick-size validation, FOK/FAK order types
• Multi-outcome markets, not just YES/NO; Kalshi markets supported via kalshi:<ticker> slugs
• Multi-account battles (pk), local leaderboards, and strategy comparison for A/B testing agents
• The MCP server carries a full trading playbook as instructions and a skill:// resource, so even MCP-only clients get the guidance
• 100% coverage gate on the core package, with end-to-end tests against the live API

Caveats

• The streamable-http transport has no authentication and no caller isolation — self-host only, bind to localhost, or put a real proxy in front
• backtest and pk_battle (local file reads and strategy-module execution) are stdio-only and disabled over HTTP
• The benchmark harness is a separate install from the main package

Verdict

If you’re building or evaluating agents that make probability judgments, this is a rare honest scoreboard — real books, real fees, zero risk. If you just want to place actual bets with real money, this is deliberately not that tool.