Polymarket Gamma API Deep Dive: Market Discovery, Price History, and Backtesting

Overview

The Gamma API is Polymarket’s market discovery layer. Hosted at gamma-api.polymarket.com, it indexes every event, market, tag, and sports category on the platform. No authentication is required — you can start querying immediately.

Use the Gamma API to:

• Discover markets by category, volume, liquidity, or keyword search
• Get token IDs and condition IDs needed for CLOB trading
• Build scanners that surface high-volume or mispriced markets
• Retrieve event structures to understand how multi-outcome questions decompose into binary markets

The Gamma API is read-only. It does not support placing orders, streaming prices, or querying on-chain balances. For those capabilities, you need the CLOB API, WebSocket feeds, or the Subgraph.

When to Use Which API

Polymarket exposes several APIs, each optimized for a different use case. The Gamma API is the starting point for nearly every workflow because it is where you discover markets and retrieve the identifiers needed by other APIs.

A typical workflow looks like this: query the Gamma API to find a market, extract its token IDs, then pass those token IDs to the CLOB API for live prices, order placement, or historical data.

Data Model

Understanding the relationship between Events and Markets is essential before working with any endpoint.

Events

Events are top-level questions. An event like “Who will win the 2024 Presidential Election?” groups together all the individual tradable outcomes under a single umbrella.

Each event has:

• A unique numeric ID and a URL-friendly slug
• A title and description describing the question
• One or more Markets as sub-outcomes
• Tags for categorization (e.g., “politics”, “crypto”, “sports”)
• Metadata like startDate, endDate, and volume

Markets

Markets are the tradable binary outcomes within events. Each market represents a single Yes/No question with its own order book and pricing.

Each market has:

• conditionId — the unique identifier for CTF (Conditional Token Framework) contracts on-chain
• questionId — a hash of the market question used by the resolution oracle
• clobTokenIds — an array of two token IDs, one for the Yes outcome and one for No (ERC-1155 tokens)
• outcomes and outcomePrices — parallel arrays mapped 1:1, so outcomes[0] corresponds to outcomePrices[0]
• enableOrderBook — a boolean indicating whether CLOB trading is available for this market
• volume — total trading volume in USDC
• liquidity — current liquidity depth

A single event can contain many markets. For example, an election event might have separate markets for each candidate, each independently tradable.

Slugs

Slugs are URL-friendly identifiers like fed-decision-in-october or bitcoin-above-100k-2025. You can use slugs to query both the /events and /markets endpoints, which is convenient when building integrations that reference markets by their human-readable names rather than numeric IDs.

Endpoint Reference

All endpoints are prefixed with https://gamma-api.polymarket.com. Responses are JSON.

GET /events

Retrieve a list of events with optional filtering, sorting, and pagination.

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

Returns an array of event objects, each containing a nested markets array with full market details.

GET /events/{id}

Retrieve a single event by its numeric ID.

curl "https://gamma-api.polymarket.com/events/12345"

Returns the full event object including all child markets, tags, and metadata.

GET /markets

Retrieve a list of markets with optional filtering. Useful when you want to query across events or find specific markets by condition ID.

curl "https://gamma-api.polymarket.com/markets?active=true&limit=10"

GET /markets/{id}

Retrieve a single market by its numeric ID or condition ID.

curl "https://gamma-api.polymarket.com/markets/67890"

Returns the full market object with token IDs, prices, outcomes, volume, and all metadata.

GET /public-search

Full-text search across events and markets. This is the best endpoint for keyword-based discovery.

curl "https://gamma-api.polymarket.com/public-search?query=bitcoin&limit=10"

Returns matching events and markets ranked by relevance.

GET /tags, /series, /sports, /teams

Categorization endpoints for browsing the market taxonomy:

• /tags — returns all available category tags (politics, crypto, sports, etc.)
• /series — returns event series (e.g., recurring monthly predictions)
• /sports — returns sports categories for sports-specific markets
• /teams — returns team entities linked to sports markets

