Decimal strings vs numbers
This is the one to get right. Some fields come back as decimal strings, others as numbers, and it varies by route:| Shape | Fields | Why |
|---|---|---|
| Decimal string | L2 px/sz, mid_price, spread, trade price/size/fee, funding_rate, premium, open interest values | Preserves precision; small rates and large sizes lose information as floats |
| Number | L4 price/size, candle open/high/low/close/volume | These routes return numeric types directly |
px is a string, but the same book’s L4 price is a number. Check the type per route on the data-type page.
Timestamps
Response timestamps are ISO 8601 UTC (for example2026-06-05T13:53:33.971Z). Request windows are different: market-state routes take Unix milliseconds and order routes take ISO 8601 — see Parameters. Store timestamps in UTC and convert only at display.
Symbol and the coin alias
symbol is the canonical field. coin appears in some payloads as a deprecated alias for the same value; prefer symbol and treat coin as legacy. Preserve the venue-specific symbol shape (plain perp, pair, builder prefix, outcome side) exactly as returned.
HIP-4 prices are probabilities
On HIP-4 outcome markets,mark_price and mid_price are implied probabilities in the [0, 1] range, not USD. Label them as probability-like values in any chart, model, or export so downstream code does not treat them as asset prices.
One envelope
Market-data routes wrap the result in{ success, data, meta }. Some auth, system, and data-quality routes return resource-specific bodies instead. See Response envelope for the full contract and the field dictionary for individual fields.