Fetch Order Book

Fetch the order book (bids/asks) for a specific outcome. Supports live and historical queries. For historical data, pass since to get a single snapshot, or since + until to get an array of fully reconstructed L2 books from the archive. Range queries return up to limit snapshots (default 100, max 1000).

GET /api/{exchange}/fetchOrderBook

Python

Polymarket

import pmxt

# API key optional — enables faster catalog-backed lookups
exchange = pmxt.Polymarket(
    pmxt_api_key="YOUR_PMXT_API_KEY",
)
result = exchange.fetch_order_book(
    outcome_id="67890",
    limit=10,
    side="yes",
    outcome="value",
    since=1,
    until=1,
)

200

{
  "success": true,
  "error": {
    "message": "<string>"
  },
  "data": {
    "bids": [
      {
        "price": 123,
        "size": 123
      }
    ],
    "asks": [
      {
        "price": 123,
        "size": 123
      }
    ],
    "timestamp": 123,
    "datetime": "<string>"
  }
}

Use cases

Live order book

Fetch the current L2 order book for an outcome. If you already have an outcome token ID, pass it directly:

Python

import pmxt

poly = pmxt.Polymarket(pmxt_api_key="pmxt_...")
book = poly.fetch_order_book("104932610032177696635191871147557737718087870958469629338467406422339967452218")
print(f"{len(book.bids)} bids, {len(book.asks)} asks")

Historical snapshot

Get the order book at a specific point in time. Pass since as a Unix timestamp in milliseconds — returns the nearest snapshot at or before that time.

For binary markets, you can pass the market ID and choose the side with params.outcome. Use "yes" or "no" instead of copying the long outcome token ID:

Python

import pmxt

poly = pmxt.Polymarket(pmxt_api_key="pmxt_...")

market = poly.fetch_market(
    slug="will-spacex-starship-flight-test-12-launch-by-may-22-354-721"
)

book = poly.fetch_order_book(
    market.market_id,
    params={"since": 1779487200000, "outcome": "yes"},
)

print(f"{book.dt}: {len(book.bids)} bids, {len(book.asks)} asks")
print(f"  best bid: {max(b.price for b in book.bids):.3f}")
print(f"  best ask: {min(a.price for a in book.asks):.3f}")

Historical range (reconstructed L2 books)

Pass both since and until to get an array of fully reconstructed L2 order book snapshots. Each snapshot is a complete book at that moment in time — not deltas.

Default 100 snapshots per request, max 1000.

Python

import pmxt

poly = pmxt.Polymarket(pmxt_api_key="pmxt_...")

market = poly.fetch_market(
    slug="will-spacex-starship-flight-test-12-launch-by-may-22-354-721"
)

books = poly.fetch_order_book(
    market.market_id,
    params={
        "since": 1779480000000,
        "until": 1779487200000,
        "outcome": "yes",
    }
)
print(f"{len(books)} snapshots")
for ob in books[:3]:
    print(f"  {ob.dt}  bid={ob.bids[0].price}  ask={ob.asks[0].price}")

Historical order book data is backed by the PMXT Archive — the same tick-level data available as Parquet files, but queryable directly from the API without downloading or parsing files. Supports Polymarket, Kalshi, Limitless, and Opinion.

Path Parameters

exchange · enum<string> · required

The prediction market exchange to target.

Available options: polymarket, kalshi, kalshi-demo, limitless, probable, baozi, myriad, opinion, smarkets, polymarket_us, suibets, router

Query Parameters

outcomeId · string · required

limit · number

side · enum<string>

Outcome side: 'yes' or 'no'. Required for exchanges like Limitless where the API returns a single orderbook per market.

Available options: yes, no

outcome · string

Outcome alias: 'yes' or 'no', or an outcome token ID. When set, the first argument is treated as a market ID and this value selects which outcome's order book to fetch. Accepts the literal strings 'yes'/'no' (resolved via a market lookup) or a raw outcome token ID.

since · number

Unix timestamp (ms) — fetch a historical snapshot at or before this time, or the start of a range when combined with until (hosted API only).

until · number

Unix timestamp (ms) — end of a historical range. When combined with since, returns an array of reconstructed L2 OrderBook snapshots between since and until (hosted API only).

Response

200 - application/json

Fetch Order Book response

success · boolean

Example:

true

error · object

Show child attributes

data · object

Show child attributes