Polymarket data · Polygon
Every fill since Polymarket's CLOB launched
Polymarket's full trade history and live feed, in a database you own. Four ready-made packages load every fill, position and PnL from the CLOB launch in September 2022 to the latest block, then keep it current. Backtest on the full sample, track wallets, or feed a bot. Hand the setup to your AI coding agent, or run it yourself.
$ substreams run polymarket-fills-substreams@v0.1.0 map_fills \-e polygon --start-block -1# prints one JSON message per block that contains a Polymarket fill
Quickstart
How to get Polymarket data in three steps
You are consuming published packages, not writing an indexer. Every command below is copy-paste, and your AI coding agent can run all of it for you.
- No indexer to write. The packages are already built, versioned and published.
- One stream for history and live data. The same run backfills the past, then follows the chain head.
- Reorgs are signaled. Not silently skipped, so your sink undoes them cleanly.
- Your database, your rows. Nothing is metered per query once it lands.
Get a key
Install the CLI and generate a free API key. The Free plan gives you 7M processed blocks and 5 GiB of egress a month: enough to run any package against the head and see the data. Loading history or running live needs Scaling.
$ brew install streamingfast/tap/substreams$ substreams auth
See live data in your terminal
Point a package at Polygon and watch fills arrive from the head block.
$ substreams run polymarket-fills-substreams@v0.1.0 \map_fills -e polygon --start-block -1
Load it into Postgres, then backfill
The PnL package ships a ready-made Postgres schema. Create the tables, then run from the CLOB launch block. The sink keeps following the chain head once it catches up. Try a small range first, like -s 33605403 -t +100000, to check the output before the full load (about $816 in the loading month, see Pricing). It has no stores, so it is not idempotent: replaying a range into a database that already has it double-counts positions and PnL. Reset the database before replaying, or resume from the sink's saved cursor.
$ PKG=https://spkg.io/streamingfast/polymarket-pnl-substreams-v0.2.0.spkg$ DSN="postgres://user:pass@localhost:5432/polymarket?sslmode=disable"$ substreams sink postgres setup "$PKG" --dsn "$DSN"$ substreams sink postgres "$PKG" --dsn "$DSN" -e polygon -s 33605403
Set up Polymarket data in my local Postgres. 1. Install the Substreams CLI (1.20.2 or newer, the Postgres and ClickHouse sinks are built in): brew install streamingfast/tap/substreams, then run: substreams auth 2. Read the package docs: substreams info https://spkg.io/streamingfast/polymarket-pnl-substreams-v0.2.0.spkg 3. Create the tables: substreams sink postgres setup <that spkg URL> --dsn "$DSN" 4. Test a small range first: substreams sink postgres <that spkg URL> --dsn "$DSN" -e polygon -s 40000000 -t +100000 5. Then load everything from the CLOB launch and keep following the chain head: same command with -s 33605403 and no -t 6. When it is caught up, show me the 10 most profitable wallets from user_positions_pnl (total_pnl is in USDC with 6 decimals). My Postgres DSN ($DSN): <paste yours here>
What you get
What Polymarket data looks like when it arrives
Decoded, typed rows, not raw logs. This is one real fill from block 93,000,000 (31 August 2026), exactly as polymarket-fills-substreams emits it.
{
"orderHash": "0xcfdb97693a189bc908c4040e8553e6e58560cc1cf3bde4015016a00ecd5e046c",
"maker": "0x16da1dfba37b7b8f3b313924e327131b84b805c0",
"taker": "0xf33e2f782eb1c1c426badb50af841a18d9540ab8",
"makerAssetId": "408055597605916245399734714545909025147269583674481542436118321178810540780",
"takerAssetId": "0",
"makerAmountFilled": "40000000",
"takerAmountFilled": "5600000",
"fee": "0",
"exchangeVersion": 2,
"exchangeAddress": "0xe2222d279d744050d28e00520010520000310f59",
"tx": {
"txHash": "0x31283128845bdca31cf281752824a5da0f8bf0b681e6973f7f4a42556378f15f",
"logIndex": "15",
"blockNumber": "93000000",
"timestamp": "1788205027"
}
}How to read it
- Asset IDs
- In makerAssetId and takerAssetId, "0" is collateral. The long number is the outcome token (an ERC-1155 id). Here the maker sold 40 outcome tokens for 5.60 collateral.
- Amounts
- Raw 6-decimal integers, so 40000000 is 40 tokens and price is 5600000 / 40000000 = 0.14.
- One schema for both eras
- A CLOB v1 fill has the same fields with exchangeVersion: 1, so one query spans the v2 cutover.
- Chain provenance
- Every row carries the transaction hash, log index, block number and Unix timestamp.
Or query it in Postgres
polymarket-pnl-substreams writes trades, user_positions, user_pnl, markets, token_prices and whale_alerts. total_pnl is not stored directly — it is nonlinear in a running position, so no stream module can accumulate it — it comes from the user_positions_pnl view, joining user_positions to token_prices. Your AI agent can write these queries for you.
-- ten most profitable wallets, in USD (amounts are 6-decimal) select "user", sum(total_pnl) / 1e6 as pnl_usd from user_positions_pnl group by "user" order by pnl_usd desc limit 10;
Coverage
Every settled event Polymarket writes to Polygon
Four published packages, versioned on the Substreams registry. They build on each other, so pick one fills source and add the rest only where they cover something new.
Polymarket Fills
Fills from the CTF Exchange and Neg Risk CTF Exchange across both CLOB generations, merged into one ordinal-sorted stream with an exchange_version column. Fill extraction is index-filtered on the four exchange contract addresses, so you are billed only for blocks that contain Polymarket activity: about 28.7M of the 60.4M blocks since the first exchange.
polymarket-fills-substreams@v0.1.0 · streamingfast · Polygon
Polymarket PnL
Derived per-address positions, mark-to-market PnL, volume and whale detection. A pure mapper — no stores — writing straight to the trades, whale_alerts, user_pnl, user_positions and token_prices tables in PostgreSQL, with total_pnl computed by a SQL view.
polymarket-pnl-substreams@v0.2.0 · streamingfast · Polygon
Polymarket CTF
The conditional-token lifecycle: market preparation, resolution payouts, position splits and merges, redemptions, and ERC-1155 outcome-token transfers.
polymarket-ctf@v0.12.0 · colindickson · Polygon
Polymarket Exchange
Order fills and matching events from the CLOB v2 CTF Exchange only. Maker, taker, asset IDs, amounts, fees, plus fee, admin, pause and approval events. Need fills from before the v2 cutover too? polymarket-fills-substreams unifies v1 and v2.
polymarket-exchange@v0.12.0 · colindickson · Polygon · CLOB v2 only
Which package do you need?
Fills or PnL?
Choose polymarket-fills-substreams if you want the raw v1 and v2 fills to build on. Choose polymarket-pnl-substreams if you want per-address positions, mark-to-market PnL and whale alerts computed for you. It costs more because it writes derived position and PnL rows on top of every fill.
Don't stack overlapping packages
polymarket-pnl-substreams already includes every fill in its trades table and reads polymarket-fills-substreams internally, which in turn reprocesses polymarket-exchange. Running them side by side bills the same blocks twice. Add polymarket-ctf only if you want its history from before block 33,605,403.
polymarket-exchange CLOB v2 fills, one contract
└─▶ polymarket-fills-substreams fills from all four exchange contracts, v1 + v2
└─▶ polymarket-pnl-substreams positions, PnL, whale alerts, Postgres schema
polymarket-ctf splits, merges, redemptions ──▶ read by pnlOne honest limit
Polymarket's resting bids and asks live in an off-chain CLOB and are never written to Polygon, so no on-chain source, ours or anyone's, can reconstruct historical book depth. What is on-chain, and what you get in full here, is every executed fill, every position and every resolution: the settled record behind PnL, realized-outcome backtests and research.
Polymarket contract addresses on Polygon
Block 33,605,403 is 26 September 2022, when the CLOB launched. The v2 exchanges were deployed on 31 March and 3 April 2026, about four weeks before the 28 April 2026 cutover.
| Era | Contract | Address | From block |
|---|---|---|---|
| CLOB v1 | CTF Exchange | 0x4bfb41d5b3570defd03c39a9a4d8de6bd8b8982e | 33,605,403 |
| CLOB v1 | Neg Risk CTF Exchange | 0xC5d563A36AE78145C45a50134d48A1215220f80a | 50,505,492 |
| CLOB v2 | CTF Exchange V2 | 0xE111180000d2663C0091e4f400237545B87B996B | 84,902,353 |
| CLOB v2 | Neg Risk CTF Exchange V2 | 0xe2222d279d744050d28e00520010520000310F59 | 85,058,176 |
| All eras | Conditional Tokens (CTF) | 0x4D97DCd97eC945f40cF65F87097ACe5EA0476045 | 4,023,686 |
Where Polymarket API and vendor pipelines break
The same job, done two ways: one you rent, one you own.
v2 cutover
Polymarket API or vendor feed: On 28 April 2026 Polymarket moved to CLOB v2 and pUSD collateral on brand-new exchange contracts. Order structs changed, nonces disappeared, v1 SDKs stopped working. Pipelines built before that date now cover half the history.
Substreams: Substreams reprocesses straight across that boundary: one query, both eras, no manual union.
Pagination
Polymarket API or vendor feed: The official Gamma and Data APIs cap per-endpoint: 300 req/10s on /markets, 200 on /trades. Fine for live state, painful when you are pulling years of fills page by page.
Substreams: Once we deliver the data it is yours, sitting in your own database, with nothing to re-fetch or re-paginate.
Retention
Polymarket API or vendor feed: Specialist vendors sell rolling windows: 7, 30, 31, 60 or 90 days on most tiers. Several only began capturing Polymarket in 2025 or 2026, so the deep history is not there to buy.
Substreams: Backtest across any range you want, or follow a whale's history back to the CLOB launch.
Ownership
Polymarket API or vendor feed: Metered APIs price your curiosity. Every re-run of a backtest costs again, the license usually forbids redistribution, and the day you churn you keep nothing.
Substreams: Rows land in your own database. No per-query meter, and you keep every row.
Live and history
History and live Polymarket data in one stream
Parallel backfill
Historical blocks are processed in parallel across the network rather than replayed one at a time, so a full Polymarket load doesn't crawl block by block. Load it once into your own database and query it as often as you like; the rows are yours.
Continuous head
When the backfill catches up it simply keeps going, sub-second behind confirmation. There is no cutover moment, no gap to patch, no second integration to test.
Reorg-safe cursor
Every message carries a cursor. Restart from it after a crash and you resume exactly where you stopped; when Polygon reorgs, the stream tells your sink what to undo.
One stream, not two
The usual Polymarket setup is two systems: bulk history files from one vendor, a websocket from another, and a reconciliation layer you maintain forever. Substreams collapses that into one stream with one cursor.
Destinations
Load Polymarket data into Postgres, ClickHouse or files
PostgreSQL
polymarket-pnl-substreams ships a ready-made schema: trades, user_positions, user_pnl, markets, token_prices and whale_alerts, created for you by substreams sink postgres setup. No stores — every row is a plain insert or an accumulated delta, with total_pnl computed by a view.
Files and DuckDB
Stream to ProtoJSONL files with substreams sink protojson, then query them with DuckDB, pandas or Polars.
ClickHouse
substreams sink clickhouse loads the same way. The fills and CTF packages emit raw events, so add a small db_out module (your AI agent can write it) or ask us for a ready schema.
gRPC and Kafka
Consume the protobuf stream directly in Go, Rust, Python or TypeScript, and fan it out to Kafka or your own services.
Snowflake and BigQuery
Via a file export or your existing ELT. The rows are yours, so the path is yours to choose.
AI agents and MCP
Once the rows are in Postgres or ClickHouse, any MCP-capable agent can query them. There is no per-query data fee.
Something else?
Not listed? Tell us where you need the data.
Who this is for
What traders and teams build with Polymarket data
Quant research and backtesting
Every executed fill against every realized resolution since the CLOB launched. Test a strategy across the full sample instead of a 30-day window, and have your AI agent re-run it as often as you like without a meter running.
Wallet tracking and leaderboards
Per-address positions, mark-to-market PnL, and whale detection come out of the box in polymarket-pnl-substreams. Follow the sharpest wallets, or rank every trader.
Trading bots and market making
Sub-second fills over gRPC with a cursor that survives restarts, so your inventory model never silently drifts out of sync with the chain.
Forecast accuracy and academic research
Condition preparation through resolution payout, with timestamps and oracle data intact. It is the calibration dataset prediction-market research actually needs.
Risk, compliance and surveillance
A complete, reproducible on-chain audit trail of positions and settlements in infrastructure you control, which is usually the requirement rather than a nice-to-have.
Dashboards and media
Open interest, volume and platform aggregates refreshed continuously, so the numbers on your page are the numbers on the chain.
Pricing
Load the history once. Stay live on the $100/month plan.
Billing is per processed block plus egress, with no per-request meter and no per-seat charge. For Polymarket, egress is what sets the price: the block counts are small because the packages only process blocks that contain Polymarket activity.
| Package | History: blocks | History: egress | Loading month cost | Staying live |
|---|---|---|---|---|
| polymarket-fills-substreams | 28.7M | 828 GiB | ~$156 | ~50 GiB/mo |
| polymarket-pnl-substreams | 33.3M | 4.6 TiB | ~$816 | ~250 GiB/mo* |
| polymarket-ctf | 28.6M | 399 GiB | $100 | well under 500 GiB/mo |
| polymarket-exchange | 7.3M | 271 GiB | $100 | ~50 GiB/mo |
Estimated with substreams estimate against the published packages; overage is prorated at the Scaling rates. *The PnL live figure is a recent-18-month average — activity is far from uniform across it, running about 13x denser per block than the pre-2025 era.
Pick one fills source, not several: overlapping packages bill the same blocks twice.
Egress also depends on which fields you sink, so treat these as sizing estimates and check them against your own volumes. Usage figures last measured Fall 2026.
Free
$0
- 7M processed blocks included
- Egress included at 5 GiB
- 5 Parallel Workers
- 2 concurrent streams
Scaling
$100 / mo
- 155M processed blocks included
- Egress included at 500 GiB
- 15 Parallel Workers
- 5 concurrent streams
Pro
$500 / mo
- 400M processed blocks included
- Egress included at 2 TiB
- 75 Parallel Workers
- 20 concurrent streams
The short answer
What is Polymarket on-chain data, and where do you get it?
Polymarket settles on Polygon. Every trade, position and resolution is a public Polygon event: order fills on the CTF Exchange contracts, and splits, merges, resolutions and redemptions on the Gnosis Conditional Tokens contract. Substreams reads those events straight from the chain, so you get every fill since the CLOB launched in September 2022, plus the live head, in a single stream you load into your own database.
That matters because most Polymarket data products are captures: a vendor started recording on some date, holds a rolling window, and rents it back to you per request. The chain has no such window. It has every fill since the CLOB launched, and it always will.
FAQ
Polymarket data questions, answered directly
Where does Polymarket data live on-chain?
Polymarket settles on Polygon (chain ID 137). Trades clear through the CTF Exchange and Neg Risk CTF Exchange contracts, and outcome tokens are Gnosis Conditional Tokens at 0x4D97DCd97eC945f40cF65F87097ACe5EA0476045. Every fill, split, merge, resolution and redemption is a public Polygon event that anyone can read.
How far back does Polymarket history go?
Order fills go back to the launch of Polymarket's CLOB: the CTF Exchange was deployed at Polygon block 33,605,403 on 26 September 2022. Conditional-token events (market preparation, splits, merges, resolutions and redemptions) go back further, to block 4,023,686. Because Substreams reads Polygon itself rather than replaying a vendor's capture, there is no retention window.
Before the CLOB launched, Polymarket trading ran through a different set of contracts that these packages do not read. On the vendor side, several commercial Polymarket feeds only began capturing in 2025 or 2026. The deep history is not withheld from you; it was never recorded.
Does this cover Polymarket's CLOB v2 migration?
Yes. Polymarket cut over to CLOB v2 and pUSD collateral on 28 April 2026, with new exchange contracts at 0xE111180000d2663C0091e4f400237545B87B996B and 0xe2222d279d744050d28e00520010520000310F59. Order structs changed, nonces were removed, and v1 SDKs stopped working against production.
The polymarket-fills-substreams and polymarket-pnl-substreams packages merge v1 and v2 fills into a single ordinal-sorted stream and tag every row with an exchange_version column, so one query spans both eras without a manual union.
Do I need to know how to code to use this?
No. The four packages are already published and versioned. Run one command to stream fills in your terminal, or paste the prompt from the quickstart into your AI coding agent and let it install the tools and load the data into Postgres. polymarket-pnl-substreams ships a ready-made Postgres schema. Coding is only needed if you want to change what a package computes, for example a custom ClickHouse table, and if you do want that, we will write it with you.
Can I use this with an AI coding agent like Claude Code, Cursor or ChatGPT?
Yes. Everything is command-line and documented. substreams info <package> prints a package's modules and docs, and the PnL package documents its table schemas, so an agent can install the CLI, read the docs, load the data and write queries against it. The quickstart includes a prompt you can paste. Once the rows are in Postgres or ClickHouse, MCP-capable agents can query them directly.
Can I get Polymarket order book depth?
Resting bids and asks live in Polymarket's off-chain CLOB and are never written to Polygon, so no on-chain source can reconstruct historical book depth, ours or anyone else's.
What is on-chain, and what these packages give you completely, is every executed fill, every position and every resolution: the settled record behind PnL, realized-outcome backtests, forecast-accuracy research and compliance. Teams that also need point-in-time depth pair this dataset with a CLOB capture vendor, and we are happy to say which one fits your case.
How fast is the live data?
Sub-second after block confirmation, streamed over gRPC. The same cursor that drives your historical backfill continues into the head block, and reorgs are signaled on the stream so your sink can undo them, so there is no separate real-time integration to build, test and reconcile against the historical one.
What does Polymarket data cost on Substreams?
Billing is per processed block plus egress. Free covers 7M blocks and 5 GiB a month, enough to try a package on the live head; Scaling is $100/month for 155M blocks and 500 GiB; Pro is $500/month for 400M blocks and 2 TiB.
For Polymarket, egress rather than block count sets the bill. The packages only process blocks that contain Polymarket activity, so the full polymarket-fills-substreams history is about 28.7M processed blocks (of 60.4M since the first exchange) and 828 GiB of egress: roughly $156 for the loading month on Scaling. Staying live is about 1.6M blocks and 50 GiB a month, which fits Scaling's allowance ($100/month) but not the Free plan's 5 GiB. polymarket-pnl-substreams is heavier, about 4.6 TiB to backfill (roughly $816 on Scaling) — most of that from the last 18 months of Polymarket activity, which run about 13x denser per block than the years before it. Overlapping packages bill the same blocks twice, so run one fills source, not several. You keep every row either way.
For comparison, hosted Polymarket feeds from specialist vendors currently list between roughly $17 and $6,000 per month, every month, for access you do not keep, and most carry a retention window of 7 to 90 days on entry tiers.
How does this compare to the free Polymarket API?
Polymarket's Gamma, CLOB and Data APIs are excellent for live market state and light queries, and they are free. We recommend them as the canonical source for market metadata and token ID mapping. They are also rate-limited per endpoint (300 req/10s on /markets, 200 on /trades) and paginated, and they are not designed to hand you years of tick-level history.
Paginating them for years of history is slow, and gaps across the v1/v2 contract split are easy to miss. Substreams gives you the whole history as a bulk load, then keeps the same tables current.
Can I get Kalshi and other prediction markets too?
Kalshi is a centralised, off-chain exchange, so there is no chain to read. Kalshi data comes from Kalshi's API or a capture vendor. For on-chain venues, Substreams covers 70+ networks, so any prediction market that settles on-chain can be indexed the same way. Tell us which venues you need and we will scope it.
What is Substreams, and who is it good for?
Substreams is StreamingFast's blockchain indexing framework: it processes chain data in parallel across the network and streams the results, historical and live, into a database or system you control. It's built for teams that need reliable, complete, queryable blockchain data without standing up and operating their own indexing infrastructure: traders and quant teams, trading and analytics products, risk and compliance functions, and anyone building a data product on top of on-chain activity.
Why use Substreams instead of building my own indexer?
Running your own node and indexer means owning reorg handling, backfill parallelism, chain upgrades, and uptime, work that has nothing to do with the product you're actually building. Substreams packages are published, versioned, and already handle all of that; you consume a stream, not operate infrastructure. If you need something a published package doesn't compute, Substreams modules are open: fork one, write your own, or have us build it with you.
Talk to our data team
Tell us what you're building. We reply within one business day with a concrete plan, not a calendar link. Mention your use case, where the data should land, what you use today, and your timeline, and we'll come back with a sized cost model.
Start streaming Polymarket data today.
Create an account, generate an API key, and stream your first Polymarket fills in minutes. No credit card, no indexer to write.
Start free — get an API key7M blocks & 5 GiB egress included — no credit card requiredPolymarket is a trademark of its respective owner. This page describes independent, open-source packages for reading public Polygon blockchain data; it is not affiliated with or endorsed by Polymarket.