Layer 3 — Trading

py_clob_client get_order_book: Polymarket Order Book Python Guide

Q: "What does py_clob_client get_order_book return?"

"In CLOB V2 (py-clob-client-v2), get_order_book(token_id) returns the raw JSON dict — not a Pydantic model. Access it with dict syntax: book['bids'] and book['asks'] (each entry is a {price, size} dict). The dict also includes market, asset_id, timestamp, min_order_size, neg_risk, tick_size, last_trade_price, and hash."

Q: "What is OrderBookSummary in py_clob_client?"

"OrderBookSummary is a dataclass in py-clob-client-v2 that mirrors the order book JSON shape (market, asset_id, timestamp, bids, asks, min_order_size, neg_risk, tick_size, last_trade_price, hash). Note get_order_book() returns the raw dict; the OrderBookSummary dataclass is used internally (e.g. by get_order_book_hash). Access fields with dict syntax on the returned value."

Q: "How do I get order books for multiple tokens at once?"

"Use client.get_order_books() with a list of BookParams objects (import BookParams from py_clob_client_v2). Each BookParams takes a token_id. This is more efficient than calling get_order_book() in a loop because it batches the request into a single API call."

Q: "How do I calculate the spread from a Polymarket order book?"

"Fetch the order book with get_order_book(token_id), then compute spread = float(book['asks'][0]['price']) - float(book['bids'][0]['price']). The spread is the difference between the lowest ask (cheapest sell) and the highest bid (best buy offer). Or just call client.get_spread(token_id)."

Q: "Does get_order_book require authentication?"

"No. get_order_book() is a public endpoint that works without authentication. You only need a ClobClient initialized with the host URL and chain_id (chain_id is required in CLOB V2) — no private key or API credentials required."

Q: "What is the difference between get_order_book and get_price?"

"get_order_book(token_id) returns the full order book with all bids and asks at every price level. get_price(token_id, side) returns only the best available price for a given side (BUY or SELL). Use get_order_book for depth analysis and get_price for quick price checks."

By AgentBets.ai Research Team March 3, 2026May 25, 2026 · 10 min read

How to use py-clob-client-v2 get_order_book to fetch Polymarket order book data (CLOB V2). Covers the dict response shape, get_order_books batch method, BookParams, spread calculation, and working Python examples.

py_clob_client get_order_book: Polymarket Order Book Python Guide

get_order_book() is the py-clob-client-v2 method that fetches the full order book for a Polymarket outcome token — all resting bids and asks with their prices and sizes. This page covers the method, its dict response shape, batch retrieval with get_order_books(), spread calculation, and common errors.

⚠️ CLOB V2 (live April 28, 2026). The package is py-clob-client-v2 (from py_clob_client_v2 import ClobClient). In V2, get_order_book() returns the raw JSON dict — access it with dict syntax (book["bids"][0]["price"]), not attribute access or model_dump(). The dict now also carries min_order_size, neg_risk, tick_size, and last_trade_price inline. The read-only client requires both host and chain_id.

For the complete V2 method reference, see the py-clob-client-v2 Reference. For a side-by-side comparison with Kalshi’s order book API, see the Prediction Market API Reference.

Try it live: Test get_order_book in the API Playground — no setup required.

Method Signature

client.get_order_book(token_id: str) -> dict

Parameters

Parameter	Type	Required	Description
`token_id`	`str`	Yes	The outcome token ID. Each Polymarket market has two tokens: one for YES, one for NO

Return Type

get_order_book() returns the raw JSON dict (its shape mirrors the OrderBookSummary dataclass). Access fields with dict syntax:

