Docs / Quickstart

Quickstart

Get an XAU/USD spot price in under a minute. This first request is anonymous.

Before you begin

You need curl or any HTTP client. No API key is required for this request.

Your first request

Use the exact URL below. The response is always wrapped in symbols.

curl --fail-with-body --max-time 10 "https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT"
// Plain fetch; no key required for this request
const url = "https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT";
const res = await fetch(url, { signal: AbortSignal.timeout(10_000) });
if (!res.ok) throw new Error("HTTP " + res.status);
const { symbols } = await res.json();

console.log(symbols[0].price); // "4826.40"
# Plain request; no key required for this request
import requests

res = requests.get(
    "https://api.goldprice.dev/v1/prices",
    params={"symbol": "XAU-USD-SPOT"},
    timeout= 10
)
res.raise_for_status()
price = res.json()["symbols"][0]
print(price["price"]) # "4826.40"
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Main {
  public static void main(String[] args) throws Exception {
    HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder(URI.create(
    "https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT"))
    .timeout(Duration.ofSeconds(10)).build();
HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());
if (response.statusCode() / 100 != 2) throw new IOException("HTTP " + response.statusCode());
    System.out.println(response.body());
  }
}
import Foundation

var request = URLRequest(url: URL(string:
  "https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT")!)
request.timeoutInterval = 10
let (data, response) = try await URLSession.shared.data(for: request)
guard (response as? HTTPURLResponse)?.statusCode == 200 else { throw URLError(.badServerResponse) }
print(String(data: data, encoding: .utf8)!)

Reading the response

price is a decimal string per troy ounce. Check is_stale before using a price, and use computed_at to identify the price observation or source-cache timestamp. It is not when the HTTP response was assembled.

{
  "symbols": [
    {
      "symbol": "XAU",
      "quote_currency": "USD",
      "unit": "troy_ounce",
      "contract_type": "spot",
      "price": "4826.40",
      "bid": "4825.00",
      "ask": "4827.00",
      "is_stale": false,
      "computed_at": "2026-04-27T01:00:00+00:00"
    }
  ]
}

When things go wrong

Handled API errors are JSON. An unexpected unhandled server failure can return a plain-text 500. The usual first-call cases are 400 invalid_symbol for an invalid symbol, 403 plan_gated for data outside your plan, and 429 rate_limit_exceeded for the per-minute limit or 429 rate_limited for the anonymous IP cap. Authenticated calls can also return 429 quota_exceeded for the monthly quota. Wait for the response's reset or retry guidance. The API reference lists errors for every operation.

Add a key when you need one

Anonymous spot requests use shared IP limits. A free key identifies your integration, includes 1,000 calls per month, and unlocks authenticated-only options such as include=stats.

curl "https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT&include=stats" \
  -H "Authorization: Bearer ga_live_..."

Create a free API key →

Use it with

Ready-made guides for common clients and tools: