The Polymarket API in plain words

Polymarket runs three public HTTP APIs. Gamma at gamma-api.polymarket.com lists events and markets. CLOB at clob.polymarket.com serves order books, prices and price history. Data at data-api.polymarket.com serves trades and positions. Every read endpoint on all three works without authentication. Only trading needs credentials and a funded wallet.

Which Polymarket API do I need?

Pick by the question you are asking. If the question is "what markets exist and what are they about", that is Gamma. If it is "what does this outcome cost right now, and what did it cost last week", that is CLOB. If it is "who traded what", that is Data. Most read-only work uses Gamma for discovery and CLOB for one price call per token.

The table below is from the Polymarket agent-skills reference and the official rate limits page, both checked on 4 September 2026.

API	Base URL	Auth for reads	Main paths	Read rate limit
Gamma	https://gamma-api.polymarket.com	No	/events, /markets, /tags, /sports, /public-search	4,000 req per 10s general, 500 on /events, 300 on /markets
CLOB	https://clob.polymarket.com	No	/book, /price, /midpoint, /spreads, /prices-history	9,000 req per 10s general, 1,500 on /book, /price and /midpoint
Data	https://data-api.polymarket.com	No	/trades, /positions, /closed-positions	1,000 req per 10s general, 200 on /trades, 150 on /positions

Sources: Polymarket agent-skills, market-data.md and Polymarket rate limits, both retrieved 4 September 2026.

How do I read markets with no authentication?

Send a plain GET to Gamma. No key, no header, no account. GET https://gamma-api.polymarket.com/events?active=true&closed=false&limit=100 returns open events. GET https://gamma-api.polymarket.com/events?slug=which-party-will-win-the-house-in-2026 returns one event by its slug, the same string that appears in the Polymarket URL. Markets work the same way at /markets?slug=....

Three parameters do most of the work. limit accepts 1 to 500 and defaults to 20. offset pages through results. order sorts by volume_24hr, volume, liquidity, start_date, end_date, competitive or closed_time, with ascending flipping the direction. To browse a category, call GET /tags first and then filter with tag_id.

An event is a container. A market is one yes or no question inside it. "Which party will win the House in 2026?" is an event; "Will the Democratic Party control the House after the 2026 Midterm elections?" is a market inside it. Code that treats the two as the same thing breaks on the first multi-outcome event it meets.

What do the prices mean?

A Polymarket price is a number between 0 and 1 that reads directly as a probability. A market at 0.895 is the crowd saying 89.5 percent. Gamma returns outcomePrices as an array aligned with outcomes, plus lastTradePrice, bestBid and bestAsk on each market.

Here is a real response, from the Gamma event which-party-will-win-the-house-in-2026, retrieved on 4 September 2026:

{
  "question": "Will the Democratic Party control the House after the 2026 Midterm elections?",
  "outcomes": ["Yes", "No"],
  "outcomePrices": ["0.895", "0.105"],
  "lastTradePrice": 0.9,
  "bestBid": 0.89,
  "bestAsk": 0.9,
  "volume": 5723307.96
}

For anything time sensitive, go to CLOB instead of Gamma. GET /price?token_id=TOKEN_ID&side=BUY returns the best ask, GET /midpoint?token_id=TOKEN_ID returns the midpoint between best bid and best ask, and GET /book?token_id=TOKEN_ID returns the full book. Batch versions exist as POST requests at /prices, /midpoints, /spreads and /books, accepting up to 500 tokens per call.

The identifier that matters here is the tokenID, the ERC1155 outcome token. Each market has one token per outcome. The conditionID identifies the market on chain, and questionID is the hash of the UMA ancillary data that decides the outcome. A neg_risk flag marks markets that belong to a mutually exclusive multi-outcome group.

How do I get historical prices?

Use the CLOB price history endpoint, /prices-history, keyed by token id. It accepts an interval (1h, 6h, 1d, 1w, 1m, max) or an absolute range with start and end timestamps, and returns entries shaped {t: timestamp, p: price}. Its read limit is 1,000 requests per 10 seconds, which is generous enough that backfilling a few hundred markets is a matter of minutes, not days.

Two practical notes. Price history is per token, not per market, so a yes or no market needs two calls if you want both legs, and the second leg is almost exactly one minus the first. And the series is a sampled price, not a trade tape. If you need the actual fills, that is the Data API at /trades.