Field	Type	Description
`market`	`str`	The market/condition ID
`asset_id`	`str`	The token ID queried
`timestamp`	`str`	Snapshot timestamp
`bids`	`list`	Buy orders, highest price first. Each entry is a `{"price": str, "size": str}` dict
`asks`	`list`	Sell orders, lowest price first. Each entry is a `{"price": str, "size": str}` dict
`min_order_size`	`str`	Minimum order size for this market (added inline in V2)
`neg_risk`	`bool`	Whether this is a neg-risk market (added inline in V2)
`tick_size`	`str`	Minimum price increment, e.g. `"0.01"` (added inline in V2)
`last_trade_price`	`str`	Most recent trade price
`hash`	`str`	Order book hash (also available via `get_order_book_hash(book)`)

Authentication required: No. get_order_book() is a public endpoint. (The min_order_size, neg_risk, and tick_size fields inline mean you usually don’t need a separate lookup just to size or route an order.)

Basic Example

Fetch the order book for a single token and print the top bids and asks:

from py_clob_client_v2 import ClobClient

# Public/read-only client — host + chain_id are required in V2
client = ClobClient(host="https://clob.polymarket.com", chain_id=137)

book = client.get_order_book("TOKEN_ID")

print("Top 5 bids (buy orders):")
for bid in book["bids"][:5]:
    print(f"  ${bid['price']} — {bid['size']} shares")

print("\nTop 5 asks (sell orders):")
for ask in book["asks"][:5]:
    print(f"  ${ask['price']} — {ask['size']} shares")

Working with the Response

The return value is already a plain Python dict — no model_dump() needed (that was a V1-era assumption). Read the inline trading parameters directly:

book = client.get_order_book("TOKEN_ID")

print(book["bids"][0])        # {'price': '0.55', 'size': '1200.0'}
print(book["tick_size"])      # '0.01'
print(book["min_order_size"]) # e.g. '5'
print(book["neg_risk"])       # False

Batch Retrieval: get_order_books()

Fetch order books for multiple tokens in a single API call. This is significantly more efficient than calling get_order_book() in a loop.

Signature

client.get_order_books(params: list[BookParams]) -> list[dict]

Parameters

Parameter	Type	Required	Description
`params`	`list[BookParams]`	Yes	List of BookParams, each specifying a `token_id`

Example

from py_clob_client_v2 import ClobClient, BookParams

client = ClobClient(host="https://clob.polymarket.com", chain_id=137)

books = client.get_order_books([
    BookParams(token_id="YES_TOKEN_ID"),
    BookParams(token_id="NO_TOKEN_ID"),
])

for book in books:
    best_bid = book["bids"][0]["price"] if book["bids"] else "none"
    best_ask = book["asks"][0]["price"] if book["asks"] else "none"
    print(f"Token {book['asset_id'][:16]}... | Best bid: {best_bid} | Best ask: {best_ask}")

Spread Calculation

The bid-ask spread is the difference between the lowest ask and the highest bid. A narrow spread indicates high liquidity.

from py_clob_client_v2 import ClobClient

client = ClobClient(host="https://clob.polymarket.com", chain_id=137)

book = client.get_order_book("TOKEN_ID")

if book["bids"] and book["asks"]:
    best_bid = float(book["bids"][0]["price"])
    best_ask = float(book["asks"][0]["price"])
    spread = best_ask - best_bid
    midpoint = (best_bid + best_ask) / 2

    print(f"Best bid:  ${best_bid:.4f}")
    print(f"Best ask:  ${best_ask:.4f}")
    print(f"Spread:    ${spread:.4f}")
    print(f"Midpoint:  ${midpoint:.4f}")
    print(f"Spread %:  {spread / midpoint * 100:.2f}%")
else:
    print("Order book is empty on one or both sides")

You can also use the built-in helper methods:

# Quick price check (no order book parsing needed)
mid = client.get_midpoint(token_id="TOKEN_ID")
buy_price = client.get_price(token_id="TOKEN_ID", side="BUY")
sell_price = client.get_price(token_id="TOKEN_ID", side="SELL")
spread = client.get_spread(token_id="TOKEN_ID")

Order Book Depth Analysis

Calculating available liquidity at different price levels is essential for sizing orders:

from py_clob_client_v2 import ClobClient

