asset_* metadata keys. Today these are the WTI crude oil and natural gas markets: product codes cpwtif (“WTI Crude Oil Futures Price Contracts”) and cpngf (“Natural Gas Futures Price Contracts”). Do not parse the instrument symbol or slug — symbol formats are not part of the public contract and may change. Identify markets using the fields below.
The asset_* keys are the standard for new Up/Down markets on assets other than crypto. Gold and silver keep the metals_* keys they launched with (see Metals Schema), and crypto keeps the crypto_* keys (see Crypto Schema). An instrument carries one key set only.
Every WTI and natural gas window settles on a Chainlink futures mid price data stream: the mid price that Chainlink calculates from the bid and ask quotes for the front-month futures contract. It is not a traded price or an exchange settlement price. Only prices published while the stream marks the market as open count. The Retail API exposes the same terms as the typed assetPriceTerms object; see Asset Price Market Fields.
The windows work like the gold and silver windows in Metals Schema: the same weekly trading hours, a single value at each boundary, trading from the window start and a price to beat about a minute later. The differences are:
- The field names:
asset_*in place ofmetals_*. - Three keys that only
asset_*windows carry:asset_class,asset_price_decimalsandasset_contract_month. - Each window states its decimals in
asset_price_decimals: 2 for WTI, 4 for natural gas. A window keeps the decimals it was listed with. - The price follows a futures contract that rolls to the next month.
asset_contract_monthnames the contract. - The holidays and early closes follow CME Globex, not the metals calendar.
WTI and natural gas Up/Down windows are listed in production from November 18, 2026, as announced in the changelog. For the rules, trading hours and holiday calendar, see Oil and Gas FAQs.
Section 1: Common Identifying Fields
The following fields appear on everyasset_* Up/Down instrument. Together they identify the asset, the market type and the time window of a contract.
Field Reference
The instrument also carries display fields you can ignore for mapping:
market_title, market_subtitle, asset_display_name, event_sort_type, event_tags, instrument_rules, event_image and event_image_display_type (once the asset has an image), and the CFTC reporting fields cftc_instrument_id, cftc_binary_option_strike_price_alias. Unlike crypto, asset_* instruments carry no market_sort_order, market_color or market_dark_color. cftc_product_desc is in the table above because it names the product. Operational fields (requires_manual_settlement, manual_settlement_*, expected_settlement_side, settlement_*) can appear while the exchange is settling an instrument and must be ignored. asset_* instruments carry no crypto_* and no metals_* fields.
asset_market_type Enum
Treat an unknown value as a newer family: render the fields that are present and watch the changelog.
asset_class Enum
Treat an unknown value as a newer class: the asset slug and the prices are still valid.
asset_horizon Enum
Series
event_series combines asset, family and cadence:
Each window’s
market_title names the cadence without parentheses, e.g. WTI Crude Up or Down 15m, WTI Crude Up or Down Hourly or Natural Gas Up or Down Daily.
Event Attributes
event_attributes records the contract for the exchange’s DCM record: strike_value: "Up", strike_unit: "string", strike_description: "Direction", evaluation_type: "==", source agency Chainlink (https://data.chain.link). Each instrument resolves independently (EVENT_OUTCOME_INDEPENDENT). Settlement never depends on these fields; the asset_* metadata above and the rules text are authoritative.
Section 2: Market Families
All windows share the same contract attributes as the gold, silver and crypto Up/Down windows: tick size0.01, valid prices 0.01 to 0.99, minimum order 0.01 contract, payout $1.00 per contract, position accountability level 25,000 contracts, and a daily trade-day roll at 5:00 PM ET. Last trade is the settlement instant (interval_end); the instrument expires 30 minutes later, which leaves time for the exchange to resolve it. Source agency is Chainlink.
Up/Down
Will the price of WTI crude oil futures (natural gas futures) close the window at or above its open?
The window trades without a
price_to_beat for about its first minute. This is by design: the open value does not exist on the DataStore until Chainlink writes it. Re-read the instrument after interval_start rather than assuming the value at listing.
Pending Price to Beat
A window can carrypending_price_to_beat before price_to_beat arrives. It is Chainlink’s report for exactly interval_start as the exchange received it, rounded to the window’s asset_price_decimals. It is for display only:
- It is written at most once, usually 1 to 2 seconds after the window starts, and only while
price_to_beatis absent. It is never changed or removed, so it stays on the instrument next toprice_to_beat. - It can be absent, for example when Chainlink has no report for exactly the window start.
- In rare cases it can differ from
price_to_beat. The window settles only onprice_to_beat, the DataStore value. - Show
price_to_beatwhen it is present, elsepending_price_to_beatlabelled as pending. - The key has no relation to the
PENDINGinstrument state.
assetPriceTerms.pendingPriceToBeat. That field is null again once priceToBeat is set, and null on assets where a pending price is not shown.
Section 3: Identifying Markets
Use this table to identify a market from instrument metadata. Match onasset_market_type, then read the asset from asset_slug and the window from interval_start / interval_end.
event_category = "FIN" and event_subcategory = "COMMODITY" also match gold, silver and other commodity products, and every asset_* market carries asset_market_type. Select WTI and natural gas by asset_slug or the clearing symbol.
Worked Example: 15-Minute Natural Gas Window
A settled 15-minute natural gas window that opened at 23:15 UTC on November 15, 2026 (preprod values):asset_market_type = "updown"→ an up/down window;asset_horizon = "15m"→ 15 minutes long.interval_start/interval_end→ the window ran from 23:15:00 to 23:30:00 UTC (6:15 to 6:30 PM ET on Sunday), the first 15-minute window after the weekend.asset_price_decimals = "4"→ every price of this window carries four decimals.price_to_beat = "3.1595"→ the natural gas mid price at 23:15:00, on the December 2026 contract (asset_contract_month);asset_settlement_price = "3.1624"→ the mid price at 23:30:00.- Close ≥ open, so the long side (Yes, “Up”) paid $1.00.
asset_next_window_startequalsinterval_end→ the next 15-minute window opened straight after this one.
Worked Example: Daily WTI Window
A daily WTI window has this shape (preprod values from the window that opened at the 6:15 PM ET evening open on Sunday, November 15, 2026, before it settled):asset_horizon = "1d"→ a daily window.interval_start/interval_end→ 23:15 UTC on November 15 to 22:00 UTC on November 16 (6:15 PM to 5:00 PM ET), 22 hours 45 minutes.asset_price_decimals = "2"andprice_to_beat = "88.25"→ WTI carries two decimals.asset_contract_month = "2026-12"→ the window opened on the December 2026 contract and settles on the same contract.asset_next_window_start = "1794870900"→ the next daily opens at 23:15 UTC on November 16 (6:15 PM ET), after the daily break.
Best Practices
- Never parse the symbol or slug to determine the asset, market type or window. Symbol formats are not part of the public contract.
- Map on
asset_market_typeandasset_class. Treat an unknown value as newer: render the terms that are present and watch the changelog. - Read windows from
interval_startandinterval_end, not from the instrument’s expiration date, which is 30 minutes after settlement. - Read the decimals from
asset_price_decimalson each window. Show and compare every price of the window at exactly that many places. Do not assume one value per asset: a window keeps the decimals it was listed with. - Treat every price as a decimal string (
price_to_beat,pending_price_to_beat,asset_settlement_price) and convert it yourself. - Expect
price_to_beatabout a minute after a window opens. Re-read the instrument afterinterval_start. - Use
pending_price_to_beatfor display only. Show it, labelled as pending, only whileprice_to_beatis absent. Never settle or reconcile a window on it. - Use
asset_contract_monthacross contract rolls. A step between the last window before a roll and the first window after it is a change of contract, not a price move. - Use
asset_next_window_startfor closed periods. It tells you when the next window opens after the daily break, the weekend or a holiday. - Read fresh prices from the Retail API.
POST /v1/refdata/instrumentsserves a cached copy of each instrument, soprice_to_beat,pending_price_to_beat,asset_contract_monthandasset_settlement_pricecan appear there up to an hour after they are stamped. The Retail market endpoints (assetPriceTerms.priceToBeat,assetPriceTerms.contractMonthandassetPriceTerms.settlementPrice) update when the value is stamped, andGET /v1/instruments/{symbol}/settlementreads the final settlement from the exchange live. See Settlement API. - Follow each market’s own rules text (
instrument_rules). It names the stream, the two instants and the rounding, says that only prices published while the stream marks the market as open count, leaves the contract roll to Chainlink, and links the full product terms.