Get the Polymarket order book in Python

There are two different questions hiding inside "how do I get the Polymarket order book in Python". If you want the book as it is right now, Polymarket's own py-clob-client answers it in a few lines. If you want the book as it was at some point in the past, the official API cannot help, because it only serves current state. For that half we use the Marketlens SDK. By the end you will have both paths working.

Live vs historical: two different tools

Polymarket's API and WebSocket feed expose the current book for any outcome token, but each update overwrites the last: there is no endpoint for the book as of one minute ago. Historical books only exist where a service has been recording the feed, which is what Marketlens does. So: py-clob-client for the present, Marketlens for the past. If order books themselves are new to you, start with the order book explainer.

Step 1: the live book with py-clob-client

Polymarket's official Python client is open source and reading the book requires no API key. Install it first.

bash

$ pip install py-clob-client

Every market has two outcome tokens (YES and NO), and the book is queried per token. You can find a market's token ids in theclobTokenIds field of Polymarket's Gamma markets API, or in the URL data on the Polymarket site. With a token id in hand:

python

from py_clob_client.client import ClobClient

client = ClobClient("https://clob.polymarket.com")

# token_id identifies one outcome of one market
book = client.get_order_book(token_id)
print(book.bids[:3], book.asks[:3])

mid = client.get_midpoint(token_id)

The returned book holds bids and asks as lists of price and size levels, prices quoted between 0 and 1. This is the honest scope of the official client: current state, refreshed on demand or streamed over WebSocket. It is the right tool if you are placing orders or watching a market live. Everything from here on is about the part it does not cover.

Step 2: install the Marketlens SDK

The Marketlens SDK is also open source and pip installable. It serves historical books for every recurring Polymarket market type: crypto up or down, live sports, weather buckets, equities, and macro markets. Browse what is recorded per series in the data catalog.

bash

$ pip install marketlens

Create a free API key and export it as MARKETLENS_API_KEY.

Step 3: historical books with walk()

The core primitive for historical books is client.orderbook.walk(). Give it a market UUID or a series slug plus a time window, and it yields (market, book) tuples: the full L2 book at every recorded change inside the window, in order. Each book exposes book.spread and book.midpoint directly. Here we pull five minutes of the BTC up or down 5 minute series into a pandas DataFrame:

python

from marketlens import MarketLens
import pandas as pd

client = MarketLens()  # reads MARKETLENS_API_KEY

rows = []
for market, book in client.orderbook.walk(
    "btc-up-or-down-5m",
    after="2026-04-15T01:45:00Z",
    before="2026-04-15T01:50:00Z",
):
    rows.append({
        "t": book.as_of,
        "mid": book.midpoint,
        "spread": book.spread,
        "imbalance": book.imbalance(3),
    })

df = pd.DataFrame(rows)
print(df["spread"].describe())

Every book comes with a millisecond timestamp and full depth. The endpoint parameters and response shapes are documented on the order book docs page.

Step 4: point in time books and depth analytics

You do not always want a stream. client.orderbook.get() returns one book, and with at= it returns the book at any past moment. Every book, live or historical, carries the same analytics methods:

python

book = client.orderbook.get(market_id, at="2026-04-15T01:47:00Z")

book.impact("BUY", 500)          # avg fill price of a $500 market buy
book.slippage("BUY", 500)        # its cost versus the midpoint
book.imbalance(3)              # bid vs ask volume, top 3 levels
book.depth_within(0.02)        # (bid, ask) size within 2 cents of mid
book.microprice()              # size weighted fair price
book.spread_bps()              # spread in basis points of mid

Research code and monitoring code share one vocabulary: the same OrderBook object comes back whether you asked for now, a past instant, or every step of a walk.

Shortcut: pre-aggregated metrics

If you want spread, midpoint, and depth over hours or days rather than every tick, replaying the whole book is more resolution than you need. The metrics endpoint serves time-bucketed summaries at a fixed resolution and converts to a DataFrame in one call:

python

df = client.orderbook.metrics(
    market_id,
    after="2026-04-15T00:00:00Z",
    before="2026-04-15T06:00:00Z",
    resolution="1m",
).to_dataframe()

Each row holds best bid and ask, spread, midpoint, and depth per side for one bucket.

FAQ

Common questions

How do I get the Polymarket order book in Python?

For the live book, use Polymarket's official py-clob-client and request the book for an outcome token. For historical books the official API has nothing; use a recording service like Marketlens, whose Python SDK walks past books over any time window.

Does Polymarket's API provide historical order book data?

No. The official CLOB API serves the current book and live WebSocket streams only. Once the book changes, the previous state is gone. Historical books exist only where someone has been recording them; Marketlens has recorded every recurring Polymarket market at millisecond resolution since March 2026.

How do I compute spread and midpoint from a Polymarket order book?

Spread is the best ask minus the best bid; midpoint is their average. In the Marketlens SDK every book exposes both directly, plus depth analytics like imbalance and impact, so you rarely compute them by hand.

Can I load Polymarket order book history into a pandas DataFrame?

Yes. Build rows inside a walk loop and pass them to pandas, or use the metrics endpoint, which returns pre-aggregated spread, midpoint, and depth buckets at a fixed resolution and converts to a DataFrame in one call.

Is the historical order book data sampled or tick level?

Tick level. Every individual book change is recorded with a millisecond timestamp, anchored by a full snapshot roughly every minute, rather than sampling the book at fixed intervals. Sampling leaves a blind window between frames, which is exactly where queue position, fleeting liquidity, and true slippage live.

Try it

Replay your first order book in two minutes

The free tier includes 5M events per day with full API and full archive access, no card required.

bash

$ pip install marketlens

Get a free API key Read the docs