API Documentation

Base URL: https://api.predmktdata.com

Quick start

Get data flowing in 3 steps:

1. Sign in at predmktdata.com with Google and subscribe to Lite. You get your API key instantly.
2. Test your key:

curl -H "x-api-key: YOUR_KEY" https://api.predmktdata.com/status

3. Download data — list available Parquet dumps and start downloading:

# List available files
curl -H "x-api-key: YOUR_KEY" https://api.predmktdata.com/dumps

# Download a Parquet file
curl -L -H "x-api-key: YOUR_KEY" -o fills.parquet \
  https://api.predmktdata.com/dumps/order_filled_events_v2/20261008.parquet

# Or query remotely with DuckDB (no download needed)
# Get the presigned URL, then: SELECT * FROM read_parquet('URL')

That's it. You have Polymarket data. For full sync patterns, see Sync patterns below.

How Polymarket works

Polymarket is a prediction market where people bet on real-world outcomes. Every market is a yes/no question (e.g. "Will Bitcoin hit $100k by July 2026?"). Each side has a token that trades between $0 and $1 — if the event happens, "Yes" tokens pay out $1; otherwise, they're worth $0.

All trading happens on the Polygon blockchain — a public, permanent ledger where every transaction is recorded and verifiable. A wallet is a user's identity on the blockchain, represented by an address like 0xed86.... Every trade, deposit, and withdrawal is tied to a wallet address.

When a user buys an outcome, they receive outcome tokens — ERC-1155 tokens on Polygon, each identified by a large numeric token_id. On its own, a token_id is just a number — the included markets lookup table maps each one to its human-readable question and outcome (e.g. token 123... → "Will Bitcoin hit $100k?" / "Yes"). A user's position is their current holding of a specific outcome token: how many they hold, what they paid on average, and their realized profit/loss from any tokens they've already sold or redeemed.

What this API provides

predmktdata reads every relevant transaction from Polygon and delivers it as daily Parquet dumps. Here is what you get:

• Events — the raw history of everything that happened: order fills (trades), position splits, merges, and redemptions. Append-only, one row per event.
• Positions — the computed current state of every wallet: amount held, average entry price, and realized PnL per outcome token. Snapshot regenerated daily (05:00 UTC).
• Resolution — UMA Oracle data: who proposed each market's outcome, who disputed it, and the final settlement. Track proposer/disputer addresses, bond payouts, and dispute rates.
• Perps — Polymarket's off-chain perpetual futures (indices, commodities, crypto). Captured live from the exchange's own feed as 7 daily Parquet streams (trades, order book, best bid/ask, tickers, market stats, 1-minute candles, funding). These trades never touch a blockchain, so this is capture-or-lose data. See the Perps section below.

You don't need to understand Solidity, ABIs, or how to talk to a blockchain node. The API handles all of that and gives you clean, structured data you can load into any database or spreadsheet.

Authentication

All endpoints require an API key via the x-api-key header. Get your key by signing in with Google at predmktdata.com.

curl -H "x-api-key: YOUR_API_KEY" https://api.predmktdata.com/status

Endpoints

{
  "last_block": 84570000,
  "head_block": 84570000,
  "tables": {
    "order_filled_events": 854000000,
    "order_filled_events_v2": 1500000,
    "positions": 150000000,
    "payout_redemptions": 93000000, ...
  }
}

{
  "files": [
    {"path": "order_filled_events_v2/20261008.parquet", "size": 171966464, "mtime": 1791522000},
    {"path": "positions/positions_current.parquet", "size": 8612345678, "mtime": 1791522000}, ...
  ],
  "base_url": "/dumps/"
}

curl -i -H "x-api-key: YOUR_KEY" -H 'If-None-Match: "ETAG_FROM_LAST_LISTING"' \
  https://api.predmktdata.com/dumps
# HTTP/1.1 304 Not Modified  -> nothing new since your last listing

Available tables

Sizes are approximate and grow over time. With Parquet, you can query remotely with DuckDB without downloading — only the columns and rows you need are transferred.

Schema

order_filled_events (v1 — legacy CTF + NegRisk, Nov 2022 → Apr 28, 2026)

order_filled_events_v2 (CTF v2 + NegRisk v2 + Exchange v3 parlays, since April 28, 2026)

Cash-flow semantics match v1: for side=0 (buy), maker pays maker_amount_filled USDC and receives taker_amount_filled outcome tokens. For side=1 (sell), maker delivers tokens and receives USDC. The v1 flow ended on-chain at the cutover (last v1 fill Apr 28, 2026 ~11:00 UTC) — all new fills land here. Union both tables for full history.

