The Polymarket API: What It Shows and Hides

The Polymarket API answers one question well and a different question poorly. It is built to tell you the current state of a market (open orders, live prices, active positions) so an app or trader can act on it in real time. It is not built to hand you a clean, settled history of who won which market and how positions resolved across hundreds of events, which is exactly what a trading desk, researcher, or risk team needs.

That gap is the whole story. Understanding which surface answers which question saves you from building a data pipeline that quietly returns the wrong thing.

Key takeaways

• Polymarket exposes two public API layers: the Gamma API for market metadata and prices, and the CLOB API for order books, orders, and trades. Both are documented in Polymarket's developer docs.
• Reading data (prices, markets, order books) generally requires no signature. Placing or cancelling orders requires cryptographic authentication tied to a wallet.
• The API is strong on live state and weaker on settled, cross-market history. Reconstructing resolved outcomes and full position histories usually means reading the underlying blockchain, not the app API.
• Polymarket settles onchain in USDC on Polygon, so the ground truth of every trade and payout lives on a public ledger regardless of what the app API returns.
• Rate limits and pagination apply. Anyone building at scale should read the current limits in the docs rather than assume, because these change.

Why the two-layer design exists

Polymarket runs a hybrid model. Order matching happens off-chain through a Central Limit Order Book (the CLOB), while final settlement and custody of funds happen onchain. Polymarket's own documentation describes this central limit order book operated by the exchange, with trades settled on the Polygon network in USDC. That architecture is why the API is split.

The Gamma API serves the human-readable layer: what markets exist, their titles, categories, resolution rules, and current prices. If you want to list every open election market or read the last traded price on a specific outcome, Gamma is the surface. The CLOB API serves the trading layer: the live order book, your open orders, order placement, and cancellations. Placing an order requires signing with the wallet that holds the funds, because that signature is what authorises a real onchain-settled position.

The practical consequence: a read-only analyst and an active market maker are using two different parts of the same system, with different auth and different guarantees.

Which API surface answers which question

This is the table to bookmark. The left column is a real question a builder or analyst asks. The right column is what actually answers it.

The pattern is clear. Everything about now is a direct call. Everything about the settled past across many markets falls off the edge of the app API and lands on the blockchain, where you have to do the assembly yourself.

How to actually connect

The path from zero to reading data is short. The path to trading is longer because of auth.

1. Read public data with no auth. Both Gamma and the CLOB expose read endpoints you can query directly. Listing markets or pulling a price does not require credentials, per Polymarket's docs.
2. For trading, derive API credentials from your wallet. The CLOB uses signed requests. You generate or derive an API key set tied to the wallet address that holds your USDC, then sign order payloads. Polymarket publishes client libraries in Python and TypeScript to handle the signing.
3. Fund and approve onchain. Because settlement is USDC on Polygon, the trading wallet needs USDC and the relevant token approvals set before orders will fill.
4. Respect pagination and rate limits. Historical trade queries are paginated and rate limited. Always read the current limits in the docs before designing a backfill, because assuming an old number is how you get throttled mid-job.

The settlement layer is where the truth lives

Here is the detail that reframes everything: the app API is a convenience layer over a public ledger. Every filled trade, every position token, and every payout settles as an onchain transaction in USDC on Polygon. Polymarket describes market resolution as driven by an oracle, with the UMA optimistic oracle used to report outcomes, documented in the resolution section of its docs.

That means the ground truth is not the API response. It is the chain. If the API is rate limited, deprecates an endpoint, or scopes a query too narrowly, the underlying record still exists in Polygon blocks. For anyone who needs a complete and auditable history, reading the settlement layer is the only source that cannot silently drop rows.

The data problem this creates

Say you want to answer a question the app API does not serve: how did political betting flow through Polymarket over a full year, broken down by wallet geography and net position. Nothing in Gamma or the CLOB returns that. The raw material is thousands of Polygon transactions, ERC-1155 outcome-token transfers, order-fill events, and USDC settlements, none of which arrive pre-labeled with which market they belong to, which outcome resolved, or what the USD value was at the time.

