Order Book

GET /v1/markets/{condition_id}/book

Returns the CLOB L2 order book snapshot for a market’s primary token, keyed by condition id. The same OrderBookSnapshot payload is also available keyed by token id via GET /v1/clob/book/{token_id} or GET /v1/book?token_id=... — see the Order Book Lookup Recipe on the Markets page for when to use each form.

Request

curl -H "X-API-Key: $API_KEY" \
  "https://api.polysimulator.com/v1/markets/0x1a2b3c/book?outcome=Yes&depth=5"

Parameter	Type	Default	Description
`outcome`	string	—	Filter by outcome label (e.g. `Yes`, `No`)
`depth`	int	full book	Optional trim: keep only the best N levels per side (max 500). Omitted = the FULL book — Polymarket’s wire contract.

Response

{
  "token_id": "71321...",
  "market": "0x1a2b3c...",
  "asset_id": "71321...",
  "hash": "0x9f4c...",
  "bids": [
    {"price": "0.62", "size": "3000.0"},
    {"price": "0.63", "size": "1200.0"},
    {"price": "0.64", "size": "500.0"}
  ],
  "asks": [
    {"price": "0.68", "size": "2500.0"},
    {"price": "0.67", "size": "800.0"},
    {"price": "0.66", "size": "400.0"}
  ],
  "min_order_size": "5",
  "tick_size": "0.01",
  "neg_risk": false,
  "last_trade_price": "0.65",
  "mid": "0.65",
  "spread": "0.02",
  "timestamp": "1778995283697"
}

In the example above the best bid is 0.64 — the LAST bids entry (bids[-1]) — and the best ask is 0.66 — the LAST asks entry (asks[-1]). The best level is at the tail on both sides, byte-identical to Polymarket’s live /book wire. For safety, read order-independently — see the warning below.

Understanding the Book

Field	Type	Description
`token_id`	`string`	The CLOB outcome token (asset) the book is for.
`market`	`string \| null`	The market’s `condition_id`. PM-compat alias — the SDK reads this to associate the book with a market condition ID.
`asset_id`	`string \| null`	Same value as `token_id`. Polymarket CLOB uses `asset_id` as the canonical book key, so `py-clob-client`-ported code reads this name.
`hash`	`string \| null`	Order-book hash for change detection (PM convention). Compare across snapshots to detect whether the book moved without diffing every level.
`timestamp`	`string \| null`	Snapshot timestamp as a Unix epoch milliseconds string (e.g. `"1778995283697"`), matching Polymarket’s live CLOB wire contract. Parse with `datetime.fromtimestamp(int(ts) / 1000, tz=timezone.utc)` in Python or `new Date(Number(ts))` in JavaScript. Do not parse as ISO 8601.
`bids`	`BookLevel[]`	Buy orders sorted by price ascending — best (highest) bid is `bids[-1]` (the last element), worst bid first. This is byte-identical to what the real Polymarket CLOB `/book` returns on the wire, so SDKs ported from `py-clob-client` read the same index.
`asks`	`BookLevel[]`	Sell orders sorted by price descending — best (lowest) ask is `asks[-1]` (the last element), worst ask first.
`min_order_size`	`string \| null`	Minimum orderable shares for this market (string, e.g. `"5"`).
`tick_size`	`string \| null`	Price quantum as a string (e.g. `"0.01"`). `py-clob-client` reads this to quantize limit prices client-side. (Note: the standalone `GET /v1/tick-size/{token_id}` endpoint returns the tick as a JSON number; here, inside the book, it is a string — see String Numerics.)
`neg_risk`	`boolean \| null`	`true` when the market is a negative-risk (multi-outcome) market, `false` for a standard binary, or `null` when unknown. SDKs use this for order-routing.
`last_trade_price`	`string \| null`	The most recent trade price for this token (string, e.g. `"0.65"`), or `null` if no trades yet.
`mid`	`string \| null`	Average of best bid and best ask (Polysimulator extension, stringified).
`spread`	`string \| null`	Difference between best ask and best bid, capped at $0.10 for PM parity. Markets with extreme thin-liquidity books (e.g. `bid=0.001 ask=0.999`) report `spread="0.10"`, not the raw difference. This stops arbitrage filters from treating every illiquid book as a free-money signal.
`stale`	`boolean \| null`	Present and `true` only when the live CLOB fetch failed and the snapshot was served from a recent cached book. Absent (`null`) on a fresh read. Treat a `stale` book as a best-effort fallback, not a real-time quote.
`price`	`string`	Price level (inside a `bids`/`asks` entry; 0.00–1.00 implied probability, stringified).
`size`	`string`	Total shares available at that price level (stringified).

