Half the broken Polymarket bots I've seen fail because the dev used the wrong API for the wrong job

Gamma API and CLOB API are two completely different layers

Here's exactly what each one does -and how to connect them correctly in your bot

> Gamma API - market discovery

Public. No auth required. No wallet needed

This is where you find markets, read prices, get metadata. Key endpoints:

• GET gamma-api.polymarket.com/markets?conditionId={conditionId} - single market details (recommended, returns object)
• GET gamma-api.polymarket.com/markets?ids={conditionId} - market details (returns array)
• GET gamma-api.polymarket.com/events?slug={slug} - event by slug + all markets inside
• GET gamma-api.polymarket.com/events/slug/{slug} - direct event access (even cleaner)
• GET gamma-api.polymarket.com/markets?tag_id={id}&active=true - active markets by category
• GET gamma-api.polymarket.com/public-search?q=?{query} - market search (use q= only)

Most important field in the response:

clobTokenIds[] - array of two token IDs
clobTokenIds[0] = YES token
clobTokenIds[1] = NO token

These are your bridge to trading

> CLOB API - trade execution

• GET clob.polymarket.com/book?token_id={id} - live order book
• GET clob.polymarket.com/price?token_id={id}&side=buy - best available price
• GET clob.polymarket.com/midpoint?token_id={id} - midpoint price
• GET clob.polymarket.com/spread?token_id={id} - spread
• GET clob.polymarket.com/last-trade-price?token_id={id} - last trade price
• GET clob.polymarket.com/fee-rate?token_id={id} - fee rate
• GET clob.polymarket.com/tick-size?token_id={id} - tick size
• GET clob.polymarket.com/time - server time (for nonce)

Only trading endpoints require auth (POST /order, cancels, etc.)

> Correct two-step flow

# Step 1: Gamma - get metadata + token IDs

r = requests.get(f"gamma-api.polymarket.com/markets?conditionId={market_condition_id}")
data = r.json()
token_id_yes = data["clobTokenIds"][0]

# Step 2: CLOB - read endpoints work without auth

price_resp = requests.get(f"clob.polymarket.com/price?token_id={token_id_yes}&side=buy")
price = float(price_resp.json()["price"])

You cannot place orders with conditionId. CLOB only understands token_id.

> Right bot architecture:

Gamma for discovery → CLOB for execution (and now all market data reads are public)

If your bot is broken = 90% of the time you’re either hitting the wrong endpoint on Gamma or using outdated assumptions about CLOB auth

Save this - it’s 100% synced with official docs