MercadoDice

Polymarket API guide: read markets and prices with no API key

Polymarket's Gamma API is public and needs no key. Endpoints, parameters, how to parse outcomePrices and pull price history, with curl and JavaScript examples.

By Matías MardonesUpdated on October 25, 20266 min read

The short answer

Polymarket’s read API is public: the Gamma API (https://gamma-api.polymarket.com) needs no key and no sign-up. You can list events and markets, sort them by volume and read their prices. Price history comes from a second API, the CLOB API (https://clob.polymarket.com). Trading through the API is a different matter: it requires signing with a wallet and your own API keys. The full reference lives at docs.polymarket.com.

The two Polymarket APIs

API Base URL What you use it for Key needed?
Gamma https://gamma-api.polymarket.com Events, markets, search, tags No
CLOB https://clob.polymarket.com Price history; orders and trading Not for price history. Yes for trading

If events, markets and contracts are still fuzzy, start with what Polymarket is.

Gamma API endpoints

Endpoint Returns
GET /events A list of events
GET /events/{id} A single event
GET /markets A list of markets
GET /markets/{id} A single market
GET /public-search Text search results
GET /tags Tags or categories
GET /series Recurring event series
GET /sports Sports
GET /teams Teams

Common parameters

Parameter Use
active true for live markets
closed false to leave out closed ones
archived Include or exclude archived items
order Field to sort by, for example volume24hr
ascending false for highest first
limit Results per page
offset Where to start (pagination)

Listing events by volume

With curl, the ten active events with the most volume in the last 24 hours:

curl "https://gamma-api.polymarket.com/events?active=true&closed=false&order=volume24hr&ascending=false&limit=10"

Before you build on a field, print one full response and see what is actually there.

Using the Polymarket API with Python

With the requests library (pip install requests), this minimal script fetches the five active markets with the most volume today and prints the probability of each outcome:

import json
import requests

BASE = "https://gamma-api.polymarket.com"
params = {"active": "true", "closed": "false",
          "order": "volume24hr", "ascending": "false", "limit": 5}

r = requests.get(f"{BASE}/markets", params=params, timeout=10)
r.raise_for_status()

for m in r.json():
    outcomes = json.loads(m["outcomes"])
    prices = [float(p) for p in json.loads(m["outcomePrices"])]
    print(m["question"])
    for o, p in zip(outcomes, prices):
        print(f"  {o}: {p * 100:.1f}%")

You need json.loads for the reason explained in the next section: those fields arrive as strings.

Reading outcomes, outcomePrices and clobTokenIds

Every Gamma market includes, among others, these fields:

Field Contains
outcomes The possible results, for example “Yes” and “No”
outcomePrices The price of each result, between 0 and 1
clobTokenIds The token IDs used by the CLOB API
volumeNum Market volume as a number
oneDayPriceChange Price change over the last day
groupItemTitle Short label for the market inside its event
image Market image

The detail that trips almost everyone up: outcomes and outcomePrices arrive as JSON arrays stored as strings. You get "[\"Yes\", \"No\"]", not an array. Parse it:

const parse = (v) => (typeof v === 'string' ? JSON.parse(v) : v);

const res = await fetch(
  'https://gamma-api.polymarket.com/markets?active=true&closed=false&order=volume24hr&ascending=false&limit=5'
);
const markets = await res.json();

for (const m of markets) {
  const outcomes = parse(m.outcomes);
  const prices = parse(m.outcomePrices).map(Number);
  const tokens = parse(m.clobTokenIds);
  outcomes.forEach((o, i) => {
    console.log(`${o}: ${(prices[i] * 100).toFixed(1)}%  token=${tokens?.[i]}`);
  });
}

An outcome’s price is the probability the market assigns to it: 0.62 means 62%. Match each outcome to its price and token by position, and confirm on a real response that the order lines up before relying on it. The parse helper works whether a field arrives as a string or already as an array.

Price history from the CLOB API

History is requested per token, not per market. Use one of the values from clobTokenIds:

curl "https://clob.polymarket.com/prices-history?market=TOKEN_ID&interval=1w&fidelity=60"
  • market: the token ID.
  • interval: 1d, 1w or 1m.
  • fidelity: resolution of the series, in minutes.

In JavaScript:

async function priceHistory(tokenId, interval = '1w', fidelity = 60) {
  const url = new URL('https://clob.polymarket.com/prices-history');
  url.search = new URLSearchParams({ market: tokenId, interval, fidelity: String(fidelity) });
  const res = await fetch(url);
  if (!res.ok) throw new Error(`CLOB API returned ${res.status}`);
  return res.json();
}

const data = await priceHistory('TOKEN_ID');
console.log(JSON.stringify(data, null, 2));

As with Gamma, print the response and check its shape before you chart it.

Polymarket API rate limits

The official docs publish per-IP limits over 10-second windows (Rate Limits). For the Gamma API, as of 25 October 2026:

Endpoint Limit
General 4,000 requests / 10 s
/events 500 / 10 s
/markets 300 / 10 s
/public-search 350 / 10 s

Go over them and requests are throttled (delayed or queued) rather than rejected outright. The figures change, so check that page.

Good practice

  • Cache. For almost any read-only use, storing the response for a few minutes and serving it from your cache is enough.
  • Do not hammer the API. No tight loops, no hundreds of parallel requests.
  • Paginate with limit and offset instead of asking for everything at once.
  • Handle errors. Check res.ok, retry with increasing back-off and keep your page alive when the API is slow.
  • Show context. A price on a market with low volumeNum says little. If you publish probabilities, show the volume and the time of the query too. You can see live prices on our markets board.

A note on trading through the API

The CLOB API can also create and cancel orders, but that requires signing with your wallet and using API keys. We do not cover it here. Keep two things in mind: countries in close-only mode are close-only on the API as well as the website, and automating a strategy does not make it profitable. Before you think about a bot, read strategies and risks and the fees guide: every taker trade pays according to its category.

Frequently asked questions

Do I need an API key for the Polymarket API?

Not to read events, markets and prices through the Gamma API, and not to request price history from the CLOB API. Keys are only needed to trade.

What is the Polymarket API rate limit?

According to the official docs, the Gamma API allows 4,000 requests every 10 seconds per IP in general, with lower limits per endpoint (300 for /markets). Above that, requests are throttled.

Which ID do I use to get a market’s price history?

The token ID of the outcome you care about, taken from clobTokenIds. Each outcome has its own token and its own price series.

Can I build a trading bot with the Polymarket API?

Technically yes, but trading requires wallet signing and keys, and country restrictions apply to the API too. A bot guarantees nothing.

Keep reading