To turn that into an answer, every onchain record has to resolve to consistent fields: the market, the outcome token, the wallet on each side, the size, the USD value at execution, and whether the position ultimately won or lost. That normalization across raw Polygon logs is the work behind Allium's prediction market datasets, which index Polymarket activity into queryable tables with defined schemas. It is the same reconstruction that let Allium's analysts examine US users leading political betting volume despite the ban, and why Bloomberg cited Allium on possible settlement manipulation, a question you can only investigate with the full settled history in front of you.

What you gain by matching the surface to the question

The concrete payoff of understanding this split is avoiding two expensive failure modes.

• No silent gaps in history. If you build a research pipeline on paginated app-API trade calls, you inherit whatever that endpoint chooses to return and drop the rest. Reading the settlement layer instead means every filled position is present, so a year-long backfill does not quietly miss the markets that resolved before you started querying.
• Real cross-market position views. The app shows one market at a time. A risk view of a wallet holding fifty positions has to be assembled from onchain transfers. Doing that assembly once, correctly, means a desk can see net exposure across an entire book instead of fifty separate screens.
• Faster iteration for builders. Using Gamma for live prices and the CLOB for order flow, rather than trying to force one to do the other's job, means a trading bot gets fresh state without hammering the wrong endpoint into a rate limit.

For the general shape of how these indexing systems work under the hood, the mechanics of blockchain API providers turning raw chain data into usable records follow the same pattern applied to any chain, not just Polygon.

Risks and open questions

• Endpoints and limits change. Polymarket has revised its API surfaces over time. Any specific endpoint, parameter, or rate limit in a blog post can go stale. Treat the official docs as the only current authority.
• Resolution is not instantaneous or purely mechanical. Because outcomes are reported through an optimistic oracle with a dispute window, a market's "resolved" state can move during that window. Reading resolution once and caching it can be wrong.
• Geographic and legal access varies. Whether and how you can trade depends on jurisdiction. The regulatory picture around prediction markets in the US in particular keeps shifting, covered in more depth in the state of play on Polymarket's US legality.
• Reconstruction is non-trivial. Deciding to read the settlement layer is easy. Correctly joining outcome-token transfers to markets, pricing them in USD at execution time, and tracking wins and losses is meaningful engineering. Underestimating it is the most common mistake teams make.

The through-line: the Polymarket API is a good tool for the job it was built for, live market interaction. The moment your question shifts to settled, cross-market history, the honest answer is that the chain, not the app API, holds it, and someone has to do the assembly.

Frequently asked questions

Is the Polymarket API free to use?

Reading public data (markets, prices, order books) through the Gamma and CLOB APIs generally requires no payment or signature. Trading requires wallet-signed authentication and onchain USDC on Polygon to fund positions. Confirm current terms and any limits in Polymarket's official developer documentation.

Do I need an API key for the Polymarket API?

For read-only data you typically do not. For placing or cancelling orders through the CLOB, you derive an API credential set from the wallet holding your funds and sign each request. Polymarket publishes Python and TypeScript client libraries that handle this signing.

What is the difference between the Gamma API and the CLOB API?

Gamma serves market metadata and prices: titles, categories, resolution rules, and current outcome prices. The CLOB serves the trading layer: live order books, order placement, cancellations, and recent trades. Analysts often use Gamma, while active traders and market makers use the CLOB.

Can I get full historical trade and resolution data from the Polymarket API?

Not cleanly. The app API is built around current market state, with paginated and rate-limited access to recent trades. Complete settled history across many markets, including how each resolved and full wallet position histories, is best reconstructed from the underlying Polygon blockchain, where every trade and payout settles in USDC.

Where does Polymarket actually settle trades?

Onchain, in USDC on the Polygon network. Order matching happens off-chain through the central limit order book, but final settlement and custody occur onchain, which is why the blockchain, rather than the API, is the authoritative record of what happened.

How are Polymarket market outcomes resolved?

Resolution is reported through an oracle, with Polymarket using UMA's optimistic oracle to report outcomes according to each market's stated rules. Because it includes a dispute window, a market's resolved status can change during that window, so a single cached read of the resolution can be premature. See Polymarket's documentation for the current process.