# Bullion API

> Bullion API is a precious metals prices API for developers. Gold spot prices updated hourly, daily historical closes, simple `X-API-Key` auth, predictable monthly quota, no rate-limit games. Hosted on Cloudflare Workers.

- Base URL: `https://api.bullionapi.dev`
- Auth: `X-API-Key: bullion_<key>` header is the canonical and preferred transport; clients that cannot set custom headers may use the `api_key` query parameter as a fallback
- Security: Query credentials may appear in browser history, copied URLs, referrers, intermediary infrastructure, and logs. Use the X-API-Key header whenever your client supports custom headers. Query authentication does not enable cross-origin browser fetch; CORS remains separate. If both transports are supplied, they must match; differing values return HTTP 401 with code `conflicting_credentials`.
- Free tier: 30 requests / month, no credit card, non-commercial use only
- Pricing: Pro is $9 USD/month or $90 USD/year; Enterprise is £299 GBP/month or £2,990 GBP/year. Annual subscriptions keep the same plan and monthly request quota.
- Refunds: Within 14 days of the first payment on a new Pro subscription, the customer can request a full refund whether that payment is monthly or yearly. Later Pro renewals and unused time in a billing period are not automatically refunded, except where required by law or manually approved. Enterprise refunds are handled manually through contact sales.
- Usage rights: Free and Pro are for non-commercial use only. Enterprise includes commercial display and integration. Raw or substantially equivalent data redistribution and resale are excluded from all standard plans.
- Endpoints: `/v1/latest`, `/v1/carat`, `/v1/timeseries`, `/v1/rates/{region}` (US, UK, and euro-area macro data), `/v1/central-bank-reserves` (Pro and Enterprise), `/v1/central-bank-gold` (Pro and Enterprise), `/v1/portfolio`, `/v1/portfolio/lots`, `/v1/portfolio/transactions`, `/v1/usage`, `/health`
- Macro sources: New York Fed policy rates, U.S. Treasury daily interest-rate XML, BLS CPI-U NSA series `CUUR0000SA0`, Bank of England Bank Rate series `IUDBEDR`, BoE nominal and real zero-coupon spot curves plus RPI-linked implied inflation from month-end archives, ONS CPI series `D7G7`, and European Central Bank policy rates, AAA yields, HICP, and Consumer Expectations Survey data; macro observations include source attribution
- UK source licensing: Bank of England and Office for National Statistics data are attributed under the Open Government Licence https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/
- Reserve source: World Bank, World Development Indicators, with International Monetary Fund, International Financial Statistics as the underlying provider. The source data is available free of charge at https://data.worldbank.org/ under https://data.worldbank.org/summary-terms-of-use; annual value changes do not measure tonnes bought or sold.
- Central-bank gold source: monthly and fortnightly holdings from official national central-bank feeds (ECB/ESCB, Deutsche Bundesbank reserve-assets statistics for Germany, Bank of England, the National Bank of Kazakhstan international reserves table, the Central Bank of the Republic of Türkiye EVDS international-reserves series, Bank Negara Malaysia's SDDS ILV00 Gold valuation, and the weekly U.S. Treasury International Reserve Position), cached by the scheduled refresh. Germany gold-bullion volumes come from the Bundesbank Statistical Data Web Service under https://api.statistiken.bundesbank.de/rest/data, attributed per https://www.bundesbank.de/en/bundesbank/organisation/gtc-and-legal-basis. Kazakhstan monetary gold is an end-of-period USD reserve value under https://www.nationalbank.kz/en/page/data-usage-terms (free reuse with reference to the source) and measures holdings, not domestic-market purchases. Türkiye reserve gold is published as USD valuations of official reserve assets (weekly TP.AB.C1 and monthly SDDS TP.REZVARPD.K10) with no published quantity; CBRT information may be quoted with specific attribution and commercial use requires prior written permission from the CBRT. Malaysia's BNM valuation is reported in USD billions without a published quantity, so tonnes remain unavailable and changes are not purchase claims.
- Metals: gold (XAU) only at launch
- Currencies: use authenticated GET /v1/symbols for the active production catalogue

## Docs

- [Full API reference](https://bullionapi.dev/docs.md): endpoints, params, response shapes, errors, currencies, rate limits
- [Pricing](https://bullionapi.dev/pricing.md): Free / Pro / Enterprise breakdown
- [Terms](https://bullionapi.dev/terms.md): acceptable use, billing, refunds
- [Privacy](https://bullionapi.dev/privacy.md): data collection, sub-processors, analytics

## Examples

- [Latest gold price](https://bullionapi.dev/docs.md#quick-start): `curl -H "X-API-Key: bullion_your_key" https://api.bullionapi.dev/v1/latest?currency=USD`
- [Gold karat prices per gram](https://bullionapi.dev/docs.md#get-v1carat): `curl -H "X-API-Key: bullion_your_key" https://api.bullionapi.dev/v1/carat?currency=USD`
- [Spreadsheet or no-code latest price](https://bullionapi.dev/docs.md#quick-start): `https://api.bullionapi.dev/v1/latest?currency=USD&api_key=bullion_your_key` (fallback; treat the URL as a secret)
- [Historical daily closes](https://bullionapi.dev/docs.md#get-v1timeseries): `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"`
- [US macro rates](https://bullionapi.dev/docs.md#get-v1ratesregion): `curl -H "X-API-Key: bullion_your_key" https://api.bullionapi.dev/v1/rates/us` — policy, Treasury yields, breakevens, and CPI-U with per-observation provenance
- [Euro-area macro rates](https://bullionapi.dev/docs.md#get-v1rateseu): `curl -H "X-API-Key: bullion_your_key" https://api.bullionapi.dev/v1/rates/eu` — ECB policy rates, AAA yields, HICP, and survey expectations with `euro_area` provenance
- [UK macro rates](https://bullionapi.dev/docs.md#get-v1ratesregion): `curl -H "X-API-Key: bullion_your_key" https://api.bullionapi.dev/v1/rates/uk` — Bank Rate and CPI annual rate with per-observation provenance
- [Annual central-bank reserves](https://bullionapi.dev/docs.md#get-v1central-bank-reserves): annual World Bank WDI reserve values and gold share for Pro and Enterprise, with IMF IFS as the underlying provider
- [Central-bank gold](https://bullionapi.dev/docs.md#get-v1central-bank-gold): monthly and fortnightly central-bank gold holdings from official national feeds, including the National Bank of Kazakhstan and Bank Negara Malaysia, for Pro and Enterprise
- [Portfolio transaction history](https://bullionapi.dev/docs.md#get-v1portfoliotransactions): owner-scoped cursor pagination with exact decimal-string values
- [Portfolio open lots](https://bullionapi.dev/docs.md#get-v1portfoliolots): open purchase lots for explicit sale allocation; allocated quantities must sum exactly to the sale quantity

## Optional

- [MCP server](https://mcp.bullionapi.dev): connect an AI client to Bullion's get_gold_latest tool with a Bearer API key
- [Status](https://bullionapi.dev/status): live system health
- [Sign up](https://bullionapi.dev/signup): create an account and API key