# polymarket-paper-trader: an MCP paper trading simulator for AI agents

> A Python CLI and MCP server that gives an agent a $10,000 paper account, fills orders against live Polymarket books, and records slippage and fees. Useful for strategy rehearsal, not for real fills.

**agent-next/polymarket-paper-trader** — Paper trading simulator for Polymarket — built for AI agents. MCP server, live order books, strategy backtesting. Install: npx clawhub install polymarket-paper-trader

- Repository: https://github.com/agent-next/polymarket-paper-trader
- Website: https://clawhub.com/robotlearning123/polymarket-paper-trader
- Stars: 399 · Forks: 59
- Language: Python
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/agent-next-polymarket-paper-trader

## What polymarket-paper-trader actually solves

An agent that can call a buy function is dangerous in a way a human trader is not: it will place the order, log the result, and do it again. polymarket-paper-trader exists to put a wall between that behaviour and real money. The README describes the intended loop plainly: install, the agent receives $10,000 in paper money, trades against real Polymarket order books, and tracks P&L. No private key, no wallet, no on-chain transaction.

The audience is narrow and specific. It is for people wiring an LLM agent into a prediction market workflow, and for researchers who want to compare two strategies on the same price history without funding two accounts. The repository is organised around that: an MCP server entry point, a CLI, a benchmark command, and a skill/ directory for agent hosts. The pyproject classifiers list Development Status 4 - Beta, which matches a project whose latest release is v0.1.8.

The stated design claim is that other tools mock prices or use random numbers while this one simulates the exchange. That claim is checkable in the README's fee formula and in the order book commands, and it is the reason the project is worth a look rather than a shrug.

## How the simulator fills an order

The mechanism the README describes is level-by-level order book execution. An order walks the real Polymarket ask or bid book and consumes liquidity at each price level, the way a marketable order would on the exchange. That is a different model from a single midpoint fill, and it is the source of the project's most useful output: slippage.

Fees use the formula bps/10000 x min(price, 1-price) x shares, which the README states is the same formula Polymarket uses. The min(price, 1-price) term means the fee peaks at a 50 cent contract and falls toward the extremes. Every trade also records how much worse the fill was than the midpoint, in basis points. Those two numbers are what make a paper result comparable to a real one, and they are also what will make a naive strategy look worse here than in a simulator that fills at the midpoint.

Limit orders run as a state machine with GTC (good-til-cancelled) and GTD (good-til-date) lifetimes. Orders do not fill on their own: the CLI exposes orders check, and the MCP server exposes check_orders, both of which execute pending orders if the price has crossed. That is a deliberate design choice. It means the agent controls when the book is consulted, and it also means a pending order can sit unfilled indefinitely if nothing calls check.

State lives locally. The CLI accepts --data-dir PATH and the environment variables PM_TRADER_DATA_DIR and PM_TRADER_ACCOUNT, and the topics list names sqlite, so accounts, positions and trade history are file-backed rather than server-side. Nothing in the README describes a hosted account, which is consistent with a tool that never touches a wallet.

## Installing polymarket-paper-trader and placing a first paper trade

The README gives three install paths. The pip route is the one to use outside an agent host:

```bash
pip install polymarket-paper-trader
```

Python 3.10 or newer is required. ClawHub is the second route, aimed at OpenClaw agents, and it is the command in the project's own 60-second demo:

```bash
npx clawhub install polymarket-paper-trader
```

For development the README uses uv with the dev extra:

```bash
uv pip install -e ".[dev]"
```

Once installed, two console scripts are registered in pyproject.toml: pm-trader, which maps to pm_trader.cli:main, and pm-trader-mcp, which maps to pm_trader.mcp_server:main. Initialise an account and browse markets:

```bash
pm-trader init --balance 10000
pm-trader markets search "bitcoin"
pm-trader markets list --sort liquidity
```

A marketable buy takes a slug, an outcome and a dollar amount. The README's example buys $500 of YES on will-bitcoin-hit-100k:

```bash
pm-trader buy will-bitcoin-hit-100k yes 500
pm-trader portfolio
pm-trader stats --card
```

The expected result is a recorded fill at whatever the book allowed, a position in pm-trader portfolio valued at live prices, and a stats card with win rate, ROI, profit and max drawdown. If the slug does not exist or the book is thin, the fill will reflect that rather than being rejected silently.

To let an agent drive it, the README shows a Claude Code configuration pointing at the stdio server:

```json
{
  "mcpServers": {
    "polymarket-paper-trader": {
      "command": "pm-trader-mcp"
    }
  }
}
```

The MCP surface is broad: search_markets, get_order_book, buy, sell, place_limit_order, check_orders, stats, resolve, backtest and leaderboard_entry among roughly thirty tools. That breadth is convenient for an agent and also the main thing to constrain, since every one of those tools is callable.

## Where the simulation stops being real

The honest limit is in the project's own framing: paper P&L would match real P&L within the spread. Within the spread is doing a lot of work in that sentence. Your simulated order does not move the market, does not compete with other takers for the same level, and does not face the queue position problem that decides whether a resting limit order fills at all. A strategy that looks profitable because it was first in line at a price level may not be first in line on the exchange.

