The Polymarket API: two APIs, one token-ID dance

By Melvin Tercan, Octagon Research Editor

Polymarket exposes its data through three public API surfaces. The Gamma API is the catalog — events, markets, slugs, volumes. The CLOB API is the order book — prices, depth, and history, keyed by per-outcome token IDs; its market-data endpoints are public while order management requires wallet-signed authentication. The Data API covers activity: positions, trades, holders, and open interest. Reading either requires no account and no KYC, which makes Polymarket one of the most open market-data sources in finance. The one non-obvious step: almost everything useful requires resolving a market's token IDs first.

The two APIs, and what lives where

• Gamma API — the metadata layer: events, their markets, slugs, categories, liquidity and volume figures, and each market's clobTokenIds. This is where you discover what exists and translate a human-readable slug into machine identifiers.
• CLOB API — the market layer: current order books, midpoints, spreads, and time-series price history per outcome token. The market-data side is public; order placement and management on the same API require wallet-signed authentication, carry the platform's geographic restrictions, and put key management on you.
• Data API — the activity layer: wallet positions, trade history, market holders, and open interest. Useful for flow analysis and "who holds this market" questions the order book alone can't answer.

The canonical pipeline: slug → token → series

Every Polymarket data integration converges on the same three steps, and it's the pipeline Octagon runs in production for its own Polymarket coverage:

• 1. Query Gamma by event slug to fetch the event and its markets.
• 2. Extract each outcome's CLOB token ID from the market record.
• 3. Call the CLOB price-history endpoint per token for the interval you need, and normalize timestamps into candles.

Gotchas worth knowing before they cost you an afternoon: multi-outcome events are groups of binary markets, each with its own YES/NO token pair, so "the odds" of an event is a set of series, not one; token IDs — not slugs — are the stable join key; and thin markets can have long gaps in price history that naive resampling will interpolate into fiction.

Polymarket API vs Kalshi API

The contrast mirrors the platforms: Polymarket's read APIs are permissionless and anonymous, while Kalshi's API ties private endpoints to a KYC'd account with RSA-signed requests. Kalshi gives you a regulated exchange's clean, single-venue data model; Polymarket gives you open access with crypto-native quirks. If you're building cross-venue analysis — the same event priced on both — you'll end up writing both integrations, plus entity resolution to match markets across venues. That's precisely the infrastructure Octagon has already built.

When to consume the research layer instead

If your goal is analysis — which markets moved, which are mispriced, which cluster together — raw exchange APIs leave you the hard 90%: ingestion, normalization, news detection, and probability modeling. Octagon's platform does that continuously across Kalshi and Polymarket and exposes the results as typed REST endpoints and a hosted MCP server — so both your code and your AI agents can query "what repriced today and why" as one call instead of a data platform project.

Frequently asked questions

Is the Polymarket API free?

Reading market data is free and doesn't require an account: the Gamma API serves events and markets metadata, and the CLOB API serves order books and price history over public HTTP. Trading through the API is a different matter — it requires wallet-based authentication and is subject to the same geographic restrictions as the site.

What's the difference between Polymarket's Gamma, CLOB, and Data APIs?

Gamma is the catalog: events, markets, slugs, categories, volumes. The CLOB (central limit order book) API is the market layer: order books, prices, and time-series price history keyed by token IDs — public for reads, wallet-authenticated for order management. The Data API is the activity layer: positions, trades, holders, and open interest. A typical pipeline resolves token IDs via Gamma, then queries the CLOB or Data API as the question requires.

How do I get historical prices from Polymarket?

Resolve the market's clobTokenIds from the Gamma API (each outcome has its own token), then call the CLOB prices-history endpoint with the token ID and an interval. This is exactly the pipeline Octagon runs in production for its Polymarket coverage — slug to token to daily series.

Can I trade through the Polymarket API?

Yes, with wallet-signed authentication — orders are signed with your key, consistent with the platform's crypto-native custody. US access restrictions apply to trading exactly as they do on the site, and key management is the security burden: anyone with your key controls your funds.

Does Octagon provide Polymarket data?

Octagon's research platform ingests Polymarket alongside Kalshi — live markets, price history, and news detection — and exposes research, search, and probability analysis through its API and hosted MCP server. If your goal is analysis rather than order routing, that's the layer to consume; raw execution stays with Polymarket's own APIs.