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 — building an agentic world.

60-second demo

bashCopy code
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

bashCopy code
# 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

bashCopy code
# 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

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:

bashCopy code
pm-trader-mcp  # starts on stdio

Add to your Claude Code config:

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

MCP tools

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.

bashCopy code
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.

bashCopy code
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.

bashCopy code
pm-trader benchmark run examples.limit_grid.run

Writing your own strategy

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

bashCopy code
pm-trader benchmark run my_strategy.run

For backtesting with historical data:

pythonCopy code
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:

bashCopy code
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:

bashCopy code
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:

bashCopy code
npx clawhub install polymarket-paper-trader

GitHub bot

Comment /oc or /opencode on an issue or PR. New issues get a triage reply; non-draft PRs get a shallow review. The public bot uses FreeInference (qwen3.6-35b) via a repo Actions secret — no wallet, no real trades. Sessions are not shared.

Tests

bashCopy code
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

Also in this repository

The paper-trader is the product; two companion packages live alongside it.

bashCopy code
pip install -e "benchmark[dev]"
cd benchmark && polymarket-benchmark run --model opencode/jev-1.13-free --market-set mini

See CONTRIBUTING.md for how to work on each package.

License

MIT