How to Get Polymarket Market Data

If you want to know how to get Polymarket data, the honest answer is that there is no single endpoint that covers every need. Polymarket exposes its market information through several official services, and the right one depends on whether you need current market metadata, a live order-book snapshot, streaming updates, wallet activity, or a replayable historical archive for research. A quick lookup is a few lines of code; a reproducible backtest on complete order books is a storage and validation project.

The practical split is this: use Polymarket's public Gamma and CLOB APIs for current lookups, subscribe to the public market WebSocket for live strategies, and reach for a prepared data service when you need tick-level books, trades, aligned timestamps, and settlement-aware labels without building a collector first. This guide maps each route to the decision it fits, then covers the checks that separate a usable dataset from a misleading one.

Table of contents

What Polymarket market data actually contains

A Polymarket market is a prediction contract represented by outcome tokens. The metadata identifies the question, outcomes, status, and identifiers, while the central limit order book (CLOB) carries prices, bids, asks, and trades for those outcome tokens. Confusing the two is the first mistake people make: a market list is not a historical order book, and a current book snapshot cannot reconstruct every quote that previously appeared.

Polymarket's official documentation separates these functions across different services: the Gamma API for discovery and metadata, the CLOB API for prices and order books, the Data API for activity and participation, and WebSockets for real-time updates. Knowing which service owns which job saves you from pulling the wrong feed and discovering the gap only after a backtest looks suspiciously good.

The main ways to get Polymarket data

There are five routes, and most serious projects end up combining two or three of them rather than picking one.

Official REST APIs are the direct path for a current lookup or a lightweight integration. Polymarket documents three primary hosts: the Gamma API at gamma-api.polymarket.com for events and markets, the CLOB API at clob.polymarket.com for prices and order books, and the Data API at data-api.polymarket.com for positions and participation. Public market data is available without credentials, so discovering open markets or resolving a token ID is immediate. The cost shows up when you need reliable history: you own pagination, retries, identifier changes, timestamp normalization, raw storage, and the gaps that disconnects create.

An order-book snapshot from the CLOB answers "what is in the book right now?" The documented endpoint, GET https://clob.polymarket.com/book?token_id={TOKEN_ID}, returns bids, asks, market information, and the last trade price. A snapshot is enough to read the best bid, the best ask, the spread, and the displayed liquidity near the midpoint. It cannot tell you how the spread evolved over a month, how often liquidity vanished before a price move, or what the book looked like immediately before a historical trade. Those are time-series questions, and a single request does not produce a time series. Before using any snapshot in a trading system, verify the response schema, price units, timestamp behavior, and whether the quantities represent aggregate displayed liquidity.

The public WebSocket at wss://ws-subscriptions-clob.polymarket.com/ws/market is the efficient choice for live applications. The market channel delivers public order-book, price, and lifecycle updates, which is better than repeatedly polling for full snapshots when you need to maintain a local book or react to quote changes with low delay. A production consumer should hold a local state model rather than treating each message as an isolated observation: apply the initial snapshot, apply subsequent updates in sequence, detect disconnects or sequence gaps, resynchronize after reconnect, and persist both raw messages and the reconstructed book. The real danger is silent state corruption, where the process stays connected but quietly misses messages because of a network interruption or a faulty update rule. For research, save the raw feed and periodically compare your reconstructed book against fresh snapshots.

The Data API targets activity and participation rather than quote-by-quote state. Polymarket's documentation describes cursor pagination and a version 2 trades endpoint that can filter by wallet, market, event, or the global feed. That makes it suitable for wallet activity analysis, participation studies, and address-level research. Keep the distinction clear: a list of trades generally does not expose every resting quote, cancellation, or intermediate book state, so microstructure work needs trade records paired with order-book events.

A prepared historical data service is often the most practical option when the goal is research rather than integration. Our Polymarket dataset currently describes full order-book and trade records for Polymarket crypto Up/Down markets, with separate exchange and receive timestamps and history beginning June 1, 2025, covering BTC, ETH, SOL, and XRP across 5-minute, 15-minute, 1-hour, 4-hour, and 24-hour windows. Instead of building a collector and waiting for observations to accumulate, you start from archived event-level data and spend your time on feature construction, market-making simulation, execution modeling, and short-horizon probability forecasting. Our market IDs identify each Up/Down window by combining the market family with the window-start Unix timestamp, which makes joining a prediction market to the underlying coin price over the same interval straightforward. For the full workflow, see our Polymarket historical data guide, or review current coverage on the Polymarket data catalog.

Direct Polymarket API or a prepared dataset?

The decision turns on whether you are building an integration or running repeatable research. A direct integration gives you control over collection and transport, which is usually right for a bot that must react to current market state. A prepared dataset shifts effort away from ingestion and toward validation, labeling, modeling, and simulation, which is usually right for research teams that need reproducible historical samples.

We present our Polymarket data as part of a broader market-data platform with consistent delivery surfaces across historical and real-time feeds. Depending on your workflow, the relevant options are our REST API, live streams, bulk files, and MCP server. Tell us your date range, venues, and output format through the contact form and we can confirm the current scope against your use case before you commit a production workflow.

