polymarket-paper-trader: an MCP order book simulator for agents that trade prediction markets

The gap between a price feed and a fill

Most agent trading demos stop at reading a number. An agent polls a price, decides the number looks favorable, and writes a line to a log. Nothing in that loop tells you whether the order would have filled, at what average price, or how much of the size would have been left sitting unfilled. polymarket-paper-trader exists to close that gap for Polymarket specifically. The README frames the target plainly: the agent gets a paper balance, trades against live order books, and tracks P&L, all without capital at risk. The audience is narrow and identifiable. It is people building autonomous agents that already have a decision process and need a place to execute it, plus anyone who wants to backtest a Polymarket strategy without replaying it against a random number generator. The project is MIT licensed, written in Python, and requires Python 3.10 or later.

Level-by-level fills and the fee formula the README publishes

The mechanism the README describes is an order book walk. A buy order does not get a single midpoint price. It consumes liquidity at each ask level in turn, so a $500 order can fill across several prices and produce an average that is worse than the best quote. The documentation states that every trade records the slippage against the midpoint in basis points. That is the part that makes the simulator useful rather than decorative: slippage is stored per trade, not estimated after the fact. The fee model is given as bps/10000 x min(price, 1-price) x shares, which the README says is the same formula Polymarket uses. The min(price, 1-price) term is worth pausing on. It means fees shrink as a contract approaches either extreme, so a YES contract at 0.95 and a NO contract at 0.05 are treated symmetrically. Any strategy that concentrates on long-shot or near-certain outcomes will see its cost structure change with price in a way a flat per-share fee would not produce. Beyond market orders, the project implements a limit order state machine with GTC and GTD variants, and the README notes support for multi-outcome markets rather than only binary YES/NO. Order state lives in SQLite under the data directory, which is what makes pm-trader orders list, cancel, and check meaningful across separate CLI invocations.

Running it: init, buy, and the MCP stdio server

The README's 60-second demo is four commands. npx clawhub install polymarket-paper-trader installs through ClawHub, which the README describes as the path for OpenClaw agents. pip install polymarket-paper-trader is the plain Python route, and uv pip install -e ".[dev]" is the source checkout with development extras. After that, pm-trader init --balance 10000 creates the paper account, pm-trader markets search "bitcoin" finds markets, and pm-trader buy will-bitcoin-hit-100k yes 500 places a market buy of $500 of YES. Portfolio and P&L come from pm-trader portfolio and pm-trader stats, the latter with --card, --tweet, or --plain output modes. Two global flags matter for anything beyond a single-account experiment: --data-dir PATH and --account NAME, with PM_TRADER_DATA_DIR and PM_TRADER_ACCOUNT as environment equivalents. For agent integration the project ships an MCP server. pm-trader-mcp starts on stdio, and the README gives a Claude Code config block with the command set to pm-trader-mcp. The MCP surface is wider than the CLI in places: it includes get_tags, get_markets_by_tag, and get_event for browsing structure, plus resolve and resolve_all, which the README says pay winners $1 per share. That resolve step is manual. Nothing in the supplied material indicates that settlement happens automatically when a market closes, so a paper portfolio can hold positions in resolved markets until someone calls the tool.

Backtesting replays snapshots, not a continuous tape

The backtest tool and the benchmark commands are the parts where the README is thinnest. pm-trader benchmark run MODULE.FUNC takes a Python module path and function, and the MCP backtest tool is described as replaying a strategy against historical snapshots. Snapshots are not a tape. A snapshot-based replay cannot tell you what happened between two captures, so a strategy whose edge depends on reacting to intrabar movement, or on placing a limit order that would have been touched and then missed, will look different in replay than it would have live. The README does not state the snapshot interval, how far back the history goes, or whether snapshots are captured by the tool itself or fetched from elsewhere. Treat the backtest output as a sanity check on position sizing and order sequencing, not as an estimate of realized edge. The same caution applies to the limit order flow. The README lists pm-trader orders check as the command that fills pending orders if price crosses, which implies fills are evaluated when you ask, not continuously in the background. A GTC order that would have filled at 14:03 and reversed by 14:04 may be recorded as filled at whatever price the book shows when check runs. That is a real difference from a live exchange, and it is not something the README flags.