These are useful for building navigation UIs or filtering markets by category programmatically.

Filtering, Sorting, and Pagination

The Gamma API supports a consistent set of query parameters across its listing endpoints.

Filter Parameters

Combine filters to narrow results precisely. For example, active=true&tag_id=crypto returns only open crypto markets.

Sort Options

Use the order parameter to sort results and ascending to control direction (defaults to descending).

Pagination

Use limit and offset for pagination. The default limit varies by endpoint but is typically 20-100. To iterate through all results, increment offset by limit until you receive an empty response.

Example — iterating all active events:

import requests

def get_all_active_events():
    """Paginate through all active events on Polymarket."""
    events = []
    offset = 0
    limit = 100
    while True:
        resp = requests.get(
            "https://gamma-api.polymarket.com/events",
            params={"active": "true", "limit": limit, "offset": offset}
        )
        batch = resp.json()
        if not batch:
            break
        events.extend(batch)
        offset += limit
    return events

This pattern works for any listing endpoint. Adjust limit based on your rate limit budget — larger pages mean fewer requests but each response is heavier.

Price History for Backtesting

Price history is not available through the Gamma API. To get historical price data for backtesting, use the CLOB API’s /prices-history endpoint.

The workflow is:

1. Use the Gamma API to discover a market and extract its clobTokenIds
2. Pass the token ID to the CLOB API’s /prices-history endpoint
3. Specify a time range and fidelity (resolution) for the data points

import requests

def get_price_history(token_id, start_ts=None, end_ts=None, interval="1h", fidelity=60):
    """Fetch historical price data from the CLOB API.

    Args:
        token_id: The CLOB token ID (from Gamma API's clobTokenIds field)
        start_ts: Start timestamp (Unix seconds)
        end_ts: End timestamp (Unix seconds)
        interval: Candle interval (e.g., '1h', '1d')
        fidelity: Data point resolution in minutes

    Returns:
        Dict with 'history' array of {t: timestamp, p: price} objects
    """
    params = {"market": token_id, "interval": interval, "fidelity": fidelity}
    if start_ts:
        params["startTs"] = start_ts
    if end_ts:
        params["endTs"] = end_ts

    resp = requests.get(
        "https://clob.polymarket.com/prices-history",
        params=params
    )
    return resp.json()

# Get 1-hour candles for the last 7 days
history = get_price_history("<token-id>", interval="1h")
for point in history.get("history", []):
    print(f"{point['t']}: {point['p']}")

Each data point in the history array contains:

• t — the timestamp for the data point
• p — the price at that timestamp (0.00 to 1.00, representing probability)

For backtesting, combine Gamma API market discovery with CLOB price history to build datasets spanning multiple markets across any time range.

Caching Strategies

Market metadata from the Gamma API — questions, token IDs, event structures, and tag lists — changes infrequently. Caching aggressively reduces your request count and keeps you well under rate limits.

import requests
import time

class GammaCache:
    """Simple TTL cache for Gamma API responses."""

    def __init__(self, ttl=300):
        self._cache = {}
        self._ttl = ttl

    def get(self, endpoint, params=None):
        """Fetch from cache or make a fresh request."""
        key = f"{endpoint}:{params}"
        if key in self._cache:
            data, ts = self._cache[key]
            if time.time() - ts < self._ttl:
                return data

        resp = requests.get(
            f"https://gamma-api.polymarket.com{endpoint}",
            params=params
        )
        data = resp.json()
        self._cache[key] = (data, time.time())
        return data

Recommended TTL values by data type:

For production scanners, consider persisting cached data to disk or a database so you can restart without re-fetching everything.

Rate Limits

The Gamma API enforces rate limits via Cloudflare throttling. Exceeding limits returns HTTP 429 responses.

Best practices for staying within limits:

