API Documentation

Quick start

Get live prices in 30 seconds. If you don’t have an API key yet, get one here.

curl -H "X-API-Key: bullion_your_key" \
  "https://api.bullionapi.dev/v1/latest?currency=USD"

A successful response is JSON. Each request counts as one against your monthly quota, regardless of how many metals, currencies, or dates you ask for.

GET /v1/latest

Returns the most recent spot prices for all four metals and the FX rates needed to convert them into the requested base currency.

Query parameters

Response

{
  "status": "success",
  "currency": "USD",
  "unit": "toz",
  "metals": { "gold": 4527.86, "silver": 38.42, "platinum": 1523.10, "palladium": 1412.55 },
  "currencies": { "EUR": 0.9134, "GBP": 0.7783, "JPY": 154.22, "CAD": 1.3715 },
  "timestamps": { "metal": "2026-07-08T11:58:50.781Z", "currency": "2026-07-08T11:58:50.781Z" }
}

Cached for 1 hour. If the upstream feed is briefly unavailable we return a 200 with status: "partial" so your application keeps working in a degraded state.

GET /v1/timeseries

Returns daily closes for one or more metals across a date range. Up to 365 days per request.

Query parameters

Example

curl -H "X-API-Key: bullion_your_key" \
  "https://api.bullionapi.dev/v1/timeseries?currency=USD&start_date=2025-07-08&end_date=2026-07-08"

Response

{
  "status": "success",
  "currency": "USD",
  "unit": "toz",
  "start_date": "2025-07-08",
  "end_date": "2026-07-08",
  "series": {
    "gold":     [{ "date": "2025-07-08", "price": 3320.10 }, { "date": "2025-07-09", "price": 3342.55 }],
    "silver":   [{ "date": "2025-07-08", "price": 36.42 },   { "date": "2025-07-09", "price": 36.71 }],
    "platinum": [{ "date": "2025-07-08", "price": 1180.00 }, { "date": "2025-07-09", "price": 1189.30 }],
    "palladium":[{ "date": "2025-07-08", "price": 1010.40 }, { "date": "2025-07-09", "price": 1015.20 }]
  },
  "missing": []
}

Dates with no cached data are listed in missing. We backfill on the next request and cache the result so subsequent calls are fast.

Rate limits

Every response includes these headers so you can track usage in real time:

Example

HTTP/1.1 200 OK
x-ratelimit-limit: 50000
x-ratelimit-used: 142
x-ratelimit-remaining: 49858
x-ratelimit-reset: 2026-08-01T00:00:00.000Z
content-type: application/json

{ ... }

Error responses

Errors return JSON in the form { "error": "...", "code": "..." }. The HTTP status is the source of truth.

401 — Missing or invalid API key

HTTP/1.1 401 Unauthorized
content-type: application/json

{ "error": "Invalid or missing API key", "code": "UNAUTHORIZED" }

429 — Monthly quota exceeded

HTTP/1.1 429 Too Many Requests
x-ratelimit-limit: 1000
x-ratelimit-used: 1000
x-ratelimit-remaining: 0
x-ratelimit-reset: 2026-08-01T00:00:00.000Z
retry-after: 86400
content-type: application/json

{ "error": "Monthly quota exceeded", "code": "QUOTA_EXCEEDED" }

400 — Bad request

HTTP/1.1 400 Bad Request
content-type: application/json

{ "error": "start_date must be before end_date", "code": "INVALID_RANGE" }

502 — Upstream unavailable

Returned when the upstream feed is down and we have no cached data to fall back on. Retry with exponential backoff.

HTTP/1.1 502 Bad Gateway
content-type: application/json

{ "error": "Upstream feed unavailable", "code": "UPSTREAM_UNAVAILABLE" }

Supported currencies

Pass any of these ISO 4217 codes as the currency query parameter. Defaults to USD.

CLI

The official @paulund/bullion-cli wraps the API so you can call it from the terminal:

# Set your key once
export BULLION_API_KEY=bullion_your_key

# Live gold and silver
npx @paulund/bullion-cli gold
npx @paulund/bullion-cli silver

# Historical range
npx @paulund/bullion-cli gold --start 2025-01-01 --end 2025-12-31