DocsCommodities

Commodities

Indicative reference prices for precious and industrial metals, energy benchmarks, and agricultural contracts, normalized for dashboards, research tooling, and cross-asset displays. Not a claim about physical delivery, warehouse stocks, or venue-listed futures.

Open .md
Authx-api-key headerBase path/commoditiesWebSocketcommodities.quotes · commodities.tradesSymbol formatCanonical codes and aliases (e.g. XAUUSD, WTIUSD)

Data is consolidated and indicative: it may differ materially from any single venue or official settlement print.

Symbols

Metals

Precious and industrial metals vs USD.

XAUUSDXAGUSDXPTUSDXPDUSDCOPPERUSD

Energy

Oil and gas benchmarks.

WTIUSDBRENTUSDNGASUSD

Agriculture

Grains and softs. SUGARUSD values are cents per pound.

WHEATUSDCORNUSDSOYBEANUSDSUGARUSD

Use GET /commodities/symbols to list the canonical commodity symbols.

Accepted aliases map to canonical codes, for example USOILUSD and CL1 to WTIUSD; XBRUSD and BZUSD to BRENTUSD; HG1 to COPPERUSD. The symbol list returns canonical codes; quote and aggregate routes accept aliases where configured, and responses carry the canonical code (a request for CL1 answers as WTIUSD).

GET/commodities/symbols
Open .md

Symbol list

Canonical commodity symbols for the REST API. Aliases are accepted on quote/snapshot/aggregate routes but are not repeated in this list.

Request

curl -sS "https://api.tickerlayer.com/commodities/symbols" \
  -H "x-api-key: <YOUR_API_KEY>"

Response 200 OK

JSON
{
  "symbols": [
    { "symbol": "BRENTUSD", "name": "Brent crude oil" },
    { "symbol": "CANOLAUSD", "name": "Canola / rapeseed" },
    { "symbol": "XAUUSD", "name": "Gold" },
    { "symbol": "WTIUSD", "name": "WTI crude oil" }
  ]
}
GET/commodities/quote/:symbol
Open .md

Latest quote

Consolidated bid/ask with sizes and timestamp from the aggregated commodity quote view.

Path parameters

symbolstringRequired
Enabled commodity symbol (e.g. XAUUSD, WTIUSD). Trimmed and uppercased before lookup. Discover tickers with GET /commodities/symbols.

Request

curl -sS "https://api.tickerlayer.com/commodities/quote/XAUUSD" \
  -H "x-api-key: <YOUR_API_KEY>"

Send runs against the live API with your account key (never exposed in the browser).

Response 200 OK

JSON
{
  "symbol": "XAUUSD",
  "bid": 2318.10,
  "ask": 2318.74,
  "bid_size": 72,
  "ask_size": 68,
  "timestamp": 1743512400000
}

Notes

404 commodity symbol not supported when the code is not in the curated registry. 404 no quote available when no consolidated quote can be resolved. 503 service temporarily unavailable when data cannot be retrieved temporarily.
GET/commodities/trade/last/:symbol
Open .md

Last trade

Most recent trade-like price for the symbol when present; otherwise a deterministic midpoint derived from the consolidated quote.

Path parameters

symbolstringRequired
Enabled commodity symbol (e.g. XAUUSD, WTIUSD). Trimmed and uppercased before lookup. Discover tickers with GET /commodities/symbols.

Request

curl -sS "https://api.tickerlayer.com/commodities/trade/last/XAUUSD" \
  -H "x-api-key: <YOUR_API_KEY>"

Send runs against the live API with your account key (never exposed in the browser).

Response 200 OK

JSON
{
  "symbol": "XAUUSD",
  "price": 2318.42,
  "size": 42,
  "timestamp": 1743512400000
}

Notes

404 symbol not available when the code is not in the curated registry; 404 no fresh trade available when no quote can be resolved.
GET/commodities/snapshot/:symbol
Open .md

Snapshot

Combined bid/ask, last price, previous daily close, and derived change metrics in one normalized commodity snapshot.

Path parameters

symbolstringRequired
Enabled commodity symbol (e.g. XAUUSD, WTIUSD). Trimmed and uppercased before lookup. Discover tickers with GET /commodities/symbols.

Request

curl -sS "https://api.tickerlayer.com/commodities/snapshot/WTIUSD" \
  -H "x-api-key: <YOUR_API_KEY>"

Send runs against the live API with your account key (never exposed in the browser).

Response 200 OK

JSON
{
  "symbol": "WTIUSD",
  "bid": 71.22,
  "ask": 71.25,
  "bid_size": 58,
  "ask_size": 55,
  "last_price": 71.235,
  "last_timestamp": 1743512400000,
  "prev_close": 70.90,
  "change": 0.335,
  "change_percent": 0.472
}

Notes

