Report Schema: Futures (v14)
Available Report Schemas
Choose the schema version you want to explore.
Chainlink Data Streams that use the Futures (v14) schema adhere to the structure outlined below.
Schema Fields
| Field | Type | Description |
|---|---|---|
feedId | bytes32 | Unique identifier for the Data Streams feed |
validFromTimestamp | uint32 | Earliest timestamp when the price is valid (seconds) — How report timestamps work |
observationsTimestamp | uint32 | Latest timestamp when the price is valid (seconds) — How report timestamps work |
nativeFee | uint192 | Legacy onchain verification fee field |
linkFee | uint192 | Legacy onchain verification fee field; not used for subscription billing |
expiresAt | uint32 | Expiration date of the report (seconds) |
midPrice | int192 | DON consensus mid price |
bidPrice | int192 | DON consensus bid price |
askPrice | int192 | DON consensus ask price |
expiryTime | uint64 | Contract expiration time (Unix seconds) |
firstDayOfNotice | uint64 | First day of notice for the tracked contract (Unix seconds) |
lastSeenTimestampNs | uint64 | Timestamp of the last update received from the data provider (nanoseconds) |
marketStatus | uint32 | Market status. Mapping varies by feed; see schema docs. — Status values |
contractMonth | uint32 | Standard futures month code (F=Jan, G=Feb, H=Mar, J=Apr, K=May, M=Jun, N=Jul, Q=Aug, U=Sep, V=Oct, X=Nov, Z=Dec) |
goldmanRollPrice | int192 | Continuous price using the Goldman Roll (GSCI) methodology |
currentBusinessDay | uint32 | Current business day count within the active roll window |
interpolatedGoldmanRollPrice | int192 | Interpolated Goldman Roll price (0 when not in an active roll window) |
Market Status Values
Each feed's marketStatus field reflects the current market status of the primary exchange venue for that instrument. Futures trade during standard trading hours for each instrument, with a scheduled break each trading day. Consult the exchange where the underlying contract is listed for holiday and early-close schedules.
For full trading schedules and marketStatus mappings, see Market Hours and the Futures reference.
Continuous roll price fields
In addition to the raw generic feed prices — which switch entirely to the next contract at the first notice date — the v14 schema includes continuous price series built using alternative rolling methodologies, for integrators who want a smoothed price instead of a hard cutover:
| Field | Description |
|---|---|
goldmanRollPrice | Uses the Goldman Roll (GSCI methodology): shifts 20% of the position to the next contract each business day, over business days 5–9 of the month preceding delivery |
interpolatedGoldmanRollPrice | Interpolated Goldman Roll price. Reported as 0 when the feed is not within an active roll window |
currentBusinessDay | Current business day count within the active roll window, so integrators can implement the Goldman Roll methodology themselves |
For details on how the generic feeds rotate between contracts and how the continuous roll fields behave, see the Futures reference.
Notes
lastSeenTimestampNs
lastSeenTimestampNshelps applications detect stale data, especially important during market transitions and holidays.- Do not use
lastSeenTimestampNs(or any other timestamp field) to determine whether the market is open. Timestamps indicate when data was last recorded, not whether the market is currently active. Use themarketStatusfield as the authoritative signal for market availability.
interpolatedGoldmanRollPrice
interpolatedGoldmanRollPrice is reported as 0 when the feed is not within an active roll window. Behavior on non-trading days (holding the last value versus resetting to zero) is still being finalized.