Polymarket Paper Trader

polymarket-paper-trader

A zero-risk gym for AI agents on real prediction markets — real order books, official fees, verified fill fidelity. Practice, evaluate, and benchmark decision intelligence.

Agents make probability judgments all day. Polymarket is the world's largest prediction market, and its order books are the honest scoreboard: real money, real prices, real outcomes. But you cannot hand an agent a wallet to learn with. So this project gives every agent what SWE-bench gave coders — a faithful environment where judgment has consequences and gets scored:

• Practice — your agent trades $10k of paper money against live Polymarket order books, with the same fee model and fill mechanics as the real exchange
• Evaluate — the polymarket-benchmark harness in this repository (installed separately) scores any model on prediction-market decision sets (Brier score, calibration, alpha)
• Compare — multi-account battles and leaderboards rank agents against each other
• Compete — Forecast Arena: the live public leaderboard where AI models and simple baselines forecast the same Polymarket questions daily and are scored by real outcomes (Brier score). Runs from this repo (enter your model · workflow · raw data).

Part of agent-next — building an agentic world.

60-second demo

pip install polymarket-paper-trader

pm-trader init --balance 10000 # $10k paper money pm-trader markets search "bitcoin" # find markets pm-trader buy will-bitcoin-hit-100k yes 500 # buy $500 of YES pm-trader stats --card # shareable stats card

Prefer not to install? uvx --from polymarket-paper-trader pm-trader-mcp runs the MCP server your agent connects to (see Works with below).

That's it. Your AI agent is now trading Polymarket with zero risk.

Install

# via pip (CLI + MCP server)

pip install polymarket-paper-trader

or the MCP server alone, with no install

uvx --from polymarket-paper-trader pm-trader-mcp

from source (development)

uv pip install -e ".[dev]"

Requires Python 3.10+.

Works with

Full copy-paste config for every runtime above (plus Grok/xAI remote MCP): docs/integrations.md. Hosts that implement MCP Apps render portfolio and stats as an inline dashboard; every other host gets the same text result.

Use it from ChatGPT / Claude.ai / personal agents

Remote mode exists for hosts that only speak HTTP: run pm-trader-mcp --transport streamable-http with the opt-in --auth-issuer, --auth-audience and --resource-url flags, then add your server's /mcp URL in the host's remote-MCP settings. It is off by default, and it needs an OAuth/OIDC issuer you operate — pm-trader verifies bearer tokens against it and gives every verified subject its own paper accounts. There is no hosted endpoint to add: you run the server yourself. Setup, threat model and the environment equivalents: docs/remote-mcp.md.

Quick start

# Initialize with $10k paper balance

pm-trader init --balance 10000

Browse markets

pm-trader markets list --sort liquidity pm-trader markets search "bitcoin"

Trade

pm-trader buy will-bitcoin-hit-100k yes 100 # buy $100 of YES pm-trader sell will-bitcoin-hit-100k yes 50 # sell 50 shares

Check portfolio and P&L

pm-trader portfolio pm-trader stats

How it works — and why to trust it

• Your order walks the real book. A buy consumes live ask levels from the lowest price upward, exactly like a real taker order — slippage is real and reported in basis points
• Fees follow the official per-match curve — fee = C × rate × p × (1-p), rounded to 5 decimals, makers exempt (exact spec in the CHANGELOG) — charged per filled level from each market's published fee schedule, not an approximation
• Paper cash, real discipline. Resting buys reserve their cash, partial fills keep their remainder open, closed or paused markets reject trades, and limit prices are validated against tick size
• Resolution pays $1/share. Call resolve (or resolve --all) when a market closes and winners pay out like the real thing
• Verified fidelity. The live test suite asserts that simulated fills land inside the band of prices the market actually quoted (Data API v2 price history) and that fees match the official curve exactly — run against real APIs on CI
• Upstream-aligned. The client tracks the current Gamma / CLOB / Data API surface, contract-verified by live probes
• Multi-outcome markets — any number of outcomes, not just YES/NO
• Kalshi too. Paper trade Kalshi markets with the same commands and tools by passing a kalshi: slug (pm-trader buy kalshi:KXNBAGAME-26OCT16DENLAL-LAL yes 25); find them with kalshi markets. Fees follow each series' published curve (docs/kalshi.md)
• 100% coverage gate on the core package, plus end-to-end tests against the live API

CLI commands

Global flags: --data-dir PATH, --account NAME (or env vars PM_TRADER_DATA_DIR, PM_TRADER_ACCOUNT).

MCP server — what your agent can do

Your agent gets the following tools via the Model Context Protocol. The server also carries the full trading playbook with it — as MCP server instructions, as a trading_playbook prompt, and as a skill://trading-playbook resource — so MCP-only clients (Cursor, Claude.ai connectors, Grok API remote MCP, ChatGPT apps) get the same guidance skill-aware agents get from skill/polymarket-paper-trader/SKILL.md.

pm-trader-mcp  # starts on stdio

or, with no local install:

uvx --from polymarket-paper-trader pm-trader-mcp

Add to your Claude Code config:

{

"mcpServers": { "polymarket-paper-trader": { "command": "pm-trader-mcp" } } }

Remote transport (streamable-http)

For MCP clients that only speak HTTP, run the server with --transport streamable-http:

pm-trader-mcp --transport streamable-http --host 127.0.0.1 --port 8000

or: pm-trader mcp --transport streamable-http --host 127.0.0.1 --port 8000

The MCP endpoint is then http:// : /mcp. There is no isolation between callers — everyone who reaches the server shares all of its paper accounts; it is self-host-only, not a public multi-user service. There is no authentication on this transport; anyone who can reach the port can call every exposed tool. backtest and pk_battle (local file reads + local strategy-module execution) are stdio-only and are not registered when serving over streamable-http.

Docker

docker build -t pm-trader-mcp .

docker run -p 127.0.0.1:8000:8000 -v pm-trader-data:/root/.pm-trader pm-trader-mcp

Publish the port to 127.0.0.1 only (as above) unless you put a real authenticating proxy in front of it — the container has no auth of its own.

MCP tools

| get_market | Market detail