Spot metals API reference

Spot prices for gold, silver, platinum and palladium, plus WTI, Brent and copper reference prices, with units and UTC timestamps.

Authentication and request

Send your API key in the Authorization bearer header. Product overview →

curl "https://api.narwhalapi.com/v1/commodities/spot/XAU/USD" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

Operations

Endpoint	Operation
`GET /v1/commodities/spot/{commodity}/{currency}`	Get a spot price or a futures-based reference price.
`GET /v1/commodities/spot/{commodity}/{currency}/bars`	Get open, high, low and close bars for gold, silver, platinum, palladium, WTI and BRENT. Copper history is not available yet.

Parameters

Field	Meaning
`commodity`	Path parameter. XAU, XAG, XPT, XPD, WTI (WTI crude oil), BRENT (Brent crude oil), or XCU (copper).
`currency`	Path parameter, uppercase. Gold: USD, AUD, BGN, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, IDR, ILS, INR, ISK, JPY, KRW, MXN, MYR, NOK, NZD, PHP, PLN, RON, SEK, SGD, THB, TRY, or ZAR. Silver, platinum, palladium, WTI, BRENT and XCU: USD only.
`interval`	Bars only. 1m, 5m, 15m, 1h, 4h, or 1d (default).
`start / end`	Bars only. UTC instants at whole interval boundaries (4h at 00, 04, 08 and so on; 1d at midnight). Start is inclusive; end is exclusive.
`limit / cursor`	Bars only. Default 100, at most 500. Reuse next_cursor with the same query.

Quote fields

Field	Meaning
`symbol, currency, unit`	The symbol and quote currency. unit is troy_ounce for precious metals, barrel for WTI and BRENT, and pound for XCU.
`price`	One positive indicative price as a decimal string.
`timestamp, stale`	Quote UTC timestamp and explicit freshness flag.
`bars`	Bars only. Closed bars, oldest first, each with timestamp (bar start) and open, high, low and close as four-decimal strings. Gold in currencies other than USD has close only.
`next_cursor`	Bars only. Continuation cursor; null when no bars remain.

Illustrative response for GET /v1/commodities/spot/{commodity}/{currency}.

Quote response

{
  "symbol": "XAU-USD",
  "price": "2500.00",
  "currency": "USD",
  "unit": "troy_ounce",
  "timestamp": "2026-08-21T12:00:00Z",
  "stale": true
}

Interpreting the data

WTI, BRENT and XCU are reference prices derived from futures markets, not physical spot cargo prices. Display the unit and timestamp with the price. The timestamp is the start of the minute the price belongs to; the daily 21:00-22:00 UTC pause returns stale: true. A quote can be stale while markets are closed; do not present it as a fresh market price. Other commodity or currency combinations return 404. Price history is available for gold, silver, platinum, palladium, WTI and BRENT, but not XCU. We never fill gaps: missing bars stay missing. We keep minute bars for 30 days and hourly and daily bars indefinitely, within your plan's history window. WTI and BRENT have 15-minute and hourly history from 2020.

Error format and quota →

MCP tools

commodities_get_spot_pricecommodities_get_price_history

Connect through MCP →