Historical data semantics

Canonical field definitions and aggregation rules for historical API responses. Historical corrections that change closed windows are published separately in the machine-readable correction feed.

Time buckets and source grain

Historical bars are start-labelled: a row labelled T covers the half-open interval [T, T + resolution).

In the v2 futures and perpetual APIs, 1m is a persisted aggregate of finer source events such as trades and ticker observations. It is not a raw exchange-event feed. Resolutions above 1m are computed at request time from those persisted one-minute aggregates.

Field suffix Definition inside the requested interval
open First valid source observation.
high Maximum valid source observation.
low Minimum valid source observation.
close Last valid source observation.
avg Arithmetic mean; never a substitute for close.

Carry

basis is mark_price - index_price evaluated component by component. basis_close therefore uses the closing mark and index values from the last source sub-bar.

For perpetuals, funding_rate_close and funding_8h_close are the final funding observations in the bucket. annualized_carry is funding_rate_close * 24 * 365 * 100.

For dated futures, annualized carry is (basis_close / index_price_close) * (365 / days_to_expiry) * 100.

V1 options model fields

Field Definition
atm Modelled at-the-money implied-volatility level for the requested tenor.
c Modelled call implied-volatility level at the requested absolute-delta bucket.
p Modelled put implied-volatility level at the same absolute-delta bucket.
d Endpoint-specific derived value: risk reversal c - p, butterfly (c + p) / 2 - atm, or normalized skew (p - c) / atm * 100.
b Interpolated bid implied volatility for the requested delta and tenor.
a Interpolated ask implied volatility for the requested delta and tenor.
m Independently interpolated exchange mark implied volatility. It is not (b + a) / 2 and may lie outside the bid/ask interval.

Cross-currency Other

Futures and perpetual aggregate endpoints classify BTC and ETH by base_currency. Other is the sum of rows whose base currency is neither BTC nor ETH, after the requested date and granularity filters and the endpoint’s future/perpetual type filter.

Options aggregate endpoints include all non-CME option rows in the requested date/granularity window. BTC and ETH require both the matching currency and their canonical instrument prefix; Other is every remaining included row.

Membership is deterministic for a fixed stored dataset and query. If a documented correction or backfill changes historical source rows, the affected window and effective version are published in the correction feed.

Logical row identity and canonical values

One endpoint natural key and timestamp identify one logical observation. Rows or repeated responses that differ only at floating-point representation scale are not separate market observations and should not both be retained.

Before the 1 August 2026 canonical-query deployment, some request-time currency aggregates could sum floating-point values in different parallel orders. There was no authoritative bit-level winner between those legacy representations. The corrected endpoints use fixed-scale accumulation and return a canonical value. See correction record HIST-2026-08-01-V1-CANONICAL-QUERIES for re-collection scope.

Publication cadence and availability

Publication cadence is not a maximum availability guarantee. Unless endpoint-specific response metadata states otherwise, the historical APIs currently have no contractual worst-case publication lag. During an incident, lag can exceed the normal cadence; incidents and recovery updates are published in the data-status feed.

  • V2 one-minute derivatives bars are persisted from finer live events and normally become queryable after ingestion of the closed minute. Higher resolutions are computed at request time from those rows and have no separate materialization schedule.
  • V1 options model and actual-volatility publications run every five minutes. Their normal expectation is the next successful scheduled run.
  • V1 realized volatility runs hourly at minute 6. Its normal expectation is the next successful hourly run.
  • Cross-currency aggregates are computed at request time from persisted source rows and add no separate publication schedule.
  • Liquidation histories are sparse event streams, not hourly heartbeats. Their latest event timestamp is not, by itself, a measure of publication lag.