# Bullion API

> Bullion API is a precious metals prices API for developers, with available daily historical closes, `X-API-Key` auth and monthly request quotas. Hosted on Cloudflare Workers.

Build indicative valuations, reference displays and charts from metal prices. Metal observations refresh hourly; projected currencies use an accepted daily FX snapshot. These estimates are not executable checkout prices or binding quotes and must not be used for trading or settlement.

- Base URL: `https://api.bullionapi.dev`
- Metering: A market-data request consumes one monthly request once it passes authentication and quota checks and reaches endpoint execution, even if it returns a validation error, missing data or a controlled service error. Repeated calls and retries each count; there is no automatic refund. Requests rejected before this point do not consume monthly allowance.
- 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 API use only
- Pricing: Pro is $9 USD/month; Business is $29 USD/month. Annual list prices are $90 USD/year for Pro and $290 USD/year for Business. Annual list prices do not establish checkout availability. New annual subscriptions are offered only when annual checkout is enabled; check the billing options shown on the pricing page. Request quotas still reset monthly, and existing annual subscriptions retain their billing interval.
- Refunds: Within 14 days of the first payment on a new Pro or Business subscription, the customer can request a full refund whether that payment is monthly or yearly. Later renewals and unused time in a billing period are not automatically refunded, except where required by law or manually approved.
- Usage rights: Free and Pro are for non-commercial use of the Bullion API Service only. Business includes commercial display and integration. Standard plans do not permit redistribution of raw or substantially equivalent market-price data or redistribution or resale of API access. Where the source grants reuse or redistribution rights in particular public statistics, those rights remain unaffected by plan and are subject to the source terms. See https://bullionapi.dev/terms.
- Endpoints: `/v1/{metal}/price` (per-metal latest price, or daily weekday closes with `start`/`end`), `/v1/{metal}/change`, `/v1/gold/carat`, `/v1/gold-silver-ratio`, `/v1/gold/moving-average`, `/v1/gold/volatility`, `/v1/gold/drawdown` (gold technical indicators), `/v1/policy-rates/{country}`, `/v1/inflation/{country}` and `/v1/bond-yields/{country}` (US, GB, and EA macro time series; the bare paths return every covered country's latest value), `/v1/government-debt/{country}`, `/v1/government-borrowing/{country}`, `/v1/debt-interest/{country}` (government debt, borrowing, and interest; the bare paths list every covered country), `/v1/central-bank-reserves`, `/v1/central-bank-reserves/{country}` (annual reserves per country), `/v1/countries` and `/v1/countries/{country}` (which datasets each country has), `/v1/central-bank-gold` and `/v1/central-bank-gold/{country}` (reported central-bank gold series per country), `/v1/gold/mine-production`, `/v1/gold/recycling`, `/v1/gold/trade`, `/v1/silver/mine-production`, `/v1/silver/recycling`, `/v1/silver/consumption` and `/v1/silver/trade` (annual USGS market indicators), `/v1/portfolio`, `/v1/portfolio/lots`, `/v1/portfolio/transactions`, `/v1/usage`, `/health`
- Government-finance country-path coverage: debt: `us`, `gb` (or `uk`), `au`, `is`, `ea` (or `eu`), `sg`, `at`, `be`, `bg`, `cy`, `cz`, `de`, `dk`, `ee`, `es`, `fi`, `fr`, `gr`, `hr`, `hu`, `ie`, `it`, `lt`, `lu`, `lv`, `mt`, `nl`, `pl`, `pt`, `ro`, `se`, `si`, `sk`, `no`, `ca`, `ch`, `qa`, `jp`, `pe`; borrowing: `us`, `gb` (or `uk`), `is`, `ea` (or `eu`), `at`, `be`, `bg`, `cy`, `cz`, `de`, `dk`, `ee`, `es`, `fi`, `fr`, `gr`, `hr`, `hu`, `ie`, `it`, `lt`, `lu`, `lv`, `mt`, `nl`, `pl`, `pt`, `ro`, `se`, `si`, `sk`, `no`, `ca`, `ch`; debt interest: `gb` (or `uk`), `is`, `ea` (or `eu`), `at`, `be`, `bg`, `cy`, `cz`, `de`, `dk`, `ee`, `es`, `fi`, `fr`, `gr`, `hr`, `hu`, `ie`, `it`, `lt`, `lu`, `lv`, `mt`, `nl`, `pl`, `pt`, `ro`, `se`, `si`, `sk`, `no`, `ca`
- Macro sources: New York Fed policy rates, U.S. Treasury daily interest-rate XML, BLS CPI-U NSA series `CUUR0000SA0`, UK Bank Rate from the BIS central bank policy rates statistics, 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: Office for National Statistics data is attributed under the Open Government Licence https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/; UK Bank Rate cites the BIS under its terms of use https://data.bis.org/help/legal
- Gold and silver market indicators: annual U.S. Geological Survey (USGS) statistics in metric tonnes as decimal strings — world and United States mine production, plus United States recycling (secondary production), silver apparent consumption, and imports and exports. There is no gold consumption endpoint. These annual statistics have a multi-year publication lag, and observations identified as estimates carry an `estimated` flag. These are partial indicators, not total demand or a market balance. USGS data are in the U.S. public domain; credit the U.S. Geological Survey. The USGS does not endorse this product.
- Annual central-bank reserves: reported total reserve values and derived gold-value series by country. Annual value changes combine holdings changes, price movement and revisions; they do not measure tonnes bought or sold.
- Central-bank gold: cached reported holdings by measure and cadence (monthly, weekly, fortnightly, quarterly, annual and irregular). Value-only measures do not imply a physical quantity, and changes in reported holdings are not purchase or sale transactions. Source-data reuse rights remain separate from API plan terms.
- Metals: gold (XAU); the gold/silver ratio also reads silver (XAG) prices
- 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
- [MCP server](https://bullionapi.dev/docs/mcp): connect an AI agent to `https://api.bullionapi.dev/mcp` (Streamable HTTP, OAuth 2.1 sign-in with consent, read-only tools for prices, derived metrics, country data and your portfolio; same plans and limits as the API)
- [Pricing](https://bullionapi.dev/pricing.md): Free / Pro / Business 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#get-v1metalprice): `curl -H "X-API-Key: bullion_your_key" https://api.bullionapi.dev/v1/gold/price?currency=USD`
- [Gold karat prices per gram](https://bullionapi.dev/docs.md#get-v1goldcarat): `curl -H "X-API-Key: bullion_your_key" https://api.bullionapi.dev/v1/gold/carat?currency=USD`
- [Spreadsheet or no-code latest price](https://bullionapi.dev/docs.md#quick-start): `https://api.bullionapi.dev/v1/gold/price?currency=USD&api_key=bullion_your_key` (fallback; treat the URL as a secret)
- [Historical daily closes](https://bullionapi.dev/docs.md#historical-prices): `curl -H "X-API-Key: bullion_your_key" "https://api.bullionapi.dev/v1/gold/price?currency=USD&start=2025-07-08&end=2026-07-08"` — one final close per UTC weekday
- [Metal price change](https://bullionapi.dev/docs.md#get-v1metalchange): `curl -H "X-API-Key: bullion_your_key" "https://api.bullionapi.dev/v1/silver/change?currency=USD&period=1w"` — absolute and percentage change between two UTC days
- [Gold/silver ratio](https://bullionapi.dev/docs.md#get-v1gold-silver-ratio): `curl -H "X-API-Key: bullion_your_key" "https://api.bullionapi.dev/v1/gold-silver-ratio?currency=USD"` — latest or historical daily closes from the local cache
- [Gold technical indicators](https://bullionapi.dev/docs.md#get-v1goldmoving-average): `curl -H "X-API-Key: bullion_your_key" "https://api.bullionapi.dev/v1/gold/moving-average?window=50&currency=USD&start=2026-01-01&end=2026-12-31"` — cached moving averages, plus `/v1/gold/volatility` and `/v1/gold/drawdown`
- [Macro-derived gold](https://bullionapi.dev/docs.md#get-v1goldreal-price-and-get-v1goldyield-correlation): `/v1/gold/real-price` uses official seasonally adjusted CPI index levels; `/v1/gold/yield-correlation` uses 90 aligned daily gold-return and real-yield-change pairs. USD only, required start/end, stored inputs, exact decimal strings and explicit unavailable dependencies.
- [Policy rates](https://bullionapi.dev/docs.md#get-v1policy-ratescountry): `curl -H "X-API-Key: bullion_your_key" https://api.bullionapi.dev/v1/policy-rates/gb` — latest Bank Rate with per-series provenance (add `start`/`end` for history); `/v1/policy-rates` compares US, GB, and EA
- [Inflation](https://bullionapi.dev/docs.md#get-v1inflationcountry): `curl -H "X-API-Key: bullion_your_key" "https://api.bullionapi.dev/v1/inflation/eu?basis=expectation"` — CPI, HICP, breakevens, and survey expectations
- [Bond yields](https://bullionapi.dev/docs.md#get-v1bond-yieldscountry): `curl -H "X-API-Key: bullion_your_key" "https://api.bullionapi.dev/v1/bond-yields/us?tenor=10y&start=2025-01-01"` — Treasury and ECB AAA yields by tenor and basis
- [Government debt, borrowing, and interest](https://bullionapi.dev/docs.md#government-finance-endpoints): `curl -H "X-API-Key: bullion_your_key" https://api.bullionapi.dev/v1/government-debt/pe` — Peru BCRPData non-financial-public-sector debt and its reported GDP ratio; Iceland annual Statistics Iceland debt, ratio, balance and interest series; plus US, UK, euro-area, EU-member-state, Norway, Canada, Switzerland, Singapore and Qatar debt coverage, with borrowing and interest where source-backed, per-series scope, basis, reuse terms and provenance
- [Gold and silver market indicators](https://bullionapi.dev/docs.md#market-indicator-endpoints): `curl -H "X-API-Key: bullion_your_key" https://api.bullionapi.dev/v1/gold/mine-production` — annual USGS world and US mine production in metric tonnes; add `start`/`end` for history, and see `/v1/silver/consumption` and the recycling and trade endpoints
- [Annual central-bank reserves](https://bullionapi.dev/docs.md#get-v1central-bank-reservescountry): `curl -H "X-API-Key: bullion_your_key" https://api.bullionapi.dev/v1/central-bank-reserves/gb` — annual reported reserve values and derived gold-share series as decimal strings
- [Countries](https://bullionapi.dev/docs.md#get-v1countries): `curl -H "X-API-Key: bullion_your_key" https://api.bullionapi.dev/v1/countries` — every country with the datasets it has and their paths
- [Central-bank gold](https://bullionapi.dev/docs.md#get-v1central-bank-gold): `curl -H "X-API-Key: bullion_your_key" https://api.bullionapi.dev/v1/central-bank-gold/de` — reported central-bank gold holdings as decimal-string series per measure and cadence; `/v1/central-bank-gold` returns the latest value for every country
- [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

- [Status](https://bullionapi.dev/status): live system health
- [Sign up](https://bullionapi.dev/signup): create an account and API key