Resolution is manual. The MCP tool list includes resolve and resolve_all, described as resolving a closed market where winners get $1 per share. Nothing in the README describes automatic settlement, so a portfolio's P&L depends on someone or something calling resolve after a market closes. An agent that never calls it will carry stale positions.

Limit order fills depend on check_orders or orders check being invoked. There is no background process in the README. This is a reasonable choice for a test harness and a poor one for anything that needs to react to a price crossing while nobody is looking.

Finally, the market data comes from Polymarket's API over the network. The pytest configuration defines a live marker for tests requiring network access to the Polymarket API, which confirms the dependency. If that API changes shape or rate-limits you, the CLI and the MCP tools degrade with it. Backtesting avoids the live dependency but only to the extent that the historical price snapshots exist for the markets and window you care about.

## Compared with writing your own fill logic

The obvious alternative is a few hundred lines of your own: fetch the Polymarket book, multiply shares by price, subtract a fee, store the result in SQLite. That is genuinely not much code, and it gives you total control over the fill model.

The difference is in what you would have to reproduce. The fee formula bps/10000 x min(price, 1-price) x shares, the level-walking fill, the slippage-in-basis-points record, the GTC and GTD state machine, multi-outcome markets beyond binary YES/NO, and the backtest replay against historical snapshots. Each is small. Together they are the part of a paper trading harness that is easy to get subtly wrong, and a wrong fee model quietly flatters every strategy you test with it.

The second alternative is simply trading a small real amount. That removes the simulation gap entirely, at the cost of real capital and real losses while you are still debugging the agent. For an agent that may place hundreds of orders before you notice a logic error, the paper layer is cheaper than the tuition.

The third is a generic backtesting framework. Those are stronger at portfolio analytics and weaker at this specific venue: they will not know Polymarket's fee curve, its outcome structure, or how to walk its book.

## Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-08-15. The release history is uneven: v0.1.5 and v0.1.6 both landed on 2026-03-01, and v0.1.8 arrived on 2026-08-14. That is a burst pattern rather than a steady cadence, and it is worth knowing before you build a dependency on a specific behaviour.

The dependency list is short: click, httpx, and mcp constrained to >=1.28,<2. The upper bound on mcp is the one to watch. It means a future major version of the MCP SDK will require a project release before your agent host can move to it, and there is nothing in the README about a migration path.

The licence is MIT, declared both in pyproject.toml and in the repository's LICENSE file. MIT is permissive: you can use, modify and redistribute the code, including commercially, provided the copyright notice and permission notice are retained. That is a description of the licence text, not legal advice, and if you are embedding this in a product you should read the LICENSE file yourself.

The upgrade cost is low in the ordinary case, because state is local and file-backed under --data-dir. The command that carries real risk is reset --confirm, which the README describes as wiping all data, and the MCP equivalent reset_account. There is no documented export-and-restore path for an account beyond export trades and export positions, which cover history and holdings but not pending limit orders.

## Conclusion

Adopt it if you are building an agent that needs to rehearse order placement, limit order lifetimes, or portfolio accounting against real Polymarket quotes before any capital is at risk, and if you accept that fills are simulated. Do not adopt it if you need a real trading client, a hosted demo account, or a service that runs without a local Python process. Verify first that your Python is 3.10 or newer, that your agent host can launch pm-trader-mcp over stdio, and that the market slugs you intend to trade still appear in pm-trader markets search.

## FAQ

### Does Polymarket allow paper trading?

Polymarket itself is not described in the README as offering paper trading. polymarket-paper-trader provides the paper layer locally: it reads live Polymarket order books and simulates fills without placing anything on the exchange.

### Can you actually make money from paper trading?

The paper account starts at $10,000 and the stats command reports ROI, win rate, profit and max drawdown, so it measures strategy behaviour rather than producing withdrawable money. The README's own claim is that paper P&L would match real P&L within the spread, which is a statement about fill accuracy, not about profitability.

### How do I install polymarket-paper-trader?

Install with pip install polymarket-paper-trader, or with npx clawhub install polymarket-paper-trader for OpenClaw agents. Python 3.10 or newer is required, and the install registers the pm-trader and pm-trader-mcp commands.

### Does polymarket-paper-trader work as an MCP server for AI agents?

Yes. Running pm-trader-mcp starts an MCP server on stdio, and the README shows adding it to a Claude Code config under mcpServers with the command pm-trader-mcp. It exposes tools such as search_markets, buy, sell, get_order_book, place_limit_order and check_orders.

### Where does polymarket-paper-trader store its accounts and trade history?

State is local and file-backed. The CLI accepts a --data-dir PATH global flag and the PM_TRADER_DATA_DIR environment variable, and the repository topics include sqlite. pm-trader reset --confirm wipes all of it.

## Sources

- [agent-next/polymarket-paper-trader on GitHub](https://github.com/agent-next/polymarket-paper-trader)
- [License: MIT](https://github.com/agent-next/polymarket-paper-trader/blob/main/LICENSE)
- [Project website](https://clawhub.com/robotlearning123/polymarket-paper-trader)
- [README](https://github.com/agent-next/polymarket-paper-trader/blob/main/README.md)
- [Releases](https://github.com/agent-next/polymarket-paper-trader/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/agent-next-polymarket-paper-trader