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. Bid/ask are optional and paid-only, requiring a coherent two-sided quote; Free/keyless omit them.

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

When things go wrong

API errors normally return JSON. An unexpected server failure may return a plain-text 500. Common first-request errors 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

Keyless: 10/minute, 100/hour per IP; prices 15 minutes late. Free keys include 5,000 calls/month and authenticated 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

Guides for common clients and tools: