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: Given a market, read its outcome token IDs: Given a market object, its outcome token IDs are stored as a JSON-encoded
array:Parse the array, then select the outcome you want to read: 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: Call get_order_book() on an AsyncPublicClient or AsyncSecureClient to
fetch an outcome’s order book. The synchronous PublicClient and
SecureClient provide the same method.The returned OrderBook describes its price levels and the market details
needed to interpret them: Fetch an outcome’s order book:Alongside its price levels, the response includes the trading constraints
needed to validate an order: 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: Call get_order_books() on an AsyncPublicClient or AsyncSecureClient to
fetch several order books in one request. The synchronous PublicClient
and SecureClient provide the same method.Each item uses the OrderBook shape described above: Fetch several order books in one request:The response contains one order book for each requested token ID: 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: Call get_price() on an AsyncPublicClient or AsyncSecureClient to fetch
the best price for one side. For a BUY, the method returns the lowest ask.
The synchronous PublicClient and SecureClient provide the same method.The method returns the price as a Decimal: Fetch the lowest ask available to a buyer:The response contains 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: Call get_prices() on an AsyncPublicClient or AsyncSecureClient to
fetch several prices in one request. The synchronous PublicClient and
SecureClient provide the same method.The result maps each token ID to the requested side and price: Fetch several prices in one request:The response 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: Call get_midpoint() on an AsyncPublicClient or AsyncSecureClient to
fetch the midpoint.
The synchronous PublicClient and SecureClient provide the same method.The method returns the midpoint as a Decimal: Fetch the midpoint:The response contains 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: Call get_midpoints() on an AsyncPublicClient or AsyncSecureClient to
fetch several midpoints. The synchronous PublicClient and SecureClient
provide the same method.The result maps each token ID to its midpoint: Fetch several midpoints in one request:The response 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: Call get_spread() on an AsyncPublicClient or AsyncSecureClient to fetch
the spread. The synchronous PublicClient and SecureClient provide the
same method.The method returns the spread as a Decimal: Fetch the spread:The response contains 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: Call get_spreads() on an AsyncPublicClient or AsyncSecureClient to
fetch several spreads in one request. The synchronous PublicClient and
SecureClient provide the same method.The result maps each token ID to its spread: Fetch several spreads in one request:The response maps each token ID to its spread: Last Trade Price
Use the last trade price to see where an outcome most recently traded.
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:When a token has never traded, fetchLastTradePrice() returns null
instead of a LastTradePrice object: Call get_last_trade_price() on an AsyncPublicClient or
AsyncSecureClient to fetch the last trade. The synchronous PublicClient
and SecureClient provide the same method.LastTradePrice pairs the traded price with its order side:When a token has never traded, get_last_trade_price() returns None
instead of a LastTradePrice object: Fetch the last trade:The response contains the traded price and side:When a token has never traded and its order book is empty, the API returns
the "0.5" placeholder and an empty side string: 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: Call get_last_trade_prices() on an AsyncPublicClient or
AsyncSecureClient to fetch several last trades. The synchronous
PublicClient and SecureClient provide the same method.Each LastTradePriceForToken identifies the outcome alongside its traded
price and side: Fetch several last trade prices in one request:The response identifies each outcome alongside its traded price and side: Price History
Read historical prices for an outcome token over a selected time period.
Call listPriceHistory() on a PublicClient or SecureClient. Choose a
relative window, an explicit time range, or a point in time.Each PriceHistoryPoint carries the observation time in epoch
milliseconds, the price as a decimal string, and the window it was
observed in:Output: PriceHistoryPoint
resolutionSeconds instead of assuming uniform spacing.History Windows and Resolution
- Explicit
start/end ranges span at most 15 days. start is inclusive and end exclusive.
PriceHistoryInterval.Max returns full history at 12-hour buckets by default. Explicit bucketSeconds values of 10800 or 43200 also cover full history. Finer widths return only the last 30 days.bucketSeconds accepts 60 to 86400 seconds, with a floor of 600 for max/1m and 300 for 1w. Omit it to let the server choose a width for the span and available history.- One-minute data lasts at least 7 days, five-minute at least 60 days, and thirty-minute at least 90 days (floors, not exact horizons). Three-hour and twelve-hour data is permanent. Explicitly requesting a resolution the store cannot fill returns an empty or sparse page with
resolution_seconds echoing the requested grid; omit bucket_seconds to always get the densest series that exists.
Call list_price_history() on an existing AsyncPublicClient or AsyncSecureClient.Choose a relative window, an explicit time range, or a point in time.Output: PriceHistoryPoint
timestamp is a timezone-aware datetime and price is a Decimal. resolution_seconds is the observation window in seconds, with zero for an exact tick.History Windows and Resolution
- Explicit ranges span at most 15 days.
start is inclusive and end is exclusive.
- Choose exactly one of
interval, start, or as_of. An as_of request cannot set bucket_seconds or page_size.
bucket_seconds accepts 60 to 86400 seconds. The minimum is 600 for max, all, and 1m, and 300 for 1w. Omit it to let the service choose the resolution.- Use
interval="max" without bucket_seconds for full history at the default resolution.
Pass token_id and exactly one time form: interval for a relative
window, start (with optional end, epoch seconds, at most 15 days) for
an absolute range, or as_of for a point-in-time read. bucket_seconds
sets the bucket width in seconds; deeper pages come from ?cursor=.The response contains the price points under data, oldest first, with
the cursor pagination object:Points are oldest first. The final observation can fall between bucket
boundaries. Read resolution_seconds instead of assuming uniform spacing.History Windows and Resolution
- Explicit
start/end ranges span at most 15 days. start is inclusive and end exclusive.
max returns full history at 12-hour buckets by default. Explicit bucket_seconds values of 10800 or 43200 also cover full history. Finer widths return only the last 30 days.bucket_seconds accepts 60 to 86400 seconds, with a floor of 600 for max/1m and 300 for 1w. Omit it to let the server choose a width for the span and available history.- One-minute data lasts at least 7 days, five-minute at least 60 days, and thirty-minute at least 90 days (floors, not exact horizons). Three-hour and twelve-hour data is permanent. Explicitly requesting a resolution the store cannot fill returns an empty or sparse page with
resolution_seconds echoing the requested grid; omit bucket_seconds to always get the densest series that exists.
