Skip to main content
Glama
PolyOrderbooks MCP Server

PolyOrderbooks MCP Server

Official

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.

npm

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

  1. Sign up at polyorderbooks.com/signup. No card is required.

  2. Open the dashboard and create a key. It looks like pob_ followed by a long random string.

  3. Put it in the env block 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

POLYORDERBOOKS_API_KEY

yes

Your API key. The server exits at startup if this is missing, rather than failing later on the first tool call.

POLYORDERBOOKS_BASE_URL

no

Overrides the API base URL. Defaults to https://api.polyorderbooks.com. Only needed for a self-hosted or staging deployment.

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

search_series

Recurring families — btc-up-or-down-5m is every BTC 5-minute round.

search_events

Groups of markets that resolve together.

search_markets

Individual markets by keyword or date range.

get_market

One market in full, including outcome tokens and the winner.

get_order_book_history

L2 ladders over time. The thing Polymarket does not archive.

get_price_history

Price series per outcome token.

get_market_metrics

Spread, liquidity and volume as a time series.

get_usage

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 dev

The server speaks stdio. To exercise it without an MCP client, send JSON-RPC on stdin — initialize, then tools/list, then tools/call.


Licence

MIT. Not affiliated with, endorsed by, or connected to Polymarket.

Available Tools

8 tools
get_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

    A4.2/5.0

    Scored across 8 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      A 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.
      14
      46 PyPI
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A 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.
      10
      98 npm
      3
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Historical 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.
      8
      18 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Provides read-only access to Polymarket US public market data, including prices, order books, and spread/fee analytics, via MCP tools.
      16
      MIT