last_size appears when a trade size is available in the consolidated snapshot; otherwise it is omitted from the payload. change_percent is null when prev_close is zero or unavailable. An unknown symbol or an all-null snapshot returns 404.
GET/commodities/agg/:symbol/prev
Open .md

Previous bar

Single most-recently completed UTC daily candle for the symbol.

Path parameters

symbolstringRequired
Enabled commodity symbol (e.g. XAUUSD, WTIUSD). Trimmed and uppercased before lookup. Discover tickers with GET /commodities/symbols.

Query parameters

intervalstring
Returns the most recently settled bar at that interval instead of the previous daily bar, and adds interval, bar_start, bar_end and as_of to the response. Leave it out for the daily bar.
Values1m5m15m1h4h1d

Request

curl -sS "https://api.tickerlayer.com/commodities/agg/XAUUSD/prev" \
  -H "x-api-key: <YOUR_API_KEY>"

Response 200 OK

JSON
{
  "symbol": "XAUUSD",
  "result": {
    "o": 2295.10,
    "h": 2325.40,
    "l": 2288.20,
    "c": 2318.42,
    "v": 0,
    "t": 1733011200000
  }
}

Notes

404 no bar available when the daily bar cannot be resolved yet. A bar requested with ?interval= is held for a short settle lag after it closes, so small clock differences between callers do not change which bar comes back, and it is the same bar the range endpoint returns for that window. Cache-Control and ETag mark when the value can next change. While the market is closed the last real bar is returned, still labelled with its own bar_start.
GET/commodities/agg/:symbol/:multiplier/:timespan/:from/:to
Open .md

Aggregate bars (OHLCV)

Historical bars between two UTC calendar dates.

Path parameters

symbolstringRequired
Enabled commodity symbol (e.g. XAUUSD, CORNUSD). Trimmed and uppercased before lookup.
multipliernumberRequired
Bar size in units of timespan: 1, 5 or 15 with minute; 1 or 4 with hour; 1 with day. Other pairs return 400, and the message lists the valid ones.
timespanstringRequired
Case-insensitive. Other values return 400.
Valuesminutehourday
fromstringRequired
First UTC date, inclusive, as YYYY-MM-DD.
tostringRequired
Last UTC date, inclusive, as YYYY-MM-DD. Not before from.

Query parameters

limitnumber
Page size, up to 5000. results_count is the size of this page and total_count the bars in the whole range; follow next_offset until it is null.
Default500
offsetnumber
Zero-based row offset, applied after sorting.
Default0
sortstring
Order of bars by timestamp t, applied before pagination.
ValuesascdescDefaultdesc

Request

curl -sS "https://api.tickerlayer.com/commodities/agg/XAUUSD/1/day/2025-11-01/2025-11-30?sort=desc&limit=2" \
  -H "x-api-key: <YOUR_API_KEY>"

Response 200 OK

JSON
{
  "symbol": "XAUUSD",
  "results_count": 2,
  "results": [
    { "o": 2295.10, "h": 2325.40, "l": 2288.20, "c": 2318.42, "v": 0, "t": 1733011200000 },
    { "o": 2270.50, "h": 2305.00, "l": 2265.00, "c": 2295.10, "v": 0, "t": 1732924800000 }
  ],
  "next_offset": 2
}

Notes

  • One request covers at most 31 days of 1-minute bars, 90 of 5-minute, 180 of 15-minute, 365 of hourly, 730 of 4-hour and 5000 of daily bars, counting from and to as whole UTC days. A longer range returns 400 with the limit in the message.
  • v is the aggregated volume for the bar. For energy, copper and the agricultural contracts it is the front-month futures contract's exchange volume over the bar's span; for the metals it comes from the aggregation layer. It is null when no volume is available for that bar, and 0 when the bar traded nothing.

WebSocket

Stream live quotes and trades for this asset class over the public WebSocket.

Connect
wss://stream.tickerlayer.com/?apiKey=<YOUR_API_KEY>

Available channels

Quotescommodities.quotesTradescommodities.trades

Subscribe example

After the connection is ready, send a JSON text frame:

Subscribe
{
  "action": "subscribe",
  "channels": [
    "commodities.quotes",
    "commodities.trades"
  ],
  "symbols": [
    "XAUUSD",
    "WTIUSD"
  ]
}

Example message

commodities.quotes
{
  "type": "quote",
  "channel": "commodities.quotes",
  "asset": "commodities",
  "symbol": "XAUUSD",
  "bid": 2318.1,
  "ask": 2318.74,
  "bid_size": 58,
  "ask_size": 48,
  "ts": 1743512400000,
  "timestamp": 1743512400000
}

General WebSocket documentation

For authentication, subscribe/unsubscribe lifecycle, errors, limits, and heartbeats, see the WebSocket overview, Subscriptions and Message types.