Docs / Quickstart

Quickstart

Ten minutes from sign-up to a live XAU/USD price in your app. No credit card for Free, no sales call.

Prerequisites

You'll need three things. If you have all three, skip ahead to your first request.

  • An API key. Grab one at /login.
  • A terminal.Or any HTTP client — Postman, Bruno, or your IDE's REST panel.
  • Five minutes. The API is small on purpose.

Your first request

Pick a flavor. All four fetch the same live XAU/USD spot price.

# Plain curl — works anywhere curl https://api.goldprice.dev/v1/prices \ -H "Authorization: Bearer ga_live_a94f…2c71"
// No SDK — plain fetch against the REST API const res = await fetch("https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT", { headers: { Authorization: `Bearer ${process.env.GP_KEY}` }, }); const { symbols } = await res.json(); console.log(symbols[0].price); // "4803.94"
# No SDK — plain requests against the REST API import os, requests res = requests.get( "https://api.goldprice.dev/v1/prices", params={"symbol": "XAU-USD-SPOT"}, headers={"Authorization": f"Bearer {os.environ['GP_KEY']}"}, ) price = res.json()["symbols"][0] print(price["price"]) # "4803.94"
# In Claude Desktop config (~/Library/Application Support/Claude/…) { "mcpServers": { "goldprice": { "command": "npx", "args": ["-y", "@goldprice/mcp"], "env": { "GP_KEY": "ga_live_..." } } } } # Then: "What's gold trading at?" → Claude calls the spot tool.

Reading the response

The default response is lean — a 9-field core, same shape for anonymous and authenticated callers alike:

// GET /v1/prices?symbol=XAU-USD-SPOT
{
  "symbol": "XAU",
  "quote_currency": "USD",
  "unit": "troy_ounce",
  "contract_type": "spot",
  "price": "4803.94",
  "bid": "4802.23",
  "ask": "4804.61",
  "is_stale": false,
  "computed_at": "2026-05-01T02:34:02Z"
}

Want per-source provenance? Add ?include=sources — no blending, no hidden weights, you decide what to trust:

// GET /v1/prices?symbol=XAU-USD-SPOT&include=sources
{
  "symbol": "XAU",
  ...
  "sources": [
    { "source": "oracle.xau_usd",     "license": "commercial-ok",  "price": "4803.94" },
    { "source": "spot_reference.usd", "license": "reference-only", "price": "4803.42" }
  ]
}
  • price — decimal string in the requested currency per troy ounce. Always a string; we never force you through JS number precision. Pulled from the primary source (live oracle on Physical/Pro, continuous spot reference on Free).
  • is_stale — true when the primary source is past its refresh window. Check per-source timestamps in sources[] (via ?include=sources) if you want to override.
  • computed_at — ISO-8601 UTC. When we assembled this response. Upstream feed timestamps live on each row in sources[].
  • include — opt-in field groups, comma-separated: sources (provenance array), karat (per-gram karat pricing), stats (OHLC + divergence — requires an API key), or all. Full reference: API reference.

When things go wrong

Every error is a JSON body with a machine-readable code and a human-readable message. HTTP status codes are honest. A 429 really is a rate limit, a 401 really is a bad key.

StatusCodeWhen
401invalid_api_keyMissing or malformed bearer token.
403plan_gatedYour plan doesn't include this endpoint (e.g. futures on Free).
404unknown_symbolSymbol doesn't exist. See supported symbols in the API reference.
429rate_limitedBack off. Retry-After header tells you how long.
503upstream_unavailableAll our sources are stale. Rare; check status.

Where to next