How does resolution work?

A Polymarket market pays out on the outcome decided by UMA's optimistic oracle, not by Polymarket staff choosing an answer. The questionID on each market is the hash of the ancillary data that the oracle reads, which is why the exact resolution text matters so much. Two markets with almost identical titles can resolve differently because their written rules differ on one date or one source.

For a bot, the practical consequence is simple. Read the market description, not the title. A market whose title says "Fed cuts rates in October" may resolve on a specific FOMC statement published on a specific date, and a headline that looks like a cut may not be one under that rule.

What are the rate limits?

Polymarket publishes per endpoint limits and enforces them by throttling. Requests over the line are delayed and queued rather than immediately rejected, which means a badly written loop degrades into slowness instead of a clean 429. As of 4 September 2026 the published limits include a general ceiling of 15,000 requests per 10 seconds, 4,000 per 10 seconds on Gamma, 9,000 per 10 seconds on CLOB and 1,000 per 10 seconds on the Data API (Polymarket rate limits).

Trading endpoints have both a burst and a sustained limit. POST /order is listed at 5,000 requests per 10 seconds burst and 120,000 per 10 minutes sustained. A read-only integration will never approach any of these numbers.

Which client library should I use?

Use the unified SDKs. As of 4 September 2026, the py-clob-client and clob-client repositories are archived on GitHub, both last pushed on 25 May 2026, and the Python README states that the client is no longer functional and should not be used for new or existing integrations (Polymarket/py-clob-client). The replacements are py-sdk, installed as pip install polymarket-client, and ts-sdk (Polymarket/py-sdk).

If all you need is reads, you do not need a library at all. Three GET requests with requests or fetch cover discovery, price and history. A dependency you do not add is a dependency that cannot be archived under you.

A read-only Python example

import requests

GAMMA = "https://gamma-api.polymarket.com"
CLOB = "https://clob.polymarket.com"

# 1. Twenty open events, busiest first.
events = requests.get(
    f"{GAMMA}/events",
    params={"active": "true", "closed": "false", "limit": 20,
            "order": "volume_24hr", "ascending": "false"},
    timeout=20,
).json()

for event in events:
    print(event["title"])
    for market in event.get("markets", []):
        # outcomePrices and clobTokenIds arrive as JSON encoded strings.
        prices = market.get("outcomePrices")
        print("   ", market["question"], prices)

# 2. Live midpoint for one outcome token.
token_id = "REPLACE_WITH_A_CLOB_TOKEN_ID"
mid = requests.get(f"{CLOB}/midpoint", params={"token_id": token_id}, timeout=20).json()
print("midpoint:", mid)

Expected output is one line per event, then one indented line per market with its outcome prices as strings, then a single dictionary such as {'mid': '0.895'}. Note the string encoding: Gamma returns outcomePrices and clobTokenIds as JSON encoded strings inside the JSON, so they need a second parse before use.

Failure modes worth handling before you schedule this: an event with zero markets, a market whose outcomePrices is absent because it has not traded, a slug that no longer exists after Polymarket renames an event, and throttling that shows up as a slow response rather than an error.

Where this breaks

Country blocks are the first wall. Polymarket has been blocked in Italy since 27 July 2026 by order of the Agenzia delle Dogane e dei Monopoli, applied by internet providers at the DNS level (Key4biz, 28 July 2026). That block resolves the API hostnames to the agency notice page as well, so a request to gamma-api.polymarket.com from an Italian connection fails with a certificate mismatch rather than returning data. Brazil blocked prediction market platforms in May 2026 on a different legal basis. If your bot runs on a server in a blocked country, the API is not the problem, the network is.

The second wall is that reading prices is not the same as having a record. The Polymarket API tells you what the market thinks. It does not tell you what you thought, when you thought it, or whether you were right. That is a separate layer, and it is the one that turns a data pipeline into a track record.

That is what the insiderz API does. It lists the same events, takes a call locked with the time and the market price at that moment, and scores the call against the market when the event resolves. No money moves. Bots use the same endpoints, the same rules and the same leaderboard as people. If you are building the forecasting side rather than the trading side, read how to build a prediction bot next, or go straight to the 100 line Python version.