Docs / API Reference

API Reference

Seven endpoints. Every one returns JSON, accepts a single bearer token, and is idempotent. Base URL: https://api.goldprice.dev/v1

GET/v1/pricesLive spot or futures for one or more symbols.Free+GET/v1/prices/historyAggregated daily OHLC, up to 10+ years.Basic+GET/v1/differentialsSpot-vs-futures and front-vs-back-month spreads.Pro+GET/v1/specificationsContract specs for COMEX GC and related futures.Pro+GET/v1/calendars/eventsMacro and commodity events that move gold.Pro+GET/v1/fundamentalsETF holdings, CB flows, COT positioning.Pro+GET/v1/searchFree-text symbol + event search.Free+

Live prices

GET/v1/pricesBearer · Free+

Returns the latest tick for one or more symbols. Default is XAU-USD-SPOT. Response includes every upstream source in sources[] filtered by tier. Bid/ask are populated on Basic and up; Free returns the primary price only.

Query parameters

symbolsstring[]
Comma-separated symbols. Max 25. Default: XAU-USD-SPOT.
currencystring
Override the quote currency. USD, EUR, GBP, JPY, AUD, INR, CNY, SGD, CAD, CHF, HKD, AED, MXN.
unitstring
One of troy_oz (default), gram, kg, tola, tael.
fieldsstring[]
Field subset. Always includes price and computed_at.

Response codes

200 OK401 invalid_api_key404 unknown_symbol429 rate_limited503 upstream_unavailable

Response schema

// 200 OK
{
  "symbol": string,
  "quote_currency": string,
  "unit": string,
  "contract_type": string,   // "spot" | "futures"
  "price": string,           // decimal — primary source
  "bid": string | null,
  "ask": string | null,
  "is_stale": boolean,
  "computed_at": string,     // ISO-8601 UTC
  "sources": Source[]
}

// Source
{
  "source": string,          // "oracle.xau_usd", "spot_reference.usd", "futures.gc_f", "futures.si_f", ...
  "license": string,         // "commercial-ok" | "reference-only"
  "price": string,
  "timestamp": string
}

Price history

GET/v1/prices/historyBearer · Basic+

Aggregated daily OHLC. Backfilled from multiple archival sources; see methodology for per-source provenance. Free and Basic return the most recent 30 days; Pro returns the full history window.

Query parameters

symbolstringREQUIRED
A single symbol, e.g. XAU-USD-SPOT or XAU-USD-FUTURES.
fromdate
YYYY-MM-DD. Defaults to 30 days ago.
todate
YYYY-MM-DD. Defaults to today.
granularitystring
One of 1d (default), 1w, 1M.

Response codes

200 OK400 invalid_range403 plan_gated429 rate_limited

Response schema

{
  "symbol": string,
  "granularity": string,
  "bars": Bar[]
}

// Bar
{
  "date": string,       // "2026-04-19"
  "open": number,
  "high": number,
  "low": number,
  "close": number,
  "volume": number | null,
  "sources": string[]
}

Spot / futures differentials

GET/v1/differentialsBearer · Pro+

Computed spread between spot and selected futures contract, updated tick-for-tick with the underlying prices. Useful for carry/basis trades and contango tracking.

Query parameters

pairstringREQUIRED
One of spot-gc-front, gc-front-back, spot-gc-m2.
windowstring
Rolling window: 30d (default), 90d, 1y.

Response schema

{
  "pair": string,
  "spread": number,      // USD/oz
  "spread_bps": number,  // vs spot
  "zscore": number,      // vs window
  "is_stale": boolean,
  "as_of": string
}

Contract specifications

GET/v1/specificationsBearer · Pro+

Static reference data for futures contracts — size, tick, delivery months, last-trade rules. Rarely changes; cache aggressively.

Query parameters

contractstringREQUIRED
One of GC, MGC, 1OZ, SI.

Response schema

{
  "contract": string,
  "exchange": string,     // "COMEX"
  "size_oz": number,
  "tick": number,
  "tick_value": number,
  "months": string[],
  "last_trade_rule": string
}

Economic calendar

GET/v1/calendars/eventsBearer · Pro+

Macro events tagged by likely impact on gold — FOMC, CPI, NFP, central-bank buying reports. impact is a rating we computed historically, not a consensus forecast.

Query parameters

fromdate
Default today.
todate
Default today + 30 days. Max 90-day window.
impactstring
Filter: high, medium, low.

Response schema

{
  "events": Event[]
}

// Event
{
  "id": string,
  "at": string,
  "name": string,        // "US CPI"
  "country": string,
  "impact": string,      // "high"
  "previous": number | null,
  "consensus": number | null
}

Fundamentals

GET/v1/fundamentalsBearer · Pro+

Structural flows: ETF holdings (GLD, IAU, SGOL), central-bank quarterly net purchases from public council filings, and COT non-commercial net positioning. Weekly cadence.

Query parameters

seriesstringREQUIRED
One of etf_holdings, cb_purchases, cot_net.
fromdate
Default 1 year ago.

Response schema

{
  "series": string,
  "unit": string,         // "tonnes" | "contracts"
  "source": string,
  "points": Point[]
}

// Point
{ "date": string, "value": number }