polymarket-paper-trader
# polymarket-paper-trader [](https://pypi.org/project/polymarket-paper-trader/) [](https://github.com/agent-next/polymarket-paper-trader/actions/workflows/test.yml) [](https://clawhub.com/robotlearning123/polymarket-paper-trader) [](https://github.com/agent-next/polymarket-paper-trader/blob/main/LICENSE) **Your AI agent just became a Polymarket trader.** Install → your agent gets $10,000 paper money → trades real Polymarket order books → tracks P&L → competes on a public leaderboard. Zero risk. Real prices. > "My AI agent hit +18% ROI on Polymarket in one week. Zero risk, real order books." Part of [agent-next](https://github.com/agent-next) — open research lab for self-evolving autonomous agents. ## 60-second demo ```bash npx clawhub install polymarket-paper-trader # install via ClawHub 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 ``` That's it. Your AI agent is now trading Polymarket with zero risk. ## Install ```bash # via pip pip install polymarket-paper-trader # via ClawHub (for OpenClaw agents) npx clawhub install polymarket-paper-trader # from source (development) uv pip install -e ".[dev]" ``` Requires Python 3.10+. ## Not a toy — this is a real exchange simulator Other tools mock prices or use random numbers. We simulate the actual exchange: - **Level-by-level order book execution** — your order walks the real Polymarket ask/bid book, consuming liquidity at each price level, just like a real trade - **Exact fee model** — `bps/10000 × min(price, 1-price) × shares` — the same formula Polymarket uses - **Slippage tracking** — every trade records how much worse your fill was vs the midpoint, in basis points - **Limit order state machine** — GTC (good-til-cancelled) and GTD (good-til-date) with full lifecycle - **Strategy backtesting** — replay your strategy against historical price snapshots - **Multi-outcome markets** — not just YES/NO binary, supports any number of outcomes Your paper P&L would match real P&L within the spread. That's the point. ## Quick start ```bash # 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 ``` ## CLI commands | Command | Description | |---------|-------------| | `init [--balance N]` | Create paper trading account | | `balance` | Show cash, positions value, total P&L | | `reset --confirm` | Wipe all data | | `markets list [--limit N] [--sort volume\|liquidity]` | Browse active markets | | `markets search QUERY` | Full-text market search | | `markets get SLUG` | Market details | | `price SLUG` | YES/NO midpoints and spread | | `book SLUG [--depth N]` | Order book snapshot | | `watch SLUG [SLUG...] [--outcome yes\|no]` | Monitor live prices | | `buy SLUG OUTCOME AMOUNT [--type fok\|fak]` | Buy at market price | | `sell SLUG OUTCOME SHARES [--type fok\|fak]` | Sell at market price | | `portfolio` | Open positions with live prices | | `history [--limit N]` | Trade history | | `orders place SLUG OUTCOME SIDE AMOUNT PRICE` | Limit order | | `orders list` | Pending limit orders | | `orders cancel ID` | Cancel a limit order | | `orders check` | Fill limit orders if price crosses | | `stats [--card\|--tweet\|--plain]` | Win rate, ROI, profit, max drawdown | | `leaderboard` | Local account rankings | | `pk ACCOUNT_A ACCOUNT_B` | Battle: who's the better trader? | | `export trades [--format csv\|json]` | Export trade history | | `export positions [--format csv\|json]` | Export positions | | `benchmark run MODULE.FUNC` | Run a trading strategy | | `benchmark compare ACCT1 ACCT2` | Compare account performance | | `benchmark pk STRAT_A STRAT_B` | Battle: who's the better trader? | | `accounts list` | List named accounts | | `accounts create NAME` | Create account for A/B testing | | `mcp` | Start MCP server (stdio transport) | 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 26 tools via the [Model Context Protocol](https://modelcontextprotocol.io): ```bash pm-trader-mcp # starts on stdio ``` Add to your Claude Code config: ```json { "mcpServers": { "polymarket-paper-trader": { "command": "pm-trader-mcp" } } } ``` ### MCP tools | Tool | What it does | |------|---------| | `init_account` | Create paper account with starting balance | | `get_balance` | Cash, positions value, total P&L | | `reset_account` | Wipe all data and start fresh | | `search_markets` | Find markets by keyword | | `list_markets` | Browse markets sorted by volume/liquidity | | `get_market` | Market details with outcomes and prices | | `get_order_book` | Live order book snapshot (bids + asks) | | `watch_prices` | Monitor prices for multiple markets | | `buy` | Buy shares at best available prices | | `sell` | Sell shares at best available prices | | `portfolio` | Open positions with live valuations and P&L | | `history` | Recent trade log with execution details | | `place_limit_order` | Limit order — stays open until filled or cancelled/expired | | `list_orders` | Pending limit orders | | `cancel_order` | Cancel a pending order | | `check_orders` | Execute pending orders against live prices | | `stats` | Win rate, ROI, profit, max drawdown | | `resolve` | Resolve a closed market (winners get $1/share) | | `resolve_all` | Resolve all closed markets | | `backtest` | Backtest a strategy against historical snapshots | | `stats_card` | Shareable stats card (tweet/markdown/plain) | | `share_content` | Platform-specific content (twitter/telegram/discord) | | `leaderboard_entry` | Generate verifiable leaderboard submission | | `leaderboard_card` | Top 10 ranking card from all local accounts | | `pk_card` | Head-to-head comparison between two accounts | | `pk_battle` | Run two strategies head-to-head, auto-compare | ## Strategy examples Three ready-to-use strategies in `examples/`: ### Momentum (`examples/momentum.py`) Buys when YES price crosses above 0.55, takes profit at 0.70, stops loss at 0.35. ```bash pm-trader benchmark run examples.momentum.run ``` ### Mean reversion (`examples/mean_reversion.py`) Buys when YES price drops 12+ cents below 0.50 fair value, sells when it reverts. ```bash pm-trader benchmark run examples.mean_reversion.run ``` ### Limit grid (`examples/limit_grid.py`) Places a grid of limit buy orders below current price with take-profit sells above. ```bash pm-trader benchmark run examples.limit_grid.run ``` ### Writing your own strategy ```python # my_strategy.py from pm_trader.engine import Engine def run(engine: Engine) -> None: """Your strategy receives a fully initialized Engine.""" markets = engine.api.search_markets("crypto") for market in markets: if market.closed or market.yes_price < 0.3: continue engine.buy(market.slug, "yes", 100.0) ``` ```bash pm-trader benchmark run my_strategy.run ``` For backtesting with historical data: ```python def backtest_strategy(engine, snapshot, prices): """Called once per historical price snapshot.""" if snapshot.midpoint > 0.6: engine.buy(snapshot.market_slug, snapshot.outcome, 50.0) ``` ## Multi-account support Run parallel strategies with isolated accounts: ```bash pm-trader --account aggressive init --balance 5000 pm-trader --account conservative init --balance 5000 pm-trader --account aggressive buy some-market yes 500 pm-trader --account conservative buy some-market yes 100 pm-trader benchmark compare aggressive conservative ``` ## Share your results Generate a shareable stats card and post to X/Twitter: ```bash pm-trader stats --tweet # X/Twitter optimized pm-trader stats --card # markdown for Telegram/Discord pm-trader stats --plain # plain text ``` AI agents can use the `stats_card` MCP tool to generate and share cards automatically. ## OpenClaw / ClawHub Available on [ClawHub](https://clawhub.com) as `polymarket-paper-trader`: ```bash npx clawhub install polymarket-paper-trader ``` ## Tests ```bash pytest -m "not live" # unit + integration (skips live API tests) pytest # full test suite (requires network) pytest tests/test_e2e_live.py # live API integration tests only ``` ## License MIT <!-- mcp-name: io.github.agent-next/polymarket-paper-trader -->