client = ClobClient(host="https://clob.polymarket.com", chain_id=137)
book = client.get_order_book("TOKEN_ID")

def calculate_depth(orders, levels=10):
    """Calculate cumulative depth for the top N price levels."""
    cumulative = 0.0
    depth = []
    for order in orders[:levels]:
        size = float(order["size"])
        price = float(order["price"])
        cumulative += size
        depth.append({
            "price": price,
            "size": size,
            "cumulative": cumulative,
            "notional": cumulative * price
        })
    return depth

bid_depth = calculate_depth(book["bids"])
ask_depth = calculate_depth(book["asks"])

print("Bid depth (top 10 levels):")
for level in bid_depth:
    print(f"  ${level['price']:.2f} | {level['size']:.0f} shares | "
          f"cumulative: {level['cumulative']:.0f} | "
          f"${level['notional']:.2f} notional")

Method	What It Returns	Auth Required
`get_order_book(token_id)`	Full order book (bids + asks)	No
`get_order_books([BookParams])`	Multiple order books in one call	No
`get_price(token_id, side)`	Best price for BUY or SELL side	No
`get_midpoint(token_id)`	Midpoint between best bid and ask	No
`get_spread(token_id)`	Bid-ask spread	No

For order placement methods that interact with the order book, see create_order().

Common Errors

Error	Cause	Fix
`Invalid token ID`	Token ID doesn’t exist or is malformed	Verify the token ID from the Gamma API (`clobTokenIds` on `GET /markets`)
Empty bids/asks	Market has no resting orders on one side	Check `len(book["bids"])` and `len(book["asks"])` before accessing indices
`ConnectionError`	CLOB API is unreachable	Retry with exponential backoff. Check Polymarket status
`429 Too Many Requests`	Rate limit exceeded	Back off and retry. See the Rate Limits Guide
Stale data	Order book snapshot may be milliseconds old	For real-time data, use the WebSocket feed

Frequently Asked Questions

What does py_clob_client get_order_book return?

In CLOB V2 (py-clob-client-v2), get_order_book(token_id) returns the raw JSON dict — not a Pydantic model. Access it with dict syntax: book['bids'] and book['asks'] (each entry is a {price, size} dict). The dict also includes market, asset_id, timestamp, min_order_size, neg_risk, tick_size, last_trade_price, and hash.

What is OrderBookSummary in py_clob_client?

OrderBookSummary is a dataclass in py-clob-client-v2 that mirrors the order book JSON shape (market, asset_id, timestamp, bids, asks, min_order_size, neg_risk, tick_size, last_trade_price, hash). Note get_order_book() returns the raw dict; the OrderBookSummary dataclass is used internally (e.g. by get_order_book_hash). Access fields with dict syntax on the returned value.

How do I get order books for multiple tokens at once?

Use client.get_order_books() with a list of BookParams objects (import BookParams from py_clob_client_v2). Each BookParams takes a token_id. This is more efficient than calling get_order_book() in a loop because it batches the request into a single API call.

How do I calculate the spread from a Polymarket order book?

Fetch the order book with get_order_book(token_id), then compute spread = float(book['asks'][0]['price']) - float(book['bids'][0]['price']). The spread is the difference between the lowest ask (cheapest sell) and the highest bid (best buy offer). Or just call client.get_spread(token_id).

Does get_order_book require authentication?

No. get_order_book() is a public endpoint that works without authentication. You only need a ClobClient initialized with the host URL and chain_id (chain_id is required in CLOB V2) — no private key or API credentials required.

What is the difference between get_order_book and get_price?

get_order_book(token_id) returns the full order book with all bids and asks at every price level. get_price(token_id, side) returns only the best available price for a given side (BUY or SELL). Use get_order_book for depth analysis and get_price for quick price checks.

Method Signature

Parameters

Return Type

Basic Example

Working with the Response

Batch Retrieval: get_order_books()

Signature

Parameters

Example

Spread Calculation

Order Book Depth Analysis

Related Methods

Common Errors

See Also

Frequently Asked Questions