Recommended: read the inside market order-independently, not by index. Bids are sorted ascending (best/highest bid last, bids[-1]) and asks descending (best/lowest ask last, asks[-1]) — the best of each side is the last element, byte-identical to what Polymarket’s live CLOB /book returns on the wire. Rather than indexing a fixed position, compute the best bid as the max bid price and the best ask as the min ask price. Coerce the price to a number first — prices are JSON strings, and max(b["price"] for b in bids) compares them lexicographically, where "0.9" > "0.10" is True (wrong). Use max(float(b["price"]) for b in bids) / min(float(a["price"]) for a in asks) (or Decimal for exactness). This stays correct regardless of array order, matching the live clob.polymarket.com/book wire.

Book level ordering matches Polymarket’s live wire: levels are bids ascending (best = bids[-1]), asks descending (best = asks[-1]) — best at the tail on both sides, byte-identical to the real clob.polymarket.com/book wire. Read the inside market with the order-independent max/min reads above rather than hard-coding bids[0] / asks[0], so your integration survives any future wire-format change.

Timestamp Parsing

The timestamp field is returned as a Unix epoch milliseconds string (e.g. "1778995283697"), matching Polymarket’s CLOB wire format. It is not an ISO 8601 string.

import datetime

# timestamp is a Unix epoch milliseconds string, e.g. "1778995283697"
ts_ms = int(book["timestamp"])
snapshot_time = datetime.datetime.fromtimestamp(
    ts_ms / 1000, tz=datetime.timezone.utc
)
print(f"Snapshot UTC: {snapshot_time.isoformat()}")

// timestamp is a Unix epoch milliseconds string, e.g. "1778995283697"
const tsMs = Number(book.timestamp);
const snapshotTime = new Date(tsMs);
console.log(`Snapshot UTC: ${snapshotTime.toISOString()}`);

Liquidity Assessment

from decimal import Decimal

book = api.get_order_book("0x1a2b3c...")

# Calculate total bid liquidity
bid_liquidity = sum(
    Decimal(level["size"]) for level in book["bids"]
)

# Calculate total ask liquidity
ask_liquidity = sum(
    Decimal(level["size"]) for level in book["asks"]
)

spread = Decimal(book["spread"])

print(f"Spread: {spread}")
print(f"Bid depth: {bid_liquidity} shares")
print(f"Ask depth: {ask_liquidity} shares")

Check the book before large orders. If your order size exceeds the top-of-book liquidity, you’ll walk through multiple price levels and experience slippage. Use slippage protection to guard against this.

Next Steps

Markets — Browse available markets
Placing Orders — Trade with real book depth

Getting Started

Core Concepts

Trading Guide

Market Data

Simulation

Account & Portfolio

WebSocket Feeds

Bot Development

Going Live

Order Book

Order Book

Request

Response

Understanding the Book

Timestamp Parsing

Liquidity Assessment

Next Steps

​Order Book

​Request

​Response

​Understanding the Book

​Timestamp Parsing

​Liquidity Assessment

​Next Steps

Order Book

Request

Response

Understanding the Book

Timestamp Parsing

Liquidity Assessment

Next Steps