Futures API
Latest available and historical futures data for energy commodities. Access contract prices, spreads, curves, and OHLC data with source timestamps.
Available Commodities
| Commodity | Exchange | Base Endpoint | Contracts |
|---|---|---|---|
| Brent Crude | ICE | /v1/futures/ice-brent | 12 months |
| WTI Crude | NYMEX / ICE | /v1/futures/ice-wti or /v1/futures/nymex-wti | 12 months |
| Gas Oil | ICE | /v1/futures/ice-gasoil | 12 months |
| Natural Gas | NYMEX | /v1/futures/natural-gas | 12 months |
| EUA Carbon | ICE | /v1/futures/eua-carbon | 12 months |
| EU Carbon | ICE | /v1/futures/eu-carbon | 12 months |
| TTF Gas | ICE Endex | /v1/futures/ttf-gas | 12 months |
| LNG JKM | ICE | /v1/futures/lng-jkm | 12 months |
| UK Carbon / UKA | ICE | /v1/futures/uk-carbon | Base, historical, and curve only |
| Brent / WTI continuous | ICE / NYMEX | /v1/futures/continuous/{brent,wti} | Auto-rolled front-month series; base and /historical only |
Endpoint Types
Most futures products support 7 endpoint types. UK carbon currently supports the base, historical, and curve endpoints (curve verified live in production 2026-07-22); do not assume OHLC, intraday, spreads, or spread-history are available for UKA until the backend ships them. Note the canonical slug is uk-carbon — not uka-carbon.
| Endpoint | Description | Use Case |
|---|---|---|
/ | Current prices | Real-time contract prices |
/historical | Date range data | Backtesting, analysis |
/ohlc | Daily OHLC | Charting, technical analysis |
/intraday | 5-minute intervals | Intraday trading |
/spreads | Calendar spreads | Spread trading |
/curve | Futures curve | Contango/backwardation analysis |
/spread-history | Historical spreads | Spread trend analysis |
Quick Start
# Get current Brent futures prices
curl "https://api.oilpriceapi.com/v1/futures/ice-brent" \
-H "Authorization: Token YOUR_API_KEY"
{
"commodity": "BRENT_FUTURES",
"source": "market_reporting",
"updated_at": "2025-12-29T14:30:00.000Z",
"trading_hours": "01:00-23:00 GMT",
"contracts": [
{
"contract_month": "2026-02",
"last_price": 74.52,
"currency": "USD",
"open": 74.15,
"close": 74.45,
"high": 74.85,
"low": 74.0,
"volume": 125432,
"change_percent": 0.47,
"days_to_expiry": 20,
"contract_status": "front_month",
"is_front_month": true,
"is_nearest_contract": true,
"expiry_date": "2026-01-30",
"open_interest": 285432
}
],
"metadata": {
"total_contracts": 12,
"data_source": "market_reporting",
"front_month_contract": "2026-02",
"nearest_contract_month": "2026-02",
"front_month_selection": {
"method": "roll_warning_days",
"roll_warning_days": 7,
"nearest_contract": "2026-02",
"nearest_days_to_expiry": 20,
"front_month_contract": "2026-02",
"rolled": false,
"reason": "nearest still-trading contract 2026-02 is outside the 7-day roll window, so front_month and nearest_contract are the same contract"
}
}
}
/v1/futures/nymex-wti and its sub-paths (/historical, /ohlc, /intraday, /spreads, /curve, /spread-history) serve the same WTI family as /v1/futures/ice-wti, with an identical response. The family follows the NYMEX CL contract calendar. See WTI Futures.
Price fields: close is a capture, not a settlement
close is the last price we collected for the trading session, at close_captured_at. It is not the exchange settlement. settlement is the exchange settlement where one was captured, and null otherwise; it is never copied from close or last_price. settlement_date is the trading session a quote belongs to and does not mean a settlement price exists for it.
| Field | Meaning |
|---|---|
last_price | Most recent price we collected |
close | Last price collected for the session, at close_captured_at (UTC, our collection time) |
settlement | Exchange settlement where captured, otherwise null. On the latest curve it appears only for gas oil; for other markets it is on /historical |
change_percent | Captured close versus captured open for the same session. open may be the first price we collected, not the session open |
change_from_prior_close_percent | Captured close versus this contract's previous captured close, dated by prior_close_date |
change_from_prior_settlement_percent | Settlement versus the previous session's settlement (/historical daily rows). null when either is missing |
For change_from_prior_close_percent, the prior close is the latest earlier weekday close for the same contract within 7 days, so weekends and missed sessions are bridged. Both fields are null when there is no such close. For *_CONTINUOUS codes the prior close can belong to the previous contract month on a roll day.
The latest curve endpoints carry close_captured_at, change_from_prior_close_percent and prior_close_date on each contract that has a captured close, and state these definitions in metadata.field_semantics.
Historical query parameters
These apply to /historical on every contract family (ice-brent, ice-wti/nymex-wti, ice-gasoil, natural-gas, eua-carbon/eu-carbon, uk-carbon, ttf-gas, lng-jkm).
| Parameter | Description |
|---|---|
from, to | Window as YYYY-MM-DD. Default: the last 30 days. start_date and end_date are accepted as aliases; send one spelling, not both |
days | The last N days ending today (1-730). Cannot be combined with from, to, start_date or end_date |
contracts | Comma-separated contract months, such as 2026-02,2026-03. Default: every contract. contract_month is accepted for one month |
interval | daily (default), weekly or monthly. weekly and monthly replace trading_date with period_start/period_end and add avg_close and trading_days |
format | json (default) or csv. Anything else returns 400 INVALID_PARAMETER |
The window can span at most 730 days, and to cannot be in the future.
Any other query parameter returns 400 UNKNOWN_PARAMETERS, with unrecognized_parameters, allowed_parameters and suggestions in the body. For example, period suggests days, and contract (singular) suggests contracts. Earlier, unknown parameters were ignored and the default 30-day window was returned with HTTP 200. The check runs after authentication and the futures entitlement check, and a rejected request does not count against your quota.
Continuous series accept from, to, start_date, end_date, days (1-7300), months (1-240) and interval, and return JSON only.
Daily history rows
With interval=daily, each row in contracts[].daily_data has trading_date, open, high, low, close, volume, open_interest, change_percent, settlement, open_captured_at, close_captured_at, change_from_prior_settlement_percent, settlement_available, change_from_prior_close_percent and prior_close_date. settlement_available is true only on rows that carry an exchange settlement. The response metadata object defines close, close_captured_at, settlement and the change fields.
CSV
format=csv returns text/csv as a download named futures_historical_<from>_<to>.csv. Daily columns:
contract_month,contract_code,date,open,high,low,close,change_percent
With interval=weekly or monthly:
contract_month,contract_code,period_start,period_end,open,high,low,close,avg_close,volume,trading_days
The CSV does not include settlement or the prior-close fields; use JSON for those.
Authentication
All futures endpoints require authentication:
Authorization: Token YOUR_API_KEY
Endpoints
- ICE Brent Futures
- WTI Futures (
ice-wti,nymex-wti) - ICE Gas Oil Futures
- NYMEX Natural Gas Futures
- ICE EUA Carbon Futures
- ICE EU Carbon Futures
- TTF Gas Futures
- LNG JKM Futures
- UK Carbon Futures
Enhanced Contract Data
Each contract includes additional fields for trading intelligence:
| Field | Type | Description |
|---|---|---|
days_to_expiry | integer | Days until contract expires |
contract_status | string | Current contract status |
is_front_month | boolean | Whether this is the front month contract |
is_nearest_contract | boolean | Whether this is the nearest contract still trading (see below) |
expiry_date | date | Calculated expiry date |
open_interest | integer | Open interest (when available) |
Contract Status Values
| Status | Description |
|---|---|
front_month | Primary trading contract (>7 days to expiry) |
near_expiry | Contract expiring within 7 days |
active | Future contract with >30 days to expiry |
expired | Contract has expired |
Front month vs. nearest contract
front_month is the contract the market has substantially rolled into. It moves to the next contract 7 days before the current one's last trading day (roll_warning_days), so for a few days each month the contract that is still trading is not the front_month.
If you run your own roll rule, use nearest_contract instead. It is the nearest unexpired contract and stays in place through its own last trading day. Both are returned side by side, and metadata.front_month_selection states which method chose front_month and whether the two currently differ:
{
"front_month": { "contract_month": "2026-09", "is_front_month": true, "..." : "..." },
"nearest_contract": { "contract_month": "2026-08", "contract_status": "near_expiry", "is_nearest_contract": true, "days_to_expiry": 6, "..." : "..." },
"metadata": {
"front_month_contract": "2026-09",
"nearest_contract_month": "2026-08",
"front_month_selection": {
"method": "roll_warning_days",
"roll_warning_days": 7,
"nearest_contract": "2026-08",
"nearest_days_to_expiry": 6,
"front_month_contract": "2026-09",
"rolled": true,
"reason": "nearest contract 2026-08 is within 7 days of its last trading day (6 days remaining), so front_month has rolled to 2026-09; 2026-08 continues to trade until its expiry_date"
}
}
}
| Field | Meaning |
|---|---|
nearest_contract | Nearest contract still trading, held through its last trading day. Same shape as front_month. |
metadata.front_month_selection.method | The rule that chose the current front_month: roll_warning_days (proximity, with the 7-day early roll), december_benchmark (EU carbon's liquid December contract), liquidity_benchmark (EU carbon with no December listed: highest volume), or none (the only contract still trading is inside the roll window, so no front_month is designated). |
metadata.front_month_selection.rolled | true while front_month and nearest_contract are different contracts. |
metadata.front_month_selection.reason | Plain-language explanation of the current selection. |
To apply your own rule, take contracts[], filter on days_to_expiry / expiry_date, and ignore front_month entirely. Nothing about front_month changed when these fields were added.
Roll Indicator
When the front month is near expiry, the API includes a roll indicator:
{
"roll_indicator": {
"should_roll": true,
"days_remaining": 4,
"next_contract": "2026-04",
"message": "Consider rolling to April 2026 contract"
}
}
Trading Hours
| Exchange | Hours (Local) | Hours (GMT) |
|---|---|---|
| ICE Brent | 01:00-23:00 | 01:00-23:00 |
| ICE WTI | 01:00-23:00 | 01:00-23:00 |
| ICE Gas Oil | 01:00-23:00 | 01:00-23:00 |
| ICE EUA Carbon | 07:00-17:00 CET | 06:00-16:00 |
| NYMEX Nat Gas | 18:00-17:00 ET | 23:00-22:00 |
Data Updates
- Intraday: Source-dependent refresh during trading hours
- Settlement: Daily at 19:30 GMT
- Historical: 30+ days retention
Access and Limits
Futures Data is included with Professional and Scale. An active trial may include futures access, but that access ends when the trial ends unless the account has a futures-entitled plan or add-on. Free includes spot data, not ongoing access to /v1/futures/*. The Free allowance of 50 requests per day applies to endpoints available on Free; it does not grant futures entitlement.
Other paid plans can add Futures Data for $39/month from Dashboard → Billing. A key without Futures Data receives 403; the response includes message, current_plan, required_plan, and access_url so the account owner can choose a supported plan or add-on. A rejected request does not count against the allowance.
Errors
| Status | Code | When |
|---|---|---|
401 | UNAUTHORIZED | Missing or invalid API key |
403 | — | Key has no Futures Data entitlement (see above) |
503 | DATA_TOO_STALE | The newest quote for the family is more than 96 hours old. The body carries data_age_hours, max_age_hours (96), last_updated, and commodity. Quotes under 96 hours old are served; older-than-usual ones carry a data_age_warning string such as Data is 26.0 hours old. |
503 | LIVE_DATA_STALE | Gasoil and Henry Hub natural-gas families only (their family-latest and /intraday endpoints): intraday data went stale while the market is open (distinct from the 96-hour bound above, which is checked first and applies at all hours). The error object carries the market-hours context — freshness_status, market_status, expected_live_updates, checked_at, market_timezone, and (when a timestamp exists) latest_data_at and stale_by_minutes — with commodity at the top level. A refresh is normally triggered automatically; retry after a few minutes. |
503 | — | No futures data held for the family |
The 96-hour ceiling clears the longest weekend and holiday closures observed across the futures families (about 62 hours), so a normal weekend never triggers it.