Computing volume: each row is one on-chain OrderFilled log, not one unique trade — a match emits one log per maker order plus a taker-side roll-up that restates the same volume, so summing every row double-counts. To count each match once, drop rows where lower(taker) is an exchange contract: 0x4bfb…982e, 0xc5d5…f80a (v1), 0xe111…996b, 0xe222…0f59 (v2), 0xe333…00aa (v3). Full lowercase addresses and worked SQL are in llms.txt. Note Polymarket's published per-market volume counts both sides of every match (≈2× the single-counted metric).

Row identity: the unique key for an event is (transaction_hash, log_index) at the source, but the fills dumps omit log_index (and v1 dumps also omit order_hash). As a result, distinct on-chain fills can appear as byte-identical rows — about 1% of v1 rows, e.g. one order matched in several equal legs in the same transaction. These are real, separate fills: never DISTINCT or deduplicate the fills dumps.

combinatorial_redemptions (parlays — multi-leg bets, since June 2026)

A parlay combines several markets into one position that pays out only if every leg wins. This table records the cash-outs; opening a parlay is a regular trade on the new exchange and appears in order_filled_events_v2 with the same position_id as token_id. Voided legs pay 0.5, so fractional settlement prices (0.5, 0.25, 0.75…) are legitimate.

parlay_legs (lookup: parlay → underlying markets, overwritten daily)

One row per leg. Lets you name every parlay with plain SQL: join a v3 fill's token_id against position_id_yes/position_id_no, then each leg_condition_id against the markets table. See llms.txt for a worked query.

positions

Served as one rolling file, positions/positions_current.parquet, regenerated daily. The file carries realized PnL; to mark open positions to market, join token_id to daily_token_prices (below) and value amount at the latest price.

daily_token_prices (one file per UTC day)

Path: daily_token_prices/YYYYMMDD.parquet. A token only has a row on days it traded — for a mark on a given day, take the latest row on or before it.

markets

Lookup table that maps token IDs to human-readable market info. Join with event or position tables on yes_token_id / no_token_id to see which question and outcome a trade or position belongs to. Overwritten daily.

resolution_proposals (UMA Oracle)

Who proposed the outcome of each market. Indexed from UMA OptimisticOracleV2, filtered to Polymarket adapters only. Full snapshot updated daily in uma/ folder.

resolution_disputes (UMA Oracle)

When someone challenges a proposed outcome. ~2% of proposals are disputed.

resolution_settlements (UMA Oracle)

Final resolved outcome and bond payouts.

Perps (off-chain perpetual futures)

Polymarket Perps is a separate Polymarket product from everything above (its data is included in Lite): leveraged perpetual futures on equity indices, commodities, and crypto, traded on an off-chain central limit order book. Matching happens off-chain, so an individual trade produces no on-chain record — every trade's hash is an empty "0x". Unlike the on-chain tables, there is no ledger to reconstruct this from later, so we capture it live from the exchange's public WebSocket firehose, plus a one-time REST backfill for history predating capture start. Live capture began 2026-07-09 ~12:31 UTC. Either you record this feed as it arrives or the data is gone — there is no way to fetch a missed trade back from a blockchain.

Instruments are keyed by an integer iid, the exchange's own instrument_id — 89 instruments as of 2026-09-17 (crypto, single stocks, indices, commodities), e.g. 1=SP500-USD, 2=GOLD-USD, 6=BTC-USD, 7=ETH-USD, 19=NVDA-USD. The authoritative, always-current iid → symbol mapping is the exchange's instruments endpoint: curl https://api.perpetuals.polymarket.com/v1/info/instruments (fields instrument_id, symbol, category). The list grows; new listings are captured in every stream automatically.

Common columns (every stream except perps_funding):

Each stream then adds its own columns. All numeric fields (prices, quantities, rates, volumes) are delivered as strings to preserve raw precision — cast in your query.

Conventions a quant needs

