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 pick a plan. 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/20260405.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 Parquet dumps and CSV API responses. You get two types of data:

• 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. Updated daily (Lite) or in real time (Pro).
• 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.
• Order book — Level-2 depth snapshots from pmxt: best bid/ask, full bid & ask depth, mid and spread per market, enriched with the market question and Yes/No outcome. Consolidated into 6-hour windows.
• 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, ...
  }
}

# Fetch fills for 500 blocks
curl --compressed -H "x-api-key: YOUR_KEY" \
  "https://api.predmktdata.com/events?after_block=84420000&limit=500&tables=order_filled_events"

# Response: CSV with header row
transaction_hash,log_index,block_number,exchange,maker,taker,...
0x7fe2...,210,84420001,ctf,0xed86...,0x9ce4...,...

{
  "realized_pnl": -52.34,
  "unrealized_pnl": 184.21,
  "total_pnl": 131.87,
  "portfolio_value": 1250.00,
  "total_volume": 8340.50,
  "active_positions": 12,
  "markets_traded": 47
}

wscat -c "wss://api.predmktdata.com/ws/feed?x_api_key=YOUR_KEY"

# Watch a specific wallet's fills and position changes
{"action": "subscribe", "type": "user", "address": "0xabc..."}

# Watch large fills (raw units, divide by 1e6 for USDC)
{"action": "subscribe", "type": "threshold", "min_fill_amount": 10000000000}

# Watch positions with low avg_price (cheap bets)
{"action": "subscribe", "type": "threshold", "max_avg_price": 50000}

# Unsubscribe
{"action": "unsubscribe", "type": "user", "address": "0xabc..."}

# Keepalive
{"action": "ping"}

{
  "fills": [{"transaction_hash": "0x...", "maker": "0x...", ...}],
  "positions": [{"user_address": "0x...", "amount": 5000000, ...}]
}

wscat -c "wss://api.predmktdata.com/ws/stream?x_api_key=YOUR_KEY&start_block=84650000"

# Or stream only specific tables:
wscat -c "wss://api.predmktdata.com/ws/stream?x_api_key=YOUR_KEY&start_block=84650000&tables=order_filled_events,positions"

# Catchup batches (sent rapidly until caught up)
{"type": "batch", "from_block": 84650000, "to_block": 84650100,
 "order_filled_events": [{...}], "positions": [{...}], ...}

# Catchup complete signal
{"type": "caught_up", "block": 84651400}

# Live batches (every few seconds as indexer commits)
{"type": "batch", "from_block": 84651400, "to_block": 84651410, ...}

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)

The /events API returns additional columns: log_index, exchange. The timestamp column is named block_timestamp in API responses.

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. If you need a strict per-row key, use /events, which includes log_index.

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 · dumps only)

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

The /events API and /user endpoints add block_timestamp. The /user/*/positions endpoint also adds unrealized_pnl and total_pnl (computed from live market prices).

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.

polymarket_orderbook (L2 depth)

Level-2 order book snapshots for every Polymarket outcome token, sourced from pmxt (CC BY 4.0) and consolidated into 6-hour windows. Each row is an order-book event with best bid/ask and full depth; we enrich it with the market question, slug, and Yes/No outcome. Order book dumps are Parquet, served from the orderbook/ folder (path: orderbook/polymarket_orderbook_YYYYMMDD_HH.parquet), with windows starting at hour 00, 06, 12, 18 UTC. History starts April 2026.

Perps (off-chain perpetual futures)

Polymarket Perps is a separate product from everything above: 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: 1=SP500-USD, 2=GOLD-USD, 3=WTIOIL-USD, 4=NAS100-USD, 5=SILVER-USD, 6=BTC-USD, 7=ETH-USD, 8=SOL-USD, 9=SPCX-USD, 10=HYPE-USD. The list can grow — new instruments appear with a new iid 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).
• 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

Lite: dumps only

1. GET /dumps to list available Parquet dump files
2. Download daily event files in parallel
3. Download the rolling positions snapshot (positions/positions_current.parquet) and markets lookup
4. Query directly with DuckDB, or INSERT into your database (UPSERT for positions)
5. Run daily: download new daily event files + re-download positions_current.parquet (overwritten daily)

Pro: dumps + near real-time API

1. Do the Lite setup above for fast backfill
2. Find MAX(last_block) from the positions dump — this is your sync cursor
3. Use GET /events to sync the remaining gap to chain head
4. Continue polling every few seconds for near real-time updates

Compression

The API supports two compression algorithms via Accept-Encoding header:

• 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 (<1s delay) with automatic reorg recovery
• 865M+ fills, 150M+ positions, 93M+ redemptions indexed
• Daily event dumps cover the full history as one file per day (<table>/YYYYMMDD.parquet)
• 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

Free samples (pending users)

If you've signed up but haven't subscribed yet, you can preview the data shape before paying. Samples live under samples/ and are exposed by GET /dumps like any other dump file. Cap: 50 downloads/day.

All samples are CSV.gz (paid plans get Parquet for the full history) and cover one busy day — 2025-01-20, US inauguration day — plus a 10k slice of open positions and the markets lookup. Schema matches the paid dumps.

Example:

curl -H "x-api-key: $KEY" -L \
  https://api.predmktdata.com/dumps/samples/order_filled_events_sample.csv.gz \
  -o trades.csv.gz