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 | Contract month, from 1 (Jan) to 12 (Dec) |
goldmanRollPrice | int192 | Goldman Roll price (GSCI methodology; 20% shifted per business day over days 5–9) |
currentBusinessDay | uint32 | Current business day of the month, used to determine the Goldman Roll window |
interpolatedGoldmanRollPrice | int192 | Interpolated Goldman Roll price: the 20% daily shift to the next contract, smoothed over each business day in the 5–9 window |
Market Status Values
Each feed's marketStatus field reflects the current market status for that instrument. Futures streams follow the trading hours of the underlying market, with a scheduled break each trading day. Use marketStatus in each report rather than an expected session schedule.
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 when the front contract expires — 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: the Goldman Roll's 20% daily shift to the next contract, smoothed over the course of each business day, 5–9, of the month preceding delivery |
currentBusinessDay | Current business day of the month, used to determine the Goldman Roll window |
For details on how the generic feeds rotate between contracts and how the Goldman 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 to determine market availability.
interpolatedGoldmanRollPrice
interpolatedGoldmanRollPrice is a smoothed version of the Goldman Roll. It applies the 20% daily shift to the next contract over the course of each business day, 5–9, of the month preceding delivery.