• Cache aggressively — most metadata does not change between requests
• Use larger page sizes — fetching 100 items in one request is better than 10 requests of 10
• Add backoff on 429s — if throttled, wait at least 10 seconds before retrying
• Batch your discovery — scan markets once, store the results, then query the CLOB API for live data

For the full rate limit reference across all Polymarket APIs, see the Polymarket Rate Limits Guide.

Building a Market Scanner

Here is a complete example that queries the Gamma API for high-volume markets with active order books and extracts the data needed for further analysis or trading.

import requests
import time

def scan_top_markets(min_volume=100000, limit=20):
    """Find the highest-volume active markets with CLOB order books.

    Args:
        min_volume: Minimum total volume in USDC to include
        limit: Number of events to fetch from the Gamma API

    Returns:
        List of market dicts sorted by 24h volume descending
    """
    resp = requests.get(
        "https://gamma-api.polymarket.com/events",
        params={
            "active": "true",
            "limit": limit,
            "order": "volume_24hr",
            "ascending": "false"
        }
    )
    events = resp.json()

    results = []
    for event in events:
        for market in event.get("markets", []):
            # Skip markets without CLOB trading
            if not market.get("enableOrderBook"):
                continue

            volume = float(market.get("volume", 0))
            if volume < min_volume:
                continue

            outcomes = market.get("outcomes", [])
            prices = market.get("outcomePrices", [])

            results.append({
                "question": market.get("question"),
                "condition_id": market.get("conditionId"),
                "token_ids": [
                    market.get("clobTokenIds", [None, None])[0],
                    market.get("clobTokenIds", [None, None])[1]
                ],
                "volume_24h": volume,
                "outcomes": dict(zip(outcomes, prices))
            })

    return sorted(results, key=lambda x: x["volume_24h"], reverse=True)

# Find top markets by volume
top = scan_top_markets(min_volume=50000)
for market in top[:10]:
    print(f"{market['question']}")
    for outcome, price in market['outcomes'].items():
        print(f"  {outcome}: {price}")

This scanner gives you everything you need to:

• Monitor market activity — run it on a schedule to track which markets are trending
• Feed a trading bot — pass the token_ids to the CLOB API for live pricing and order placement
• Build a dashboard — store results in a database and visualize volume trends over time
• Backtest strategies — use the token_ids with the CLOB /prices-history endpoint to pull historical data

FAQ

What is the Polymarket Gamma API?

The Gamma API at gamma-api.polymarket.com provides market discovery and metadata for Polymarket. It indexes events, markets, tags, series, and sports data. No authentication is required. Use it to find markets, get token IDs, and discover events.

How do I get Polymarket price history for backtesting?

Price history is available via the CLOB API’s /prices-history endpoint, not the Gamma API. Pass a token_id and time range to get historical price data points. Use the Gamma API to discover markets and get token IDs, then use the CLOB API for price history.

What is the difference between Events and Markets in the Gamma API?

Events are top-level questions (e.g., “Who will win the 2024 election?”). Markets are specific tradable binary outcomes within events, each with its own token IDs and condition ID. A single event can contain multiple markets for multi-outcome predictions.

What are the rate limits for the Gamma API?

The general limit is 4,000 requests per 10 seconds. Specific endpoint limits: /events is 500/10s, /markets is 300/10s, and /public-search is 350/10s. All limits are enforced via Cloudflare throttling.

See Also

• Polymarket API Guide — Full API reference covering CLOB, Gamma, and Data APIs
• Polymarket Subgraph Guide — On-chain data via GraphQL
• Polymarket WebSocket Guide — Real-time price and order book streaming
• Polymarket Rate Limits Guide — Complete rate limit reference across all APIs
• py_clob_client Reference — Python SDK methods for CLOB trading
• Prediction Market API Reference — Cross-platform API comparison

This guide is maintained by AgentBets.ai. Found an error or API change we missed? Let us know on Twitter.

Not financial advice. Built for builders.