Polymarket Order Book API (2026): How to Get Live Depth

What is the Polymarket order book API?

It is the public CLOB surface that returns the resting buy and sell orders for one Polymarket outcome. A binary market has two outcome tokens, usually YES and NO, and each token has its own book.

The book is more useful than a displayed probability when you need to trade. It tells you the best bid, the best ask and the amount available at every visible level. That makes it possible to calculate spreads, estimate slippage and decide whether enough size exists before submitting an order.

Polymarket documents two book endpoints:

How do you get a Polymarket token ID?

Start with the Gamma API, which handles events and market discovery. A market object includes its CLOB token IDs. The outcome and token arrays map by position, so identify which token represents the outcome you want before requesting a book.

curl -s \
  "https://gamma-api.polymarket.com/markets?active=true&closed=false&limit=1"

This identifier distinction causes many empty or invalid responses. A market slug works for human navigation, a condition ID anchors the binary market, and a token ID selects the exact order book.

How do you fetch one Polymarket order book?

Send the token ID to the public CLOB host:

curl -s \
  "https://clob.polymarket.com/book?token_id=YOUR_TOKEN_ID"

A successful response follows this shape:

{
  "market": "0xCONDITION_ID",
  "asset_id": "YOUR_TOKEN_ID",
  "timestamp": "1780000000000",
  "hash": "0xBOOK_HASH",
  "bids": [
    { "price": "0.45", "size": "100" },
    { "price": "0.44", "size": "200" }
  ],
  "asks": [
    { "price": "0.46", "size": "150" },
    { "price": "0.47", "size": "250" }
  ],
  "min_order_size": "1",
  "tick_size": "0.01",
  "neg_risk": false,
  "last_trade_price": "0.45"
}

The best bid is the highest bid price. The best ask is the lowest ask price. The spread is the difference between them. In this example the market is 45 cents bid and 46 cents ask, for a one-cent spread.

What do the order-book fields mean?

Prices and sizes are JSON strings. Convert them to a decimal-safe representation before doing arithmetic. Plain floating-point numbers are acceptable for display, but order construction and accounting should preserve the venue's exact increments.

How do you fetch multiple Polymarket order books?

Use POST /books when a screen or scanner needs several outcomes at once.

curl -s \
  -X POST "https://clob.polymarket.com/books" \
  -H "Content-Type: application/json" \
  -d '[
    { "token_id": "YES_TOKEN_ID" },
    { "token_id": "NO_TOKEN_ID" }
  ]'

Keep a map keyed by asset_id rather than relying on array position. That makes the join explicit and prevents one missing book from shifting the relationship between tokens and responses.

How do you calculate live depth and slippage?

The best ask tells you the cost of the first available contracts. A larger order walks upward through the asks until the requested quantity is filled.

function priceBuy(asks, contracts) {
  let remaining = contracts;
  let cost = 0;

  const levels = asks
    .map(({ price, size }) => ({
      price: Number(price),
      size: Number(size),
    }))
    .sort((a, b) => a.price - b.price);

  for (const level of levels) {
    const fill = Math.min(remaining, level.size);
    cost += fill * level.price;
    remaining -= fill;
    if (remaining === 0) break;
  }

  return {
    fillable: remaining === 0,
    filled: contracts - remaining,
    cost,
    averagePrice: remaining === 0 ? cost / contracts : null,
  };
}

Slippage is the difference between that weighted average and the initial best ask. It grows when the book is thin or the order is large. A scanner that uses only the first level will systematically overstate the quality of its largest opportunities.

How do you stream the Polymarket order book?

The public market WebSocket sends order-book snapshots and price changes for subscribed asset IDs. The initial subscription names the token IDs and the market channel:

{
  "assets_ids": ["YES_TOKEN_ID", "NO_TOKEN_ID"],
  "type": "market"
}

The first book message gives a complete snapshot. Later price-change messages update levels, while trade and tick-size messages carry related market changes. Send the documented ping on schedule, track timestamps and replace local state with a new snapshot after reconnecting.

REST is best for an initial state or occasional lookup. The WebSocket is the right source for a screen that needs to stay current without requesting the same books repeatedly.

How do you read Polymarket depth through Predictefy?

Predictefy converts the venue response into the same best-first bids and asks arrays used for every supported venue. The outcomeId is the same Polymarket CLOB token ID.

curl -s \
  "https://data.predictefy.com/api/polymarket/fetchOrderBook?outcomeId=YOUR_TOKEN_ID" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

The current TypeScript SDK exposes the same call:

npm install @predictefy/sdk@1.0.0-beta.8

import Predictefy from '@predictefy/sdk';

const client = new Predictefy({
  apiKey: process.env.PREDICTEFY_API_KEY,
});

const book = await client.polymarket.fetchOrderBook({
  outcomeId: process.env.POLYMARKET_TOKEN_ID,
});

console.log(book.bids, book.asks, book.timestamp);

How do you get historical Polymarket order-book depth?

A current book endpoint returns a snapshot, and price history is not the same as historical depth. Reconstructing a past ladder requires snapshots or level changes captured while the market was live.

Predictefy exposes its stored raw book tape through a time-bounded history route:

curl -s \
  "https://data.predictefy.com/v1/history/books/events?venue=polymarket&outcomeId=YOUR_TOKEN_ID&since=2026-09-01T00:00:00Z&until=2026-09-02T00:00:00Z" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Use this event tape for questions about spread, depth and queue movement. Use price candles when the question is only how the market probability changed over time. Keeping those datasets separate prevents a closing price series from being mistaken for evidence that size was available at that price.

Frequently Asked Questions