• side is long/short, not buy/sell. hash is always 0x — off-chain, no transaction to point to.
• Canonical 1-minute candle. A candle is re-emitted as it fills, so one (iid, candle_ts) has many rows; the closed candle is the row with max(timestamp_received). Because files bucket on timestamp_received, a candle that opened just before UTC midnight can finalize in the next day's file — read day D+1 when reconstructing candles at a day boundary.
• perps_funding files overlap ~24h. Each hourly poll returns a rolling ~24 hours and the daily finalize dedups only within a day, so consecutive funding files repeat the same (iid, ts) settlement. This is the only overlapping stream. When concatenating days, dedup on (iid, ts) keeping max(fetched_at) — this also picks up any retroactively restated rate.
• Backfilled vs live rows. Backfilled (REST) rows carry timestamp_received == ts (for klines, timestamp_received == candle_ts) and sq IS NULL; live WSS rows have a real receive time and a real sq. For perps_funding the backfill marker is fetched_at == ts.
• History depth by stream. klines reach each instrument's launch (first ones 2026-05-06); trades reach a ~30-day REST retention floor (2026-06-09), or the instrument's launch if later; funding begins 2026-07-08; book/bbo/tickers/statistics are not backfilled and exist only from live-capture start (2026-07-09).
• Known coverage gaps (2026-07-28 → 2026-09-17). A 100-channel-per-connection subscription cap left perps_tickers/perps_statistics empty from 2026-07-28 ~14:51 UTC and perps_book/perps_bbo without iid ≥ 27 until 2026-09-17 15:06 UTC; a capture-host outage 2026-09-11 ~14:41 → 2026-09-17 15:06 UTC left no book/bbo and no funding settlements between 09-11 14:00 and ~09-16 15:00. perps_trades and perps_klines were repaired from the exchange's REST history for all instruments (trades for iid ≥ 27 from 2026-08-18 ~13:00–14:30, the REST retention floor). REST-sourced trade rows fetched before 2026-09-17 missed ~0.7% of trades (trades sharing a millisecond with a REST page boundary): re-repaired for 2026-08-18 → 2026-09-16; the one-time backfill days 2026-06-09 → 2026-07-09 ~12:31 keep that shortfall, and >100 trades sharing one millisecond exceed the endpoint's page size and cannot be fetched at all (15 such groups in the repaired range). Full detail in llms.txt.
• Partial days are expected in three cases: an instrument's launch day (short but complete), the earliest backfilled day of a retention-limited stream (trades, funding), and the 2026-07-09 capture start-up day for the snapshot streams.

Download with the same /dumps flow as any other file — e.g. GET /dumps/perps_trades/20260709.parquet. Full stream-by-stream detail and worked recipes are in llms.txt.

Error responses

All errors return JSON with a detail field:

Sync patterns

1. Backfill (once)

1. GET /dumps to list every file your key can download
2. Download the daily event files (<table>/YYYYMMDD.parquet) in parallel. Each /dumps/{path} call is a quick 302 redirect; the file itself downloads straight from storage, so run several downloads at once
3. Download the snapshot files: positions/positions_current.parquet, markets/markets.parquet, parlay_legs/parlay_legs.parquet, and uma/resolution_*.parquet
4. Query directly with DuckDB, or INSERT into your database (UPSERT for positions)

2. Daily incremental (after 05:00 UTC)

1. GET /dumps with If-None-Match set to the ETag of your last listing. A 304 means nothing new — you're done for the day
2. Otherwise compare the listing with what you already have, by path and mtime: download paths you don't have yet (each new day adds one file per table), and re-download any file whose mtime changed — that's how you pick up the overwritten snapshots (positions, markets, parlay legs, UMA)
3. INSERT the new event rows; replace your positions and lookup tables with the fresh snapshots

Compression

JSON responses such as the /dumps listing support two compression algorithms via the Accept-Encoding header (Parquet files are already compressed internally):

• gzip — universally supported, use curl --compressed
• zstd — ~30% smaller, faster. Send Accept-Encoding: zstd

Units and scaling

• All amounts are in raw on-chain units. Divide by 1e6 for USDC values.
• avg_price is scaled by 1e6 — divide by 1e6 for a decimal price between 0 and 1.
• token_id and condition_id are large integers (up to 78 digits).
• Addresses are lowercase hex with 0x prefix.

Coverage

• Data covers Polygon from block 35,800,000 to present
• Indexer runs at the chain tip with automatic reorg recovery; dumps are published daily
• 865M+ fills, 150M+ positions, 93M+ redemptions indexed
• Daily event dumps cover the full history as one file per day (<table>/YYYYMMDD.parquet). Full history is kept, with no expiry; a completed day file does not change
• Positions, markets, and UMA resolution snapshots regenerated daily
• Off-chain Perps captured live since 2026-07-09; klines backfilled to each instrument's launch (first ones 2026-05-06)
• Dump downloads return 302 redirects to time-limited URLs (60 min)

Plans

Lite is a single-user subscription, month-to-month via Stripe. A key without an active Lite subscription gets 403 on /dumps and /dumps/{path}. API requests are rate-limited per key (5 requests/second).