Polymarket settlement edge cases

• The nearest stored book at expiry can be hundreds of milliseconds old; age_ms exposes it
• Reference capture for some assets starts hours into the day, leaving early windows ungradeable
• Spot and native 60-second TWAP can disagree on choppy windows, and the TWAP is what settles
• Not every archived market is resolved yet; treat absent winners as censored, not as losses

The archive samples books every 250ms, so the nearest stored book to an arbitrary instant is usually within a few hundred milliseconds. But on a quiet market the gap can be larger, and treating that book as the exact expiry state is an assumption worth stating.

The snapshot-at endpoint makes the assumption measurable through age_ms. A backtest that sets a tolerance - and reports how many markets exceeded it - is honest about how many settlements it approximated rather than observed.

Reference capture is per asset and does not start at midnight. Markets that closed before an asset's capture began have no archived reference row, so their grade cannot be reproduced from reference data. The remaining markets are fine, but a study that ignores the boundary silently drops or mis-grades the earliest ones.

Detect the boundary by asset, not globally: five assets start at 07:38 UTC and three at 11:52 UTC on the measurement day. Filtering each asset against its own start time is the only correct approach.

On a quiet window the spot print and the 60-second TWAP differ by almost nothing. On a fast one they can disagree enough to flip a near-the-money contract, and the TWAP is what settles. Any backtest that grades on spot will differ from the exchange exactly where it is most sensitive.

The fix is to grade on the archived TWAP rows, then use spot only to understand the path. If a result is sensitive to the spot-versus-TWAP choice, that is a fact about the strategy worth surfacing, not hiding.

Not every market in the archive has resolved. Markets still accepting orders, or waiting on grading, have no winner recorded. Treating 'no winner' as a loss biases every win-rate downward; correctly they are simply excluded until graded.

One-sided books are the other quiet trap. When the snapshot has bids but no asks, the mid is undefined, and a fill model that assumes a two-sided book will invent liquidity. The snapshot endpoint reports null mid for exactly these cases.

import requests

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

# Check settlement freshness and reference availability at expiry.
slug = "eth-updown-5m-1787486400"
ts = 1787486700
r = requests.get(
    f"{BASE}/markets/{slug}/snapshot-at/{ts}",
    headers=HEADERS,
)
r.raise_for_status()
snap = r.json()["snapshot"]
print("book age_ms:", snap["age_ms"])
twap = snap["reference"].get("twap")
print("twap present:", twap is not None)
print("yes mid:", snap["tokens"]["Yes"]["price"])

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 coverage and gaps
• Chainlink TWAP resolution
• Resolved markets