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.

Heads up · pre-launch

We're in pre-launch (MVP ships 2026-05-01). Sign up now to lock in a launch discount on your first paid month. See pricing for the full rundown.

§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"
// npm i @goldprice/sdk
import { GoldPrice } from "@goldprice/sdk";

const gp = new GoldPrice({ apiKey: process.env.GP_KEY! });
const price = await gp.prices.get({ symbol: "XAU-USD-SPOT" });

console.log(price.price); // 4803.94
# pip install goldprice
from goldprice import GoldPrice
import os

gp = GoldPrice(api_key=os.environ["GP_KEY"])
price = gp.prices.get(symbol="XAU-USD-SPOT")
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

Every price response has one headline number plus a sources[] array listing every upstream feed that contributed. No blending, no hidden weights. You decide what to trust.

// 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",
  "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 Basic/Pro, continuous spot reference on Free).
is_stale — true when the primary source is past its refresh window. Check per-source timestamps in 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[].
sources[] — one row per upstream feed: source (identifier), license, price. Pick your own, or rely on the top-level price.

§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.

Status	Code	When
401	invalid_api_key	Missing or malformed bearer token.
403	plan_gated	Your plan doesn't include this endpoint (e.g. futures on Basic).
404	unknown_symbol	Symbol doesn't exist. Use `/v1/search`.
429	rate_limited	Back off. `Retry-After` header tells you how long.
503	upstream_unavailable	All our sources are stale. Rare; check status.

§Where to next

Full API reference → every endpoint, parameter, response shape, and error code.
Set up MCP → 30 seconds to wire Claude Desktop or Cursor into live gold data.
Methodology → how we source, aggregate, and flag stale prices.