Polymarket API Guide: How to Get Prediction Market Data

Reference · 4 min read · published 2026-07-27 · updated 2026-07-27

Polymarket exposes several public APIs, and the most common mistake is calling the wrong one. Metadata, live prices, wallet history and leaderboards live in different places, each with its own conventions. This is a practical map, written from having built an analytics site on top of them.

Which API serves what

• Gamma - the catalogue. Events, markets, titles, slugs, tags, volume, liquidity, resolution rules, end dates. Start here for anything descriptive.
• CLOB - the order book. Live bids and asks, depth, midpoints, fee parameters per market, and order placement for authenticated clients.
• Data API - the wallet layer. Positions, activity, PnL and the trader leaderboard.

A common task usually spans two of them: to display a market card you need Gamma for the question and CLOB for a price you can act on; to display a trader you need the data API for positions and Gamma to turn condition IDs into readable titles.

Reading the catalogue

Events are the unit users think in - one question, one page - and each event contains one or more markets. A binary question has a single market; a "who wins?" question has one market per candidate.

Useful conventions worth knowing before you write a parser:

• Filter by tag to build category views - this is how topic pages like NFL or Fed decisions are assembled.
• Order by volume to get anything interesting first; the unfiltered list is dominated by tiny markets.
• Filter out closed markets explicitly, or half your results will be settled questions.
• Prices sometimes arrive as JSON-encoded strings rather than arrays. Parse defensively.
• Placeholder outcomes exist. Multi-candidate events often carry rows with no price and no volume; filter them out or your odds table will show a field of zeros.

Prices: midpoint versus book

The single number attached to a market is a midpoint. It is fine for display and misleading for execution: it says nothing about how much size sits at that level. If your application implies an actionable price - a screener, a yield calculator, an arbitrage alert - read the book and use the side you would actually hit, or your numbers will be systematically optimistic.

The same caution applies to fees. Fee parameters are attached per market and have been adjusted more than once; read them from the market rather than hardcoding a table that quietly goes stale.

Rate limits and how to stay under them

The public endpoints are rate limited per endpoint, and a naive client that fetches on every page view will hit those limits with a modest number of visitors. Three things solve almost all of it:

1. Cache at the edge. Most data does not need to be fresher than a few seconds. A short shared cache turns thousands of visitor requests into a handful of upstream calls.
2. Respect pagination caps. Endpoints enforce their own maximum page size and reject larger requests outright rather than truncating - the leaderboard caps at 50 rows per request, for instance. Walk pages instead of asking for everything.
3. Batch and deduplicate. Rendering 50 market cards should not mean 50 separate lookups for the same tag.

Send a descriptive User-Agent while you are at it. Some endpoints are unfriendly to clients that send none, and it makes you a good citizen if something you wrote misbehaves.

Pitfalls that cost real time

• Identifier confusion. Event slugs, market slugs, condition IDs and token IDs are four different things. Decide early which one is your primary key - slugs are stable and human-readable, which is why market URLs use them.
• Base64url secrets. API secrets are base64url; a decoder expecting standard base64 rejects them, and the resulting failure is a signing error that looks like an authentication problem.
• Silent empty arrays. Several endpoints return [] for a malformed query rather than an error. Assert on shape, not on status code alone.
• Timestamps in seconds. Activity timestamps are unix seconds, not milliseconds. Multiply before constructing a date, or every trade will appear to have happened in 1970.
• Adapters, not the raw token contract. If you are writing anything that redeems or merges positions on-chain, route through the current collateral adapters - see the CLOB V2 reference.

A free endpoint you can use

We expose one of our own derived datasets publicly: the near-certain market screener at /api/v1/markets-99, returning JSON with price, annualised return and end date for markets trading above 99%. It is documented on the API page, requires no key, and is CORS-enabled. It exists because computing it correctly requires joining catalogue data with book data and annualising by time to resolution - which is exactly the kind of work worth doing once.

If you would rather not build it

Everything described here is already assembled on this site: live odds across every market, the trader leaderboard with wallet-level history, holding rewards and LP reward tracking, and category pages for crypto, politics and sports. Reading it here first is a reasonable way to work out what your own integration actually needs.

More Polymarket guides →