Skip to main content
This page documents the strongly-typed fields on the instrument that identify an Up/Down market on the 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 of metals_*.
  • Three keys that only asset_* windows carry: asset_class, asset_price_decimals and asset_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_month names 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 every asset_* 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 size 0.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 carry pending_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_beat is absent. It is never changed or removed, so it stays on the instrument next to price_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 on price_to_beat, the DataStore value.
  • Show price_to_beat when it is present, else pending_price_to_beat labelled as pending.
  • The key has no relation to the PENDING instrument state.
The Retail API shows it as 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 on asset_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):
To interpret this contract:
  1. asset_market_type = "updown" → an up/down window; asset_horizon = "15m" → 15 minutes long.
  2. 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.
  3. asset_price_decimals = "4" → every price of this window carries four decimals.
  4. 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.
  5. Close ≥ open, so the long side (Yes, “Up”) paid $1.00.
  6. asset_next_window_start equals interval_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):
To interpret this contract:
  1. asset_horizon = "1d" → a daily window.
  2. 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.
  3. asset_price_decimals = "2" and price_to_beat = "88.25" → WTI carries two decimals.
  4. asset_contract_month = "2026-12" → the window opened on the December 2026 contract and settles on the same contract.
  5. 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_type and asset_class. Treat an unknown value as newer: render the terms that are present and watch the changelog.
  • Read windows from interval_start and interval_end, not from the instrument’s expiration date, which is 30 minutes after settlement.
  • Read the decimals from asset_price_decimals on 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_beat about a minute after a window opens. Re-read the instrument after interval_start.
  • Use pending_price_to_beat for display only. Show it, labelled as pending, only while price_to_beat is absent. Never settle or reconcile a window on it.
  • Use asset_contract_month across 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_start for 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/instruments serves a cached copy of each instrument, so price_to_beat, pending_price_to_beat, asset_contract_month and asset_settlement_price can appear there up to an hour after they are stamped. The Retail market endpoints (assetPriceTerms.priceToBeat, assetPriceTerms.contractMonth and assetPriceTerms.settlementPrice) update when the value is stamped, and GET /v1/instruments/{symbol}/settlement reads 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.