Polymarket’s order book is a live list of resting buy and sell orders for an outcome. Developers can retrieve a snapshot through the CLOB API or SDK, or subscribe to market-stream events; the key implementation choices are selecting the correct outcome identifier and keeping displayed prices separate from executable prices.
How does the Polymarket order book work?
Polymarket uses a central limit order book (CLOB): buyers post bids, sellers post asks, and orders match when their prices are compatible. A bid is the price a buyer offers; an ask is the price a seller requests. The best bid is the highest bid, the best ask is the lowest ask, and the spread is the difference between those two prices. A narrower spread generally indicates more liquidity. Polymarket’s prices and order-book documentation explains the displayed-price conventions and order behavior.
As an Amazon Associate I earn from qualifying purchases.
Outcome shares are priced from $0.00 to $1.00, with the price interpreted as an implied probability. The displayed price is normally the midpoint between the best bid and best ask. If the spread is wider than $0.10, the displayed price uses the last traded price instead. Neither display convention guarantees that a trade can execute at that number.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →For example, if the best bid is $0.34 and the best ask is $0.40, the midpoint is $0.37. A buyer seeking immediate execution would pay the ask, $0.40; a seller seeking immediate execution would receive the bid, $0.34. The example illustrates the spread, not a typical or current market price.
How do bids, asks, and order types affect execution?
A displayed midpoint is a reference, while the order book shows the prices currently offered by buyers and sellers. The distance between the best bid and ask matters when an order must execute immediately: a buyer crosses the spread by accepting an ask, and a seller crosses it by accepting a bid.
| Order approach | Price control | Execution trade-off |
|---|---|---|
| Market-style order | Prioritizes execution against the best available resting prices. | Can execute immediately, but the fill price depends on available liquidity and may differ from the displayed midpoint. |
| Limit order | Sets a price limit; it can execute only at that price or better. | May rest in the book, fill partially, or remain unfilled; unfilled quantity can be canceled. |
Polymarket’s documentation notes that technically all orders are limit orders. A market order is a limit order priced to execute immediately against resting liquidity. This distinction is useful in code: “market” describes the execution intent, while the underlying order still has a price constraint.
How do I get a Polymarket order book snapshot?
First select the identifier for the correct market version and outcome. The current unified SDK uses an outcome token ID for CTF markets and a position ID for Polymarket Protocol V2 markets. The market object and outcome determine which identifier applies; do not assume the same identifier type works for every market version. See the get-book API documentation and the developer quickstart for version-aware context.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problems- Choose the outcome identifier. Use the outcome token ID for CTF or the position ID for Protocol V2, as appropriate to the market.
- Request one book. The documented HTTP endpoint is
GET https://clob.polymarket.com/book?token_id=<TOKEN_ID>. - Parse levels and metadata. The response includes bid and ask price levels with sizes, and metadata such as timestamp, minimum order size, tick size, negative-risk flag, last trade price, and book hash.
- Check level ordering. The documentation specifies bids in ascending price order and asks in descending price order, so the best price is the last item in each array. Verify this assumption against current responses rather than hard-coding an untested interpretation.
The SDK exposes fetchOrderBook in TypeScript and get_order_book in Python. For multiple outcome books, the documented batch endpoint accepts up to 500 items in one request; the raw API method posts a list of outcome IDs to /books. The limit is a maximum batch size, not a guarantee about response time or freshness.
Rank #3
How can I detect snapshot changes?
A snapshot’s book hash can be compared with the hash from an earlier snapshot. A changed hash indicates that the book state differs between those reads; an unchanged hash is a useful check that the returned state has not changed according to that field. Hash comparison does not deliver the intervening updates or explain which levels changed. For change events, use the market stream.
How do I stream Polymarket order-book updates?
The official market stream subscribes to one or more outcome assetId values. Standard event types include book, price_change, last_trade_price, and tick_size_change. A book event carries bids and asks, condition ID, and asset ID; optional metadata can include timestamp, minimum order size, tick size, negative-risk flag, and last-trade price. With customFeatureEnabled, the stream can also include best_bid_ask, new_market, and market_resolved. Consult the market-channel documentation for subscription details and event fields.
Use snapshots when a simple read or periodic state check is enough. A stream is better suited to event-driven updates, but a live consumer must handle connection recovery and rebuild or reconcile its state when needed. The reviewed official documentation does not specify a numeric latency service level, delivery guarantee, or universal update frequency, so an application should not describe the feed as instant or rely on an assumed freshness interval.
What should developers account for beyond the book?
Polymarket describes its CLOB as hybrid-decentralized: an operator performs matching offchain, while matched trades settle onchain through smart contracts. Outcome-token type affects the settlement route, which is why market-version-aware identifiers matter beyond simply retrieving a book. The quickstart outlines a broader workflow of authentication, fetching a market and selecting its version-appropriate outcome ID, submitting an order, waiting for asynchronous settlement, and checking the resulting position.
Quick Recap
Best Value
- Treat the best bid and ask as executable-side references, not as interchangeable with the displayed price.
- Use the snapshot’s tick size and minimum order size when interpreting or preparing orders.
- Track timestamps and plan for reconnects and state rebuilding in stream consumers.
- Recheck method names, payload details, version handling, and display conventions against the live documentation before shipping, because those pages can change.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
