Polymarket reference price snapshots, explained

• 459,597 reference-price observations archived as of 2026-10-17: 250,416 spot and 209,181 native 60-second TWAP rows
• Every row records provider (chainlink) and capture feed (polybolt) in addition to the price
• Spot rows carry window_seconds = 0; TWAP rows carry the averaging window, currently 60 seconds
• Served over GET /v1/reference-prices, filterable by asset, kind and time range

A reference-price snapshot is one observation of an underlying crypto price, captured for settlement rather than for trading. Polymarket's Up/Down markets do not resolve on the last trade in the CLOB - they resolve on an external reference level, and the archive keeps every observation of that level alongside the market data.

Each row is more than a number. It carries the observation time, the asset and quote, whether it is a spot print or a TWAP, the provider and capture feed that produced it, and the averaging window for TWAP rows. That provenance is what lets you reproduce a grade instead of trusting it.

The archive stores two kinds of observation for each asset. Spot rows are point-in-time ticks with window_seconds = 0. TWAP rows are time-weighted averages - the archive currently holds 209,181 of them, every one native, published by the provider over a 60-second window.

The split is not cosmetic. A spot print can be moved by a single instant of volatility; a 60-second TWAP smooths that out. Because the Up/Down markets settle on the TWAP, a backtest that grades on spot will disagree with the exchange on exactly the fast, wicky windows where it matters most.

The reference observations are exposed through a single endpoint that takes an asset and a time range. You can narrow to spot or twap and page through long ranges, which makes it practical to pull the exact series that graded a market.

The endpoint returns each row with its full provenance, so you can verify the provider and window rather than trusting a bare number.

import requests

BASE = "https://api.polyorderbooks.com/v1"
HEADERS = {"X-API-Key": "your-key"}

r = requests.get(
    f"{BASE}/reference-prices",
    headers=HEADERS,
    params={"asset": "btc", "kind": "twap",
            "start_ts": 1787486400, "end_ts": 1787486700},
)
r.raise_for_status()
for row in r.json()["data"]:
    print(row["t"], row["kind"], row["value"],
          row["provider"], row["window_seconds"])

A bare settlement price is not reproducible. Keeping provider, feed, twap_kind and window_seconds means anyone can re-derive the same grade the exchange used, and can tell when a number came from a native provider TWAP versus a value computed downstream.

That matters most for research that compares markets over time or across assets. If the provenance fields change - a different provider, a different window - the archive shows it rather than hiding it behind a single price column.

import requests

BASE = "https://api.polyorderbooks.com/v1"
HEADERS = {"X-API-Key": "your-key"}

# Spot and TWAP side by side for the same window.
def ref(kind):
    r = requests.get(
        f"{BASE}/reference-prices",
        headers=HEADERS,
        params={"asset": "eth", "kind": kind,
                "start_ts": 1787486400, "end_ts": 1787486460},
    )
    r.raise_for_status()
    return r.json()["data"]

print("spot:", len(ref("spot")))
print("twap:", len(ref("twap")))

The Starter plan is free, includes order books, prices, and metrics at 250ms resolution, with 3 days of history, 60 requests/min, 1,000/day, 1 free AI backtest, and 3 strategy backtests. No credit card required.

Paid data windows from $19/mo extend history to 30–120 days at higher throughput. Backtest AI add-on is +$19/mo or standalone at $29/mo.

• Reference price data
• Resolution, explained
• Chainlink TWAP resolution