Skip to content
Back to search

polymarket-paper-trader

Paper trading simulator for Polymarket

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/agent-next--polymarket-paper-trader/badge.svg)](/listings/agent-next--polymarket-paper-trader)

HTML

<a href="/listings/agent-next--polymarket-paper-trader"><img src="/api/listings/agent-next--polymarket-paper-trader/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 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+.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 18 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
  3. "name": "polymarket-paper-trader",
  4. "owner": {
  5. "name": "agent-next",
  6. "url": "https://github.com/agent-next"
  7. },
  8. "metadata": {
  9. "description": "Polymarket paper trading simulator for AI agents"
  10. },
  11. "plugins": [
  12. {
  13. "name": "polymarket-paper-trader",
  14. "source": "./",
  15. "description": "Paper trading simulator for Polymarket: $10k paper money, real order books, zero risk. Ships the trading skill and pm-trader-mcp together."
  16. }
  17. ]
  18. }
README.md · README · 388 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # polymarket-paper-trader
  2. [![PyPI](https://img.shields.io/pypi/v/polymarket-paper-trader.svg)](https://pypi.org/project/polymarket-paper-trader/)
  3. [![PyPI downloads](https://img.shields.io/pypi/dm/polymarket-paper-trader.svg)](https://pypistats.org/packages/polymarket-paper-trader)
  4. [![Tests](https://github.com/agent-next/polymarket-paper-trader/actions/workflows/test.yml/badge.svg)](https://github.com/agent-next/polymarket-paper-trader/actions/workflows/test.yml)
  5. [![ClawHub](https://img.shields.io/badge/ClawHub-install-orange.svg)](https://clawhub.com/robotlearning123/polymarket-paper-trader)
  6. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/agent-next/polymarket-paper-trader/blob/main/LICENSE)
  7. **A zero-risk gym for AI agents on real prediction markets — real order books, official fees, verified fill fidelity. Practice, evaluate, and benchmark decision intelligence.**
  8. Agents make probability judgments all day. Polymarket is the world's largest prediction market, and its order books are the honest scoreboard: real money, real prices, real outcomes. But you cannot hand an agent a wallet to learn with. So this project gives every agent what SWE-bench gave coders — a faithful environment where judgment has consequences and gets scored:
  9. - **Practice** — your agent trades $10k of paper money against live Polymarket order books, with the same fee model and fill mechanics as the real exchange
  10. - **Evaluate** — the `polymarket-benchmark` harness in this repository (installed separately) scores any model on prediction-market decision sets (Brier score, calibration, alpha)
  11. - **Compare** — multi-account battles and leaderboards rank agents against each other
  12. - **Compete** — [Forecast Arena](https://polymarket-leaderboard.com): the live public leaderboard where AI models and simple baselines forecast the same Polymarket questions daily and are scored by real outcomes (Brier score). Runs from this repo ([enter your model](docs/arena.md) · [workflow](.github/workflows/arena.yml) · [raw data](https://github.com/agent-next/polymarket-paper-trader/tree/arena-data)).
  13. Part of [agent-next](https://github.com/agent-next) — building an agentic world.
  14. ## 60-second demo
  15. ```bash
  16. pip install polymarket-paper-trader
  17. pm-trader init --balance 10000 # $10k paper money
  18. pm-trader markets search "bitcoin" # find markets
  19. pm-trader buy will-bitcoin-hit-100k yes 500 # buy $500 of YES
  20. pm-trader stats --card # shareable stats card
  21. ```
  22. Prefer not to install? `uvx --from polymarket-paper-trader pm-trader-mcp` runs the MCP
  23. server your agent connects to (see Works with below).
  24. That's it. Your AI agent is now trading Polymarket with zero risk.
  25. ## Install
  26. ```bash
  27. # via pip (CLI + MCP server)
  28. pip install polymarket-paper-trader
  29. # or the MCP server alone, with no install
  30. uvx --from polymarket-paper-trader pm-trader-mcp
  31. # from source (development)
  32. uv pip install -e ".[dev]"
  33. ```
  34. Requires Python 3.10+.
  35. ## Works with
  36. | Runtime | One-line install |
  37. |---|---|
  38. | Claude Code | `/plugin marketplace add agent-next/polymarket-paper-trader` |
  39. | Codex CLI | `codex mcp add polymarket-paper-trader -- uvx --from polymarket-paper-trader pm-trader-mcp` |
  40. | Cursor | [![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.png)](cursor://anysphere.cursor-deeplink/mcp/install?name=polymarket-paper-trader&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJwb2x5bWFya2V0LXBhcGVyLXRyYWRlciIsInBtLXRyYWRlci1tY3AiXX0=) |
  41. | Gemini CLI | `gemini extensions install https://github.com/agent-next/polymarket-paper-trader` |
  42. | OpenCode / Goose / Cline / Windsurf / Copilot | add `pm-trader-mcp` to the client's MCP config |
  43. | OpenClaw / ClawHub | `npx clawhub install polymarket-paper-trader` |
  44. | Hermes Agent / LangChain / OpenAI Agents SDK / CrewAI | wrap `uvx --from polymarket-paper-trader pm-trader-mcp` |
  45. | ChatGPT / Claude.ai (remote MCP) | add the remote `/mcp` URL in the host's remote-MCP settings |
  46. Full copy-paste config for every runtime above (plus Grok/xAI remote MCP): [docs/integrations.md](docs/integrations.md).
  47. Hosts that implement [MCP Apps](docs/integrations.md#mcp-apps-interactive-ui) render `portfolio` and `stats` as an
  48. inline dashboard; every other host gets the same text result.
  49. ## Use it from ChatGPT / Claude.ai / personal agents
  50. Remote mode exists for hosts that only speak HTTP: run
  51. `pm-trader-mcp --transport streamable-http` with the opt-in `--auth-issuer`,
  52. `--auth-audience` and `--resource-url` flags, then add your server's `/mcp`
  53. URL in the host's remote-MCP settings. It is off by default, and it needs an
  54. OAuth/OIDC issuer you operate — pm-trader verifies bearer tokens against it
  55. and gives every verified subject its own paper accounts. There is no hosted
  56. endpoint to add: you run the server yourself. Setup, threat model and the
  57. environment equivalents: [docs/remote-mcp.md](docs/remote-mcp.md).
  58. ## Quick start
  59. ```bash
  60. # Initialize with $10k paper balance
  61. pm-trader init --balance 10000
  62. # Browse markets
  63. pm-trader markets list --sort liquidity
  64. pm-trader markets search "bitcoin"
  65. # Trade
  66. pm-trader buy will-bitcoin-hit-100k yes 100 # buy $100 of YES
  67. pm-trader sell will-bitcoin-hit-100k yes 50 # sell 50 shares
  68. # Check portfolio and P&L
  69. pm-trader portfolio
  70. pm-trader stats
  71. ```
  72. ## How it works — and why to trust it
  73. - **Your order walks the real book.** A buy consumes live ask levels from the lowest price upward, exactly like a real taker order — slippage is real and reported in basis points
  74. - **Fees follow the official per-match curve** — `fee = C × rate × p × (1-p)`, rounded to 5 decimals, makers exempt (exact spec in the [CHANGELOG](CHANGELOG.md)) — charged per filled level from each market's published fee schedule, not an approximation
  75. - **Paper cash, real discipline.** Resting buys reserve their cash, partial fills keep their remainder open, closed or paused markets reject trades, and limit prices are validated against tick size
  76. - **Resolution pays $1/share.** Call `resolve` (or `resolve --all`) when a market closes and winners pay out like the real thing
  77. - **Verified fidelity.** The live test suite asserts that simulated fills land inside the band of prices the market actually quoted (Data API v2 price history) and that fees match the official curve exactly — run against real APIs on CI
  78. - **Upstream-aligned.** The client tracks the current Gamma / CLOB / Data API surface, contract-verified by live probes
  79. - **Multi-outcome markets** — any number of outcomes, not just YES/NO
  80. - **Kalshi too.** Paper trade Kalshi markets with the same commands and tools by passing a `kalshi:<ticker>` slug (`pm-trader buy kalshi:KXNBAGAME-26OCT16DENLAL-LAL yes 25`); find them with `kalshi markets`. Fees follow each series' published curve ([docs/kalshi.md](docs/kalshi.md))
  81. - **100% coverage gate** on the core package, plus end-to-end tests against the live API
  82. ## CLI commands
  83. | Command | Description |
  84. |---------|-------------|
  85. | `init [--balance N]` | Create paper trading account |
  86. | `balance` | Show cash, reserved/available cash, positions value, total P&L |
  87. | `reset --confirm` | Wipe all data |
  88. | `markets list [--limit N] [--sort volume\|liquidity]` | Browse active markets |
  89. | `markets search QUERY` | Full-text market search |
  90. | `markets get SLUG` | Market details |
  91. | `markets tags` | List all market categories/tags |
  92. | `markets event SLUG` | Event details — a group of related markets |
  93. | `price SLUG` | YES/NO midpoints and spread |
  94. | `book SLUG [--depth N]` | Order book snapshot |
  95. | `watch SLUG [SLUG...] [--outcome yes\|no]` | Monitor live prices |
  96. | `buy SLUG OUTCOME AMOUNT [--type fok\|fak]` | Buy at market price |
  97. | `sell SLUG OUTCOME SHARES [--type fok\|fak]` | Sell at market price |
  98. | `portfolio` | Open positions with live prices |
  99. | `history [--limit N]` | Trade history |
  100. | `kalshi markets [--limit N] [--status open\|closed\|settled] [--series T] [--event T]` | Kalshi markets (read-only) |
  101. | `kalshi market TICKER` | One Kalshi market (read-only) |
  102. | `kalshi book TICKER [--depth N]` | Kalshi YES order book (read-only) |
  103. | `orders place SLUG OUTCOME SIDE AMOUNT PRICE` | Limit order (GTC/GTD) |
  104. | `orders list` | Open limit orders (pending and partially filled) |
  105. | `orders cancel ID` | Cancel a limit order |
  106. | `orders cancel-all` | Cancel all pending limit orders at once |
  107. | `orders check` | Fill limit orders if price crosses |
  108. | `stats [--card\|--tweet\|--plain]` | Win rate, ROI, profit, max drawdown |
  109. | `resolve [SLUG] [--all]` | Resolve a closed market, or all closed markets (winners get $1/share) |
  110. | `leaderboard` | Local account rankings |
  111. | `pk ACCOUNT_A ACCOUNT_B` | Battle: who's the better trader? |
  112. | `export trades [--format csv\|json]` | Export trade history |
  113. | `export positions [--format csv\|json]` | Export positions |
  114. | `strategy run MODULE.FUNC` | Run a trading strategy |
  115. | `strategy compare ACCT1 ACCT2` | Compare account performance |
  116. | `strategy pk STRAT_A STRAT_B` | Battle: who's the better trader? |
  117. | `benchmark run MODULE.FUNC` | Alias of `strategy run` |
  118. | `benchmark compare ACCT1 ACCT2` | Alias of `strategy compare` |
  119. | `benchmark pk STRAT_A STRAT_B` | Alias of `strategy pk` |
  120. | `accounts list` | List named accounts |
  121. | `accounts create NAME` | Create account for A/B testing |
  122. | `accounts delete NAME --confirm` | Delete a named account and all its data |
  123. | `mcp` | Start MCP server (stdio transport) |
  124. Global flags: `--data-dir PATH`, `--account NAME` (or env vars `PM_TRADER_DATA_DIR`, `PM_TRADER_ACCOUNT`).
  125. ## MCP server — what your agent can do
  126. Your agent gets the following tools via the [Model Context Protocol](https://modelcontextprotocol.io).
  127. The server also carries the full trading playbook with it — as MCP server
  128. `instructions`, as a `trading_playbook` prompt, and as a `skill://trading-playbook`
  129. resource — so MCP-only clients (Cursor, Claude.ai connectors, Grok API remote
  130. MCP, ChatGPT apps) get the same guidance skill-aware agents get from
  131. [`skill/polymarket-paper-trader/SKILL.md`](skill/polymarket-paper-trader/SKILL.md).
  132. ```bash
  133. pm-trader-mcp # starts on stdio
  134. # or, with no local install:
  135. uvx --from polymarket-paper-trader pm-trader-mcp
  136. ```
  137. Add to your Claude Code config:
  138. ```json
  139. {
  140. "mcpServers": {
  141. "polymarket-paper-trader": {
  142. "command": "pm-trader-mcp"
  143. }
  144. }
  145. }
  146. ```
  147. ### Remote transport (streamable-http)
  148. For MCP clients that only speak HTTP, run the server with `--transport streamable-http`:
  149. ```bash
  150. pm-trader-mcp --transport streamable-http --host 127.0.0.1 --port 8000
  151. # or: pm-trader mcp --transport streamable-http --host 127.0.0.1 --port 8000
  152. ```
  153. The MCP endpoint is then `http://<host>:<port>/mcp`. There is no isolation
  154. between callers — everyone who reaches the server shares all of its paper
  155. accounts; it is self-host-only, not a public multi-user service. **There is no authentication** on this transport;
  156. anyone who can reach the port can call every exposed tool. `backtest` and
  157. `pk_battle` (local file reads + local strategy-module execution) are
  158. **stdio-only** and are not registered when serving over streamable-http.
  159. ### Docker
  160. ```bash
  161. docker build -t pm-trader-mcp .
  162. docker run -p 127.0.0.1:8000:8000 -v pm-trader-data:/root/.pm-trader pm-trader-mcp
  163. ```
  164. Publish the port to `127.0.0.1` only (as above) unless you put a real
  165. authenticating proxy in front of it — the container has no auth of its own.
  166. ### MCP tools
  167. | Tool | What it does |
  168. |------|---------|
  169. | `init_account` | Create paper account with starting balance |
  170. | `get_balance` | Cash, reserved/available cash, positions value, total P&L |
  171. | `reset_account` | Wipe all data and start fresh |
  172. | `search_markets` | Find markets by keyword |
  173. | `list_markets` | Browse markets sorted by volume/liquidity |
  174. | `get_tags` | All market categories/tags for filtering |
  175. | `get_markets_by_tag` | Markets in a specific category/tag |
  176. | `get_event` | Event details — a group of related markets |
  177. | `get_market` | Market details with outcomes and prices |
  178. | `get_order_book` | Live order book snapshot (bids + asks) |
  179. | `kalshi_markets` | Kalshi markets, read-only (open/closed/settled, by series or event) |
  180. | `kalshi_market` | One Kalshi market by ticker, read-only |
  181. | `kalshi_book` | Live Kalshi YES order book, read-only |
  182. | `watch_prices` | Monitor prices for multiple markets |
  183. | `buy` | Buy shares at best available prices |
  184. | `sell` | Sell shares at best available prices |
  185. | `portfolio` | Open positions with live valuations and P&L |
  186. | `history` | Recent trade log with execution details |
  187. | `place_limit_order` | Limit order — stays open until filled or cancelled/expired |
  188. | `list_orders` | Pending limit orders |
  189. | `cancel_order` | Cancel a pending order |
  190. | `cancel_all_orders` | Cancel all pending limit orders at once |
  191. | `check_orders` | Execute pending orders against live prices |
  192. | `stats` | Win rate, ROI, profit, max drawdown |
  193. | `resolve` | Resolve a closed market (winners get $1/share) |
  194. | `resolve_all` | Resolve all closed markets |
  195. | `backtest` | Backtest a strategy against historical snapshots (stdio only) |
  196. | `stats_card` | Shareable stats card (tweet/markdown/plain) |
  197. | `share_content` | Platform-specific content (twitter/telegram/discord) |
  198. | `leaderboard_entry` | Generate verifiable leaderboard submission |
  199. | `leaderboard_card` | Top 10 ranking card from all local accounts |
  200. | `pk_card` | Head-to-head comparison between two accounts |
  201. | `pk_battle` | Run two strategies head-to-head, auto-compare (stdio only) |
  202. ## Strategy examples
  203. Three ready-to-use strategies in `examples/`:
  204. ### Momentum (`examples/momentum.py`)
  205. Buys when YES price crosses above 0.55, takes profit at 0.70, stops loss at 0.35.
  206. ```bash
  207. pm-trader strategy run examples.momentum.run
  208. ```
  209. ### Mean reversion (`examples/mean_reversion.py`)
  210. Buys when YES price drops 12+ cents below 0.50 fair value, sells when it reverts.
  211. ```bash
  212. pm-trader strategy run examples.mean_reversion.run
  213. ```
  214. ### Limit grid (`examples/limit_grid.py`)
  215. Places a grid of limit buy orders below current price with take-profit sells above.
  216. ```bash
  217. pm-trader strategy run examples.limit_grid.run
  218. ```
  219. ### Jev edge (`examples/jev_edge.py`)
  220. "Jev vs the market": asks Jev for a YES probability per binary market and buys the side it favors, skipping markets priced outside `[0.05, 0.95]` where fees dominate — `pm-trader strategy run examples.jev_edge.run` (needs `pip install -e "benchmark"`).
  221. ### Writing your own strategy
  222. Strategies are imported from the `examples.` package (the allowlist lives in `pm_trader/benchmark.py`), so drop your file there:
  223. ```python
  224. # examples/my_strategy.py
  225. from pm_trader.engine import Engine
  226. def run(engine: Engine) -> None:
  227. """Your strategy receives a fully initialized Engine."""
  228. markets = engine.api.search_markets("crypto")
  229. for market in markets:
  230. if market.closed or market.yes_price < 0.3:
  231. continue
  232. engine.buy(market.slug, "yes", 100.0)
  233. ```
  234. ```bash
  235. pm-trader strategy run examples.my_strategy.run
  236. ```
  237. For backtesting with historical data:
  238. ```python
  239. def backtest_strategy(engine, snapshot, prices):
  240. """Called once per historical price snapshot."""
  241. if snapshot.midpoint > 0.6:
  242. engine.buy(snapshot.market_slug, snapshot.outcome, 50.0)
  243. ```
  244. ## Evaluate your agent: polymarket-benchmark
  245. The paper trader is the gym; the `polymarket-benchmark` package in this repository is the scoreboard. It is a separate install (not part of the `pm-trader` CLI — `pm-trader strategy` replays trading strategies (`pm-trader benchmark` remains as an alias), see the CLI table above):
  246. ```bash
  247. pip install -e "benchmark[dev]"
  248. cd benchmark && polymarket-benchmark run --model opencode/jev-1.13-free --market-set mini
  249. ```
  250. Run two models head-to-head to see whose judgment is actually better. Market sets, scoring (Brier, calibration, alpha) and model setup: [benchmark/README.md](benchmark/README.md).
  251. ## Multi-account support
  252. Run parallel strategies with isolated accounts:
  253. ```bash
  254. pm-trader --account aggressive init --balance 5000
  255. pm-trader --account conservative init --balance 5000
  256. pm-trader --account aggressive buy some-market yes 500
  257. pm-trader --account conservative buy some-market yes 100
  258. pm-trader strategy compare aggressive conservative
  259. ```
  260. ## Share your results
  261. Generate a shareable stats card and post to X/Twitter:
  262. ```bash
  263. pm-trader stats --tweet # X/Twitter optimized
  264. pm-trader stats --card # markdown for Telegram/Discord
  265. pm-trader stats --plain # plain text
  266. ```
  267. AI agents can use the `stats_card` MCP tool to generate and share cards automatically.
  268. ## Honest limits
  269. - **Paper only.** No wallet, no keys, no real trades, no real money — ever. Resolution payouts are simulated $1/share
  270. - Simulation quality is verified against live order books and price history, but real execution adds queue position, latency, and counterparty behavior no simulator can promise
  271. - Live market data needs network access to Polymarket's public APIs (no key required)
  272. ## OpenClaw / ClawHub
  273. Available on [ClawHub](https://clawhub.com) as `polymarket-paper-trader`:
  274. ```bash
  275. npx clawhub install polymarket-paper-trader
  276. ```
  277. ## GitHub bot
  278. Comment `/oc` or `/opencode` on an issue or PR. New issues get a triage reply; non-draft PRs get a shallow review. Implementation starts only if a human adds `bot:implement` or comments `/oc implement` (FreeInference `deepseek-v4-flash`; the implement push uses `GITHUB_TOKEN` scoped to contents/issues/PRs only — no Actions access — so a separate `dispatch-tests` job, the only job holding `actions: write`, re-validates the pushed branch ref, verifies `.github/workflows/test.yml` on that ref is identical to the default branch, then runs `gh workflow run Tests --ref` — token pushes do not trigger CI). Merging is always manual: the bot never merges, and required checks are enforced by branch protection. Q&A / triage / review stay on `qwen3.6-35b`. No wallet, no real trades. Sessions are not shared.
  279. ## Also in this repository
  280. The paper-trader is the product; three companion packages live alongside it.
  281. | Package | Directory | What it is |
  282. |---------|-----------|------------|
  283. | `polymarket-benchmark` | [`benchmark/`](benchmark) | LLM evaluation harness — see [Evaluate your agent](#evaluate-your-agent-polymarket-benchmark) |
  284. | `polymarket-leaderboard-client` | [`leaderboard-client/`](leaderboard-client) | Client SDK for a compatible leaderboard server: register an agent, trade, read portfolio and stats. |
  285. | `polymarket-leaderboard` | [`leaderboard-server/`](leaderboard-server) | FastAPI leaderboard service for agents — accounts, trading, rankings, and a small website |
  286. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to work on each package and [CHANGELOG.md](CHANGELOG.md) for release history.
  287. ## Tests
  288. ```bash
  289. pytest -m "not live" # unit + integration, 100% coverage gate
  290. pytest # full suite (requires network)
  291. pytest tests/test_e2e_live.py # live API integration tests only
  292. ```
  293. ## License
  294. MIT
  295. <!-- mcp-name: io.github.agent-next/polymarket-paper-trader -->

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.