Access L2 order book snapshots and best bid/offer (BBO) data
Prefer Streaming for Production UseThis polling API is subject to rate limits. For production applications that need continuous market data, use the gRPC Market Data Stream instead. The streaming API provides real-time updates with lower latency and no rate limit concerns.
No Participant ID RequiredThese endpoints only require Auth0 JWT authentication with read:marketdata scope. You do not need to provide the x-participant-id header or complete KYC onboarding to access order book data.
The BBO endpoint returns only the top of book - the best (highest) bid and best (lowest) offer. This is the most efficient way to get current market prices.
Spread in price units (best_offer.px - best_bid.px)
midPrice
string
Mid price ((best_bid.px + best_offer.px) / 2)
state
string
Current trading state (optional)
transactTime
datetime
Server timestamp
Instrument State Tracking: The state field in order book and BBO responses is optional. The preferred approach is to use ListInstruments to get and cache the initial state, then subscribe to the instrument state change subscription for real-time state updates.
Instruments follow the primary lifecycle: PENDING → OPEN → CLOSED → EXPIRED → TERMINATED. Instruments may also be SUSPENDED or HALTED during their lifecycle.
Initial state for a newly created instrument which has not yet begun trading.
OPEN
In this state, the instrument is open for continuous order entry and matching.
CLOSED
In this state, orders can not be entered, modified, or canceled, and no matching occurs. Any existing Day orders will be expired.
EXPIRED
An instrument moves to this state when its Expiration Date/Time is reached. In this state, any resting orders are expired and no new orders can be entered.
TERMINATED
When an instrument’s Termination Date is reached, the order book is removed from the matching engine, orders are canceled, and positions are closed. Historical data will still remain in Polymarket US ledgers.
Orders can be entered and modified, but no matching occurs. When the instrument transitions to an OPEN state, the orders entered during PREOPEN will match at a single opening price that is automatically determined by an algorithm that is designed to maximize the volume traded at the open.
MATCH_AND_CLOSE_AUCTION
This state is similar to PREOPEN, with the exception that matching will occur upon the transition of this state to any other state. This state is useful if you want matching to occur at the end of the state, but you don’t want the instrument to be open after.
