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.

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, since Aug 2022)

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

order_filled_events_v2 (new CTF v2 + NegRisk v2, since April 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. To capture all Polymarket trading activity you must query both order_filled_events and order_filled_events_v2 — they are separate tables with different schemas.

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.

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
• Dump downloads return 302 redirects to time-limited URLs (20 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