polymarket-paper-trader

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 — open research lab for self-evolving autonomous agents.

60-second demo

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

# 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

# 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:

pm-trader-mcp  # starts on stdio

Add to your Claude Code config:

{
  "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.

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.

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.

pm-trader benchmark run examples.limit_grid.run

Writing your own strategy

# 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)

pm-trader benchmark run my_strategy.run

For backtesting with historical data:

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:

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:

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 as polymarket-paper-trader:

npx clawhub install polymarket-paper-trader

Tests

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