Skip to main content
Each Polymarket outcome is represented by a token traded on the CLOB. Its price reflects what traders are willing to pay for that outcome, while its order book shows the resting bids and asks. The examples below assume you already have a market object from which to read the outcome token IDs. To find or fetch one, see Discover Markets.
Given a market, read its outcome token IDs:

Order Book

Retrieve the resting bids and asks for one outcome token. Bids are ordered by ascending price and asks by descending price, so the best bid and ask are the last entries in their respective arrays. Each response also includes a hash for the order-book state. Compare it with the previous response’s hash to determine whether the book changed between reads.

Fetch an Order Book

Call fetchOrderBook() on a PublicClient or SecureClient to fetch an outcome’s order book.
The returned OrderBook describes its price levels and the market details needed to interpret them:

Fetch Multiple Order Books

Batch order-book reads return the resting bids and asks for several outcomes in one request.
Maximum 500 items per request.
Call fetchOrderBooks() on a PublicClient or SecureClient to fetch several order books in one request.
Each item uses the OrderBook shape described above:

Best Market Price

Read the best available execution price for an outcome and side. BUY returns the lowest ask, which is the price you would pay to buy. SELL returns the highest bid, which is the price you would receive when selling.

Fetch a Price

Call fetchPrice() on a PublicClient or SecureClient to fetch the best price for one side. For a BUY, the method returns the lowest ask.
The method returns the price as a decimal string:

Fetch Multiple Prices

Batch price reads return the best market price for several outcome-and-side pairs in one request. Use them when the same view or calculation needs more than one outcome.
Maximum 500 items per request.
Call fetchPrices() on a PublicClient or SecureClient to fetch several prices in one request.
Prices maps each token ID to the requested side and price:

Midpoint Price

The midpoint is the average of the best bid and best ask. It provides a reference price between the two sides of the order book.

Fetch a Midpoint

Call fetchMidpoint() on a PublicClient or SecureClient to fetch the midpoint.
The method returns the midpoint as a decimal string:

Fetch Multiple Midpoints

Fetch midpoint prices for several outcomes in one request.
Maximum 500 items per request.
Call fetchMidpoints() on a PublicClient or SecureClient to fetch several midpoints.
Midpoints maps each token ID to its midpoint:

Spread

The spread is the difference between the best ask and best bid. A narrower spread indicates that the two sides of the order book are closer together.

Fetch a Spread

Call fetchSpread() on a PublicClient or SecureClient to fetch the spread.
The method returns the spread as a decimal string:

Fetch Multiple Spreads

Batch spread reads return the bid-ask spread for several outcomes in one request.
Maximum 500 items per request.
Call fetchSpreads() on a PublicClient or SecureClient to fetch several spreads in one request.
The result maps each token ID to its spread:

Last Trade Price

The last trade price records the most recent matched trade for an outcome. It includes the trade price and side.

Fetch a Last Trade Price

Call fetchLastTradePrice() on a PublicClient or SecureClient to fetch the last trade.
LastTradePrice pairs the traded price with its order side:

Fetch Multiple Last Trade Prices

Fetch the most recent matched trade for several outcomes in one request.
Maximum 500 items per request.
Call fetchLastTradePrices() on a PublicClient or SecureClient to fetch several last trades.
Each LastTradePriceForToken identifies the outcome alongside its traded price and side:

Price History

Price history is a time series of observed prices for an outcome. Fetch either a relative window or an absolute time range, but do not combine the two forms. You can also control the interval between returned observations; longer time ranges require a sampling interval.
Call fetchPriceHistory() on a PublicClient or SecureClient to fetch historical prices. Set interval for a relative window, or set startTs and endTs for an absolute range. Use fidelity to set the sampling interval in minutes.
Each PriceHistoryPoint contains a timestamp and its observed price: