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