Polymarket's order book arrives worst-first

Ask Polymarket's CLOB for a book and you get something that looks obvious and is not:

curl -s "https://clob.polymarket.com/book?token_id=<token>" | jq '.bids[0], .asks[0]'

bids[0] is the worst bid on the book, and asks[0] is the worst ask. The ladders are sorted away from the touch: bids ascend toward the best, asks descend toward it. The best levels are at the end of each array.

Why it bites

Every prior a language model has says index zero is the top of book. An agent that reads bids[0].price as the best bid will quote a price that is often several cents away from the market, and will size against depth that is not where it thinks it is. The error is silent: the numbers are real prices from a real book, just the wrong end of it.

What the correct read looks like

Take the last element of each ladder for the touch, and walk from the touch inward when you need more than the top level:

book = requests.get(url, params={"token_id": token}).json()
best_bid = float(book["bids"][-1]["price"])   # not [0]
best_ask = float(book["asks"][-1]["price"])   # not [0]

A size question is a different question again. "What does 200 shares cost" is not the best ask times 200; it is a walk down the ladder until the size is filled, and the average is what you actually pay.

What oddsrail does

Both venues are normalised to best-first, and quote_cost walks the book for a real size and returns the average price, the slippage against the touch, and whether the book can fill it at all. The agent never sees a raw ladder and never has to remember which way it points.

pip install oddsrail
python examples/footguns.py     # section 1 prints the raw book next to the normalised one

Found by driving the venues live, then encoded so an agent never rediscovers it. Reproduce every one of these with no keys: pip install oddsrail && python examples/footguns.py (source).

Try an agent that knows all six All notes