Polymarket data

Polymarket Data

Public-API access to Polymarket that just works. Every header, pagination quirk, and field-decoding gotcha here was found the hard way against the live API — so you get clean data on the first run instead of debugging 403s and double-counted trades.

What this skill gets you

• Markets — metadata for any slice of markets (open/closed), with the JSON-encoded fields properly decoded.
• Prices — mid-price history for any market token.
• Trades — full trade history, correctly deduped to unique matches.
• Research artifacts — calibration (do 70¢ markets resolve YES ~70%?) and settlement P&L, straight from the trade-level data.

Core principles

1. Public data only. Unauthenticated endpoints, no keys, no licensed feeds.
2. Browser User-Agent always. The Data API returns 403 without a real Mozilla/5.0 ... UA. The bundled scripts already send one.
3. Dedupe trades. The trades endpoint returns one row per participant per match — every fill appears as a BUY and a SELL. Keep only side=BUY for unique matches (the script does this by default).
4. Don't trust list-response volume. It's null in market lists; use the single-market endpoint for full numbers.
5. Mind the mid-price bias. Price history is last-trade-per-minute, not volume-weighted; markets sit near 0/1 for their final weeks, so naive means skew toward settlement.

Phase 0: What does the user want?

Goal	Go to
A list of markets to work from	Phase 1 → markets
Price history for a known market	Phase 2 → prices
Trade history / microstructure	Phase 2 → trades
"Are Polymarket prices well-calibrated?"	Phase 3 → analysis

Phase 1: Discover markets

python scripts/polymarket.py markets --closed --limit 500 --out markets.jsonl

Each row carries id, conditionId, question, clobTokenIds (decoded list of token_ids — usually [yes_token, no_token]), outcomes, endDate. You need conditionId for trades and a token_id for prices.

Phase 2: Pull prices and/or trades

# Mid-price history for one outcome token
python scripts/polymarket.py prices --token <token_id> --out prices.jsonl

# Full trade history for a market, deduped to unique matches
python scripts/polymarket.py trades --condition <conditionId> --out trades.jsonl

Trade semantics (binary market, yes_token / no_token):

asset	side	meaning	YES-equivalent price
yes_token	BUY	long YES	price
yes_token	SELL	short YES	price
no_token	BUY	long NO	1 - price
no_token	SELL	short NO	1 - price

Phase 3: Calibration & P&L

# Needs markets.jsonl WITH resolved outcomes (closed markets)
python scripts/polymarket.py calibrate --markets markets.jsonl --out calib.csv

Calibration buckets entry prices and compares to realized YES-resolution rate. Settlement P&L per $1/$0 contract:

• BUY YES at p → settle YES +(1-p), settle NO -p
• BUY NO at q → settle NO +(1-q), settle YES -q

Phase 4: Report

Always tell the user: row counts, date coverage (min/max timestamp), and the two caveats above (trade dedup, mid-price bias) so the dataset isn't misread.

Advanced: maker/taker

The Data API has no aggressor flag. For true maker/taker (Kyle's λ, VPIN), use the goldsky orders-subgraph GraphQL endpoint exposing OrderFilledEvent with maker/taker/makerAssetId/takerAssetId. Out of scope for the bundled scripts; noted here so you know where to go.