{"id":2833,"date":"2026-04-16T10:00:00","date_gmt":"2026-04-16T10:00:00","guid":{"rendered":"https:\/\/oddspapi.io\/blog\/?p=2833"},"modified":"2026-10-15T13:17:37","modified_gmt":"2026-10-15T13:17:37","slug":"polymarket-api-gamma-clob-json-format","status":"publish","type":"post","link":"https:\/\/oddspapi.io\/blog\/polymarket-api-gamma-clob-json-format\/","title":{"rendered":"Polymarket API: Trace 28 NFL Tokens From Gamma to CLOB"},"content":{"rendered":"
Polymarket Has Two APIs, and the Order Book Reads Upside Down<\/h2>\n
Search polymarket api<\/code> and you land on two subdomains and a docs site that assumes you know what a condition ID<\/em> is. Polymarket splits its public data across two services. Gamma<\/strong> is the catalogue. CLOB<\/strong> is the order book. They do not share a schema, and you need both.<\/p>\n
This post maps the two services with payloads captured on 15 October 2026. It then traces one token from Gamma to CLOB to a decimal-odds feed. We ran that trace on all 14 NFL Week 7 fixtures, 28 outcomes in total, and every top-of-book price and size matched to the share. You will learn:<\/p>\n
\n
What Gamma and CLOB each return, and which one holds the number you want.<\/li>\n
Three parser traps we hit on live data: the stringified arrays, the worst-first order book, and a \/price<\/code> endpoint whose BUY<\/code> side returns the bid.<\/li>\n
How to convert share prices (0 to 1) to decimal odds and back.<\/li>\n
How to pull Polymarket next to Pinnacle and bet365 in one call, then check that feed against CLOB yourself.<\/li>\n<\/ul>\n
Reads need no key and no wallet. You only need requests<\/code>.<\/p>\n
The Landscape: Gamma vs CLOB<\/h2>\n
Polymarket settles on Polygon, but you do not query the chain. Two off-chain APIs wrap the market state:<\/p>\n
Discovery: events, markets, metadata, volume, mid price. The catalogue.<\/td>\n
None<\/td>\n<\/tr>\n
\n
CLOB<\/strong><\/td>\n
https:\/\/clob.polymarket.com<\/code><\/td>\n
Order book depth, best bid and ask, midpoint, price history, order placement.<\/td>\n
None for reads. Signed EIP-712 payloads plus L2 headers for writes.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\n
Rule of thumb: Gamma tells you what exists. CLOB tells you what you can trade at.<\/strong> Most developers start at CLOB and then stall, because every CLOB endpoint wants a 77-digit token_id<\/code>. Gamma hands you the token IDs.<\/p>\n
The four ID types<\/h3>\n
\n
\n\n
\n
ID<\/th>\n
Example (Chargers v Chiefs)<\/th>\n
Where it comes from<\/th>\n
What it refers to<\/th>\n<\/tr>\n<\/thead>\n
\n
\n
Event slug<\/strong><\/td>\n
nfl-lac-kc-2026-10-18<\/code><\/td>\n
Gamma \/events<\/code><\/td>\n
The fixture. This event holds 308 markets: moneyline, spreads, totals.<\/td>\n<\/tr>\n
\n
Market ID<\/strong><\/td>\n
4329891<\/code><\/td>\n
Gamma \/markets<\/code><\/td>\n
One question, here “Chargers vs. Chiefs”.<\/td>\n<\/tr>\n
\n
Condition ID<\/strong><\/td>\n
0xa70da744\u2026b546<\/code><\/td>\n
Gamma markets[].conditionId<\/code><\/td>\n
The on-chain market hash. CLOB returns it as market<\/code>.<\/td>\n<\/tr>\n
\n
Token ID<\/strong> (asset_id<\/code>)<\/td>\n
58167714289864\u2026<\/code> (77 digits)<\/td>\n
Gamma markets[].clobTokenIds<\/code><\/td>\n
One outcome. Every CLOB endpoint wants this.<\/strong><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\n
A two-way market has one condition ID and two token IDs. On an NFL moneyline the tokens are the two participants, not Yes and No.<\/p>\n
Gamma API: The Catalogue<\/h2>\n
Gamma is plain REST. You will use \/markets<\/code> and \/events<\/code> most of the time.<\/p>\n
Listing active markets<\/h3>\n
import requests, json\n\nGAMMA = \"https:\/\/gamma-api.polymarket.com\"\n\nr = requests.get(f\"{GAMMA}\/markets\", params={\n \"limit\": 3,\n \"active\": \"true\",\n \"closed\": \"false\",\n})\nfor m in r.json():\n # outcomes \/ outcomePrices \/ clobTokenIds are stringified JSON arrays\n outcomes = json.loads(m[\"outcomes\"])\n prices = json.loads(m[\"outcomePrices\"])\n tokens = json.loads(m[\"clobTokenIds\"])\n print(m[\"question\"])\n for o, p, t in zip(outcomes, prices, tokens):\n print(f\" {o}: {p} (token {t[:12]}...)\")\n<\/code><\/pre>\n
Output on 15 October 2026:<\/p>\n
Xi Jinping out before 2027?\n Yes: 0.0285 (token 323382201900...)\n No: 0.9715 (token 256593106749...)\nWill Gavin Newsom win the 2028 Democratic presidential nomination?\n Yes: 0.1545 (token 545330438199...)\n No: 0.8455 (token 878541741480...)\nWill Alexandria Ocasio-Cortez win the 2028 Democratic presidential nomination?\n Yes: 0.1685 (token 107064985435...)\n No: 0.8315 (token 651760722613...)\n<\/code><\/pre>\n
Trap 1: the stringified arrays.<\/strong> Gamma ships outcomes<\/code>, outcomePrices<\/code> and clobTokenIds<\/code> as JSON inside<\/em> strings. Skip the json.loads<\/code> and you iterate over characters, so the first outcome becomes the letter [<\/code>.<\/p>\n
The Chiefs moneyline as Gamma returns it (captured 15 Oct 2026, 13:13 UTC, trimmed from 90+ keys):<\/p>\n
Three details matter here. outcomePrices<\/code> holds the midpoint<\/strong> (0.785 for the Chiefs), not a price you can fill. bestBid<\/code> and bestAsk<\/code> belong to the first<\/strong> outcome only, so 0.21 \/ 0.22 is the Chargers. And Gamma lists the away participant first<\/strong>: “Chargers vs. Chiefs” for a Chiefs home fixture. Gamma did this on 14 of 14 Week 7 fixtures. If you zip Gamma outcomes against a feed that puts the home side first, you flip every price. Match on the token ID, never on position.<\/p>\n
Finding an event from its slug<\/h3>\n
import requests\n\nGAMMA = \"https:\/\/gamma-api.polymarket.com\"\n\n# fixturePath from OddsPapi ends in the Gamma event slug\nev = requests.get(f\"{GAMMA}\/events\", params={\"slug\": \"nfl-lac-kc-2026-10-18\"}).json()[0]\nprint(ev[\"title\"], \"|\", len(ev[\"markets\"]), \"markets\")\nfor m in ev[\"markets\"][:4]:\n print(\" -\", m[\"question\"], \"| condition\", m[\"conditionId\"][:10] + \"...\")\n<\/code><\/pre>\n
active=true&closed=false<\/code> filters to tradeable markets. active<\/code> alone still returns resolved ones.<\/li>\n
Market volume<\/code> is a string, but event volume<\/code> is a number. Wrap both in float()<\/code> before you sort.<\/li>\n
\/markets?clob_token_ids=<token><\/code> takes you from a token back to its market. It resolved 28 of 28 NFL tokens in our run.<\/li>\n
Paginate with limit<\/code> and offset<\/code>, and do not assume a stable order between calls.<\/li>\n<\/ul>\n
CLOB API: The Order Book<\/h2>\n
CLOB serves depth and history for one token at a time. Read endpoints need no auth.<\/p>\n
import requests\n\nCLOB = \"https:\/\/clob.polymarket.com\"\nCHIEFS = \"58167714289864717825087991545150213770744040987591942526721915426213133665357\"\n\nbook = requests.get(f\"{CLOB}\/book\", params={\"token_id\": CHIEFS}).json()\n# both sides arrive worst-first: the touch is the LAST element\nbest_bid, best_ask = book[\"bids\"][-1], book[\"asks\"][-1]\nprint(\"tick\", book[\"tick_size\"], \"| min order\", book[\"min_order_size\"], \"| neg_risk\", book[\"neg_risk\"])\nprint(\"best bid\", best_bid, \"| best ask\", best_ask)\n\n# side=BUY returns the best BID, side=SELL the best ASK\nbuy = requests.get(f\"{CLOB}\/price\", params={\"token_id\": CHIEFS, \"side\": \"BUY\"}).json()\nsell = requests.get(f\"{CLOB}\/price\", params={\"token_id\": CHIEFS, \"side\": \"SELL\"}).json()\nmid = requests.get(f\"{CLOB}\/midpoint\", params={\"token_id\": CHIEFS}).json()\nprint(\"BUY\", buy[\"price\"], \"| SELL\", sell[\"price\"], \"| mid\", mid[\"mid\"])\n\nhist = requests.get(f\"{CLOB}\/prices-history\", params={\n \"market\": CHIEFS, # named \"market\", takes a token_id\n \"interval\": \"1d\",\n \"fidelity\": \"60\", # 60-minute buckets\n}).json()[\"history\"]\nprint(len(hist), \"points, first\", hist[0])\n<\/code><\/pre>\n
tick 0.01 | min order 5 | neg_risk False\nbest bid {'price': '0.78', 'size': '39472.87'} | best ask {'price': '0.79', 'size': '2495.56'}\nBUY 0.78 | SELL 0.79 | mid 0.785\n24 points, first {'t': 1791986416, 'p': 0.785}\n<\/code><\/pre>\n
Trap 2: the book reads worst-first.<\/strong> bids<\/code> run from 0.01 up to 0.78, and asks<\/code> run from 0.99 down to 0.79. The first rows you print are deep, far-from-the-money orders. The touch sits at index -1<\/code> on both sides. Every number is a string, so cast before you do math.<\/p>\n
Trap 3: side=BUY<\/code> returns the bid.<\/strong> The side<\/code> names the resting orders, not your trade. If you want to buy the Chiefs now, you pay the SELL<\/code> price, 0.79. A bot that reads BUY<\/code> as “my cost to buy” quotes one tick too cheap on every market.<\/p>\n
\/prices-history<\/code> returns {t, p}<\/code> points, where p<\/code> is the midpoint. interval<\/code> accepts 1h<\/code>, 6h<\/code>, 1d<\/code>, 1w<\/code>, 1m<\/code> and max<\/code>. fidelity<\/code> is the bucket size in minutes.<\/p>\n