// reference

API documentation

Every request uses an X-API-Key header. Base URL is https://api.bullionapi.dev. Usage increments after API-key and quota checks but before endpoint validation.

// quick start

Quick start

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

GET/v1/latest

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

// endpoint

GET/v1/latest

Latest prices

Returns the most recent gold spot price and the FX rates needed to convert it into the requested base currency.

// parameters

Query parameters

Name	Type	Description
`currency`	string	ISO 4217 currency code. Defaults to USD. See supported currencies below.

// response

Response

json

{
  "status": "success",
  "currency": "USD",
  "unit": "toz",
  "metals": { "gold": 4527.86 },
  "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 and refreshed by the scheduled data pipeline.

// endpoint

GET/v1/timeseries

Historical prices

Returns daily gold closes across a date range. Up to 365 days per request.

// parameters

Query parameters

Name	Type	Description
`start_date`	YYYY-MM-DD	First day to include (inclusive).
`end_date`	YYYY-MM-DD	Last day to include (inclusive). Max 365-day range.
`currency`	string	ISO 4217 base currency. Defaults to USD.

// example

Example

GET/v1/timeseries

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

Response

json

{
  "status": "success",
  "currency": "USD",
  "unit": "toz",
  "start_date": "2025-07-08",
  "end_date": "2026-07-08",
  "rates": {
    "2025-07-08": {
      "currencies": { "EUR": 0.9134, "GBP": 0.7783 },
      "date": "2025-07-08",
      "metals": { "gold": 3320.10 }
    },
    "2025-07-09": {
      "currencies": { "EUR": 0.9141, "GBP": 0.7790 },
      "date": "2025-07-09",
      "metals": { "gold": 3342.55 }
    }
  }
}

Only cached dates are included in rates. Scheduled refresh and backfill jobs populate the cache; API requests never call upstream providers.

// rate limits

Rate limits

Responses after successful API-key validation include these headers so you can track usage in real time:

Header	Type	Description
x-ratelimit-limit	integer	Your plan’s monthly cap.
x-ratelimit-used	integer	Requests used this month.
x-ratelimit-remaining	integer	Requests remaining.
x-ratelimit-reset	ISO 8601	When the quota resets (1st 00:00 UTC).

// errors

Error responses

Errors return JSON with details about the failure. The HTTP status is the source of truth.

401 — Missing API key

http

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

{
  "error": "Missing X-API-Key header",
  "code": "missing_api_key"
}

429 — Monthly quota exceeded

http

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

{
  "error": "quota_exceeded",
  "message": "Monthly request limit reached for free plan (30/30).",
  "plan": "free",
  "used": 30,
  "limit": 30,
  "reset_at": "2026-08-01T00:00:00.000Z"
}

400 — Bad request

http

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

{
  "error": "start_date must be <= end_date",
  "code": "invalid_range"
}

// currencies

Supported currencies

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

USDEURGBPJPYCHFCADAUDNZDCNYHKDSGDSEKNOKDKKPLNCZKHUFTRYZARINRKRWBRLMXNAEDSARILSTHBIDRMYRPHP

// mcp server

Use from Claude, ChatGPT, Cursor

Bullion hosts an MCP server at https://mcp.bullionapi.dev. AI clients call the get_gold_latest tool directly — same API key, same quota.

// one-click install

Install in Cursor · Install in VS Code

// manual install

Claude Desktop, ChatGPT (Settings → Connectors) and other clients: add the server with your API key as a Bearer token.

json

{
  "mcpServers": {
    "bullion": {
      "type": "http",
      "url": "https://mcp.bullionapi.dev",
      "headers": { "Authorization": "Bearer bullion_your_key" }
    }
  }
}

// machine-readable

OpenAPI spec

The full API contract as OpenAPI 3.1, for code-gen, Postman and AI function-calling clients: api.bullionapi.dev/openapi.json.