Gold Data API

Make your first request

curl https://xaus.com/api/v1/spot

# With currency conversion
curl "https://xaus.com/api/v1/spot?currency=EUR"

# Price per gram in GBP
curl "https://xaus.com/api/v1/spot?currency=GBP&unit=gram"

// Fetch live XAU spot price
const res  = await fetch('https://xaus.com/api/v1/spot');
const data = await res.json();

console.log(data.spot_usd_oz);   // e.g. 3330.42
console.log(data.xau.price);     // price in requested currency + unit

// With options
const res2 = await fetch(
  'https://xaus.com/api/v1/spot?currency=EUR&unit=gram'
);
const eurGram = await res2.json();
console.log(eurGram.xau.price);  // EUR per gram

import requests

# Basic request
r    = requests.get("https://xaus.com/api/v1/spot")
data = r.json()
print(data["spot_usd_oz"])    # 3330.42
print(data["per_gram_usd"])   # 107.0601

# Price per kg in JPY
r2 = requests.get(
    "https://xaus.com/api/v1/spot",
    params={"currency": "JPY", "unit": "kg"}
)
print(r2.json()["xau"]["price"])   # JPY per kg

<?php
$response = file_get_contents(
    'https://xaus.com/api/v1/spot?currency=EUR'
);
$data = json_decode($response, true);

echo $data['spot_usd_oz'];   // 3330.42
echo $data['xau']['price']; // EUR/oz

Interactive explorer

Runs against the real API from your browser, no key, no setup. The response below is live.

Loading live response…

Example response

{
  "xau": {
    "price":    4007.20,       // price in requested currency + unit
    "currency": "USD",
    "unit":     "troy_oz"
  },
  "spot_usd_oz":  4007.20,       // always USD/oz regardless of params
  "per_gram_usd": 128.8344,
  "per_kg_usd":   128834.37,
  "silver_usd_oz":     48.27,     // XAG/USD spot
  "gold_silver_ratio": 83.02,
  "xaut_gold_ratio":   1.0018,    // tokenized gold vs spot (>1 = premium)
  "paxg_gold_ratio":   0.9994,
  "btc_usd":           104300,
  "btc_gold_oz":       26.03,     // oz of gold per 1 BTC
  "gold_market_cap_usd": 28330000000000,
  "gold_supply_tonnes":  219890,
  "fx_rate":      1,             // FX rate used (USD→requested currency)
  "updated_at":   "2026-07-02T09:00:00.000Z",
  "source":       "xaus.com",
  "docs":         "https://xaus.com/api"
  // + tokenized-gold prices, BTC-vs-gold aggregates, central-bank
  //   reserve stats & full fx_rates table, see field reference below
}

Query parameters

History & reserves

GET /api/v1/history, up to 5 years of daily XAU/USD candles plus computed statistics. Cached 6 hours.

{
  "symbol": "XAUUSD",
  "interval": "daily",
  "points": [ { "d": "2026-07-01", "c": 4007.20, "h": 4021.10, "l": 3988.60 }, … ],
  "high_52w": 4381.50,
  "low_52w":  3312.40,
  "ranges": {              // true high/low per trailing window
    "day":   { "low": 3988.60, "high": 4021.10 },
    "week":  { … }, "month": { … }, "year": { … }
  },
  "return_ytd_pct": 12.4,   // vs last close of previous year
  "return_1y_pct":  35.3    // vs close ~365 days ago
}

GET /api/v1/reserves, central-bank gold holdings by country (119 countries), as shown on the reserves page.

GET /api/v1/intraday, XAUS's own recorded price series: the live gold-api quote sampled every 2 minutes by our infrastructure (gold and silver). Params: ?symbol=xau|xag, ?hours=1..48 (default 24). Returns points of {t, p} with a data_state block and coverage_seconds so consumers can judge series warmth. Retention: 14 days.

Error responses

All errors return JSON with an error field. There is currently no hard rate limit, see fair use below.

Data states & provenance

Every data group in the response is in exactly one of three states, always machine-detectable:

The single canonical read is the data_state object, { status, as_of, source, age_seconds }, describing the core gold price on every response, including 503s. The flat stale and price_as_of fields are retained for backward compatibility.

AI agents & automated consumers

data_state describes freshness at the moment the response was generated. If your requests pass through a caching layer you do not control (AI assistant fetchers, corporate proxies, scraper infrastructure), you can receive an old copy that still reads status: "fresh", age_seconds: 0, because it was fresh when built. Two rules make any integration stale-proof:

1. Validate updated_at yourself. Every response carries a generation timestamp. Compare it to the current time; treat anything older than a few minutes (spot, intraday) or a day (history, reserves) as a cached copy, not a live reading.

Machine-readable resources: /api/openapi.json (OpenAPI 3.1 contract for all endpoints, importable into agent frameworks and API tooling) and /llms.txt (plain-text site and API map for AI crawlers). On /api/v1/spot, pass ?compact=1 to omit the ~160-entry FX table: the response shrinks by roughly 75%, which matters when an AI agent pays per token.

2. Cache-bust when freshness is critical. Append a throwaway unique query parameter, e.g. /api/v1/spot?fresh=1720000000 (any name, any changing value). Endpoints ignore unknown parameters, but caches key on the full URL, so a unique value bypasses every intermediary layer. Use this for freshness-critical calls only; default requests should let the CDN work.

Provenance. Each data group carries its own source attribution in the payload:

Operational behaviour

One feed, every channel

This API is the engine behind every XAUS surface, use it directly, or ship the same data through the channels below.

API changelog

Rate limits & fair use

CORS is fully open, you can call this API directly from browser JavaScript. Prices are indicative mid-market rates, not tradable quotes. For settlement-grade rates refer to the LBMA benchmark.