polyorderbooks
Summary: This server gives historical Polymarket order book depth and market data over MCP — the L2 ladders that Polymarket itself does not archive — plus search, pricing, and market-quality metrics.
Search recurring market series, related event groups, and individual markets by keyword/date.
Get full market details including outcome token IDs, resolution status, and the winning outcome.
Retrieve historical L2 bid/ask order book depth at 1-second to 1-day resolution, with pagination for large windows.
Get per-outcome-token price history aligned to the same timeline, finer than Polymarket's free 1-minute data.
Get derived market quality metrics: spread, liquidity, and volume over time.
Check your plan, rate limits, quota, and available history window.
Works via an MCP client using npx and a free API key; it does not provide live odds or trade execution.
PolyOrderbooks MCP Server
Historical Polymarket order book depth for Claude, Cursor and any other MCP client — full L2 bid and ask ladders at 1-second 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: polymarket-mcp
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 1-second 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 1-second resolution is 3,600 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 | 1-second |
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 1-second resolution is 3,600 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 target distinct entities (individual markets, recurring series, and event groupings), and the descriptions clarify which search to start with, but an agent could still hesitate between search_series and search_events for some workflows. The get_* tools are clearly separated by data type: order book depth, price series, and derived metrics.
All tool names follow a consistent verb_noun pattern: search_* for discovery and get_* for retrieval. There is no mixed casing, vague verb, or off-pattern name.
With eight tools, the server is well-scoped: discovery tools for each Polymarket entity, one market detail tool, three historical data tools, and one usage-account tool. Each tool fills a distinct role.
The read-only analytics workflow is well covered: find a market, expand to series or events, inspect a market, and then retrieve price, orderbook, or quality time series. A minor gap is the lack of an explicit current-orderbook snapshot endpoint, though historical snapshots and market detail cover most needs.
Maintenance
Related MCP Connectors
Polymarket orderbook history, live books, trades and settlements, plus Hyperliquid perp books.
Order-book depth & history for Polymarket, Kalshi & Limitless. Keyless demo, key for full access.
Live Polymarket odds, order books, fee-inclusive quotes and non-custodial prediction trading.
Fetches live Polymarket prediction market orderbooks, implied Yes/No probabilities, volume, and wh
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceReference data layer for prediction markets: resolution-clarity grades (A/B/C), named resolution sources with provenance, cross-venue linking, and per-contract eligibility screens across Kalshi and Polymarket. Open,read-only, no key required.3MIT
- 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
- AlicenseAqualityCmaintenanceEnables access to historical Polymarket order book depth, with full L2 bid and ask ladders at 1-second resolution and resolved outcomes, for use in MCP clients like Claude and Cursor.818 npmMIT
- AlicenseAqualityBmaintenanceEnables MCP clients to query historical Polymarket order book depth at 1-second resolution, including full L2 bid and ask ladders with resolved outcomes, alongside market search, price history, and liquidity metrics. It also exposes depth data that Polymarket's own API does not archive, letting users analyze what could actually have been traded at a specific past moment.818 npmMIT