What to validate before trusting Polymarket data

The most damaging data problems rarely look like errors. A request can return HTTP 200 and still produce a dataset that quietly breaks your analysis.

Market and token identity. A single event can hold multiple outcomes, each with its own token identifier. Store the event ID, market ID, outcome label, token ID, and question together, and never rely on a ticker-like label alone. For rolling crypto markets, also record the window start, window end, interval length, underlying asset, and settlement rule. A market labelled "BTC Up" is meaningless without its time window.

Timestamps. Keep exchange timestamps and receive timestamps separately when both exist. Exchange time reconstructs when an event occurred at the venue; receive time measures latency and when your system observed it. Collapsing both into one field hides ingestion delay and makes latency analysis impossible.

Order-book reconstruction. Do not assume every displayed quote was available for the entire bar. Preserve price, quantity, side, event type, event timestamp, token ID, sequence or ordering information where available, snapshot boundaries, and data-gap indicators. If a disconnect creates an uncertain interval, flag it instead of silently interpolating the book.

Trade and quote alignment. Join each trade to the most recent valid book state using a clearly defined time rule. Joining by rounded minute or candle timestamp will mislead any strategy that is sensitive to spread, depth, or queue position.

Settlement and resolution. A market's final outcome is not its last traded price. Keep settlement data separate from prices and build labels from the official resolution rule. Treating a voided market as a normal loss, assigning the wrong outcome token, or mixing closure time with settlement time will corrupt a prediction-market backtest.

Survivorship and selection bias. Studying only active, high-volume markets produces an optimistic sample. Include closed and resolved markets, and retain thin or short-lived markets if they were eligible for the strategy at the time.

If you want the deeper mechanics of spread, depth, and imbalance before building these checks, our explainer on order book data for traders covers the fields and the sanity tests to run first.

A practical research architecture

A robust Polymarket research stack tends to have four layers. Discovery resolves markets, outcomes, token IDs, lifecycle status, and settlement metadata. Market data stores snapshots, book updates, prices, and trades. Normalization standardizes timestamps, identifiers, sides, quantities, and event types. The research layer generates features, labels, execution assumptions, and backtest results.

How much of that you build depends on the goal. A small live dashboard may only need the first two layers. A trading bot also needs local state, reconnect logic, and risk controls. An academic or quantitative workflow demands reproducibility: immutable raw data, versioned transformations, and an explicit record of excluded intervals.

A short illustration of why reconstruction matters is the spread calculation. Reading the best bid and ask from a snapshot is trivial, but a monitoring value is not an execution model. A real backtest has to add timestamp selection, market-status checks, depth limits, fees, latency, partial fills, and the possibility that displayed quantity disappears before the order arrives. The gap between those two things is where overstated performance lives.

When the delivery problem is broader than a single request, our trading solutions and AI-agent solutions address consistent access across Polymarket and other supported venues, so a bot or agent can query one schema instead of stitching several together.

Common mistakes when getting Polymarket data

Most failed Polymarket projects trip on the same handful of errors, and all of them are avoidable with the right source choice.

Mistaking current data for historical data is the big one: a market endpoint does not hand you a complete archive, so confirm date range, event granularity, and retention before designing a backtest. Using candles for an order-book strategy hides queue changes, spread variation, cancellations, and depth, so anything sensitive to execution quality needs event-level data. Treating the midpoint as executable ignores the side you cross, available quantity, fees, delay, and adverse movement. Ignoring token-level identity turns slugs and questions into fragile join keys instead of durable token IDs. Losing the exchange-versus-receive time distinction can make a slow collector look predictive or wreck a latency-sensitive evaluation. And failing to account for resolution leaves a backtest without a reliable outcome label or a clear treatment of voids and unresolved observations.

Frequently asked questions

Is Polymarket market data public?

Much of the public market data is available without credentials. Polymarket's documentation lists public market discovery through the Gamma API and public updates through the market WebSocket. Access and use should still be checked against the applicable Polymarket terms and your local legal requirements.

What is the easiest way to get Polymarket data?

For a current lookup, use the Gamma API for discovery and the CLOB API for prices or an order-book snapshot. For historical quantitative research, use a prepared event-level dataset or build and operate your own collector over time.

How do I get Polymarket order-book data?

Use the CLOB order-book endpoint for a point-in-time snapshot, or subscribe to the public market WebSocket for ongoing updates. A historical order-book study requires stored snapshots and updates, not a single current request.

Can I get Polymarket trade data?

Yes. Polymarket documents Data API trade queries and public real-time trade activity through its documented data and streaming surfaces. Confirm whether the response contains the granularity and historical range your research needs.

Is Polymarket data good for backtesting?

It can be, provided the dataset includes the relevant market states, trades, timestamps, fees, settlement labels, and periods free of unrecognized gaps. A backtest built only on last prices or candles can materially overstate executable performance.

Where can I get historical Polymarket order books?

You can collect them yourself from live market updates, or start from a historical provider. We currently list Polymarket crypto Up/Down order books and trades from June 1, 2025, covering BTC, ETH, SOL, and XRP time-window markets.