PolyOrderbooks MCP Server
OfficialClick on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@PolyOrderbooks MCP Server Show how order book depth moved in the last 2 minutes of yesterday's BTC 5-minute markets"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
PolyOrderbooks MCP Server
Historical Polymarket order book depth for Claude, Cursor and any other MCP client — full L2 bid and ask ladders at 250ms resolution, with resolved outcomes attached.
Polymarket's own API serves price history well. It does not archive order
book depth at any granularity — /book returns the current state and nothing
stores it. This server exposes depth that was captured live, which is the part
that cannot be recovered after the fact.
Install
Nothing to install. Add it to your MCP client config and it runs via npx.
Claude Desktop — claude_desktop_config.json:
{
"mcpServers": {
"polyorderbooks": {
"command": "npx",
"args": ["-y", "@polyorderbooks/mcp-server"],
"env": { "POLYORDERBOOKS_API_KEY": "pob_..." }
}
}
}Cursor — .cursor/mcp.json, same shape.
Restart the client after editing the config; MCP servers are started at launch.
Related MCP server: EdgeDepth Research MCP Server
Getting an API key
Sign up at polyorderbooks.com/signup. No card is required.
Open the dashboard and create a key. It looks like
pob_followed by a long random string.Put it in the
envblock of your MCP client config, as above.
The free Starter plan queries at 250ms resolution — the same as the paid plans. What the paid plans add is a longer history window and a higher request allowance, not finer data. Starter is enough to answer a real question before you decide whether to pay for anything.
Call the get_usage tool at any time to see the plan, limits and remaining
allowance on the key you configured.
Environment variables
Variable | Required | Purpose |
| yes | Your API key. The server exits at startup if this is missing, rather than failing later on the first tool call. |
| no | Overrides the API base URL. Defaults to |
Set these in the MCP client config, not in your shell. A client launches the
server as a subprocess and does not pass your interactive shell environment to
it, so a key exported in .zshrc will not be visible to the server.
Tools
Tool | What it does |
| Recurring families — |
| Groups of markets that resolve together. |
| Individual markets by keyword or date range. |
| One market in full, including outcome tokens and the winner. |
| L2 ladders over time. The thing Polymarket does not archive. |
| Price series per outcome token. |
| Spread, liquidity and volume as a time series. |
| Plan, rate limits and quota. |
The catalogue is series → events → markets. Ask for a kind of market with
search_series, a set that resolves together with search_events, and a
specific one with search_markets.
Things worth knowing before you interpret the data
Books go one-sided as markets resolve. In the final minute of a 5-minute market, 76% of snapshots have an empty bid or ask side — nobody offers the losing outcome. This is real market behaviour, not missing data, and it breaks analysis that assumes two-sided books.
Contract length changes everything. A 4-hour contract is one-sided 0.5% of the time; a 5-minute contract, 17%. Conclusions from one do not transfer to the other.
Responses get large quickly. An hour at 250ms resolution is 14,400 buckets
per token, and a market has two. Keep windows narrow or resolution coarse, and
page with the returned next_cursor.
Example prompts
Find BTC 5-minute markets that resolved yesterday and show me how the order book depth changed in the final two minutes before settlement.
For this market, what would a 100-share buy have cost against the actual ladder five seconds before close, versus the midpoint at that moment?
Compare spread and liquidity across 5-minute, 15-minute and 4-hour BTC contracts over the last day.
The second one is the point of L2 data. A price series tells you where the market was; only the ladder tells you what you could have traded at.
How this differs from other Polymarket MCP servers
Several good ones exist — kukapay/polymarket-predictions-mcp, demwick/polymarket-agent-mcp, PaulieB14/graph-polymarket-mcp. They wrap Polymarket's own Gamma and CLOB APIs and do it well.
Those | This one | |
Live odds and current book | yes | no |
Placing trades | some | no |
Market metadata and resolution | yes | yes |
Price history | 1-minute, from Polymarket | 250ms |
Historical order book depth | not available | yes |
The difference is structural rather than a matter of effort. Polymarket's /book
endpoint returns the present state and nothing archives it, so no server built on
that API can serve yesterday's ladders. This one reads an archive that was
captured live.
If you want to trade, or want live odds, use one of theirs — they cover that better. Use this when the question is about what the book looked like at a specific past moment.
Troubleshooting
"POLYORDERBOOKS_API_KEY is not set" — the key is missing. It goes in the env
block of the client config, not your shell. See
Environment variables.
Authentication failed — the key reached the server but the API rejected it.
Keys start with pob_; check for a trailing newline or a stray quote if you
pasted from a terminal. If it looks right, call get_usage to confirm the key is
active.
Responses truncated or slow — an hour at 250ms resolution is 14,400 buckets
per token, and a market has two. Narrow the window, or use resolution: "1m" and
page with next_cursor.
Empty ladders — expected near settlement. See the note above on one-sided books.
Open data
897,192 snapshots across 805 resolved markets and three contract lengths are published under CC BY 4.0 with a DOI, no signup:
doi.org/10.5281/zenodo.22084114
Useful for checking the properties above yourself before relying on the API.
Development
npm install
npm run build
POLYORDERBOOKS_API_KEY=pob_... npm run devThe server speaks stdio. To exercise it without an MCP client, send JSON-RPC on
stdin — initialize, then tools/list, then tools/call.
Links
polyorderbooks.com — the API
docs.polyorderbooks.com — reference
Python client —
pip install polyorderbooksFree BTC sample — one market, no signup
Licence
MIT. Not affiliated with, endorsed by, or connected to Polymarket.
Available Tools
8 toolsget_marketGet one marketA
Full detail for a single market by slug or id, including its outcome tokens, resolution status and winning outcome. Use this to get token ids before calling the token-level tools.
Inputs: id_or_slug (required).
get_market_metricsSpread and liquidity over timeA
Derived market quality metrics — spread, liquidity and volume — as a time series. Cheaper than pulling full order books when the question is about market quality rather than specific price levels. Note that spread is only meaningful while both sides of the book are populated, which stops being true near settlement.
Inputs: end_ts (required), start_ts (required), id_or_slug (required), limit, +2 more.
get_order_book_historyHistorical order book depthA
Full L2 bid and ask ladders over time for a market — every price level and the size resting at each. This is data Polymarket does not archive: its /book endpoint returns only the current state, so depth exists only where it was captured live.
One thing to expect when reading the results: binary markets go one-sided as they resolve. In the final minute of a 5-minute market most snapshots have an empty bid or ask side, because nobody offers the losing outcome. That is real market behaviour rather than missing data, so guard before indexing the first level of a ladder.
Responses are large. Keep the window narrow or the resolution coarse: a one-hour window at 1s is 3,600 buckets per token, and a market has two tokens.
Inputs: end_ts (required), start_ts (required), id_or_slug (required), limit, +2 more.
get_price_historyHistorical pricesA
Price series per outcome token over time. Prices are probabilities in [0, 1].
Polymarket serves its own price history down to 1-minute buckets and that is free — use this tool when you need finer than a minute, or when you want prices aligned to the same timeline as order book depth. For 1-minute or coarser history alone, Polymarket's public API is equivalent.
Inputs: end_ts (required), start_ts (required), id_or_slug (required), limit, +2 more.
get_usagePlan and quotaA
Current plan, rate limits, history window and requests used. Call this when a request fails with a limit error, or before planning a large extraction, to see what the key is allowed to do.
Inputs: no named parameters.
search_eventsSearch eventsA
An event groups markets that resolve together — "what-price-will-solana-hit-august-17-23-2026" holds every price threshold for that week, and "btc-updown-5m-1787685000" is one 5-minute round. Use this to find the set of related markets to compare, then search_markets to get the markets themselves. Date filters are useful here: events carry an end_date.
Inputs: limit, search, end_date_max, end_date_min.
search_marketsSearch Polymarket marketsA
Find Polymarket markets by keyword. Start here — the other tools need a market slug, and slugs are not guessable. Coverage is Polymarket crypto markets: up/down contracts at 5m, 15m and 4h, price thresholds like "bitcoin-above-80k", and related event markets. Resolved markets are excluded unless include_closed is true, which is usually what you want for historical analysis. For a whole family of markets rather than one, search_series is more reliable than guessing slug patterns here.
Inputs: limit, search, end_date_max, end_date_min, +1 more.
search_seriesSearch recurring market seriesA
A series is a recurring family of markets — "btc-up-or-down-5m" is every BTC 5-minute up/down contract ever created. Use this when the question is about a kind of market rather than a specific one: it is more reliable than guessing at slug patterns with search_markets. Take the series slug, then use search_events to find its individual rounds.
Inputs: limit, search.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
The three search tools (search_markets, search_series, search_events) form a clearly explained hierarchy of market vs. series vs. event, and the three history tools target distinct data (prices, L2 order book depth, derived metrics). Boundaries are mostly clear, though search_markets/search_series and the trio of get_*_history/metrics tools could still be conflated at a glance since they all return time-series data.
All eight names follow a strict snake_case verb_noun pattern with a consistent get_/search_ prefix split. The pattern is predictable and readable throughout.
Eight tools is well within the ideal range and each earns its place: a search hierarchy, per-market detail, three distinct history/metric tools, and a usage check. Nothing feels redundant or padded.
The surface covers the full read path for a market-data server: discovery (markets/series/events), market detail with token ids, price history, order book depth, quality metrics, and account limits. Read-only is appropriate for this analytics domain, so no create/update/delete gaps are meaningful.
Maintenance
Related MCP Connectors
Historical tick, order book and settlement data for Polymarket and Predict.fun crypto up/down markets, plus smart-money lists and backtest quotes, over a read-only MCP server.
Order-book depth & history for Polymarket, Kalshi & Limitless. Keyless demo, key for full access.
Polymarket orderbook history, live books, trades and settlements, plus Hyperliquid perp books.
Read-only Polymarket search, market details, order books, price history, and market cards.
Related MCP Servers
- AlicenseAqualityCmaintenanceA read-only MCP server exposing Polymarket's public prediction-market data. Search markets, read live odds and order books, pull historical probability time-series, and inspect public wallet positions.1446 PyPIMIT
- AlicenseAqualityBmaintenanceA read-only MCP server for EdgeDepth's market microstructure search engine, enabling users to query recorded crypto and TradFi perpetuals for market conditions, outcomes, and reproducibility-keyed evidence directly from MCP clients.1098 npm3MIT
- AlicenseAqualityBmaintenanceHistorical Polymarket order book depth — full L2 bid/ask ladders at 1-second resolution on resolved markets, plus prices, spread and liquidity. Polymarket archives no order book history, so this serves depth captured live.818 npmMIT
- AlicenseAqualityCmaintenanceProvides read-only access to Polymarket US public market data, including prices, order books, and spread/fee analytics, via MCP tools.16MIT