Where a paper simulator on live books is the wrong instrument

The project's own framing is that paper P&L would match real P&L within the spread. That claim is about execution mechanics, and it is the right claim to make. It is not a claim about market impact. A paper order consumes liquidity in the book without changing it, so a strategy that trades size relative to available depth will look better in simulation than it can be in practice. The README does not describe any impact model. There is also the question of what the simulator does when the book is stale or empty. The supplied material does not say, and that is exactly the kind of edge case that decides whether an agent's order flow is trustworthy. Anyone using this to size a real position should read the fill code before trusting the output. Finally, the README's own promotional line, a quoted claim of +18% ROI in one week, is a marketing flourish rather than a result. A one-week paper return on a prediction market strategy is dominated by which markets happened to move, and the README offers no sample size, period, or strategy behind the number. Ignore it when evaluating the tool.

Compared with writing your own book simulator

The obvious alternative is not another named product. It is the thing most agent builders actually do: write a thin wrapper that fetches a midpoint price, applies a fee constant, and records the trade. That approach is faster to build and easier to reason about, and for a strategy that only ever takes small market orders it is close enough. The difference in approach is where the two diverge. A midpoint wrapper has no concept of depth, so it cannot tell you that your $500 order would have moved the price 40 basis points. It also has no limit order state machine, no GTC or GTD lifecycle, and no per-trade slippage record, which means it cannot answer the question a strategy author usually cares about most: how much of the edge survives execution. polymarket-paper-trader trades that simplicity for book walking, a published fee formula, and a persisted order state in SQLite. The cost is that you inherit its assumptions about when fills are evaluated and how resolution is triggered. If your strategy never places resting orders and never trades size, the wrapper is the better fit. If it does either, the simulator is worth the extra moving parts.

Maintenance, versioning, and what the MIT licence leaves you

The release history in the supplied material is short and unevenly spaced. v0.1.5 and v0.1.6 both landed on 2026-03-01, roughly five months before v0.1.8 on 2026-08-14. The version numbering is still in the 0.1.x range, which is a reasonable signal that interfaces can move. The README documents a CLI surface of roughly thirty commands plus a comparable MCP tool list, and every one of those is a compatibility surface an agent depends on. An upgrade that renames a tool or changes an argument shape will break an agent loop silently rather than loudly, because the agent will simply stop finding the tool it expects. Pin the version in whatever installs it. On licensing, MIT is permissive: it allows commercial use, modification, and redistribution provided the copyright notice and permission notice are retained. That is a statement about the licence text, not legal advice, and it says nothing about whether paper trading a Polymarket strategy is permitted in your jurisdiction or under Polymarket's own terms of service. Those are separate questions the repository does not answer.

Editorial conclusion

Adopt it if you are building an agent that needs to rehearse order placement, limit order lifecycle, and P&L accounting against real Polymarket books before any capital is at risk, and if you are comfortable reading the CLI or MCP tool list to find out what the simulator does not model. Do not adopt it as a settlement or risk engine: the fee formula and the fill walk are documented, but resolution depends on an explicit resolve call, and backtests replay snapshots rather than a continuous tape. Before wiring it into an agent loop, verify three things in your own environment: that pm-trader init --balance writes to the directory named by PM_TRADER_DATA_DIR, that pm-trader orders check behaves the way your strategy assumes when a limit price crosses, and how the resolve and resolve_all tools treat a market that has already closed.

Official sources

1. agent-next/polymarket-paper-trader on GitHub
2. License: MIT
3. Project website
4. README
5. Releases