Gold Price API Reference

Response schema

// 200 OK
{
  "symbols": SpotRow[]
}

// SpotRow — required keys
{
  "symbol": string,
  "quote_currency": string,
  "unit": string,             // "troy_ounce" for XAU/XAG; "pound" for HG
  "contract_type": string,    // "spot" | "futures"
  "is_stale": boolean
}

// Optional core keys; omitted when unavailable
{
  "price"?: string,           // decimal-as-string
  "bid"?: string,
  "ask"?: string,
  "computed_at"?: string      // ISO-8601 UTC
}

// + ?include=sources
{
  "sources": Source[]         // tier-filtered provenance
}

// + ?include=karat (XAU only; omitted for XAG/HG or null price)
{
  "price_gram_24k": string, "price_gram_22k": string, "price_gram_21k": string,
  "price_gram_20k": string, "price_gram_18k": string, "price_gram_16k": string,
  "price_gram_14k": string, "price_gram_10k": string
}

// + ?include=stats (auth-gated — anon never receives this group)
{
  "divergence_flag": boolean,
  "divergence_bps"?: number,
  "value_stale"?: boolean,    // only when primary source is the council rate
  "open_price"?: string, "high_price"?: string, "low_price"?: string,
  "prev_close_price"?: string, "ch"?: string, "chp"?: string,
  "open_time"?: number        // epoch seconds at UTC midnight
}

// Source
{
  "source": string,
  "display_name"?: string,
  "price"?: string,
  "unit"?: string,
  "license"?: string,
  "is_stale"?: boolean,
  "informational"?: boolean // true for reference-only feeds (e.g. tokenized gold) that never set the primary price
}

Response schema

// 200 OK
// Successful and plan-gated response headers include:
//   Deprecation: true
//   Link: </v1/bars>; rel="successor-version"
//   Sunset: <ISO-8601 date>  // once configured
{
  "symbol": string,
  "interval": string,        // "1d" | "1h"
  "from": string,            // ISO-8601 date or timestamp
  "to": string,
  "series": SeriesEntry[],
  "meta": {
    "tier": string,
    "count": number,
    "ohlc_note": string
  }
}

// SeriesEntry
{
  "date": string,            // "YYYY-MM-DD" (daily) or ISO-8601 UTC (intraday)
  "open": string | null,     // decimal-as-string
  "high": string | null,
  "low": string | null,
  "close": string | null,
  "volume": string | null,   // always null (close-only path)
  "is_stale": boolean,
  "is_closed": boolean       // forming vs. settled bar; present since the 2026-06-19 real-bars cutover
}

Response schema

// 200 OK
{
  "asset": string,
  "spot_usd": string,        // decimal-as-string
  "computed_at": string,     // ISO-8601 UTC
  "horizons": Horizon[],
  "sources": SourceBlock[],
  "errors": string[]         // partial-failure per horizon
}

// Horizon
{
  "expiry": string,          // "YYYY-MM-DD"
  "futures": FuturesBlock | null,
  "errors": string[]
}

// FuturesBlock
{
  "contract": string,
  "settle_usd": string,
  "settle_source": string,
  "settle_age_seconds": number,
  "open_interest": number | null,
  "volume": number | null
}

// SourceBlock
{
  "id": string,
  "publisher": string,
  "url": string,
  "retrieved_at": string | null, // ISO-8601 UTC
  "type": "futures"
}

Response schema

Same lean-by-default SpotRow shape as /v1/prices, unwrapped (no symbols[] array).

Response schema

// Anonymous
{
  "threshold_bps": number,
  "computed_at": string,
  "diverged_count": number
}

// Authenticated (any tier)
{
  "threshold_bps": number,
  "computed_at": string,
  "diverged": [{
    "symbol": string,
    "quote_currency": string,
    "contract_type": string,
    "divergence_bps": number,
    "primary_sources": Source[],  // tier-filtered
    "computed_at": string
  }]
}

Response schema

{
  "settlements": [{
    "symbol": string,
    "settlement_date": string,     // "YYYY-MM-DD"
    "settlement_price": string | null,
    "prior_settlement": string | null,
    "change_value": string | null,
    "volume": number | null,
    "open_interest": number | null,
    "source": string | null,
    "source_type": string,         // e.g. "proxy_daily_close"
    "source_timestamp": string | null,
    "fetched_at": string | null,
    "disclaimer": string           // present only when source_type is a proxy
  }]
}

Response schema

{
  "from": string,
  "to": string,
  "amount": string,      // decimal-as-string
  "rate": string,
  "result": string,
  "unit": string,        // "oz" | "gram" | "kg"
  "timestamp": string    // UTC ISO-8601
}

Response schema

{
  "currency": string,
  "timestamp": string,
  "price_gram_24k": string, "price_gram_22k": string, "price_gram_21k": string,
  "price_gram_20k": string, "price_gram_18k": string, "price_gram_16k": string,
  "price_gram_14k": string, "price_gram_10k": string
}

Response schema

// array, one entry per tier: free, basic (hidden), physical, pro, realtime
[{
  "name": string,
  "monthly_price_usd": string,
  "yearly_price_usd": string,
  "rate_limit_per_minute": number,
  "monthly_quota": number,
  "allowed_bases": string[],       // e.g. ["XAU"], ["XAU","XAG","HG"]
  "allowed_contracts": string[],   // e.g. ["spot"], ["spot","futures"]
  "includes_mcp": boolean,
  "commercial_use": boolean,
  "support_sla_hours": number | null,
  "max_concurrent_streams": number,
  "hidden": boolean
}]

Response schema

[{
  "id": string,
  "key_prefix": string,
  "name": string,
  "created_at": string,
  "last_used_at": string | null,
  "revoked_at": string | null   // future-dated during the 24h grace window
}]

Response schema

{
  "id": string,
  "plaintext": string,   // shown once — store it now
  "key_prefix": string,
  "created_at": string,
  "previous_key_revokes_at": string | null
}

Response schema

{
  "calls_today": number,
  "calls_this_month": number,
  "active_streams": number | null,
  "max_streams": number | null
}