{"openapi":"3.1.0","info":{"title":"Bullion API","version":"1.0.0","summary":"Metal spot prices as a simple JSON REST API.","description":"Metal prices and historical data in the currencies returned by authenticated GET /v1/symbols, the authoritative runtime catalogue. Responses are served from a cache; API requests never call upstream providers. Metal observations refresh hourly. Enabled projected prices combine that hourly canonical USD observation with a separate daily Bullion API conversion snapshot. The two timestamps remain distinct, and conversion snapshots become stale when more than seven UTC calendar days old; latest projected prices converted with such a snapshot are withheld (404 no_data) until a new one is accepted. Internal UniRateAPI observations are not exposed through price responses. Currency conversion input attribution: [Exchange Rates By UniRateAPI](https://unirateapi.com/). Prices are informational only. They are not live FX rates, executable prices, transaction benchmarks or binding quotes, and must not be used for trading or settlement. Bullion API does not publish, redistribute or resell raw FX rates. Price methodology: https://bullionapi.dev/docs#methodology. Authenticate price-data requests with the canonical and preferred X-API-Key header, or use the api_key query parameter as a fallback when a client cannot set custom headers. Query credentials may appear in browser history, copied URLs, referrers, intermediary infrastructure, and logs. 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. Any /v1 path without a documented operation returns HTTP 404 with code not_found for every method (components.responses.NotFound), without authentication or quota use. 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 the Terms of Service for details.","termsOfService":"https://bullionapi.dev/terms","contact":{"name":"Bullion API","url":"https://bullionapi.dev","email":"hello@bullionapi.dev"}},"servers":[{"url":"https://api.bullionapi.dev"}],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"tags":[{"name":"prices","description":"Metal price data (API key required)"},{"name":"symbols","description":"Production-serviceable symbols (API key required)"},{"name":"countries","description":"Country coverage across per-country datasets (API key required)"},{"name":"macro","description":"Macroeconomic time series by country: policy rates, inflation, bond yields and government finance (API key required)"},{"name":"derived","description":"Cache-backed derived market metrics, one endpoint per metric (API key required)"},{"name":"market-indicators","description":"Annual USGS gold and silver market indicators: world mine production and United States recycling, consumption and trade (API key required)"},{"name":"reserves","description":"Annual central-bank reserve data (API key required)"},{"name":"central-bank-gold","description":"Monthly central-bank gold holdings (API key required)"},{"name":"portfolio","description":"Private account-owned multi-metal portfolio settings"},{"name":"account","description":"Account-scoped usage (session cookie)"},{"name":"meta","description":"Service metadata (public)"}],"paths":{"/v1/symbols":{"get":{"tags":["symbols"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Production-serviceable metals and currencies","description":"Returns the authoritative runtime catalogue of reviewed, configured currencies that have materialised production price data. Static documentation reflects deployment configuration but cannot verify materialised rows. The route never reads FX observations, constructs an upstream provider or makes an upstream request. It authenticates and retains the rolling per-key limit, but does not increment monthly quota, deny an account whose monthly quota is exhausted or record product activation. Monthly quota headers report the unchanged account state and successful calls are written to the request log.","operationId":"getSymbols","responses":{"200":{"description":"Reviewed production-serviceable metal and currency descriptions.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap. This endpoint does not consume it.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month. This endpoint does not increment the value.","schema":{"type":"integer","example":0}},"x-ratelimit-remaining":{"description":"Requests remaining this month. This endpoint does not decrement the value.","schema":{"type":"integer","example":30}},"x-ratelimit-plan":{"description":"The plan whose monthly quota state is reported.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for the informational x-ratelimit-used value.","schema":{"type":"integer","example":0}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SymbolsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"429":{"$ref":"#/components/responses/ApiKeyRateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["symbols"],"security":[],"summary":"Not supported — read-only API","operationId":"postSymbolsNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/gold/price":{"get":{"tags":["prices"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"gold price, latest or daily history","description":"Returns the gold spot price as one `gold_price` series. The route reads the local cache and never calls an upstream provider. Without start and end, the series holds the latest cached price with its full UTC observation timestamp (`frequency: hourly`, `method: latest`). With a range of at most five years, it holds one final close per UTC weekday dated YYYY-MM-DD (`frequency: daily`, `method: weekday_close`); Saturday and Sunday UTC observations, including the Sunday-evening market reopen, are excluded. Values are decimal strings in the requested unit, rounded to eight decimal places; pass unit=gram, unit=kilogram, or unit=troy_oz (including documented aliases). For a configured projected currency the series carries `conversion`, the daily Bullion API conversion snapshot provenance; it is omitted for native currencies. History series also carry coverage.earliest, coverage.latest and coverage.observation_count for usable stored weekday closes before the current request time, independent of the requested range. Coverage may be sparse; the five-year query limit does not guarantee five years of history. Non-gold history comes from retained refreshes; projected history begins at activation without backfill.","operationId":"getGoldPrice","parameters":[{"$ref":"#/components/parameters/Currency"},{"$ref":"#/components/parameters/MetalPriceUnit"},{"$ref":"#/components/parameters/SeriesStart"},{"$ref":"#/components/parameters/SeriesEnd"}],"responses":{"200":{"description":"gold price series.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetalPriceResponse"}}}},"400":{"description":"The currency or unit is not supported, or the date range is missing its start, malformed, reversed or longer than the maximum.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_unit","message":"The requested output unit is invalid."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"No cached gold price exists for the requested currency or date range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"The cached price data could not be read.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"tags":["prices"],"summary":"Not supported — read-only API","operationId":"postGoldPriceNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/silver/price":{"get":{"tags":["prices"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"silver price, latest or daily history","description":"Returns the silver spot price as one `silver_price` series. The route reads the local cache and never calls an upstream provider. Without start and end, the series holds the latest cached price with its full UTC observation timestamp (`frequency: hourly`, `method: latest`). With a range of at most five years, it holds one final close per UTC weekday dated YYYY-MM-DD (`frequency: daily`, `method: weekday_close`); Saturday and Sunday UTC observations, including the Sunday-evening market reopen, are excluded. Values are decimal strings in the requested unit, rounded to eight decimal places; pass unit=gram, unit=kilogram, or unit=troy_oz (including documented aliases). For a configured projected currency the series carries `conversion`, the daily Bullion API conversion snapshot provenance; it is omitted for native currencies. History series also carry coverage.earliest, coverage.latest and coverage.observation_count for usable stored weekday closes before the current request time, independent of the requested range. Coverage may be sparse; the five-year query limit does not guarantee five years of history. Non-gold history comes from retained refreshes; projected history begins at activation without backfill.","operationId":"getSilverPrice","parameters":[{"$ref":"#/components/parameters/Currency"},{"$ref":"#/components/parameters/MetalPriceUnit"},{"$ref":"#/components/parameters/SeriesStart"},{"$ref":"#/components/parameters/SeriesEnd"}],"responses":{"200":{"description":"silver price series.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetalPriceResponse"}}}},"400":{"description":"The currency or unit is not supported, or the date range is missing its start, malformed, reversed or longer than the maximum.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_unit","message":"The requested output unit is invalid."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"No cached silver price exists for the requested currency or date range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"The cached price data could not be read.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"tags":["prices"],"summary":"Not supported — read-only API","operationId":"postSilverPriceNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/palladium/price":{"get":{"tags":["prices"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"palladium price, latest or daily history","description":"Returns the palladium spot price as one `palladium_price` series. The route reads the local cache and never calls an upstream provider. Without start and end, the series holds the latest cached price with its full UTC observation timestamp (`frequency: hourly`, `method: latest`). With a range of at most five years, it holds one final close per UTC weekday dated YYYY-MM-DD (`frequency: daily`, `method: weekday_close`); Saturday and Sunday UTC observations, including the Sunday-evening market reopen, are excluded. Values are decimal strings in the requested unit, rounded to eight decimal places; pass unit=gram, unit=kilogram, or unit=troy_oz (including documented aliases). For a configured projected currency the series carries `conversion`, the daily Bullion API conversion snapshot provenance; it is omitted for native currencies. History series also carry coverage.earliest, coverage.latest and coverage.observation_count for usable stored weekday closes before the current request time, independent of the requested range. Coverage may be sparse; the five-year query limit does not guarantee five years of history. Non-gold history comes from retained refreshes; projected history begins at activation without backfill.","operationId":"getPalladiumPrice","parameters":[{"$ref":"#/components/parameters/Currency"},{"$ref":"#/components/parameters/MetalPriceUnit"},{"$ref":"#/components/parameters/SeriesStart"},{"$ref":"#/components/parameters/SeriesEnd"}],"responses":{"200":{"description":"palladium price series.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetalPriceResponse"}}}},"400":{"description":"The currency or unit is not supported, or the date range is missing its start, malformed, reversed or longer than the maximum.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_unit","message":"The requested output unit is invalid."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"No cached palladium price exists for the requested currency or date range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"The cached price data could not be read.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"tags":["prices"],"summary":"Not supported — read-only API","operationId":"postPalladiumPriceNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/copper/price":{"get":{"tags":["prices"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"copper price, latest or daily history","description":"Returns the copper spot price as one `copper_price` series. The route reads the local cache and never calls an upstream provider. Without start and end, the series holds the latest cached price with its full UTC observation timestamp (`frequency: hourly`, `method: latest`). With a range of at most five years, it holds one final close per UTC weekday dated YYYY-MM-DD (`frequency: daily`, `method: weekday_close`); Saturday and Sunday UTC observations, including the Sunday-evening market reopen, are excluded. Values are decimal strings in the requested unit, rounded to eight decimal places; pass unit=gram, unit=kilogram, or unit=troy_oz (including documented aliases). For a configured projected currency the series carries `conversion`, the daily Bullion API conversion snapshot provenance; it is omitted for native currencies. History series also carry coverage.earliest, coverage.latest and coverage.observation_count for usable stored weekday closes before the current request time, independent of the requested range. Coverage may be sparse; the five-year query limit does not guarantee five years of history. Non-gold history comes from retained refreshes; projected history begins at activation without backfill.","operationId":"getCopperPrice","parameters":[{"$ref":"#/components/parameters/Currency"},{"$ref":"#/components/parameters/MetalPriceUnit"},{"$ref":"#/components/parameters/SeriesStart"},{"$ref":"#/components/parameters/SeriesEnd"}],"responses":{"200":{"description":"copper price series.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetalPriceResponse"}}}},"400":{"description":"The currency or unit is not supported, or the date range is missing its start, malformed, reversed or longer than the maximum.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_unit","message":"The requested output unit is invalid."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"No cached copper price exists for the requested currency or date range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"The cached price data could not be read.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"tags":["prices"],"summary":"Not supported — read-only API","operationId":"postCopperPriceNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/platinum/price":{"get":{"tags":["prices"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"platinum price, latest or daily history","description":"Returns the platinum spot price as one `platinum_price` series. The route reads the local cache and never calls an upstream provider. Without start and end, the series holds the latest cached price with its full UTC observation timestamp (`frequency: hourly`, `method: latest`). With a range of at most five years, it holds one final close per UTC weekday dated YYYY-MM-DD (`frequency: daily`, `method: weekday_close`); Saturday and Sunday UTC observations, including the Sunday-evening market reopen, are excluded. Values are decimal strings in the requested unit, rounded to eight decimal places; pass unit=gram, unit=kilogram, or unit=troy_oz (including documented aliases). For a configured projected currency the series carries `conversion`, the daily Bullion API conversion snapshot provenance; it is omitted for native currencies. History series also carry coverage.earliest, coverage.latest and coverage.observation_count for usable stored weekday closes before the current request time, independent of the requested range. Coverage may be sparse; the five-year query limit does not guarantee five years of history. Non-gold history comes from retained refreshes; projected history begins at activation without backfill.","operationId":"getPlatinumPrice","parameters":[{"$ref":"#/components/parameters/Currency"},{"$ref":"#/components/parameters/MetalPriceUnit"},{"$ref":"#/components/parameters/SeriesStart"},{"$ref":"#/components/parameters/SeriesEnd"}],"responses":{"200":{"description":"platinum price series.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetalPriceResponse"}}}},"400":{"description":"The currency or unit is not supported, or the date range is missing its start, malformed, reversed or longer than the maximum.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_unit","message":"The requested output unit is invalid."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"No cached platinum price exists for the requested currency or date range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"The cached price data could not be read.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"tags":["prices"],"summary":"Not supported — read-only API","operationId":"postPlatinumPriceNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/gold/change":{"get":{"tags":["prices"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Gold price change between two UTC days","description":"Returns the absolute and percentage change in the gold price between the final cached observation of two UTC days. Use either start and end (at most 365 days apart; start alone runs to today) or one rolling period: 1d, 1w, 1m or 1y (1, 7, 30 or 365 days back from today). Values are decimal strings: `change` is in the requested unit and `change_percent` is relative to the start price, rounded to four decimal places. Gram and kilogram start and end values are rounded to eight decimal places before `change` is taken. A zero start price returns invalid_change_baseline. The endpoint is a database-only reader and never calls upstream providers.","operationId":"getGoldChange","parameters":[{"$ref":"#/components/parameters/Currency"},{"$ref":"#/components/parameters/MetalPriceUnit"},{"$ref":"#/components/parameters/ChangeStart"},{"$ref":"#/components/parameters/ChangeEnd"},{"$ref":"#/components/parameters/ChangePeriod"}],"responses":{"200":{"description":"Absolute and percentage change for cached gold observations.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeResponse"}}}},"400":{"description":"Invalid currency, unit, date, period, conflicting forms, or range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeBadRequestError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"One or both requested UTC days have no cached gold observation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeNoDataError"}}}},"422":{"description":"The cached start price cannot be used as a percentage baseline.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeBaselineError"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"The cached price data could not be read.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"tags":["prices"],"summary":"Not supported — read-only API","operationId":"postGoldChangeNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/silver/change":{"get":{"tags":["prices"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Silver price change between two UTC days","description":"Returns the absolute and percentage change in the silver price between the final cached observation of two UTC days. Use either start and end (at most 365 days apart; start alone runs to today) or one rolling period: 1d, 1w, 1m or 1y (1, 7, 30 or 365 days back from today). Values are decimal strings: `change` is in the requested unit and `change_percent` is relative to the start price, rounded to four decimal places. Gram and kilogram start and end values are rounded to eight decimal places before `change` is taken. A zero start price returns invalid_change_baseline. The endpoint is a database-only reader and never calls upstream providers.","operationId":"getSilverChange","parameters":[{"$ref":"#/components/parameters/Currency"},{"$ref":"#/components/parameters/MetalPriceUnit"},{"$ref":"#/components/parameters/ChangeStart"},{"$ref":"#/components/parameters/ChangeEnd"},{"$ref":"#/components/parameters/ChangePeriod"}],"responses":{"200":{"description":"Absolute and percentage change for cached silver observations.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeResponse"}}}},"400":{"description":"Invalid currency, unit, date, period, conflicting forms, or range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeBadRequestError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"One or both requested UTC days have no cached silver observation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeNoDataError"}}}},"422":{"description":"The cached start price cannot be used as a percentage baseline.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeBaselineError"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"The cached price data could not be read.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"tags":["prices"],"summary":"Not supported — read-only API","operationId":"postSilverChangeNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/palladium/change":{"get":{"tags":["prices"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Palladium price change between two UTC days","description":"Returns the absolute and percentage change in the palladium price between the final cached observation of two UTC days. Use either start and end (at most 365 days apart; start alone runs to today) or one rolling period: 1d, 1w, 1m or 1y (1, 7, 30 or 365 days back from today). Values are decimal strings: `change` is in the requested unit and `change_percent` is relative to the start price, rounded to four decimal places. Gram and kilogram start and end values are rounded to eight decimal places before `change` is taken. A zero start price returns invalid_change_baseline. The endpoint is a database-only reader and never calls upstream providers.","operationId":"getPalladiumChange","parameters":[{"$ref":"#/components/parameters/Currency"},{"$ref":"#/components/parameters/MetalPriceUnit"},{"$ref":"#/components/parameters/ChangeStart"},{"$ref":"#/components/parameters/ChangeEnd"},{"$ref":"#/components/parameters/ChangePeriod"}],"responses":{"200":{"description":"Absolute and percentage change for cached palladium observations.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeResponse"}}}},"400":{"description":"Invalid currency, unit, date, period, conflicting forms, or range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeBadRequestError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"One or both requested UTC days have no cached palladium observation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeNoDataError"}}}},"422":{"description":"The cached start price cannot be used as a percentage baseline.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeBaselineError"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"The cached price data could not be read.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"tags":["prices"],"summary":"Not supported — read-only API","operationId":"postPalladiumChangeNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/copper/change":{"get":{"tags":["prices"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Copper price change between two UTC days","description":"Returns the absolute and percentage change in the copper price between the final cached observation of two UTC days. Use either start and end (at most 365 days apart; start alone runs to today) or one rolling period: 1d, 1w, 1m or 1y (1, 7, 30 or 365 days back from today). Values are decimal strings: `change` is in the requested unit and `change_percent` is relative to the start price, rounded to four decimal places. Gram and kilogram start and end values are rounded to eight decimal places before `change` is taken. A zero start price returns invalid_change_baseline. The endpoint is a database-only reader and never calls upstream providers.","operationId":"getCopperChange","parameters":[{"$ref":"#/components/parameters/Currency"},{"$ref":"#/components/parameters/MetalPriceUnit"},{"$ref":"#/components/parameters/ChangeStart"},{"$ref":"#/components/parameters/ChangeEnd"},{"$ref":"#/components/parameters/ChangePeriod"}],"responses":{"200":{"description":"Absolute and percentage change for cached copper observations.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeResponse"}}}},"400":{"description":"Invalid currency, unit, date, period, conflicting forms, or range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeBadRequestError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"One or both requested UTC days have no cached copper observation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeNoDataError"}}}},"422":{"description":"The cached start price cannot be used as a percentage baseline.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeBaselineError"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"The cached price data could not be read.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"tags":["prices"],"summary":"Not supported — read-only API","operationId":"postCopperChangeNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/platinum/change":{"get":{"tags":["prices"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Platinum price change between two UTC days","description":"Returns the absolute and percentage change in the platinum price between the final cached observation of two UTC days. Use either start and end (at most 365 days apart; start alone runs to today) or one rolling period: 1d, 1w, 1m or 1y (1, 7, 30 or 365 days back from today). Values are decimal strings: `change` is in the requested unit and `change_percent` is relative to the start price, rounded to four decimal places. Gram and kilogram start and end values are rounded to eight decimal places before `change` is taken. A zero start price returns invalid_change_baseline. The endpoint is a database-only reader and never calls upstream providers.","operationId":"getPlatinumChange","parameters":[{"$ref":"#/components/parameters/Currency"},{"$ref":"#/components/parameters/MetalPriceUnit"},{"$ref":"#/components/parameters/ChangeStart"},{"$ref":"#/components/parameters/ChangeEnd"},{"$ref":"#/components/parameters/ChangePeriod"}],"responses":{"200":{"description":"Absolute and percentage change for cached platinum observations.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeResponse"}}}},"400":{"description":"Invalid currency, unit, date, period, conflicting forms, or range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeBadRequestError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"One or both requested UTC days have no cached platinum observation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeNoDataError"}}}},"422":{"description":"The cached start price cannot be used as a percentage baseline.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeBaselineError"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"The cached price data could not be read.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"tags":["prices"],"summary":"Not supported — read-only API","operationId":"postPlatinumChangeNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/gold/carat":{"get":{"tags":["prices"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Gold karat prices per gram","description":"Returns gold prices per gram for the approved karat keys. Without date, the current stored gold row is used. With date=YYYY-MM-DD, the final cached gold observation within that UTC day is used. Each karat price is an eight-place decimal string; this is a response-type compatibility change from the earlier JSON-number values. This database-only reader never calls an upstream provider or bridges currencies.","operationId":"getGoldCarat","parameters":[{"$ref":"#/components/parameters/CaratCurrency"},{"$ref":"#/components/parameters/CaratDate"}],"responses":{"200":{"description":"Gold karat prices per gram.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaratResponse"}}}},"400":{"description":"The currency or date query parameter is malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaratBadRequestError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"No cached gold row exists for the currency or requested UTC day.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"The cached gold data could not be read.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"tags":["prices"],"summary":"Not supported — read-only API","operationId":"postGoldCaratNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/gold/real-price":{"get":{"tags":["derived"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Inflation-adjusted USD gold price","operationId":"getRealPrice","description":"USD gold × latest stored published seasonally adjusted CPI-U index / observation-month index. USD gold per troy ounce × latest stored seasonally adjusted CPI-U index / index for the gold observation month. reference_period names the latest stored published month, not today. Missing months and gold dates are omitted; no carry-forward or interpolation. Uses final stored USD gold closes per UTC weekday. Inclusive start/end are required, with a maximum five-year range; currency is USD only. SQL selects stored inputs and exact decimal arithmetic calculates eight-place decimal strings. No customer request calls an upstream. Successful nonempty series are cached for five minutes. All plans have the same data access and existing monthly quotas. A missing source returns 503 dependency_not_ready for this endpoint independently of other metrics. Attribution is included.","parameters":[{"name":"currency","in":"query","schema":{"type":"string","enum":["USD"],"default":"USD"}},{"$ref":"#/components/parameters/DerivedRangeStart"},{"$ref":"#/components/parameters/DerivedRangeEnd"}],"responses":{"200":{"description":"Stored-data derived series.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RealPriceResponse"}}}},"400":{"description":"Missing or invalid date range or unsupported currency.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"Required index/daily-yield data is absent (dependency_not_ready), or stored data cannot be read (data_unavailable). Dependency details contain a public dependency name and metric, never provider internals.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"tags":["derived"],"summary":"Not supported — read-only API","operationId":"postRealPriceNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/gold/yield-correlation":{"get":{"tags":["derived"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Gold and real-yield correlation","operationId":"getYieldCorrelation","description":"90-pair rolling Pearson correlation of simple USD gold daily returns and daily 10-year real constant-maturity yield changes, with matching current and previous dates. Rolling Pearson correlation of 90 aligned gold simple daily returns and daily 10-year real Treasury constant-maturity yield changes. Both independently lagged series must have the same previous date. Incomplete and zero-variance windows are omitted. Up to one calendar year of pre-range lookback is read. Uses final stored USD gold closes per UTC weekday. Inclusive start/end are required, with a maximum five-year range; currency is USD only. SQL selects stored inputs and exact decimal arithmetic calculates eight-place decimal strings. No customer request calls an upstream. Successful nonempty series are cached for five minutes. All plans have the same data access and existing monthly quotas. A missing source returns 503 dependency_not_ready for this endpoint independently of other metrics. Attribution is included.","parameters":[{"name":"currency","in":"query","schema":{"type":"string","enum":["USD"],"default":"USD"}},{"$ref":"#/components/parameters/DerivedRangeStart"},{"$ref":"#/components/parameters/DerivedRangeEnd"}],"responses":{"200":{"description":"Stored-data derived series.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/YieldCorrelationResponse"}}}},"400":{"description":"Missing or invalid date range or unsupported currency.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"Required index/daily-yield data is absent (dependency_not_ready), or stored data cannot be read (data_unavailable). Dependency details contain a public dependency name and metric, never provider internals.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"tags":["derived"],"summary":"Not supported — read-only API","operationId":"postYieldCorrelationNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/gold-silver-ratio":{"get":{"tags":["derived"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Cache-backed gold-to-silver ratio","description":"Returns the gold-to-silver ratio from stored observations. With no start and end dates, the route uses the latest cached gold and silver rows and returns one point. With both dates, it uses the final stored gold and silver observation in each UTC day within the inclusive range. Missing dates are omitted and missing or invalid input never triggers an upstream request. The query is calculated in SQL and cached in memory for five minutes per currency and range. Derived values remain subject to the plan commercial-use terms; all plans receive the same data contract and differ only in monthly quota.","operationId":"getGoldSilverRatio","parameters":[{"$ref":"#/components/parameters/Currency"},{"$ref":"#/components/parameters/DerivedStart"},{"$ref":"#/components/parameters/DerivedEnd"}],"responses":{"200":{"description":"Gold-to-silver ratio series calculated from the local price cache.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoldSilverRatioResponse"}}}},"400":{"description":"The currency or inclusive date range is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_range","message":"The requested range is invalid."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"No latest gold and silver rows are available for the requested currency, or they were observed more than six hours apart.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"The cached derived data could not be read.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"tags":["derived"],"summary":"Not supported — read-only API","operationId":"postGoldSilverRatioNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/gold/moving-average":{"get":{"tags":["derived"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Gold simple moving average","description":"Returns the simple moving average of daily gold closes over the requested window. Each value uses up to 50 or 200 valid stored daily closes including the current close and is a partial warm-up average when fewer closes exist. Uses the final stored gold observation in each UTC weekday (Saturday and Sunday UTC rows are excluded) within the inclusive start/end range, which is required. Missing dates are omitted and no request triggers an upstream call. The derived series is cached in memory for five minutes per currency and range. All plans receive the same data contract and differ only in monthly quota. Moving-average values are decimal strings rounded half-up to eight decimal places.","operationId":"getMovingAverage","parameters":[{"$ref":"#/components/parameters/MovingAverageWindow"},{"$ref":"#/components/parameters/Currency"},{"$ref":"#/components/parameters/DerivedRangeStart"},{"$ref":"#/components/parameters/DerivedRangeEnd"}],"responses":{"200":{"description":"Moving-average series calculated from the local price cache.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MovingAverageResponse"}}}},"400":{"description":"A date is missing (missing_params), the window is not 50 or 200 (invalid_window), or the currency or inclusive date range is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"missing_params","message":"Required request parameters are missing."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"The cached derived data could not be read.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"tags":["derived"],"summary":"Not supported — read-only API","operationId":"postMovingAverageNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/gold/volatility":{"get":{"tags":["derived"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Gold realised volatility over 30 daily returns","description":"Returns annualised sample volatility of 30 daily gold returns (standard deviation × √252) as a fraction. Days before 30 returns exist are omitted, so a short range can return an empty points array. Uses the final stored gold observation in each UTC weekday (Saturday and Sunday UTC rows are excluded) within the inclusive start/end range, which is required. Missing dates are omitted and no request triggers an upstream call. The query is calculated in SQL and cached in memory for five minutes per currency and range. All plans receive the same data contract and differ only in monthly quota.","operationId":"getVolatility","parameters":[{"$ref":"#/components/parameters/Currency"},{"$ref":"#/components/parameters/DerivedRangeStart"},{"$ref":"#/components/parameters/DerivedRangeEnd"}],"responses":{"200":{"description":"Volatility series calculated from the local price cache.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolatilityResponse"}}}},"400":{"description":"A parameter is missing or invalid, or the inclusive date range is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"missing_params","message":"Required request parameters are missing."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"The cached derived data could not be read.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"tags":["derived"],"summary":"Not supported — read-only API","operationId":"postVolatilityNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/gold/drawdown":{"get":{"tags":["derived"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Gold drawdown from its running peak","description":"Returns the decline of each trading-day gold close from its running peak over up to 1,260 trading-day observations, as a fraction that is zero or negative. Values are partial warm-up drawdowns when fewer observations exist. Uses the final stored gold observation in each UTC weekday (Saturday and Sunday UTC rows are excluded) within the inclusive start/end range, which is required. Missing dates are omitted and no request triggers an upstream call. The query is calculated in SQL and cached in memory for five minutes per currency and range. All plans receive the same data contract and differ only in monthly quota.","operationId":"getDrawdown","parameters":[{"$ref":"#/components/parameters/Currency"},{"$ref":"#/components/parameters/DerivedRangeStart"},{"$ref":"#/components/parameters/DerivedRangeEnd"}],"responses":{"200":{"description":"Drawdown series calculated from the local price cache.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrawdownResponse"}}}},"400":{"description":"A parameter is missing or invalid, or the inclusive date range is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"missing_params","message":"Required request parameters are missing."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"The cached derived data could not be read.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"tags":["derived"],"summary":"Not supported — read-only API","operationId":"postDrawdownNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/policy-rates/{country}":{"get":{"tags":["macro"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Central-bank policy rates for one country","description":"Returns the central-bank policy rate series of one country. Without start and end each series holds its latest observation; with a range it holds every observation whose period end is in range, in chronological order. Series without observations in the range are left out. Covered countries are `US`, `GB` and `EA` (euro area); any other valid country code returns 404 `no_data`. Values are decimal strings. Each series carries its label, unit, frequency, method and source attribution with the upstream series id. Requests read stored observations and never call upstream sources; every plan receives the same data contract and differs only in monthly quota. Policy rates are stored per daily source observation. United States series are the effective federal funds rate and the target range bounds from New York Fed Markets Data (EFFR). Euro-area series are the ECB deposit facility, main refinancing operations and marginal lending facility rates. United Kingdom policy uses Bank of England IUDBEDR Bank Rate observations; BoE data is attributed under the Open Government Licence: https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/. European Central Bank statistics are freely available for reuse when accurately reproduced and cited.","operationId":"getPolicyRates","parameters":[{"$ref":"#/components/parameters/CountryPath"},{"$ref":"#/components/parameters/SeriesStart"},{"$ref":"#/components/parameters/SeriesEnd"}],"responses":{"200":{"description":"Central-bank policy rates with per-series provenance.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyRatesResponse"}}}},"400":{"description":"The country code or date range is invalid (`invalid_country`, `missing_params`, `invalid_date` or `invalid_range`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_country","message":"The country code is invalid."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"The country is valid but not covered by this metric, or no stored observation matches the request.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["macro"],"summary":"Not supported — read-only API","operationId":"postPolicyRatesNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/policy-rates":{"get":{"tags":["macro"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Latest central-bank policy rate for every covered country","description":"Returns the latest observation of each central-bank policy rate series for every covered country in the order US, GB, EA, as one quota-counted request. Countries without any matching observation are left out. This route always returns latest values and ignores `start` and `end`; use the per-country route for history. Covered countries are `US`, `GB` and `EA` (euro area); any other valid country code returns 404 `no_data`. Values are decimal strings. Each series carries its label, unit, frequency, method and source attribution with the upstream series id. Requests read stored observations and never call upstream sources; every plan receives the same data contract and differs only in monthly quota. Policy rates are stored per daily source observation. United States series are the effective federal funds rate and the target range bounds from New York Fed Markets Data (EFFR). Euro-area series are the ECB deposit facility, main refinancing operations and marginal lending facility rates. United Kingdom policy uses Bank of England IUDBEDR Bank Rate observations; BoE data is attributed under the Open Government Licence: https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/. European Central Bank statistics are freely available for reuse when accurately reproduced and cited.","operationId":"getPolicyRatesCollection","parameters":[],"responses":{"200":{"description":"Latest central-bank policy rate for every covered country.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyRatesCollectionResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"No covered country has a stored observation matching the request.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["macro"],"summary":"Not supported — read-only API","operationId":"postPolicyRatesCollectionNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/inflation/{country}":{"get":{"tags":["macro"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Inflation measures for one country","description":"Returns the inflation series of one country. Without start and end each series holds its latest observation; with a range it holds every observation whose period end is in range, in chronological order. Series without observations in the range are left out. Covered countries are `US`, `GB` and `EA` (euro area); any other valid country code returns 404 `no_data`. Values are decimal strings. Each series carries its label, unit, frequency, method and source attribution with the upstream series id. Requests read stored observations and never call upstream sources; every plan receives the same data contract and differs only in monthly quota. Realised inflation is monthly and year on year: BLS CPI-U is the not-seasonally-adjusted CUUR0000SA0 series, euro-area HICP uses the metadata-verified all-items annual-rate series and UK inflation uses the Office for National Statistics D7G7 CPI annual rate. U.S. Treasury breakevens (basis breakeven) are monthly averages derived from matched nominal and real yield dates. UK RPI-linked implied inflation (basis implied) comes from Bank of England yield curves at 2y, 5y, 10y and 30y tenors using official month-end archive dates and method month_end. ECB Consumer Expectations Survey values (basis expectation, 12m and 5y horizons) are weighted-median survey expectations, not market-implied. BoE and ONS data are attributed under the Open Government Licence: https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/. European Central Bank statistics are freely available for reuse when accurately reproduced and cited.","operationId":"getInflation","parameters":[{"$ref":"#/components/parameters/CountryPath"},{"$ref":"#/components/parameters/SeriesStart"},{"$ref":"#/components/parameters/SeriesEnd"},{"$ref":"#/components/parameters/InflationBasis"}],"responses":{"200":{"description":"Inflation measures with per-series provenance.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InflationResponse"}}}},"400":{"description":"The country code, date range or a series filter is invalid (`invalid_country`, `missing_params`, `invalid_date`, `invalid_range` or `invalid_series_filter`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_country","message":"The country code is invalid."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"The country is valid but not covered by this metric, or no stored observation matches the request.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["macro"],"summary":"Not supported — read-only API","operationId":"postInflationNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/inflation":{"get":{"tags":["macro"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Latest inflation for every covered country","description":"Returns the latest observation of each inflation series for every covered country in the order US, GB, EA, as one quota-counted request. Countries without any matching observation are left out. This route always returns latest values and ignores `start` and `end`; use the per-country route for history. Covered countries are `US`, `GB` and `EA` (euro area); any other valid country code returns 404 `no_data`. Values are decimal strings. Each series carries its label, unit, frequency, method and source attribution with the upstream series id. Requests read stored observations and never call upstream sources; every plan receives the same data contract and differs only in monthly quota. Realised inflation is monthly and year on year: BLS CPI-U is the not-seasonally-adjusted CUUR0000SA0 series, euro-area HICP uses the metadata-verified all-items annual-rate series and UK inflation uses the Office for National Statistics D7G7 CPI annual rate. U.S. Treasury breakevens (basis breakeven) are monthly averages derived from matched nominal and real yield dates. UK RPI-linked implied inflation (basis implied) comes from Bank of England yield curves at 2y, 5y, 10y and 30y tenors using official month-end archive dates and method month_end. ECB Consumer Expectations Survey values (basis expectation, 12m and 5y horizons) are weighted-median survey expectations, not market-implied. BoE and ONS data are attributed under the Open Government Licence: https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/. European Central Bank statistics are freely available for reuse when accurately reproduced and cited.","operationId":"getInflationCollection","parameters":[{"$ref":"#/components/parameters/InflationBasis"}],"responses":{"200":{"description":"Latest inflation for every covered country.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InflationCollectionResponse"}}}},"400":{"description":"A series filter is invalid (`invalid_series_filter`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_series_filter","message":"The series filter value is invalid."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"No covered country has a stored observation matching the request.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["macro"],"summary":"Not supported — read-only API","operationId":"postInflationCollectionNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/bond-yields/{country}":{"get":{"tags":["macro"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Government bond yields for one country","description":"Returns the government bond yield series of one country. Without start and end each series holds its latest observation; with a range it holds every observation whose period end is in range, in chronological order. Series without observations in the range are left out. Covered countries are `US`, `GB` and `EA` (euro area); any other valid country code returns 404 `no_data`. Values are decimal strings. Each series carries its label, unit, frequency, method and source attribution with the upstream series id. Requests read stored observations and never call upstream sources; every plan receives the same data contract and differs only in monthly quota. Yields are monthly. U.S. Treasury nominal and real yields and European Central Bank AAA euro-area government bond yields are monthly averages of valid daily observations from complete calendar months; the euro area has no real-yield series. UK gilt yields are Bank of England nominal and real zero-coupon spot yields at 2y, 5y, 10y and 30y tenors using official month-end archive dates and method month_end. BoE data is attributed under the Open Government Licence: https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/. European Central Bank statistics are freely available for reuse when accurately reproduced and cited.","operationId":"getBondYields","parameters":[{"$ref":"#/components/parameters/CountryPath"},{"$ref":"#/components/parameters/SeriesStart"},{"$ref":"#/components/parameters/SeriesEnd"},{"$ref":"#/components/parameters/BondYieldTenor"},{"$ref":"#/components/parameters/BondYieldBasis"}],"responses":{"200":{"description":"Government bond yields with per-series provenance.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BondYieldsResponse"}}}},"400":{"description":"The country code, date range or a series filter is invalid (`invalid_country`, `missing_params`, `invalid_date`, `invalid_range` or `invalid_series_filter`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_country","message":"The country code is invalid."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"The country is valid but not covered by this metric, or no stored observation matches the request.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["macro"],"summary":"Not supported — read-only API","operationId":"postBondYieldsNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/bond-yields":{"get":{"tags":["macro"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Latest government bond yield for every covered country","description":"Returns the latest observation of each government bond yield series for every covered country in the order US, GB, EA, as one quota-counted request. Countries without any matching observation are left out. This route always returns latest values and ignores `start` and `end`; use the per-country route for history. Covered countries are `US`, `GB` and `EA` (euro area); any other valid country code returns 404 `no_data`. Values are decimal strings. Each series carries its label, unit, frequency, method and source attribution with the upstream series id. Requests read stored observations and never call upstream sources; every plan receives the same data contract and differs only in monthly quota. Yields are monthly. U.S. Treasury nominal and real yields and European Central Bank AAA euro-area government bond yields are monthly averages of valid daily observations from complete calendar months; the euro area has no real-yield series. UK gilt yields are Bank of England nominal and real zero-coupon spot yields at 2y, 5y, 10y and 30y tenors using official month-end archive dates and method month_end. BoE data is attributed under the Open Government Licence: https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/. European Central Bank statistics are freely available for reuse when accurately reproduced and cited.","operationId":"getBondYieldsCollection","parameters":[{"$ref":"#/components/parameters/BondYieldTenor"},{"$ref":"#/components/parameters/BondYieldBasis"}],"responses":{"200":{"description":"Latest government bond yield for every covered country.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BondYieldsCollectionResponse"}}}},"400":{"description":"A series filter is invalid (`invalid_series_filter`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_series_filter","message":"The series filter value is invalid."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"No covered country has a stored observation matching the request.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["macro"],"summary":"Not supported — read-only API","operationId":"postBondYieldsCollectionNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/government-debt/{country}":{"get":{"tags":["macro"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Government debt series for one country","description":"Returns the stored government debt series for one country: `US`, `GB` (alias `uk`), `AU`, `IS`, `EA` (alias `eu`, the euro-area aggregate), `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`, or `PE`. Any other valid country code returns 404 `no_data`. Without `start` and `end` each series carries its latest observation; with a range it carries every observation whose period end falls inside it, in chronological order. Ranges may span at most 10 calendar years; a longer range returns 400 `invalid_range`. When `end` is omitted it defaults to today, with the same cap. Each series declares its government `scope`, accounting `basis`, `unit`, `frequency`, `period_type`, `method`, and a plain-language `definition` including its sign convention; unlike measures are not normalised into a common definition, so compare series only when their scope and basis match. Values are decimal strings and `date` is the period end. `status` is included when a publisher provides actual, provisional or revised status. Each series includes `coverage.earliest` and `coverage.latest`: the earliest and latest usable stored observation period ends, independent of the requested range. Coverage does not imply that every intervening period is available. United States series are U.S. Treasury Fiscal Service data distributed by FRED: total public debt outstanding (GFDEBTN) and debt held by the public (FYGFDPUN) at the end of each calendar quarter, in millions of U.S. dollars with central-government scope, plus `treasury_federal_debt_to_gdp`, a quarterly Bullion API ratio (`derived_ratio`, with its formula and inputs in `derivation`) of quarter-end total public debt outstanding to BEA nominal GDP (NIPA Table 1.1.5, seasonally adjusted annual rate). This product uses the Bureau of Economic Analysis (BEA) Data API but is not endorsed or certified by BEA. This product uses the FRED® API but is not endorsed or certified by the Federal Reserve Bank of St. Louis. Peru series come from BCRPData: quarterly non-financial-public-sector debt outstanding in millions of Peruvian soles (PN03371FQ) and the separately published percentage-of-PBI ratio (PN03432FQ). Both are reported measures with public-sector scope; Bullion API does not derive the ratio. BCRPData metadata credits the Ministry of Economy and Finance, Banco de la Nación, Ministry of Transportation and Communications, ONP and Cofide as source institutions. Its terms permit reproduction with source attribution, do not identify a Creative Commons licence, and state that responsibility for externally sourced statistics rests with the original provider. United Kingdom series come from the Office for National Statistics Public sector finances time series (dataset PUSF), not seasonally adjusted: month-end public sector net debt excluding public sector banks (KSE6, millions of pounds, public-sector scope) and as a percentage of GDP (HF6X, whose ONS denominator is GDP for the 12 months centred on the month, including projected GDP, so it is revised as outturn GDP arrives). Euro-area series come from Eurostat for the Eurostat EA21 aggregate (the fixed composition of the 21 member states in the euro area from 2026, back-calculated for earlier periods) and general-government scope (sector S13): consolidated gross debt in millions of euro and as a Eurostat-published percentage of GDP, annual at 31 December from the Excessive Deficit Procedure data (`gov_10dd_edpt1`) and quarterly at the quarter end from `gov_10q_ggdebt`; annual and quarterly vintages are separate series. Norway series come from Statistics Norway (SSB) StatBank for the national-accounts general-government sector: gross public debt at nominal value in millions of Norwegian kroner, annual at 31 December (table 08753) and quarterly at the quarter end (table 11559, not seasonally adjusted), plus `ssb_gross_debt_to_gdp_annual` and `ssb_gross_debt_to_gdp_quarterly`, Bullion API ratios (`derived_ratio`, with formula and inputs in `derivation`) of that debt to GDP at current market prices including petroleum (table 09189; quarterly debt over the sum of the last four quarters of table 09190). Statistics Norway publishes no such ratio. Canada series come from Statistics Canada for the national-accounts general-government sector, quarterly only: gross debt in millions of Canadian dollars at the quarter end (table 36-10-0467-01) and gross debt to GDP as a percentage published by Statistics Canada (table 38-10-0237-01, whose gross debt is defined more widely than the debt table). Switzerland series come from the Swiss Federal Finance Administration (GFS model, whole-state general government), annual accounts years only, in millions of Swiss francs at 31 December: gross debt excluding financial derivatives as defined by the IMF, the Maastricht-style debt, and the debt ratio the Administration publishes for that debt (in percent). The two debt measures are different and neither is verified as comparable with the Eurostat series. Qatar series come from official Ministry of Finance and National Planning Council datasets: national central-government public debt in millions of Qatari riyals at 31 December (dataset MOF-OD-C0-00004) through 2025, and a Bullion API debt-to-GDP calculation from same-year nominal GDP (dataset NPC-OD-C0-01288) only for matched years through 2024. No 2025 GDP or ratio is inferred. Debt values are positive positions at the period end, so observations have no `period_start`. Singapore serves annual central-government Total Government Debt (M130071, SGD millions) at 31 December and a Bullion API derived_ratio using the same calendar year’s nominal GDP (M015731). Includes non-spending-purpose instruments whose proceeds are invested and cannot be spent, not net or consolidated general-government debt. No Singapore borrowing, servicing, quarterly data or forecasts are served. Iceland series come from Statistics Iceland THJ05181: annual total liabilities including pension/insurance liabilities and payables (not Maastricht debt), in millions of ISK and as a published percentage of GDP, preserving full PX decimal precision. Australian series are ABS general-government gross L2 debt at 30 June from Government Finance Statistics, Annual Table 14 (row Equals L2, column All Australia general government), valued at current market value under the ABS creditor approach, in AUD millions. The Bullion API derived ratio uses original current-price GDP for the matching July-to-June financial year from ABS SDMX flow ANA_AGG version 1.0.0, key M3.GPM.10.AUS.Q; it is not an ABS-published ratio or the net L2 ratio in Table 16. ABS general-government gross L2 debt is valued at current market value using the ABS creditor approach, not at nominal or face value (methodology §§13.4–13.6 and 13.9: https://www.abs.gov.au/statistics/detailed-methodology-information/concepts-sources-methods/australian-system-government-finance-statistics-concepts-sources-and-methods/2015/13-treatment-selected-items/part-b-treatment-debt-australian-gfs). The ratio denominator is the sum of the four original, current-price GDP quarters for the matching July-to-June financial year. Iceland data: Source: Statistics Iceland, THJ05181 and THJ05121, CC BY 4.0 (https://www.statice.is/publications/open-data-access/). Modifications are not attributed to Statistics Iceland. U.S. Treasury Fiscal Service data is a U.S. federal government work, distributed by FRED, Federal Reserve Bank of St. Louis. United Kingdom data: Source: Office for National Statistics, Public Sector Finances. Contains public sector information licensed under the Open Government Licence v3.0: https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/. Euro-area and EU member-state data: Source: Eurostat, government finance statistics; reuse is authorised provided the source is acknowledged. Australian data: Source: Australian Bureau of Statistics, Government Finance Statistics, Annual and Australian National Accounts. ABS website material is licensed under Creative Commons Attribution 4.0 International, subject to the exclusions and third-party rights identified in the ABS copyright terms. Those terms require attribution to the ABS for material obtained from its website; do not imply ABS endorsement. The ABS Data API is Beta and may change or be unavailable. Singapore annual debt and GDP: Singapore Open Data Licence v1.0: https://data.gov.sg/open-data-licence. Commercial use and distribution permitted with source acknowledgement and licence link; no official endorsement. Sublicensing is limited to enabling application/website use; downstream sub-licensees receive no rights. Customers needing additional rights must obtain the original licence directly at data.gov.sg. Debt catalogue: https://data.gov.sg/datasets/d_d4f7c9d15692b3c08aa9bc8bc56c0a72/view. GDP catalogue: https://data.gov.sg/datasets/d_d0db56a7c201c9a1e42c846d4fe6da8f/view. Norway data: Source: Statistics Norway (SSB), www.ssb.no, licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/); changes were made (Bullion API calculates the debt-to-GDP ratios), and Statistics Norway does not endorse Bullion API. Canada data: Source: Statistics Canada, tables 36-10-0467-01, 38-10-0237-01 and 36-10-0477-01, reference date shown on each observation. Reproduced and distributed on an \"as is\" basis with the permission of Statistics Canada (Statistics Canada Open Licence, https://www.statcan.gc.ca/en/terms-conditions/open-licence). This does not constitute an endorsement by Statistics Canada of this product. Switzerland data: Source: Swiss Federal Finance Administration (EFV/FFA), \"Main aggregates and forecasts with FS- and GFS-Model\", https://opendata.swiss/en/dataset/hauptaggregate-und-prognosen-im-fs-und-gfs-modell, published as open government data under the opendata.swiss \"Open use\" terms (commercial use permitted, source recommended); provided without verification of the derived series, and not endorsed by the Federal Finance Administration. Qatar data: Source: Qatar Ministry of Finance, dataset MOF-OD-C0-00004 (public debt); Qatar National Planning Council, dataset NPC-OD-C0-01288 (gross domestic product). Both datasets identify CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/); changes were made because Bullion API calculates matched-year debt-to-GDP ratios. Qatar Open Data Portal metadata observed 2026-09-30 reports the generic data-trust-index.ready-for-publication=false flag; this is not a publisher certification, data withdrawal or deprecation. Japan data: Source: Economic and Social Research Institute, Cabinet Office, Government of Japan, General Government Gross Debt (https://www.esri.cao.go.jp/en/sna/sddsplus/tables/ggd.xlsx) and Quarterly Estimates of GDP (https://www.esri.cao.go.jp/en/sna/sokuhou/sokuhou_top.html). The Cabinet Office notice (https://www.cao.go.jp/en/notice-e.html) states that numerical data and simple tables are not protected by copyright and may be used freely; the website Terms of Use govern website content and do not apply to those data. Source attribution and disclosure of the Bullion API debt-to-GDP calculation are Bullion API policy, not conditions imposed on those numerical data. This is not a claim of rights to separate third-party copyrighted material. The Cabinet Office does not endorse this product. A derived series is attributed as a Bullion API calculation naming every input source, never an input source alone; for a derived series `source.id` is the collecting or deriving source, not the sole provenance, so read `source.attribution` and `derivation` for every input. Forecasts, projections, and editorial classifications are never returned. Every plan can call this endpoint; API requests read the database and never call upstream sources.","operationId":"getGovernmentDebt","parameters":[{"$ref":"#/components/parameters/CountryPath"},{"$ref":"#/components/parameters/SeriesStart"},{"$ref":"#/components/parameters/SeriesEnd"}],"responses":{"200":{"description":"Government debt series with provenance.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GovernmentDebtResponse"}}}},"400":{"description":"The country code is invalid (invalid_country), end was sent without start (missing_params), a date is malformed (invalid_date), or start is after end (invalid_range).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_country","message":"The country code is invalid."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"The country is not covered (only US, GB, AU, IS, EA, 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, and PE are), or no observation exists for the request.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["macro"],"summary":"Not supported — read-only API","operationId":"postGovernmentDebtNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/government-debt":{"get":{"tags":["macro"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Latest government debt for every covered country","description":"Returns the latest observation of each government debt series for every covered country, in the order `US`, `GB`, `AU`, `IS`, `EA`, `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`, then `PE`, as one quota-counted request. Each series declares its government `scope`, accounting `basis`, `unit`, `frequency`, `period_type`, `method`, and a plain-language `definition` including its sign convention; unlike measures are not normalised into a common definition, so compare series only when their scope and basis match. Values are decimal strings and `date` is the period end. `status` is included when a publisher provides actual, provisional or revised status. Each series includes `coverage.earliest` and `coverage.latest`: the earliest and latest usable stored observation period ends, independent of the requested range. Coverage does not imply that every intervening period is available. United States series are U.S. Treasury Fiscal Service data distributed by FRED: total public debt outstanding (GFDEBTN) and debt held by the public (FYGFDPUN) at the end of each calendar quarter, in millions of U.S. dollars with central-government scope, plus `treasury_federal_debt_to_gdp`, a quarterly Bullion API ratio (`derived_ratio`, with its formula and inputs in `derivation`) of quarter-end total public debt outstanding to BEA nominal GDP (NIPA Table 1.1.5, seasonally adjusted annual rate). This product uses the Bureau of Economic Analysis (BEA) Data API but is not endorsed or certified by BEA. This product uses the FRED® API but is not endorsed or certified by the Federal Reserve Bank of St. Louis. Peru series come from BCRPData: quarterly non-financial-public-sector debt outstanding in millions of Peruvian soles (PN03371FQ) and the separately published percentage-of-PBI ratio (PN03432FQ). Both are reported measures with public-sector scope; Bullion API does not derive the ratio. BCRPData metadata credits the Ministry of Economy and Finance, Banco de la Nación, Ministry of Transportation and Communications, ONP and Cofide as source institutions. Its terms permit reproduction with source attribution, do not identify a Creative Commons licence, and state that responsibility for externally sourced statistics rests with the original provider. United Kingdom series come from the Office for National Statistics Public sector finances time series (dataset PUSF), not seasonally adjusted: month-end public sector net debt excluding public sector banks (KSE6, millions of pounds, public-sector scope) and as a percentage of GDP (HF6X, whose ONS denominator is GDP for the 12 months centred on the month, including projected GDP, so it is revised as outturn GDP arrives). Euro-area series come from Eurostat for the Eurostat EA21 aggregate (the fixed composition of the 21 member states in the euro area from 2026, back-calculated for earlier periods) and general-government scope (sector S13): consolidated gross debt in millions of euro and as a Eurostat-published percentage of GDP, annual at 31 December from the Excessive Deficit Procedure data (`gov_10dd_edpt1`) and quarterly at the quarter end from `gov_10q_ggdebt`; annual and quarterly vintages are separate series. Norway series come from Statistics Norway (SSB) StatBank for the national-accounts general-government sector: gross public debt at nominal value in millions of Norwegian kroner, annual at 31 December (table 08753) and quarterly at the quarter end (table 11559, not seasonally adjusted), plus `ssb_gross_debt_to_gdp_annual` and `ssb_gross_debt_to_gdp_quarterly`, Bullion API ratios (`derived_ratio`, with formula and inputs in `derivation`) of that debt to GDP at current market prices including petroleum (table 09189; quarterly debt over the sum of the last four quarters of table 09190). Statistics Norway publishes no such ratio. Canada series come from Statistics Canada for the national-accounts general-government sector, quarterly only: gross debt in millions of Canadian dollars at the quarter end (table 36-10-0467-01) and gross debt to GDP as a percentage published by Statistics Canada (table 38-10-0237-01, whose gross debt is defined more widely than the debt table). Switzerland series come from the Swiss Federal Finance Administration (GFS model, whole-state general government), annual accounts years only, in millions of Swiss francs at 31 December: gross debt excluding financial derivatives as defined by the IMF, the Maastricht-style debt, and the debt ratio the Administration publishes for that debt (in percent). The two debt measures are different and neither is verified as comparable with the Eurostat series. Qatar series come from official Ministry of Finance and National Planning Council datasets: national central-government public debt in millions of Qatari riyals at 31 December (dataset MOF-OD-C0-00004) through 2025, and a Bullion API debt-to-GDP calculation from same-year nominal GDP (dataset NPC-OD-C0-01288) only for matched years through 2024. No 2025 GDP or ratio is inferred. Debt values are positive positions at the period end, so observations have no `period_start`. Singapore serves annual central-government Total Government Debt (M130071, SGD millions) at 31 December and a Bullion API derived_ratio using the same calendar year’s nominal GDP (M015731). Includes non-spending-purpose instruments whose proceeds are invested and cannot be spent, not net or consolidated general-government debt. No Singapore borrowing, servicing, quarterly data or forecasts are served. Iceland series come from Statistics Iceland THJ05181: annual total liabilities including pension/insurance liabilities and payables (not Maastricht debt), in millions of ISK and as a published percentage of GDP, preserving full PX decimal precision. Australian series are ABS general-government gross L2 debt at 30 June from Government Finance Statistics, Annual Table 14 (row Equals L2, column All Australia general government), valued at current market value under the ABS creditor approach, in AUD millions. The Bullion API derived ratio uses original current-price GDP for the matching July-to-June financial year from ABS SDMX flow ANA_AGG version 1.0.0, key M3.GPM.10.AUS.Q; it is not an ABS-published ratio or the net L2 ratio in Table 16. ABS general-government gross L2 debt is valued at current market value using the ABS creditor approach, not at nominal or face value (methodology §§13.4–13.6 and 13.9: https://www.abs.gov.au/statistics/detailed-methodology-information/concepts-sources-methods/australian-system-government-finance-statistics-concepts-sources-and-methods/2015/13-treatment-selected-items/part-b-treatment-debt-australian-gfs). The ratio denominator is the sum of the four original, current-price GDP quarters for the matching July-to-June financial year. Iceland data: Source: Statistics Iceland, THJ05181 and THJ05121, CC BY 4.0 (https://www.statice.is/publications/open-data-access/). Modifications are not attributed to Statistics Iceland. U.S. Treasury Fiscal Service data is a U.S. federal government work, distributed by FRED, Federal Reserve Bank of St. Louis. United Kingdom data: Source: Office for National Statistics, Public Sector Finances. Contains public sector information licensed under the Open Government Licence v3.0: https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/. Euro-area and EU member-state data: Source: Eurostat, government finance statistics; reuse is authorised provided the source is acknowledged. Australian data: Source: Australian Bureau of Statistics, Government Finance Statistics, Annual and Australian National Accounts. ABS website material is licensed under Creative Commons Attribution 4.0 International, subject to the exclusions and third-party rights identified in the ABS copyright terms. Those terms require attribution to the ABS for material obtained from its website; do not imply ABS endorsement. The ABS Data API is Beta and may change or be unavailable. Singapore annual debt and GDP: Singapore Open Data Licence v1.0: https://data.gov.sg/open-data-licence. Commercial use and distribution permitted with source acknowledgement and licence link; no official endorsement. Sublicensing is limited to enabling application/website use; downstream sub-licensees receive no rights. Customers needing additional rights must obtain the original licence directly at data.gov.sg. Debt catalogue: https://data.gov.sg/datasets/d_d4f7c9d15692b3c08aa9bc8bc56c0a72/view. GDP catalogue: https://data.gov.sg/datasets/d_d0db56a7c201c9a1e42c846d4fe6da8f/view. Norway data: Source: Statistics Norway (SSB), www.ssb.no, licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/); changes were made (Bullion API calculates the debt-to-GDP ratios), and Statistics Norway does not endorse Bullion API. Canada data: Source: Statistics Canada, tables 36-10-0467-01, 38-10-0237-01 and 36-10-0477-01, reference date shown on each observation. Reproduced and distributed on an \"as is\" basis with the permission of Statistics Canada (Statistics Canada Open Licence, https://www.statcan.gc.ca/en/terms-conditions/open-licence). This does not constitute an endorsement by Statistics Canada of this product. Switzerland data: Source: Swiss Federal Finance Administration (EFV/FFA), \"Main aggregates and forecasts with FS- and GFS-Model\", https://opendata.swiss/en/dataset/hauptaggregate-und-prognosen-im-fs-und-gfs-modell, published as open government data under the opendata.swiss \"Open use\" terms (commercial use permitted, source recommended); provided without verification of the derived series, and not endorsed by the Federal Finance Administration. Qatar data: Source: Qatar Ministry of Finance, dataset MOF-OD-C0-00004 (public debt); Qatar National Planning Council, dataset NPC-OD-C0-01288 (gross domestic product). Both datasets identify CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/); changes were made because Bullion API calculates matched-year debt-to-GDP ratios. Qatar Open Data Portal metadata observed 2026-09-30 reports the generic data-trust-index.ready-for-publication=false flag; this is not a publisher certification, data withdrawal or deprecation. Japan data: Source: Economic and Social Research Institute, Cabinet Office, Government of Japan, General Government Gross Debt (https://www.esri.cao.go.jp/en/sna/sddsplus/tables/ggd.xlsx) and Quarterly Estimates of GDP (https://www.esri.cao.go.jp/en/sna/sokuhou/sokuhou_top.html). The Cabinet Office notice (https://www.cao.go.jp/en/notice-e.html) states that numerical data and simple tables are not protected by copyright and may be used freely; the website Terms of Use govern website content and do not apply to those data. Source attribution and disclosure of the Bullion API debt-to-GDP calculation are Bullion API policy, not conditions imposed on those numerical data. This is not a claim of rights to separate third-party copyrighted material. The Cabinet Office does not endorse this product. A derived series is attributed as a Bullion API calculation naming every input source, never an input source alone; for a derived series `source.id` is the collecting or deriving source, not the sole provenance, so read `source.attribution` and `derivation` for every input. Forecasts, projections, and editorial classifications are never returned. Every plan can call this endpoint; API requests read the database and never call upstream sources.","operationId":"listGovernmentDebt","responses":{"200":{"description":"Latest government debt series per country with provenance.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GovernmentDebtCollectionResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"No covered country has a stored observation.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["macro"],"summary":"Not supported — read-only API","operationId":"postGovernmentDebtCollectionNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/government-borrowing/{country}":{"get":{"tags":["macro"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Government borrowing series for one country","description":"Returns the stored government borrowing series for one country: `US`, `GB` (alias `uk`), `IS`, `EA` (alias `eu`, the euro-area aggregate), `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`, or `CH`. Any other valid country code returns 404 `no_data`. Without `start` and `end` each series carries its latest observation; with a range it carries every observation whose period end falls inside it, in chronological order. Ranges may span at most 10 calendar years; a longer range returns 400 `invalid_range`. When `end` is omitted it defaults to today, with the same cap. Each series declares its government `scope`, accounting `basis`, `unit`, `frequency`, `period_type`, `method`, and a plain-language `definition` including its sign convention; unlike measures are not normalised into a common definition, so compare series only when their scope and basis match. Values are decimal strings and `date` is the period end. `status` is included when a publisher provides actual, provisional or revised status. Each series includes `coverage.earliest` and `coverage.latest`: the earliest and latest usable stored observation period ends, independent of the requested range. Coverage does not imply that every intervening period is available. Sign conventions differ by source and are stated in each `definition`. United States series come from the Monthly Treasury Statement as distributed by FRED (MTSDS133FMS): the federal budget surplus (+) or deficit (-) for the calendar month, and fiscal year to date from 1 October as a Bullion API `derived_cumulative` sum of the monthly values, in millions of U.S. dollars with central-government scope; a negative value is a deficit. This product uses the FRED® API but is not endorsed or certified by the Federal Reserve Bank of St. Louis. United Kingdom series come from the Office for National Statistics Public sector finances time series (dataset PUSF), not seasonally adjusted: monthly public sector net borrowing excluding public sector banks (DZLS, millions of pounds), where a positive value is borrowing and a negative value a surplus, and fiscal-year-to-date net borrowing from 1 April as a Bullion API `derived_cumulative` sum of DZLS (not an ONS-published series). Euro-area series come from Eurostat for the Eurostat EA21 aggregate (the fixed composition of the 21 member states in the euro area from 2026, back-calculated for earlier periods) and general-government scope (sector S13): net lending (+) or net borrowing (-) (ESA 2010 B9) in millions of euro, where a negative value is net borrowing, annual for the calendar year (`fiscal_year`) from `gov_10dd_edpt1` and quarterly, not seasonally adjusted, from `gov_10q_ggnfa`. Borrowing is a flow, so observations carry `period_start`. Norway series come from Statistics Norway (SSB) for the national-accounts general-government sector: net lending (+) or net borrowing (-) in millions of Norwegian kroner at current prices, annual for the calendar year (table 14668) and quarterly, not seasonally adjusted (table 14667); a negative value is net borrowing. Canada series come from Statistics Canada: general-governments net lending (+) or net borrowing (-) in millions of Canadian dollars at current prices for the calendar quarter, unadjusted (table 36-10-0477-01); a negative value is net borrowing. Switzerland series come from the Swiss Federal Finance Administration: net lending (+) or net borrowing (-) in the GFS model in millions of Swiss francs for the calendar year (variable `saldo`); a negative value is net borrowing. Iceland reports annual financial balance (surplus positive, deficit negative) from Statistics Iceland THJ05121, in millions of ISK at current prices, at full PX decimal precision. ABS general-government gross L2 debt is valued at current market value using the ABS creditor approach, not at nominal or face value (methodology §§13.4–13.6 and 13.9: https://www.abs.gov.au/statistics/detailed-methodology-information/concepts-sources-methods/australian-system-government-finance-statistics-concepts-sources-and-methods/2015/13-treatment-selected-items/part-b-treatment-debt-australian-gfs). The ratio denominator is the sum of the four original, current-price GDP quarters for the matching July-to-June financial year. Iceland data: Source: Statistics Iceland, THJ05181 and THJ05121, CC BY 4.0 (https://www.statice.is/publications/open-data-access/). Modifications are not attributed to Statistics Iceland. U.S. Treasury Fiscal Service data is a U.S. federal government work, distributed by FRED, Federal Reserve Bank of St. Louis. United Kingdom data: Source: Office for National Statistics, Public Sector Finances. Contains public sector information licensed under the Open Government Licence v3.0: https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/. Euro-area and EU member-state data: Source: Eurostat, government finance statistics; reuse is authorised provided the source is acknowledged. Australian data: Source: Australian Bureau of Statistics, Government Finance Statistics, Annual and Australian National Accounts. ABS website material is licensed under Creative Commons Attribution 4.0 International, subject to the exclusions and third-party rights identified in the ABS copyright terms. Those terms require attribution to the ABS for material obtained from its website; do not imply ABS endorsement. The ABS Data API is Beta and may change or be unavailable. Singapore annual debt and GDP: Singapore Open Data Licence v1.0: https://data.gov.sg/open-data-licence. Commercial use and distribution permitted with source acknowledgement and licence link; no official endorsement. Sublicensing is limited to enabling application/website use; downstream sub-licensees receive no rights. Customers needing additional rights must obtain the original licence directly at data.gov.sg. Debt catalogue: https://data.gov.sg/datasets/d_d4f7c9d15692b3c08aa9bc8bc56c0a72/view. GDP catalogue: https://data.gov.sg/datasets/d_d0db56a7c201c9a1e42c846d4fe6da8f/view. Norway data: Source: Statistics Norway (SSB), www.ssb.no, licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/); changes were made (Bullion API calculates the debt-to-GDP ratios), and Statistics Norway does not endorse Bullion API. Canada data: Source: Statistics Canada, tables 36-10-0467-01, 38-10-0237-01 and 36-10-0477-01, reference date shown on each observation. Reproduced and distributed on an \"as is\" basis with the permission of Statistics Canada (Statistics Canada Open Licence, https://www.statcan.gc.ca/en/terms-conditions/open-licence). This does not constitute an endorsement by Statistics Canada of this product. Switzerland data: Source: Swiss Federal Finance Administration (EFV/FFA), \"Main aggregates and forecasts with FS- and GFS-Model\", https://opendata.swiss/en/dataset/hauptaggregate-und-prognosen-im-fs-und-gfs-modell, published as open government data under the opendata.swiss \"Open use\" terms (commercial use permitted, source recommended); provided without verification of the derived series, and not endorsed by the Federal Finance Administration. Qatar data: Source: Qatar Ministry of Finance, dataset MOF-OD-C0-00004 (public debt); Qatar National Planning Council, dataset NPC-OD-C0-01288 (gross domestic product). Both datasets identify CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/); changes were made because Bullion API calculates matched-year debt-to-GDP ratios. Qatar Open Data Portal metadata observed 2026-09-30 reports the generic data-trust-index.ready-for-publication=false flag; this is not a publisher certification, data withdrawal or deprecation. Japan data: Source: Economic and Social Research Institute, Cabinet Office, Government of Japan, General Government Gross Debt (https://www.esri.cao.go.jp/en/sna/sddsplus/tables/ggd.xlsx) and Quarterly Estimates of GDP (https://www.esri.cao.go.jp/en/sna/sokuhou/sokuhou_top.html). The Cabinet Office notice (https://www.cao.go.jp/en/notice-e.html) states that numerical data and simple tables are not protected by copyright and may be used freely; the website Terms of Use govern website content and do not apply to those data. Source attribution and disclosure of the Bullion API debt-to-GDP calculation are Bullion API policy, not conditions imposed on those numerical data. This is not a claim of rights to separate third-party copyrighted material. The Cabinet Office does not endorse this product. A derived series is attributed as a Bullion API calculation naming every input source, never an input source alone; for a derived series `source.id` is the collecting or deriving source, not the sole provenance, so read `source.attribution` and `derivation` for every input. Forecasts, projections, and editorial classifications are never returned. Every plan can call this endpoint; API requests read the database and never call upstream sources.","operationId":"getGovernmentBorrowing","parameters":[{"$ref":"#/components/parameters/CountryPath"},{"$ref":"#/components/parameters/SeriesStart"},{"$ref":"#/components/parameters/SeriesEnd"}],"responses":{"200":{"description":"Government borrowing series with provenance.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GovernmentBorrowingResponse"}}}},"400":{"description":"The country code is invalid (invalid_country), end was sent without start (missing_params), a date is malformed (invalid_date), or start is after end (invalid_range).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_country","message":"The country code is invalid."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"The country is not covered (only US, GB, IS, EA, 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, and CH are), or no observation exists for the request.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["macro"],"summary":"Not supported — read-only API","operationId":"postGovernmentBorrowingNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/government-borrowing":{"get":{"tags":["macro"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Latest government borrowing for every covered country","description":"Returns the latest observation of each government borrowing series for every covered country, in the order `US`, `GB`, `IS`, `EA`, `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`, then `CH`, as one quota-counted request. Each series declares its government `scope`, accounting `basis`, `unit`, `frequency`, `period_type`, `method`, and a plain-language `definition` including its sign convention; unlike measures are not normalised into a common definition, so compare series only when their scope and basis match. Values are decimal strings and `date` is the period end. `status` is included when a publisher provides actual, provisional or revised status. Each series includes `coverage.earliest` and `coverage.latest`: the earliest and latest usable stored observation period ends, independent of the requested range. Coverage does not imply that every intervening period is available. Sign conventions differ by source and are stated in each `definition`. United States series come from the Monthly Treasury Statement as distributed by FRED (MTSDS133FMS): the federal budget surplus (+) or deficit (-) for the calendar month, and fiscal year to date from 1 October as a Bullion API `derived_cumulative` sum of the monthly values, in millions of U.S. dollars with central-government scope; a negative value is a deficit. This product uses the FRED® API but is not endorsed or certified by the Federal Reserve Bank of St. Louis. United Kingdom series come from the Office for National Statistics Public sector finances time series (dataset PUSF), not seasonally adjusted: monthly public sector net borrowing excluding public sector banks (DZLS, millions of pounds), where a positive value is borrowing and a negative value a surplus, and fiscal-year-to-date net borrowing from 1 April as a Bullion API `derived_cumulative` sum of DZLS (not an ONS-published series). Euro-area series come from Eurostat for the Eurostat EA21 aggregate (the fixed composition of the 21 member states in the euro area from 2026, back-calculated for earlier periods) and general-government scope (sector S13): net lending (+) or net borrowing (-) (ESA 2010 B9) in millions of euro, where a negative value is net borrowing, annual for the calendar year (`fiscal_year`) from `gov_10dd_edpt1` and quarterly, not seasonally adjusted, from `gov_10q_ggnfa`. Borrowing is a flow, so observations carry `period_start`. Norway series come from Statistics Norway (SSB) for the national-accounts general-government sector: net lending (+) or net borrowing (-) in millions of Norwegian kroner at current prices, annual for the calendar year (table 14668) and quarterly, not seasonally adjusted (table 14667); a negative value is net borrowing. Canada series come from Statistics Canada: general-governments net lending (+) or net borrowing (-) in millions of Canadian dollars at current prices for the calendar quarter, unadjusted (table 36-10-0477-01); a negative value is net borrowing. Switzerland series come from the Swiss Federal Finance Administration: net lending (+) or net borrowing (-) in the GFS model in millions of Swiss francs for the calendar year (variable `saldo`); a negative value is net borrowing. Iceland reports annual financial balance (surplus positive, deficit negative) from Statistics Iceland THJ05121, in millions of ISK at current prices, at full PX decimal precision. ABS general-government gross L2 debt is valued at current market value using the ABS creditor approach, not at nominal or face value (methodology §§13.4–13.6 and 13.9: https://www.abs.gov.au/statistics/detailed-methodology-information/concepts-sources-methods/australian-system-government-finance-statistics-concepts-sources-and-methods/2015/13-treatment-selected-items/part-b-treatment-debt-australian-gfs). The ratio denominator is the sum of the four original, current-price GDP quarters for the matching July-to-June financial year. Iceland data: Source: Statistics Iceland, THJ05181 and THJ05121, CC BY 4.0 (https://www.statice.is/publications/open-data-access/). Modifications are not attributed to Statistics Iceland. U.S. Treasury Fiscal Service data is a U.S. federal government work, distributed by FRED, Federal Reserve Bank of St. Louis. United Kingdom data: Source: Office for National Statistics, Public Sector Finances. Contains public sector information licensed under the Open Government Licence v3.0: https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/. Euro-area and EU member-state data: Source: Eurostat, government finance statistics; reuse is authorised provided the source is acknowledged. Australian data: Source: Australian Bureau of Statistics, Government Finance Statistics, Annual and Australian National Accounts. ABS website material is licensed under Creative Commons Attribution 4.0 International, subject to the exclusions and third-party rights identified in the ABS copyright terms. Those terms require attribution to the ABS for material obtained from its website; do not imply ABS endorsement. The ABS Data API is Beta and may change or be unavailable. Singapore annual debt and GDP: Singapore Open Data Licence v1.0: https://data.gov.sg/open-data-licence. Commercial use and distribution permitted with source acknowledgement and licence link; no official endorsement. Sublicensing is limited to enabling application/website use; downstream sub-licensees receive no rights. Customers needing additional rights must obtain the original licence directly at data.gov.sg. Debt catalogue: https://data.gov.sg/datasets/d_d4f7c9d15692b3c08aa9bc8bc56c0a72/view. GDP catalogue: https://data.gov.sg/datasets/d_d0db56a7c201c9a1e42c846d4fe6da8f/view. Norway data: Source: Statistics Norway (SSB), www.ssb.no, licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/); changes were made (Bullion API calculates the debt-to-GDP ratios), and Statistics Norway does not endorse Bullion API. Canada data: Source: Statistics Canada, tables 36-10-0467-01, 38-10-0237-01 and 36-10-0477-01, reference date shown on each observation. Reproduced and distributed on an \"as is\" basis with the permission of Statistics Canada (Statistics Canada Open Licence, https://www.statcan.gc.ca/en/terms-conditions/open-licence). This does not constitute an endorsement by Statistics Canada of this product. Switzerland data: Source: Swiss Federal Finance Administration (EFV/FFA), \"Main aggregates and forecasts with FS- and GFS-Model\", https://opendata.swiss/en/dataset/hauptaggregate-und-prognosen-im-fs-und-gfs-modell, published as open government data under the opendata.swiss \"Open use\" terms (commercial use permitted, source recommended); provided without verification of the derived series, and not endorsed by the Federal Finance Administration. Qatar data: Source: Qatar Ministry of Finance, dataset MOF-OD-C0-00004 (public debt); Qatar National Planning Council, dataset NPC-OD-C0-01288 (gross domestic product). Both datasets identify CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/); changes were made because Bullion API calculates matched-year debt-to-GDP ratios. Qatar Open Data Portal metadata observed 2026-09-30 reports the generic data-trust-index.ready-for-publication=false flag; this is not a publisher certification, data withdrawal or deprecation. Japan data: Source: Economic and Social Research Institute, Cabinet Office, Government of Japan, General Government Gross Debt (https://www.esri.cao.go.jp/en/sna/sddsplus/tables/ggd.xlsx) and Quarterly Estimates of GDP (https://www.esri.cao.go.jp/en/sna/sokuhou/sokuhou_top.html). The Cabinet Office notice (https://www.cao.go.jp/en/notice-e.html) states that numerical data and simple tables are not protected by copyright and may be used freely; the website Terms of Use govern website content and do not apply to those data. Source attribution and disclosure of the Bullion API debt-to-GDP calculation are Bullion API policy, not conditions imposed on those numerical data. This is not a claim of rights to separate third-party copyrighted material. The Cabinet Office does not endorse this product. A derived series is attributed as a Bullion API calculation naming every input source, never an input source alone; for a derived series `source.id` is the collecting or deriving source, not the sole provenance, so read `source.attribution` and `derivation` for every input. Forecasts, projections, and editorial classifications are never returned. Every plan can call this endpoint; API requests read the database and never call upstream sources.","operationId":"listGovernmentBorrowing","responses":{"200":{"description":"Latest government borrowing series per country with provenance.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GovernmentBorrowingCollectionResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"No covered country has a stored observation.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["macro"],"summary":"Not supported — read-only API","operationId":"postGovernmentBorrowingCollectionNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/debt-interest/{country}":{"get":{"tags":["macro"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Government debt interest series for one country","description":"Returns the stored government debt interest series for one country: `GB` (alias `uk`), `IS`, `EA` (alias `eu`, the euro-area aggregate), `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`, or `CA`. Any other valid country code returns 404 `no_data`. Without `start` and `end` each series carries its latest observation; with a range it carries every observation whose period end falls inside it, in chronological order. Ranges may span at most 10 calendar years; a longer range returns 400 `invalid_range`. When `end` is omitted it defaults to today, with the same cap. Each series declares its government `scope`, accounting `basis`, `unit`, `frequency`, `period_type`, `method`, and a plain-language `definition` including its sign convention; unlike measures are not normalised into a common definition, so compare series only when their scope and basis match. Values are decimal strings and `date` is the period end. `status` is included when a publisher provides actual, provisional or revised status. Each series includes `coverage.earliest` and `coverage.latest`: the earliest and latest usable stored observation period ends, independent of the requested range. Coverage does not imply that every intervening period is available. United States debt interest is not currently available, so `US` returns 404 `no_data` and is omitted from the collection. United Kingdom series come from the Office for National Statistics Public sector finances time series (dataset PUSF), not seasonally adjusted: central government debt interest payable for the calendar month (NMFX, millions of pounds, central-government scope), including the capital uplift on index-linked gilts. Euro-area series come from Eurostat for the Eurostat EA21 aggregate (the fixed composition of the 21 member states in the euro area from 2026, back-calculated for earlier periods) and general-government scope (sector S13): interest expenditure (ESA 2010 D.41 payable, accrual basis) in millions of euro, annual for the calendar year (`fiscal_year`) from `gov_10dd_edpt1` and quarterly, not seasonally adjusted, from `gov_10q_ggnfa`. Norway series come from Statistics Norway (SSB): general-government interest expense (national accounts item B41) in millions of Norwegian kroner at current prices, annual for the calendar year only (table 14668), because Statistics Norway publishes no quarterly interest item. Canada series come from Statistics Canada: general-governments interest on debt in millions of Canadian dollars at current prices for the calendar quarter, unadjusted, quarterly only (table 36-10-0477-01). Interest is reported as a positive amount. Interest is a flow, so observations carry `period_start`. Switzerland has no debt interest series (the Swiss Federal Finance Administration publishes general-government interest expense only in a very large detailed file), so `CH` is omitted from this endpoint. Iceland reports annual general-government interest payments from Statistics Iceland THJ05121, in millions of ISK at current prices, at full PX decimal precision. ABS general-government gross L2 debt is valued at current market value using the ABS creditor approach, not at nominal or face value (methodology §§13.4–13.6 and 13.9: https://www.abs.gov.au/statistics/detailed-methodology-information/concepts-sources-methods/australian-system-government-finance-statistics-concepts-sources-and-methods/2015/13-treatment-selected-items/part-b-treatment-debt-australian-gfs). The ratio denominator is the sum of the four original, current-price GDP quarters for the matching July-to-June financial year. Iceland data: Source: Statistics Iceland, THJ05181 and THJ05121, CC BY 4.0 (https://www.statice.is/publications/open-data-access/). Modifications are not attributed to Statistics Iceland. U.S. Treasury Fiscal Service data is a U.S. federal government work, distributed by FRED, Federal Reserve Bank of St. Louis. United Kingdom data: Source: Office for National Statistics, Public Sector Finances. Contains public sector information licensed under the Open Government Licence v3.0: https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/. Euro-area and EU member-state data: Source: Eurostat, government finance statistics; reuse is authorised provided the source is acknowledged. Australian data: Source: Australian Bureau of Statistics, Government Finance Statistics, Annual and Australian National Accounts. ABS website material is licensed under Creative Commons Attribution 4.0 International, subject to the exclusions and third-party rights identified in the ABS copyright terms. Those terms require attribution to the ABS for material obtained from its website; do not imply ABS endorsement. The ABS Data API is Beta and may change or be unavailable. Singapore annual debt and GDP: Singapore Open Data Licence v1.0: https://data.gov.sg/open-data-licence. Commercial use and distribution permitted with source acknowledgement and licence link; no official endorsement. Sublicensing is limited to enabling application/website use; downstream sub-licensees receive no rights. Customers needing additional rights must obtain the original licence directly at data.gov.sg. Debt catalogue: https://data.gov.sg/datasets/d_d4f7c9d15692b3c08aa9bc8bc56c0a72/view. GDP catalogue: https://data.gov.sg/datasets/d_d0db56a7c201c9a1e42c846d4fe6da8f/view. Norway data: Source: Statistics Norway (SSB), www.ssb.no, licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/); changes were made (Bullion API calculates the debt-to-GDP ratios), and Statistics Norway does not endorse Bullion API. Canada data: Source: Statistics Canada, tables 36-10-0467-01, 38-10-0237-01 and 36-10-0477-01, reference date shown on each observation. Reproduced and distributed on an \"as is\" basis with the permission of Statistics Canada (Statistics Canada Open Licence, https://www.statcan.gc.ca/en/terms-conditions/open-licence). This does not constitute an endorsement by Statistics Canada of this product. Switzerland data: Source: Swiss Federal Finance Administration (EFV/FFA), \"Main aggregates and forecasts with FS- and GFS-Model\", https://opendata.swiss/en/dataset/hauptaggregate-und-prognosen-im-fs-und-gfs-modell, published as open government data under the opendata.swiss \"Open use\" terms (commercial use permitted, source recommended); provided without verification of the derived series, and not endorsed by the Federal Finance Administration. Qatar data: Source: Qatar Ministry of Finance, dataset MOF-OD-C0-00004 (public debt); Qatar National Planning Council, dataset NPC-OD-C0-01288 (gross domestic product). Both datasets identify CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/); changes were made because Bullion API calculates matched-year debt-to-GDP ratios. Qatar Open Data Portal metadata observed 2026-09-30 reports the generic data-trust-index.ready-for-publication=false flag; this is not a publisher certification, data withdrawal or deprecation. Japan data: Source: Economic and Social Research Institute, Cabinet Office, Government of Japan, General Government Gross Debt (https://www.esri.cao.go.jp/en/sna/sddsplus/tables/ggd.xlsx) and Quarterly Estimates of GDP (https://www.esri.cao.go.jp/en/sna/sokuhou/sokuhou_top.html). The Cabinet Office notice (https://www.cao.go.jp/en/notice-e.html) states that numerical data and simple tables are not protected by copyright and may be used freely; the website Terms of Use govern website content and do not apply to those data. Source attribution and disclosure of the Bullion API debt-to-GDP calculation are Bullion API policy, not conditions imposed on those numerical data. This is not a claim of rights to separate third-party copyrighted material. The Cabinet Office does not endorse this product. A derived series is attributed as a Bullion API calculation naming every input source, never an input source alone; for a derived series `source.id` is the collecting or deriving source, not the sole provenance, so read `source.attribution` and `derivation` for every input. Forecasts, projections, and editorial classifications are never returned. Every plan can call this endpoint; API requests read the database and never call upstream sources.","operationId":"getDebtInterest","parameters":[{"$ref":"#/components/parameters/CountryPath"},{"$ref":"#/components/parameters/SeriesStart"},{"$ref":"#/components/parameters/SeriesEnd"}],"responses":{"200":{"description":"Government debt interest series with provenance.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DebtInterestResponse"}}}},"400":{"description":"The country code is invalid (invalid_country), end was sent without start (missing_params), a date is malformed (invalid_date), or start is after end (invalid_range).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_country","message":"The country code is invalid."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"The country is not covered (only GB, IS, EA, 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, and CA are), or no observation exists for the request.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["macro"],"summary":"Not supported — read-only API","operationId":"postDebtInterestNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/debt-interest":{"get":{"tags":["macro"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Latest government debt interest for every covered country","description":"Returns the latest observation of each government debt interest series for every covered country, in the order `GB`, `IS`, `EA`, `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`, then `CA`, as one quota-counted request. Each series declares its government `scope`, accounting `basis`, `unit`, `frequency`, `period_type`, `method`, and a plain-language `definition` including its sign convention; unlike measures are not normalised into a common definition, so compare series only when their scope and basis match. Values are decimal strings and `date` is the period end. `status` is included when a publisher provides actual, provisional or revised status. Each series includes `coverage.earliest` and `coverage.latest`: the earliest and latest usable stored observation period ends, independent of the requested range. Coverage does not imply that every intervening period is available. United States debt interest is not currently available, so `US` returns 404 `no_data` and is omitted from the collection. United Kingdom series come from the Office for National Statistics Public sector finances time series (dataset PUSF), not seasonally adjusted: central government debt interest payable for the calendar month (NMFX, millions of pounds, central-government scope), including the capital uplift on index-linked gilts. Euro-area series come from Eurostat for the Eurostat EA21 aggregate (the fixed composition of the 21 member states in the euro area from 2026, back-calculated for earlier periods) and general-government scope (sector S13): interest expenditure (ESA 2010 D.41 payable, accrual basis) in millions of euro, annual for the calendar year (`fiscal_year`) from `gov_10dd_edpt1` and quarterly, not seasonally adjusted, from `gov_10q_ggnfa`. Norway series come from Statistics Norway (SSB): general-government interest expense (national accounts item B41) in millions of Norwegian kroner at current prices, annual for the calendar year only (table 14668), because Statistics Norway publishes no quarterly interest item. Canada series come from Statistics Canada: general-governments interest on debt in millions of Canadian dollars at current prices for the calendar quarter, unadjusted, quarterly only (table 36-10-0477-01). Interest is reported as a positive amount. Interest is a flow, so observations carry `period_start`. Switzerland has no debt interest series (the Swiss Federal Finance Administration publishes general-government interest expense only in a very large detailed file), so `CH` is omitted from this endpoint. Iceland reports annual general-government interest payments from Statistics Iceland THJ05121, in millions of ISK at current prices, at full PX decimal precision. ABS general-government gross L2 debt is valued at current market value using the ABS creditor approach, not at nominal or face value (methodology §§13.4–13.6 and 13.9: https://www.abs.gov.au/statistics/detailed-methodology-information/concepts-sources-methods/australian-system-government-finance-statistics-concepts-sources-and-methods/2015/13-treatment-selected-items/part-b-treatment-debt-australian-gfs). The ratio denominator is the sum of the four original, current-price GDP quarters for the matching July-to-June financial year. Iceland data: Source: Statistics Iceland, THJ05181 and THJ05121, CC BY 4.0 (https://www.statice.is/publications/open-data-access/). Modifications are not attributed to Statistics Iceland. U.S. Treasury Fiscal Service data is a U.S. federal government work, distributed by FRED, Federal Reserve Bank of St. Louis. United Kingdom data: Source: Office for National Statistics, Public Sector Finances. Contains public sector information licensed under the Open Government Licence v3.0: https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/. Euro-area and EU member-state data: Source: Eurostat, government finance statistics; reuse is authorised provided the source is acknowledged. Australian data: Source: Australian Bureau of Statistics, Government Finance Statistics, Annual and Australian National Accounts. ABS website material is licensed under Creative Commons Attribution 4.0 International, subject to the exclusions and third-party rights identified in the ABS copyright terms. Those terms require attribution to the ABS for material obtained from its website; do not imply ABS endorsement. The ABS Data API is Beta and may change or be unavailable. Singapore annual debt and GDP: Singapore Open Data Licence v1.0: https://data.gov.sg/open-data-licence. Commercial use and distribution permitted with source acknowledgement and licence link; no official endorsement. Sublicensing is limited to enabling application/website use; downstream sub-licensees receive no rights. Customers needing additional rights must obtain the original licence directly at data.gov.sg. Debt catalogue: https://data.gov.sg/datasets/d_d4f7c9d15692b3c08aa9bc8bc56c0a72/view. GDP catalogue: https://data.gov.sg/datasets/d_d0db56a7c201c9a1e42c846d4fe6da8f/view. Norway data: Source: Statistics Norway (SSB), www.ssb.no, licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/); changes were made (Bullion API calculates the debt-to-GDP ratios), and Statistics Norway does not endorse Bullion API. Canada data: Source: Statistics Canada, tables 36-10-0467-01, 38-10-0237-01 and 36-10-0477-01, reference date shown on each observation. Reproduced and distributed on an \"as is\" basis with the permission of Statistics Canada (Statistics Canada Open Licence, https://www.statcan.gc.ca/en/terms-conditions/open-licence). This does not constitute an endorsement by Statistics Canada of this product. Switzerland data: Source: Swiss Federal Finance Administration (EFV/FFA), \"Main aggregates and forecasts with FS- and GFS-Model\", https://opendata.swiss/en/dataset/hauptaggregate-und-prognosen-im-fs-und-gfs-modell, published as open government data under the opendata.swiss \"Open use\" terms (commercial use permitted, source recommended); provided without verification of the derived series, and not endorsed by the Federal Finance Administration. Qatar data: Source: Qatar Ministry of Finance, dataset MOF-OD-C0-00004 (public debt); Qatar National Planning Council, dataset NPC-OD-C0-01288 (gross domestic product). Both datasets identify CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/); changes were made because Bullion API calculates matched-year debt-to-GDP ratios. Qatar Open Data Portal metadata observed 2026-09-30 reports the generic data-trust-index.ready-for-publication=false flag; this is not a publisher certification, data withdrawal or deprecation. Japan data: Source: Economic and Social Research Institute, Cabinet Office, Government of Japan, General Government Gross Debt (https://www.esri.cao.go.jp/en/sna/sddsplus/tables/ggd.xlsx) and Quarterly Estimates of GDP (https://www.esri.cao.go.jp/en/sna/sokuhou/sokuhou_top.html). The Cabinet Office notice (https://www.cao.go.jp/en/notice-e.html) states that numerical data and simple tables are not protected by copyright and may be used freely; the website Terms of Use govern website content and do not apply to those data. Source attribution and disclosure of the Bullion API debt-to-GDP calculation are Bullion API policy, not conditions imposed on those numerical data. This is not a claim of rights to separate third-party copyrighted material. The Cabinet Office does not endorse this product. A derived series is attributed as a Bullion API calculation naming every input source, never an input source alone; for a derived series `source.id` is the collecting or deriving source, not the sole provenance, so read `source.attribution` and `derivation` for every input. Forecasts, projections, and editorial classifications are never returned. Every plan can call this endpoint; API requests read the database and never call upstream sources.","operationId":"listDebtInterest","responses":{"200":{"description":"Latest government debt interest series per country with provenance.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DebtInterestCollectionResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"No covered country has a stored observation.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["macro"],"summary":"Not supported — read-only API","operationId":"postDebtInterestCollectionNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/gold/mine-production":{"get":{"tags":["market-indicators"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Gold mine production (USGS, annual)","description":"Returns gold world and United States mine production: `world-mine-production` (World gold mine production), `us-mine-production` (United States gold mine production). Without `start` and `end` each series carries its latest year; with a range it carries every year whose 31 December period end falls inside it, in chronological order. Annual U.S. Geological Survey statistics in metric tonnes of metal content, read from Bullion API storage; requests never call USGS. Each series carries its `geography` (`world` or `US`), `category`, plain-language `definition`, `collected_at` (the last successful collection) and `freshness` (`stale` when collection is overdue; the last good data is still served). Years USGS publishes as not available are omitted, never returned as zero. These are partial market indicators, not a complete supply-and-demand balance: the only global figure is mine production, and recycling, consumption and trade are United States figures. When USGS identifies an observation as an estimate, it carries an `estimated` boolean. U.S. Geological Survey data are in the U.S. public domain. Credit: U.S. Geological Survey. The USGS does not endorse this product. These are partial market indicators, not a complete supply-and-demand balance: world figures cover mine production only, and recycling, consumption and trade figures are for the United States.","operationId":"getGoldMineProduction","parameters":[{"$ref":"#/components/parameters/SeriesStart"},{"$ref":"#/components/parameters/SeriesEnd"}],"responses":{"200":{"description":"Gold mine production series with provenance.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIndicatorsResponse"}}}},"400":{"description":"end was sent without start (missing_params), a date is malformed (invalid_date), or start is after end (invalid_range).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_range","message":"The requested range is invalid."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"No stored observation exists for the request.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["market-indicators"],"summary":"Not supported — read-only API","operationId":"postGoldMineProductionNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/gold/recycling":{"get":{"tags":["market-indicators"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Gold recycling (USGS, annual)","description":"Returns gold United States secondary (recycled) production: `us-secondary-production` (United States gold secondary production). Without `start` and `end` each series carries its latest year; with a range it carries every year whose 31 December period end falls inside it, in chronological order. Annual U.S. Geological Survey statistics in metric tonnes of metal content, read from Bullion API storage; requests never call USGS. Each series carries its `geography` (`world` or `US`), `category`, plain-language `definition`, `collected_at` (the last successful collection) and `freshness` (`stale` when collection is overdue; the last good data is still served). Years USGS publishes as not available are omitted, never returned as zero. These are partial market indicators, not a complete supply-and-demand balance: the only global figure is mine production, and recycling, consumption and trade are United States figures. When USGS identifies an observation as an estimate, it carries an `estimated` boolean. U.S. Geological Survey data are in the U.S. public domain. Credit: U.S. Geological Survey. The USGS does not endorse this product. These are partial market indicators, not a complete supply-and-demand balance: world figures cover mine production only, and recycling, consumption and trade figures are for the United States.","operationId":"getGoldRecycling","parameters":[{"$ref":"#/components/parameters/SeriesStart"},{"$ref":"#/components/parameters/SeriesEnd"}],"responses":{"200":{"description":"Gold recycling series with provenance.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIndicatorsResponse"}}}},"400":{"description":"end was sent without start (missing_params), a date is malformed (invalid_date), or start is after end (invalid_range).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_range","message":"The requested range is invalid."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"No stored observation exists for the request.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["market-indicators"],"summary":"Not supported — read-only API","operationId":"postGoldRecyclingNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/gold/trade":{"get":{"tags":["market-indicators"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Gold trade (USGS, annual)","description":"Returns gold United States imports and exports: `us-imports` (United States gold imports), `us-exports` (United States gold exports). Without `start` and `end` each series carries its latest year; with a range it carries every year whose 31 December period end falls inside it, in chronological order. Annual U.S. Geological Survey statistics in metric tonnes of metal content, read from Bullion API storage; requests never call USGS. Each series carries its `geography` (`world` or `US`), `category`, plain-language `definition`, `collected_at` (the last successful collection) and `freshness` (`stale` when collection is overdue; the last good data is still served). Years USGS publishes as not available are omitted, never returned as zero. These are partial market indicators, not a complete supply-and-demand balance: the only global figure is mine production, and recycling, consumption and trade are United States figures. When USGS identifies an observation as an estimate, it carries an `estimated` boolean. U.S. Geological Survey data are in the U.S. public domain. Credit: U.S. Geological Survey. The USGS does not endorse this product. These are partial market indicators, not a complete supply-and-demand balance: world figures cover mine production only, and recycling, consumption and trade figures are for the United States.","operationId":"getGoldTrade","parameters":[{"$ref":"#/components/parameters/SeriesStart"},{"$ref":"#/components/parameters/SeriesEnd"}],"responses":{"200":{"description":"Gold trade series with provenance.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIndicatorsResponse"}}}},"400":{"description":"end was sent without start (missing_params), a date is malformed (invalid_date), or start is after end (invalid_range).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_range","message":"The requested range is invalid."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"No stored observation exists for the request.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["market-indicators"],"summary":"Not supported — read-only API","operationId":"postGoldTradeNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/silver/mine-production":{"get":{"tags":["market-indicators"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Silver mine production (USGS, annual)","description":"Returns silver world and United States mine production: `world-mine-production` (World silver mine production), `us-mine-production` (United States silver mine production). Without `start` and `end` each series carries its latest year; with a range it carries every year whose 31 December period end falls inside it, in chronological order. Annual U.S. Geological Survey statistics in metric tonnes of metal content, read from Bullion API storage; requests never call USGS. Each series carries its `geography` (`world` or `US`), `category`, plain-language `definition`, `collected_at` (the last successful collection) and `freshness` (`stale` when collection is overdue; the last good data is still served). Years USGS publishes as not available are omitted, never returned as zero. These are partial market indicators, not a complete supply-and-demand balance: the only global figure is mine production, and recycling, consumption and trade are United States figures. When USGS identifies an observation as an estimate, it carries an `estimated` boolean. U.S. Geological Survey data are in the U.S. public domain. Credit: U.S. Geological Survey. The USGS does not endorse this product. These are partial market indicators, not a complete supply-and-demand balance: world figures cover mine production only, and recycling, consumption and trade figures are for the United States.","operationId":"getSilverMineProduction","parameters":[{"$ref":"#/components/parameters/SeriesStart"},{"$ref":"#/components/parameters/SeriesEnd"}],"responses":{"200":{"description":"Silver mine production series with provenance.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIndicatorsResponse"}}}},"400":{"description":"end was sent without start (missing_params), a date is malformed (invalid_date), or start is after end (invalid_range).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_range","message":"The requested range is invalid."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"No stored observation exists for the request.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["market-indicators"],"summary":"Not supported — read-only API","operationId":"postSilverMineProductionNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/silver/recycling":{"get":{"tags":["market-indicators"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Silver recycling (USGS, annual)","description":"Returns silver United States secondary (recycled) production: `us-secondary-production` (United States silver secondary production). Without `start` and `end` each series carries its latest year; with a range it carries every year whose 31 December period end falls inside it, in chronological order. Annual U.S. Geological Survey statistics in metric tonnes of metal content, read from Bullion API storage; requests never call USGS. Each series carries its `geography` (`world` or `US`), `category`, plain-language `definition`, `collected_at` (the last successful collection) and `freshness` (`stale` when collection is overdue; the last good data is still served). Years USGS publishes as not available are omitted, never returned as zero. These are partial market indicators, not a complete supply-and-demand balance: the only global figure is mine production, and recycling, consumption and trade are United States figures. When USGS identifies an observation as an estimate, it carries an `estimated` boolean. U.S. Geological Survey data are in the U.S. public domain. Credit: U.S. Geological Survey. The USGS does not endorse this product. These are partial market indicators, not a complete supply-and-demand balance: world figures cover mine production only, and recycling, consumption and trade figures are for the United States.","operationId":"getSilverRecycling","parameters":[{"$ref":"#/components/parameters/SeriesStart"},{"$ref":"#/components/parameters/SeriesEnd"}],"responses":{"200":{"description":"Silver recycling series with provenance.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIndicatorsResponse"}}}},"400":{"description":"end was sent without start (missing_params), a date is malformed (invalid_date), or start is after end (invalid_range).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_range","message":"The requested range is invalid."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"No stored observation exists for the request.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["market-indicators"],"summary":"Not supported — read-only API","operationId":"postSilverRecyclingNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/silver/consumption":{"get":{"tags":["market-indicators"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Silver consumption (USGS, annual)","description":"Returns silver United States apparent consumption: `us-apparent-consumption` (United States silver apparent consumption). Without `start` and `end` each series carries its latest year; with a range it carries every year whose 31 December period end falls inside it, in chronological order. Annual U.S. Geological Survey statistics in metric tonnes of metal content, read from Bullion API storage; requests never call USGS. Each series carries its `geography` (`world` or `US`), `category`, plain-language `definition`, `collected_at` (the last successful collection) and `freshness` (`stale` when collection is overdue; the last good data is still served). Years USGS publishes as not available are omitted, never returned as zero. These are partial market indicators, not a complete supply-and-demand balance: the only global figure is mine production, and recycling, consumption and trade are United States figures. When USGS identifies an observation as an estimate, it carries an `estimated` boolean. U.S. Geological Survey data are in the U.S. public domain. Credit: U.S. Geological Survey. The USGS does not endorse this product. These are partial market indicators, not a complete supply-and-demand balance: world figures cover mine production only, and recycling, consumption and trade figures are for the United States.","operationId":"getSilverConsumption","parameters":[{"$ref":"#/components/parameters/SeriesStart"},{"$ref":"#/components/parameters/SeriesEnd"}],"responses":{"200":{"description":"Silver consumption series with provenance.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIndicatorsResponse"}}}},"400":{"description":"end was sent without start (missing_params), a date is malformed (invalid_date), or start is after end (invalid_range).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_range","message":"The requested range is invalid."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"No stored observation exists for the request.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["market-indicators"],"summary":"Not supported — read-only API","operationId":"postSilverConsumptionNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/silver/trade":{"get":{"tags":["market-indicators"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Silver trade (USGS, annual)","description":"Returns silver United States imports and exports: `us-imports` (United States silver imports), `us-exports` (United States silver exports). Without `start` and `end` each series carries its latest year; with a range it carries every year whose 31 December period end falls inside it, in chronological order. Annual U.S. Geological Survey statistics in metric tonnes of metal content, read from Bullion API storage; requests never call USGS. Each series carries its `geography` (`world` or `US`), `category`, plain-language `definition`, `collected_at` (the last successful collection) and `freshness` (`stale` when collection is overdue; the last good data is still served). Years USGS publishes as not available are omitted, never returned as zero. These are partial market indicators, not a complete supply-and-demand balance: the only global figure is mine production, and recycling, consumption and trade are United States figures. When USGS identifies an observation as an estimate, it carries an `estimated` boolean. U.S. Geological Survey data are in the U.S. public domain. Credit: U.S. Geological Survey. The USGS does not endorse this product. These are partial market indicators, not a complete supply-and-demand balance: world figures cover mine production only, and recycling, consumption and trade figures are for the United States.","operationId":"getSilverTrade","parameters":[{"$ref":"#/components/parameters/SeriesStart"},{"$ref":"#/components/parameters/SeriesEnd"}],"responses":{"200":{"description":"Silver trade series with provenance.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIndicatorsResponse"}}}},"400":{"description":"end was sent without start (missing_params), a date is malformed (invalid_date), or start is after end (invalid_range).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_range","message":"The requested range is invalid."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"No stored observation exists for the request.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["market-indicators"],"summary":"Not supported — read-only API","operationId":"postSilverTradeNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/money-supply/{country}":{"get":{"tags":["macro"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Money supply series for one country","description":"Returns the latest money supply series when neither date is supplied. With `start` and `end`, returns matching observations in chronological order. Monthly and other period-end observations are selected when their period-end dates fall within the inclusive calendar date range. Weekly ISO reference-period observations are selected for every ISO week that overlaps the inclusive range: the week containing `start` through the week containing `end`. For those weekly `date` values, the canonical Sunday is an index only, not the stock measurement date. The maximum inclusive range is 30 years. Coverage is determined only by registered series definitions and stored observations; valid countries without a matching registered series return 404 `no_data`. Requests read the database and never call an upstream source. Each series preserves its source-specific identity and definition. A shared identity may span geographies only when its registered source series and full definition are identical; unlike national money aggregates are not normalized into one another. Values are decimal strings. Stocks declare whether they represent a period end or period average; each series also identifies frequency, unit scale, currency where applicable, seasonal adjustment, scope, and accounting/statistical basis. For series with dated methodology changes, top-level method and stock_semantics describe the latest period; each observation carries its period-resolved method and stock semantics, and methodology_history lists inclusive, gap-free effective periods. Source-unit metadata states the publisher scale and exact factor used to normalize to base-currency units. For reference-period weekly data, `date` is the canonical ISO-week Sunday index and not a claim about the stock observation day; the original source week is returned separately. Latest reads withhold a series rather than fall back when its newest observation fails registered source-identity, cadence, or captured UTC as-of validation, or its newest withdrawal is at least as recent as that observation. A published reference-week observation remains valid when its Sunday index is after the as-of date, provided its Monday start is not in the future.","operationId":"getMoneySupply","parameters":[{"$ref":"#/components/parameters/CountryPath"},{"$ref":"#/components/parameters/SeriesStart"},{"$ref":"#/components/parameters/SeriesEnd"}],"responses":{"200":{"description":"Money supply series with definitions and source attribution.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoneySupplyResponse"}}}},"400":{"description":"The country code is invalid (invalid_country), end was sent without start (missing_params), a date is malformed (invalid_date), or the inclusive date range exceeds the maximum span (invalid_range).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_range","message":"The requested range is invalid."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"The country has no stored observation matching a registered series.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["macro"],"summary":"Not supported — read-only API","operationId":"postMoneySupplyNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/money-supply":{"get":{"tags":["macro"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Latest money supply series for countries with data","description":"Returns the latest observation of each registered money supply series for every country with a stored observation, as one quota-counted request. Countries without data are omitted. This route always returns latest values; date parameters do not apply. Coverage is determined only by registered series definitions and stored observations; valid countries without a matching registered series return 404 `no_data`. Requests read the database and never call an upstream source. Each series preserves its source-specific identity and definition. A shared identity may span geographies only when its registered source series and full definition are identical; unlike national money aggregates are not normalized into one another. Values are decimal strings. Stocks declare whether they represent a period end or period average; each series also identifies frequency, unit scale, currency where applicable, seasonal adjustment, scope, and accounting/statistical basis. For series with dated methodology changes, top-level method and stock_semantics describe the latest period; each observation carries its period-resolved method and stock semantics, and methodology_history lists inclusive, gap-free effective periods. Source-unit metadata states the publisher scale and exact factor used to normalize to base-currency units. For reference-period weekly data, `date` is the canonical ISO-week Sunday index and not a claim about the stock observation day; the original source week is returned separately. Latest reads withhold a series rather than fall back when its newest observation fails registered source-identity, cadence, or captured UTC as-of validation, or its newest withdrawal is at least as recent as that observation. A published reference-week observation remains valid when its Sunday index is after the as-of date, provided its Monday start is not in the future.","operationId":"listMoneySupply","responses":{"200":{"description":"Latest money supply series by country.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoneySupplyCollectionResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"No registered country has a stored observation.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["macro"],"summary":"Not supported — read-only API","operationId":"postMoneySupplyCollectionNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/central-bank-balance-sheet/{country}":{"get":{"tags":["macro"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Central-bank balance sheet series for one country","description":"Returns the latest central-bank balance sheet series when neither date is supplied. With `start` and `end`, returns matching observations in chronological order. Monthly and other period-end observations are selected when their period-end dates fall within the inclusive calendar date range. Weekly ISO reference-period observations are selected for every ISO week that overlaps the inclusive range: the week containing `start` through the week containing `end`. For those weekly `date` values, the canonical Sunday is an index only, not the stock measurement date. The maximum inclusive range is 30 years. Coverage is determined only by registered series definitions and stored observations; valid countries without a matching registered series return 404 `no_data`. Requests read the database and never call an upstream source. Each series preserves its source-specific identity and definition. A shared identity may span geographies only when its registered source series and full definition are identical; unlike national money aggregates are not normalized into one another. Values are decimal strings. Stocks declare whether they represent a period end or period average; each series also identifies frequency, unit scale, currency where applicable, seasonal adjustment, scope, and accounting/statistical basis. For series with dated methodology changes, top-level method and stock_semantics describe the latest period; each observation carries its period-resolved method and stock semantics, and methodology_history lists inclusive, gap-free effective periods. Source-unit metadata states the publisher scale and exact factor used to normalize to base-currency units. For reference-period weekly data, `date` is the canonical ISO-week Sunday index and not a claim about the stock observation day; the original source week is returned separately. Latest reads withhold a series rather than fall back when its newest observation fails registered source-identity, cadence, or captured UTC as-of validation, or its newest withdrawal is at least as recent as that observation. A published reference-week observation remains valid when its Sunday index is after the as-of date, provided its Monday start is not in the future.","operationId":"getCentralBankBalanceSheet","parameters":[{"$ref":"#/components/parameters/CountryPath"},{"$ref":"#/components/parameters/SeriesStart"},{"$ref":"#/components/parameters/SeriesEnd"}],"responses":{"200":{"description":"Central-bank balance sheet series with definitions and source attribution.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CentralBankBalanceSheetResponse"}}}},"400":{"description":"The country code is invalid (invalid_country), end was sent without start (missing_params), a date is malformed (invalid_date), or the inclusive date range exceeds the maximum span (invalid_range).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_range","message":"The requested range is invalid."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"The country has no stored observation matching a registered series.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["macro"],"summary":"Not supported — read-only API","operationId":"postCentralBankBalanceSheetNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/central-bank-balance-sheet":{"get":{"tags":["macro"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Latest central-bank balance sheet series for countries with data","description":"Returns the latest observation of each registered central-bank balance sheet series for every country with a stored observation, as one quota-counted request. Countries without data are omitted. This route always returns latest values; date parameters do not apply. Coverage is determined only by registered series definitions and stored observations; valid countries without a matching registered series return 404 `no_data`. Requests read the database and never call an upstream source. Each series preserves its source-specific identity and definition. A shared identity may span geographies only when its registered source series and full definition are identical; unlike national money aggregates are not normalized into one another. Values are decimal strings. Stocks declare whether they represent a period end or period average; each series also identifies frequency, unit scale, currency where applicable, seasonal adjustment, scope, and accounting/statistical basis. For series with dated methodology changes, top-level method and stock_semantics describe the latest period; each observation carries its period-resolved method and stock semantics, and methodology_history lists inclusive, gap-free effective periods. Source-unit metadata states the publisher scale and exact factor used to normalize to base-currency units. For reference-period weekly data, `date` is the canonical ISO-week Sunday index and not a claim about the stock observation day; the original source week is returned separately. Latest reads withhold a series rather than fall back when its newest observation fails registered source-identity, cadence, or captured UTC as-of validation, or its newest withdrawal is at least as recent as that observation. A published reference-week observation remains valid when its Sunday index is after the as-of date, provided its Monday start is not in the future.","operationId":"listCentralBankBalanceSheet","responses":{"200":{"description":"Latest central-bank balance sheet series by country.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CentralBankBalanceSheetCollectionResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"No registered country has a stored observation.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["macro"],"summary":"Not supported — read-only API","operationId":"postCentralBankBalanceSheetCollectionNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/central-bank-reserves":{"get":{"tags":["reserves"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Latest annual central-bank reserve values for every country","description":"Cached annual reserve valuations. Series: total reserves including gold and excluding gold (reported, US dollars), and gold reserve value, gold share of total reserves and annual gold value change (derived by Bullion API from cached observations). Each observation date is the year end (YYYY-12-31) and each value is a decimal string. A derived series omits years whose source values are inconsistent (total below reserves excluding gold, or a negative component); the reported series flag those years in `quality_flags`, which explain such gaps. Without start and end each series returns its own latest observation, so dates can differ across series (for example a derived series skips an inconsistent latest year). Annual value change combines holdings changes, gold-price movement, and revisions; it does not measure tonnes bought or sold. Returns the latest observation of each series for every covered country, ordered by country code. Use `/v1/central-bank-reserves/{country}` for history.","operationId":"getCentralBankReserves","responses":{"200":{"description":"Latest annual reserve observations per country, served from the automated cache.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CentralBankReservesCollectionResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"The automated cache has no complete observations.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"data_unavailable","message":"The requested data is not available."}}}}}}},"post":{"tags":["reserves"],"summary":"Not supported — read-only API","operationId":"postCentralBankReservesNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/central-bank-reserves/{country}":{"get":{"tags":["reserves"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Annual central-bank reserve values and gold share for one country","description":"Cached annual reserve valuations. Series: total reserves including gold and excluding gold (reported, US dollars), and gold reserve value, gold share of total reserves and annual gold value change (derived by Bullion API from cached observations). Each observation date is the year end (YYYY-12-31) and each value is a decimal string. A derived series omits years whose source values are inconsistent (total below reserves excluding gold, or a negative component); the reported series flag those years in `quality_flags`, which explain such gaps. Without start and end each series returns its own latest observation, so dates can differ across series (for example a derived series skips an inconsistent latest year). Annual value change combines holdings changes, gold-price movement, and revisions; it does not measure tonnes bought or sold. Without start and end, returns the latest observation of each series; with a range, every annual observation whose year end falls inside it.","operationId":"getCentralBankReservesCountry","parameters":[{"$ref":"#/components/parameters/CountryPath"},{"$ref":"#/components/parameters/SeriesStart"},{"$ref":"#/components/parameters/SeriesEnd"}],"responses":{"200":{"description":"Annual reserve series for the country, served from the automated cache.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CentralBankReservesCountryResponse"}}}},"400":{"description":"Invalid country or date parameters. The request still consumes quota.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CentralBankBadRequestError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"The country has no reserve observations, or none in the requested range.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"The automated cache has no complete observations.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"data_unavailable","message":"The requested data is not available."}}}}}}},"post":{"tags":["reserves"],"summary":"Not supported — read-only API","operationId":"postCentralBankReservesCountryNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/countries":{"get":{"tags":["countries"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Countries and the datasets each one has","description":"Lists every country or aggregate with at least one per-country dataset, sorted by code. Each dataset names its metric and the path of that country on the metric endpoint. Coverage is derived from the registered series and the stored central-bank data, so a dataset is listed only where its endpoint can answer. `aliases` lists accepted lower-case path aliases.","operationId":"getCountries","responses":{"200":{"description":"Countries with at least one dataset.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountriesResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["countries"],"summary":"Not supported — read-only API","operationId":"postCountriesNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/countries/{country}":{"get":{"tags":["countries"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"The datasets one country has","description":"Returns one country with its datasets. An unknown code is rejected with `invalid_country`; a valid code without any dataset returns `no_data`.","operationId":"getCountry","parameters":[{"$ref":"#/components/parameters/CountryPath"}],"responses":{"200":{"description":"The country and its datasets.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountryResponse"}}}},"400":{"description":"The country code is not a known ISO 3166-1 alpha-2 code or aggregate.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidCountryError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"The country has no dataset.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["countries"],"summary":"Not supported — read-only API","operationId":"postCountryNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/central-bank-gold":{"get":{"tags":["central-bank-gold"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Latest reported central-bank gold holdings for every covered country","description":"Returns the latest observation of each reported central-bank gold series for every covered country, ordered by country code; sort client-side for leaderboards. Reported gold holdings are served from the scheduled database cache; API requests never call upstream providers. Each series represents one measure, cadence and reported or derived basis; weekly, fortnightly, monthly, quarterly and irregular observations are never combined. Values are decimal strings. Monthly, quarterly and irregular observations are dated at the end of their reference month; weekly and fortnightly observations retain their reference date. The million-fine-troy-ounce series preserves a reported weight; Bullion API converts that weight to tonnes using the fixed troy-ounce conversion factor. Tonnage and holdings changes are explicitly labelled as Bullion API calculations, and tonnes derived from a reported value and month-end gold price carry holdings_basis derived. Value-only series never receive an invented quantity, and a country can have a subset of measures; a missing observation is not a zero value. Use /v1/countries to discover current coverage. holdings_change_tonnes is a change between consecutive reported stocks of one series, not a purchase or sale transaction, and it is omitted where reported stocks are not directly comparable. Each series includes provenance and a reuse notice; valuation provenance describes the currency of the returned observations, including retained historical currency series. Source-data reuse rights remain separate from API plan terms. Anything Bullion API derives is stated in the series label and holdings_basis, for example \"Gold holdings derived by Bullion API from reported value (tonnes)\". Stale observations remain visible and are marked.","operationId":"getCentralBankGoldCollection","responses":{"200":{"description":"The latest observation of each series for every covered country.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CentralBankGoldCollectionResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"No reported central-bank gold holdings are cached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["central-bank-gold"],"summary":"Not supported — read-only API","operationId":"postCentralBankGoldNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/central-bank-gold/{country}":{"get":{"tags":["central-bank-gold"],"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Reported central-bank gold holdings for one country","description":"Returns one country’s reported central-bank gold series. Without start and end each series carries its latest observation; with a range it carries every observation whose date falls inside it, oldest first. The maximum range is 10 years. Reported gold holdings are served from the scheduled database cache; API requests never call upstream providers. Each series represents one measure, cadence and reported or derived basis; weekly, fortnightly, monthly, quarterly and irregular observations are never combined. Values are decimal strings. Monthly, quarterly and irregular observations are dated at the end of their reference month; weekly and fortnightly observations retain their reference date. The million-fine-troy-ounce series preserves a reported weight; Bullion API converts that weight to tonnes using the fixed troy-ounce conversion factor. Tonnage and holdings changes are explicitly labelled as Bullion API calculations, and tonnes derived from a reported value and month-end gold price carry holdings_basis derived. Value-only series never receive an invented quantity, and a country can have a subset of measures; a missing observation is not a zero value. Use /v1/countries to discover current coverage. holdings_change_tonnes is a change between consecutive reported stocks of one series, not a purchase or sale transaction, and it is omitted where reported stocks are not directly comparable. Each series includes provenance and a reuse notice; valuation provenance describes the currency of the returned observations, including retained historical currency series. Source-data reuse rights remain separate from API plan terms. Anything Bullion API derives is stated in the series label and holdings_basis, for example \"Gold holdings derived by Bullion API from reported value (tonnes)\". Stale observations remain visible and are marked.","operationId":"getCentralBankGold","parameters":[{"$ref":"#/components/parameters/CountryPath"},{"$ref":"#/components/parameters/SeriesStart"},{"$ref":"#/components/parameters/SeriesEnd"}],"responses":{"200":{"description":"Reported central-bank gold series for the country.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CentralBankGoldCountryResponse"}}}},"400":{"description":"Invalid country, date, or range. The request still consumes quota.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CentralBankGoldBadRequestError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/EmailNotVerified"},"404":{"description":"The country has no reported holdings, or none in the requested range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDataError"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["central-bank-gold"],"summary":"Not supported — read-only API","operationId":"postCentralBankGoldCountryNotAllowed","responses":{"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/v1/portfolio":{"get":{"tags":["portfolio"],"security":[{"ApiKeyAuth":[]}],"summary":"Read owned multi-metal portfolio settings and stored-price summary","description":"Requires portfolio read permission and accepts X-API-Key only. Query-string credentials are not accepted. The request retains the rolling per-key and source-IP abuse limits but does not increment the monthly market-data quota. The summary values holdings from each metal’s matching latest stored spot price in the portfolio reporting currency; the request never calls an upstream provider and never bridges currencies. Valuation is current when all held-metal prices are at most six hours old, stale when any is older, and unavailable when any held metal has no matching-currency price, including a projected price whose FX snapshot is more than seven UTC calendar days old. Mixed-metal aggregate spot_price is null. Per-metal summaries retain separate prices and quantities. current_value, unrealised_pnl, spot_price, and price_timestamp are exact decimal strings or RFC 3339 timestamps when available, and null when unavailable; holdings and cost basis always remain available.","operationId":"getPortfolio","responses":{"200":{"description":"Owned portfolio settings and an exact-decimal summary with valuation status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioResponse"}}}},"401":{"description":"The X-API-Key header is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The key owner is unverified or the key lacks portfolio read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"status":"error","error":{"code":"insufficient_scope","message":"API key lacks the required portfolio scope"}}},"email_not_verified":{"value":{"status":"error","error":{"code":"email_not_verified","message":"Verify your email address before using the API"}}}}}}},"404":{"description":"The account does not have a configured portfolio.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"portfolio_not_found","message":"Portfolio not found"}}}}},"429":{"$ref":"#/components/responses/PortfolioRateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"put":{"tags":["portfolio"],"security":[{"ApiKeyAuth":[]}],"summary":"Create or update owned multi-metal portfolio settings","description":"Requires portfolio write permission and accepts X-API-Key only. Write permission always includes read. The reporting currency can change while the ledger is empty. The request retains abuse limits but does not increment the monthly market-data quota.","operationId":"putPortfolio","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioSettingsInput"}}}},"responses":{"200":{"description":"Created or updated portfolio settings and empty summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioResponse"}}}},"400":{"description":"The reporting currency is missing or unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"invalid_currency","message":"The currency code is invalid."}}}}},"401":{"description":"The X-API-Key header is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The key owner is unverified or the key lacks portfolio write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"insufficient_scope","message":"API key lacks the required portfolio scope"}}}}},"429":{"$ref":"#/components/responses/PortfolioRateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/portfolio/transactions":{"get":{"tags":["portfolio"],"security":[{"ApiKeyAuth":[]}],"summary":"Browse owned multi-metal portfolio transactions","description":"Requires portfolio read permission and accepts X-API-Key only. Results are ordered by transaction_date DESC, created_at DESC, id DESC. Filter by type, form, CGT status, and by period: calendar_year covers 1 January through 31 December inclusive, while uk_tax_year uses the form 2025-26 (consecutive years) and covers 6 April through 5 April inclusive; the two period filters are mutually exclusive and empty values are ignored. Use the opaque cursor for keyset pagination; page size defaults to 50 and is capped at 100. Decimal quantities and monetary values are returned as strings. Portfolio reads do not increment the monthly market-data quota.","operationId":"getPortfolioTransactions","parameters":[{"$ref":"#/components/parameters/PortfolioTransactionType"},{"$ref":"#/components/parameters/PortfolioTransactionForm"},{"$ref":"#/components/parameters/PortfolioTransactionCgtStatus"},{"$ref":"#/components/parameters/PortfolioTransactionCalendarYear"},{"$ref":"#/components/parameters/PortfolioTransactionTaxYear"},{"$ref":"#/components/parameters/PortfolioTransactionLimit"},{"$ref":"#/components/parameters/PortfolioTransactionCursor"}],"responses":{"200":{"description":"A stable page of owned transactions and an opaque cursor for the next page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioTransactionPage"}}}},"400":{"description":"The page size, cursor, filter value, or period is invalid (invalid_limit, invalid_cursor, invalid_filter, invalid_calendar_year, invalid_tax_year, conflicting_periods).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The key owner is unverified or the key lacks portfolio read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The account does not have a configured portfolio.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/PortfolioRateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["portfolio"],"security":[{"ApiKeyAuth":[]}],"summary":"Record an exact metal purchase, FIFO sale, or explicit-lot sale","description":"Requires portfolio write permission and an Idempotency-Key header. Quantity is normalized to grams at 15 decimal places. Money is rounded half-up and returned as 8-place decimal strings. Reusing a key with the same canonical request replays the original transaction; a changed request returns 409. Send X-Portfolio-Transaction-Type: sale to record a sale. By default sales consume eligible open lots FIFO by transaction date, creation time, then ID; sales cannot be future-dated or precede an allocated purchase. Alternatively send explicit lot allocations: every selected lot must belong to the account, match the sale metal, form and CGT treatment, predate or equal the sale date, and have sufficient remaining quantity, and allocated quantities must sum exactly to the sale quantity. Any invalid allocation fails the whole sale with invalid_allocation (or insufficient_holdings for races) without mutation, while concurrent mutations are committed atomically at Serializable isolation.","operationId":"postPortfolioTransaction","parameters":[{"name":"X-Portfolio-Transaction-Type","in":"header","required":false,"schema":{"type":"string","enum":["sale"]},"description":"Send sale to record a sale; omit to record a purchase."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Opaque client-generated retry key. It is not stored or logged in raw form."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PortfolioPurchaseInput"},{"$ref":"#/components/schemas/PortfolioSaleInput"}]}}}},"responses":{"200":{"description":"Created purchase or sale, or the original result for an idempotent replay.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PortfolioPurchaseResponse"},{"$ref":"#/components/schemas/PortfolioSaleResponse"}]}}}},"400":{"description":"Missing idempotency key, invalid fields, an invalid sale date, or invalid explicit lot allocations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The key owner is unverified or the key lacks portfolio write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The account does not have a configured portfolio.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"The idempotency key was reused for a changed request, or holdings are insufficient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/PortfolioRateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/portfolio/lots":{"get":{"tags":["portfolio"],"security":[{"ApiKeyAuth":[]}],"summary":"List owned open purchase lots eligible for sale allocation","description":"Requires portfolio read permission and accepts X-API-Key only. Returns only the authenticated owner's open purchase lots with a positive remaining quantity, ordered by purchase transaction_date, creation time, then ID for stable identifiers. Each lot carries its stable lot_id, the originating purchase_transaction_id, purchase date, form, CGT status, remaining quantity in grams, and remaining cost basis as decimal strings. A lot is eligible for an explicit sale allocation when it belongs to the account, matches the sale form and CGT treatment, predates or equals the sale date, has sufficient remaining quantity, and the allocated quantities sum exactly to the sale quantity.","operationId":"getPortfolioLots","responses":{"200":{"description":"The owned open lots available for explicit sale allocation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioLotsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The key owner is unverified or the key lacks portfolio read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The account does not have a configured portfolio.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/PortfolioRateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/portfolio/transactions/{id}":{"get":{"tags":["portfolio"],"security":[{"ApiKeyAuth":[]}],"summary":"Read one owned multi-metal portfolio transaction","description":"Requires portfolio read permission and accepts X-API-Key only. The identifier is scoped to the authenticated account; missing, malformed, and cross-account identifiers share the transaction_not_found response. Every response carries an ETag header with the quoted transaction version; send it as If-Match when editing.","operationId":"getPortfolioTransaction","parameters":[{"$ref":"#/components/parameters/PortfolioTransactionId"}],"responses":{"200":{"description":"One owned transaction with its open lot and allocation details.","headers":{"ETag":{"description":"Quoted current version of the transaction.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioTransactionResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The key owner is unverified or the key lacks portfolio read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The transaction was not found for the authenticated account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"transaction_not_found","message":"The transaction was not found."}}}}},"429":{"$ref":"#/components/responses/PortfolioRateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"delete":{"tags":["portfolio"],"security":[{"ApiKeyAuth":[]}],"summary":"Delete one owned multi-metal portfolio transaction","description":"Requires portfolio write permission and accepts X-API-Key only. The request must send an If-Match header carrying the ETag-style quoted version from the transaction payload (\"1\"); a missing or mismatched version returns 412 stale_transaction without mutation. Deleting a sale restores every allocated quantity and cost basis to its originating purchase lot; deleting a purchase that has funded a sale is refused with 409 transaction_in_use. Missing, malformed, and cross-account identifiers share the transaction_not_found response.","operationId":"deletePortfolioTransaction","parameters":[{"$ref":"#/components/parameters/PortfolioTransactionId"},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string","pattern":"^(?:W/)?\"\\d+\"$"},"description":"Precondition header with the quoted transaction version, for example \"1\". A weak validator (W/\"1\") is accepted. Any other value fails the precondition before the ledger is touched."}],"responses":{"200":{"description":"The transaction was deleted and holdings, lots, and summary values were rebalanced.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioTransactionDeletedResponse"},"example":{"status":"success","deleted_transaction_id":"11111111-1111-4111-8111-111111111111"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The key owner is unverified or the key lacks portfolio write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"insufficient_scope","message":"API key lacks the required portfolio scope"}}}}},"404":{"description":"The transaction was not found for the authenticated account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"transaction_not_found","message":"The transaction was not found."}}}}},"409":{"description":"The purchase has funded a sale and cannot be deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"transaction_in_use","message":"Gold from this purchase has been sold and cannot be deleted."}}}}},"412":{"description":"The If-Match version does not match the stored transaction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"stale_transaction","message":"Load the transaction again and retry with its latest ETag."}}}}},"429":{"$ref":"#/components/responses/PortfolioRateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"patch":{"tags":["portfolio"],"security":[{"ApiKeyAuth":[]}],"summary":"Edit one owned multi-metal portfolio transaction with optimistic concurrency","description":"Requires portfolio write permission and accepts X-API-Key only. If-Match must quote the current version; a missing or stale precondition returns 412 stale_transaction without any mutation. The body replaces every mutable field (transaction_date, quantity, weight_unit, unit_price, delivery_cost, fees, form, cgt_status, description); type and owner are immutable. Purchases must keep enough quantity and cost for every dependent sale allocation, cannot move after an allocating sale, and cannot change form or CGT treatment while sales depend on them. Sales release and rebuild only their own allocations using their persisted fifo or explicit method: FIFO edits omit allocations, explicit edits resend them with the same eligibility and exact-sum rules as creation. Success increments the version, returns the new ETag, and recalculates lot totals, disposed cost, and realised P&L immediately. Any validation, allocation, or concurrency failure rolls the whole edit back at Serializable isolation.","operationId":"patchPortfolioTransaction","parameters":[{"$ref":"#/components/parameters/PortfolioTransactionId"},{"$ref":"#/components/parameters/PortfolioTransactionIfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PortfolioPurchaseInput"},{"$ref":"#/components/schemas/PortfolioSaleInput"}]}}}},"responses":{"200":{"description":"Edited transaction with its incremented version.","headers":{"ETag":{"description":"Quoted new version of the edited transaction.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioTransactionResponse"}}}},"400":{"description":"Invalid fields or an edit incompatible with dependent sale allocations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The key owner is unverified or the key lacks portfolio write permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The transaction was not found for the authenticated account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"transaction_not_found","message":"The transaction was not found."}}}}},"409":{"description":"The portfolio does not hold enough of the selected metal for the edited sale.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"412":{"description":"The If-Match header was missing, malformed, or did not match the current version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"stale_transaction","message":"Load the transaction again and retry with its latest ETag."}}}}},"429":{"$ref":"#/components/responses/PortfolioRateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/portfolio/gains":{"get":{"tags":["portfolio"],"security":[{"ApiKeyAuth":[]}],"summary":"Summarise owned realised gains by UK CGT treatment","description":"Requires portfolio read permission and accepts X-API-Key only. Sums realised profit or loss from owned sale transactions whose transaction_date falls inside one required period: calendar_year covers 1 January through 31 December inclusive, while uk_tax_year uses the form 2025-26 (consecutive years) and covers 6 April through 5 April inclusive. The two period filters are mutually exclusive and exactly one must be supplied. Buckets group sales by recorded CGT status; exempt and not_exempt sums use only transactions declared with that status and unknown collects the rest. All monetary values are exact 8-place decimal strings. The figures are informational only: they exclude annual allowances, matching and pooling rules, and tax rates, and are not tax advice. Portfolio reads do not increment the monthly market-data quota.","operationId":"getPortfolioGains","parameters":[{"$ref":"#/components/parameters/PortfolioTransactionCalendarYear"},{"$ref":"#/components/parameters/PortfolioTransactionTaxYear"}],"responses":{"200":{"description":"The resolved period echoed back with realised gains grouped by declared CGT treatment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioGainsResponse"}}}},"400":{"description":"No period filter was supplied, both were supplied, or a label is malformed (missing_period, conflicting_periods, invalid_calendar_year, invalid_tax_year).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_period":{"value":{"status":"error","error":{"code":"missing_period","message":"Use either calendar_year or uk_tax_year."}}},"conflicting_periods":{"value":{"status":"error","error":{"code":"conflicting_periods","message":"Use either calendar_year or uk_tax_year, not both."}}},"invalid_calendar_year":{"value":{"status":"error","error":{"code":"invalid_calendar_year","message":"The transaction history calendar year is invalid."}}},"invalid_tax_year":{"value":{"status":"error","error":{"code":"invalid_tax_year","message":"The UK tax-year label is invalid."}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The key owner is unverified or the key lacks portfolio read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The account does not have a configured portfolio.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"portfolio_not_found","message":"Portfolio not found"}}}}},"429":{"$ref":"#/components/responses/PortfolioRateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/usage":{"get":{"tags":["account"],"summary":"Plan, quota and recent requests for the signed-in user","description":"Authenticated via session cookie (NOT X-API-Key) so the dashboard can call it directly without storing an API key client-side. This spec is informational for this endpoint: browsers obtain the cookie by signing in at https://bullionapi.dev/login.","operationId":"getUsage","security":[{"CookieAuth":[]}],"responses":{"200":{"description":"Current plan, monthly quota state and the 50 most recent requests.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"401":{"description":"Not signed in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"unauthenticated","message":"A signed-in session is required."}}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/health":{"get":{"tags":["meta"],"summary":"Service health","description":"Public, no auth. Reports database reachability, metal-cache freshness and enabled projected-currency FX snapshot readiness. Returns 503 when the metal cache is stale or an enabled FX snapshot is unavailable or stale. Metal-cache age runs from the later of the last refresh and one hour before the next refresh due after it. A gap with no refresh due (the weekend market close apart from the daily 06:00 UTC refresh, and weekdays at 22:00 UTC) therefore does not age the cache until a due refresh is missed; after that, every hour counts.","operationId":"getHealth","security":[],"responses":{"200":{"description":"Healthy: database reachable, metal cache fresh and FX disabled or fresh.","headers":{"x-bullion-build-sha":{"description":"Full Git commit SHA of the deployed build when supplied by the build environment.","schema":{"type":"string","pattern":"^[0-9a-f]{40}$"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"503":{"description":"Degraded: database unreachable, metal cache stale or enabled FX unavailable or stale.","headers":{"x-bullion-build-sha":{"description":"Full Git commit SHA of the deployed build when supplied by the build environment.","schema":{"type":"string","pattern":"^[0-9a-f]{40}$"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"health_degraded","message":"The service health check is degraded.","db_reachable":false,"last_refresh_at":null,"currencies_with_data":[],"fx_snapshot_status":"disabled","last_fx_snapshot_at":null,"projected_currencies_with_data":[]}}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key created in the dashboard, prefixed `bullion_`."},"ApiKeyQuery":{"type":"apiKey","in":"query","name":"api_key","description":"Fallback API key for clients that cannot set custom headers. Query credentials can be exposed by URLs; prefer ApiKeyAuth whenever possible."},"CookieAuth":{"type":"apiKey","in":"cookie","name":"better-auth.session_token","description":"Session cookie set on sign-in. Over HTTPS the name is prefixed: `__Secure-better-auth.session_token`."}},"parameters":{"Currency":{"name":"currency","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Za-z]{3}$","default":"USD","example":"EUR"},"description":"ISO 4217 base currency, case-insensitive. Use GET /v1/symbols for the active production catalogue. Currency availability and no-data behavior are documented for each endpoint."},"CaratCurrency":{"name":"currency","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Za-z]{3}$","default":"USD","example":"EUR"},"description":"Three-letter ISO 4217 currency code, case-insensitive. The request succeeds only when that currency has cached gold data."},"CaratDate":{"name":"date","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-08-10"},"description":"Optional exact UTC day. The final cached gold observation in that day is used; malformed or impossible dates return 400 invalid_date."},"MetalPriceUnit":{"name":"unit","in":"query","required":false,"schema":{"type":"string","enum":["gram","g","kilogram","kg","troy_oz","toz"],"default":"troy_oz"},"description":"Output mass unit. Omit or leave empty for troy_oz. gram and g return grams; kilogram and kg return kilograms; troy_oz and toz return troy ounces. The response always reports the normalised unit (troy_oz, gram, or kilogram). Other non-empty values return 400 invalid_unit."},"ChangeStart":{"name":"start","in":"query","required":false,"schema":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-01"},"description":"First UTC day to compare. Use instead of period; end defaults to today."},"ChangeEnd":{"name":"end","in":"query","required":false,"schema":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-02"},"description":"Last UTC day to compare. Requires start; at most 365 days after it."},"ChangePeriod":{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["1d","1w","1m","1y"]},"description":"Rolling UTC window ending today: 1d is 1 day, 1w is 7 days, 1m is 30 days and 1y is 365 days. Use instead of start and end; combining them returns 400 conflicting_params."},"DerivedRangeStart":{"name":"start","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-01"},"description":"First inclusive UTC day."},"DerivedRangeEnd":{"name":"end","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-31"},"description":"Last inclusive UTC day. The maximum range is five years."},"MovingAverageWindow":{"name":"window","in":"query","required":true,"schema":{"type":"string","enum":["50","200"],"example":"50"},"description":"Number of stored daily closes in the moving average."},"DerivedStart":{"name":"start","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-01"},"description":"Optional first inclusive UTC day. Supply with end to read historical daily values; omit both dates for the latest value."},"DerivedEnd":{"name":"end","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"description":"Optional last inclusive UTC day. The maximum historical range is five years."},"CountryPath":{"name":"country","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z]{2}$","example":"gb"},"description":"ISO 3166-1 alpha-2 country code or `ea` for the euro area, case-insensitive. `uk` and `eu` are accepted aliases for `gb` and `ea`. Responses echo the canonical upper-case code."},"SeriesStart":{"name":"start","in":"query","required":false,"schema":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2024-01-01"},"description":"First inclusive UTC calendar date. Omit both start and end for the latest observation only; start alone runs to today. An observation is included when its period end falls in the range."},"SeriesEnd":{"name":"end","in":"query","required":false,"schema":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2024-12-31"},"description":"Last inclusive UTC calendar date. Requires start."},"InflationBasis":{"name":"basis","in":"query","required":false,"schema":{"type":"string","enum":["year_over_year","breakeven","implied","expectation"]},"description":"Only series with this basis. Unknown values return 400 invalid_series_filter. year_over_year is realised CPI or HICP inflation."},"BondYieldTenor":{"name":"tenor","in":"query","required":false,"schema":{"type":"string","enum":["2y","5y","10y","30y"]},"description":"Only series with this maturity. Unknown values return 400 invalid_series_filter."},"BondYieldBasis":{"name":"basis","in":"query","required":false,"schema":{"type":"string","enum":["nominal","real"]},"description":"Only series with this basis. Unknown values return 400 invalid_series_filter."},"PortfolioTransactionId":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Owned transaction identifier."},"PortfolioTransactionIfMatch":{"name":"If-Match","in":"header","required":true,"schema":{"type":"string","pattern":"^\"\\d+\"$","example":"\"3\""},"description":"Quoted current version of the transaction, taken from the ETag response header or the version field. Wildcard and multi-tag forms are not accepted."},"PortfolioTransactionLimit":{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Number of rows to return. Defaults to 50 and cannot exceed 100."},"PortfolioTransactionCursor":{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor returned as next_cursor. It encodes the final transaction_date, created_at, and id ordering tuple."},"PortfolioTransactionType":{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["purchase","sale"]},"description":"Only include transactions of this type. Empty values are ignored."},"PortfolioTransactionForm":{"name":"form","in":"query","required":false,"schema":{"type":"string","enum":["bar","coin","other"]},"description":"Only include transactions with this physical form. Empty values are ignored."},"PortfolioTransactionCgtStatus":{"name":"cgt_status","in":"query","required":false,"schema":{"type":"string","enum":["exempt","not_exempt","unknown"]},"description":"Only include transactions recorded with this UK CGT status. Empty values are ignored."},"PortfolioTransactionCalendarYear":{"name":"calendar_year","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}$","example":"2025"},"description":"Restrict results to 1 January through 31 December of this year, inclusive. Mutually exclusive with uk_tax_year; combining both returns 400 conflicting_periods. Invalid labels return 400 invalid_calendar_year."},"PortfolioTransactionTaxYear":{"name":"uk_tax_year","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$","example":"2025-26"},"description":"Restrict results to a UK tax year labelled with consecutive years such as 2025-26, covering 6 April through 5 April inclusive. Mutually exclusive with calendar_year; combining both returns 400 conflicting_periods. Non-consecutive or malformed labels return 400 invalid_tax_year."}},"responses":{"Unauthorized":{"description":"Missing, conflicting, or invalid API key credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing":{"value":{"status":"error","error":{"code":"missing_api_key","message":"Missing API key"}}},"conflict":{"value":{"status":"error","error":{"code":"conflicting_credentials","message":"Conflicting API key credentials"}}},"invalid":{"value":{"status":"error","error":{"code":"invalid_api_key","message":"Invalid or revoked API key"}}}}}}},"EmailNotVerified":{"description":"The API-key owner must verify their email address before accessing price data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"email_not_verified","message":"Verify your email address before using the API"}}}}},"QuotaExceeded":{"description":"Monthly quota reached. Quota resets on the 1st of next month, 00:00 UTC.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}},"retry-after":{"description":"Seconds until the quota resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuotaExceededError"},"example":{"status":"error","error":{"code":"quota_exceeded","message":"Your monthly usage limit has been reached. Please upgrade your subscription plan.","plan":"free","used":30,"limit":30,"reset_at":"2026-11-01T00:00:00.000Z"}}}}},"TooManyRequests":{"description":"The API-key rolling window or monthly quota has been exceeded.","headers":{"x-ratelimit-limit":{"description":"Your plan's monthly request cap.","schema":{"type":"integer","example":30}},"x-ratelimit-used":{"description":"Requests used this month, including this one.","schema":{"type":"integer","example":1}},"x-ratelimit-remaining":{"description":"Requests remaining this month.","schema":{"type":"integer","example":29}},"x-ratelimit-plan":{"description":"The plan the quota is enforced against.","schema":{"type":"string","enum":["free","pro","business"],"example":"free"}},"x-ratelimit-reset":{"description":"When the quota resets (1st of next month, 00:00 UTC).","schema":{"type":"string","format":"date-time"}},"X-API-CURRENT":{"description":"Compatibility alias for x-ratelimit-used.","schema":{"type":"integer","example":1}},"X-API-QUOTA":{"description":"Compatibility alias for x-ratelimit-limit.","schema":{"type":"integer","example":30}},"retry-after":{"description":"Seconds until the applicable limit resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/QuotaExceededError"},{"$ref":"#/components/schemas/RateLimitedError"}]},"examples":{"rate_limited":{"value":{"status":"error","error":{"code":"rate_limited","message":"Rate limit exceeded"}}},"quota_exceeded":{"value":{"status":"error","error":{"code":"quota_exceeded","message":"Your monthly usage limit has been reached. Please upgrade your subscription plan.","plan":"free","used":30,"limit":30,"reset_at":"2026-11-01T00:00:00.000Z"}}}}}}},"PortfolioRateLimited":{"description":"The API key has exceeded its rolling request window.","headers":{"retry-after":{"description":"Seconds until the per-key rolling limit resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"},"example":{"status":"error","error":{"code":"rate_limited","message":"Rate limit exceeded"}}}}},"ApiKeyRateLimited":{"description":"The API key has exceeded its rolling request window. Monthly quota exhaustion does not block this endpoint.","headers":{"retry-after":{"description":"Seconds until the per-key rolling limit resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"},"example":{"status":"error","error":{"code":"rate_limited","message":"Rate limit exceeded"}}}}},"MethodNotAllowed":{"description":"The API is read-only; writes are not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"method_not_allowed","message":"Method not allowed"}}}}},"NotFound":{"description":"No API operation exists at the requested /v1 path. Returned for every method, without authentication or quota use.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"not_found","message":"The requested API path was not found."}}}}},"InternalError":{"description":"Server configuration error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"status":"error","error":{"code":"config_error","message":"The service is not configured correctly."}}}}}},"schemas":{"RealPriceResponse":{"type":"object","additionalProperties":false,"required":["status","metric","currency","unit","start_date","end_date","points","attribution","reference_period"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"real_price"},"currency":{"type":"string","const":"USD"},"unit":{"type":"string","const":"usd_per_toz"},"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"},"points":{"type":"array","items":{"$ref":"#/components/schemas/DerivedPoint"}},"attribution":{"type":"string"},"reference_period":{"type":"string","format":"date","description":"Month-end of the latest stored published CPI index used to rebase every point."}}},"YieldCorrelationResponse":{"type":"object","additionalProperties":false,"required":["status","metric","currency","unit","start_date","end_date","points","attribution","window"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"corr_10y_yield"},"currency":{"type":"string","const":"USD"},"unit":{"type":"string","const":"correlation"},"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"},"points":{"type":"array","items":{"$ref":"#/components/schemas/DerivedPoint"}},"attribution":{"type":"string"},"window":{"type":"integer","const":90}}},"DerivedPoint":{"type":"object","additionalProperties":false,"required":["date","value"],"properties":{"date":{"type":"string","format":"date"},"value":{"type":"string","pattern":"^-?\\d+\\.\\d{8}$","description":"Exact decimal string, rounded half-up to eight places. A JSON number before 2026-10-07.","example":"68.40312345"}}},"MovingAveragePoint":{"type":"object","additionalProperties":false,"required":["date","value"],"properties":{"date":{"type":"string","format":"date"},"value":{"type":"string","pattern":"^\\d+\\.\\d{8}$","description":"Gold price per troy ounce as a decimal string, rounded half-up to eight places.","example":"5100.00000000"}}},"MovingAverageResponse":{"type":"object","additionalProperties":false,"required":["status","currency","window","unit","start_date","end_date","points"],"properties":{"status":{"type":"string","const":"success"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"USD"},"window":{"type":"integer","enum":[50,200]},"unit":{"type":"string","const":"toz"},"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"},"points":{"type":"array","description":"Moving-average gold price per troy ounce for each available UTC day.","items":{"$ref":"#/components/schemas/MovingAveragePoint"}}}},"VolatilityResponse":{"type":"object","additionalProperties":false,"required":["status","currency","window","start_date","end_date","points"],"properties":{"status":{"type":"string","const":"success"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"USD"},"window":{"type":"integer","const":30},"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"},"points":{"type":"array","description":"Annualised volatility as a fraction (0.15 is 15%) for each available UTC day.","items":{"$ref":"#/components/schemas/DerivedPoint"}}}},"DrawdownResponse":{"type":"object","additionalProperties":false,"required":["status","currency","lookback_observations","start_date","end_date","points"],"properties":{"status":{"type":"string","const":"success"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"USD"},"lookback_observations":{"type":"integer","const":1260,"description":"Maximum stored daily observations in the running-peak window; bounded in practice by stored history."},"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"},"points":{"type":"array","description":"Drawdown from the running peak as a fraction (-0.25 is 25% below the peak) for each available UTC day.","items":{"$ref":"#/components/schemas/DerivedPoint"}}}},"GoldSilverRatioResponse":{"type":"object","additionalProperties":false,"required":["status","currency","start_date","end_date","points"],"properties":{"status":{"type":"string","const":"success"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"USD"},"start_date":{"type":["string","null"],"format":"date"},"end_date":{"type":["string","null"],"format":"date"},"points":{"type":"array","description":"Gold price divided by silver price for each available UTC day.","items":{"$ref":"#/components/schemas/DerivedPoint"}}}},"SymbolsResponse":{"type":"object","additionalProperties":false,"required":["status","metals","currencies"],"properties":{"status":{"type":"string","const":"success"},"metals":{"type":"object","additionalProperties":false,"required":["gold","silver","palladium","copper","platinum"],"description":"Supported metals and their API symbols; all prices use troy ounces.","properties":{"gold":{"type":"string","const":"Gold (troy ounce)"},"silver":{"type":"string","const":"Silver (troy ounce)"},"palladium":{"type":"string","const":"Palladium (troy ounce)"},"copper":{"type":"string","const":"Copper (troy ounce)"},"platinum":{"type":"string","const":"Platinum (troy ounce)"}}},"currencies":{"type":"object","required":["USD","EUR","GBP"],"propertyNames":{"pattern":"^[A-Z]{3}$"},"additionalProperties":{"type":"string","minLength":1},"description":"Static deployment catalogue derived from reviewed PROJECTED_CURRENCIES configuration. Authenticated GET /v1/symbols is authoritative at runtime because projected currencies remain absent until all five production metal price rows are materialised with FX provenance.","properties":{"USD":{"type":"string","const":"US Dollar"},"EUR":{"type":"string","const":"Euro"},"GBP":{"type":"string","const":"Pound Sterling"}}}},"example":{"status":"success","metals":{"gold":"Gold (troy ounce)","silver":"Silver (troy ounce)","palladium":"Palladium (troy ounce)","copper":"Copper (troy ounce)","platinum":"Platinum (troy ounce)"},"currencies":{"USD":"US Dollar","EUR":"Euro","GBP":"Pound Sterling"}}},"PortfolioSettingsInput":{"type":"object","additionalProperties":false,"required":["reporting_currency"],"properties":{"reporting_currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"Active ISO 4217 currency from GET /v1/symbols.","example":"GBP"}}},"PortfolioSettings":{"type":"object","additionalProperties":false,"required":["id","metals","reporting_currency","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"metals":{"type":"array","items":{"type":"string","enum":["gold","silver","palladium","copper","platinum"]}},"reporting_currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"Active ISO 4217 currency from GET /v1/symbols."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"PortfolioSummary":{"type":"object","additionalProperties":false,"required":["gold_quantity_grams","cost_basis","realised_pnl","valuation","metals"],"properties":{"metals":{"type":"array","items":{"$ref":"#/components/schemas/PortfolioMetalSummary"}},"gold_quantity_grams":{"type":"string","example":"0.000000000000000"},"cost_basis":{"type":"string","example":"0.00000000"},"realised_pnl":{"type":"string","example":"0.00000000"},"valuation":{"type":"object","additionalProperties":false,"required":["status","spot_price","current_value","unrealised_pnl","price_timestamp"],"properties":{"status":{"type":"string","enum":["current","stale","unavailable"],"description":"current when all held metals have prices at most six hours old; stale when any is older; unavailable when any held metal has no matching price, including a projected price whose FX snapshot is more than seven UTC calendar days old."},"spot_price":{"type":["string","null"],"description":"Stored metal spot price per troy ounce; null for a mixed-metal aggregate."},"current_value":{"type":["string","null"],"description":"Open troy ounces multiplied by the stored spot price; null when unavailable."},"unrealised_pnl":{"type":["string","null"],"description":"current_value minus the remaining cost basis; null when unavailable."},"price_timestamp":{"type":["string","null"],"format":"date-time","description":"When the stored spot price was fetched; null when unavailable."}}}}},"PortfolioMetalSummary":{"type":"object","additionalProperties":false,"required":["metal","quantity_grams","cost_basis","realised_pnl","valuation"],"properties":{"metal":{"type":"string","enum":["gold","silver","palladium","copper","platinum"]},"quantity_grams":{"type":"string"},"cost_basis":{"type":"string"},"realised_pnl":{"type":"string"},"valuation":{"$ref":"#/components/schemas/PortfolioSummary/properties/valuation"}}},"PortfolioResponse":{"type":"object","additionalProperties":false,"required":["status","portfolio","summary"],"properties":{"status":{"type":"string","const":"success"},"portfolio":{"$ref":"#/components/schemas/PortfolioSettings"},"summary":{"$ref":"#/components/schemas/PortfolioSummary"}}},"PortfolioPurchaseInput":{"type":"object","additionalProperties":false,"required":["transaction_date","quantity","weight_unit","unit_price","delivery_cost","fees","form","cgt_status"],"properties":{"metal":{"type":"string","enum":["gold","silver","palladium","copper","platinum"],"default":"gold","description":"Omitted metal defaults to gold. A transaction metal cannot be changed by editing."},"transaction_date":{"type":"string","format":"date","description":"Real UTC calendar date, today or earlier."},"quantity":{"type":"string","pattern":"^\\d+(?:\\.\\d{1,8})?$","example":"1.005"},"weight_unit":{"type":"string","enum":["gram","g","kilogram","kg","troy_oz","toz"]},"unit_price":{"type":"string","example":"2500.125"},"delivery_cost":{"type":"string","example":"12.345678945"},"fees":{"type":"string","example":"1.005"},"form":{"type":"string","enum":["bar","coin","other"]},"cgt_status":{"type":"string","enum":["exempt","not_exempt","unknown"]},"description":{"type":"string","maxLength":500}}},"PortfolioPurchase":{"type":"object","additionalProperties":false,"required":["metal","id","transaction_date","entered_quantity","quantity_grams","weight_unit","unit_price","gross_cost","delivery_cost","fees","total_cost","cost_per_gram","form","cgt_status","description","created_at"],"properties":{"metal":{"type":"string","enum":["gold","silver","palladium","copper","platinum"]},"id":{"type":"string","format":"uuid"},"transaction_date":{"type":"string","format":"date"},"entered_quantity":{"type":"string","description":"The entered quantity in the submitted weight unit, returned as an 8-place decimal string.","example":"1.00500000"},"quantity_grams":{"type":"string","example":"31.258994184000000"},"weight_unit":{"type":"string","enum":["gram","kilogram","troy_oz"]},"unit_price":{"type":"string","example":"2500.12500000"},"gross_cost":{"type":"string","example":"2512.62562500"},"delivery_cost":{"type":"string","example":"12.34567895"},"fees":{"type":"string","example":"1.00500000"},"total_cost":{"type":"string","example":"2525.97630395"},"cost_per_gram":{"type":"string","example":"80.80798407"},"form":{"type":"string","enum":["bar","coin","other"]},"cgt_status":{"type":"string","enum":["exempt","not_exempt","unknown"]},"description":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"PortfolioPurchaseResponse":{"type":"object","additionalProperties":false,"required":["status","transaction"],"properties":{"status":{"type":"string","const":"success"},"transaction":{"$ref":"#/components/schemas/PortfolioPurchase"}}},"PortfolioSaleResponse":{"type":"object","additionalProperties":false,"required":["status","transaction"],"properties":{"status":{"type":"string","const":"success"},"transaction":{"type":"object","additionalProperties":false,"required":["metal","type","version","id","transaction_date","created_at","entered_quantity","quantity_grams","weight_unit","unit_price","gross_proceeds","delivery_cost","fees","net_proceeds","disposed_cost","realised_pnl","form","cgt_status","allocation_method","description","allocations"],"properties":{"metal":{"type":"string","enum":["gold","silver","palladium","copper","platinum"]},"type":{"type":"string","const":"sale"},"version":{"type":"integer","const":1},"id":{"type":"string","format":"uuid"},"transaction_date":{"type":"string","format":"date"},"created_at":{"type":"string","format":"date-time"},"entered_quantity":{"type":"string"},"quantity_grams":{"type":"string"},"weight_unit":{"type":"string","enum":["gram","kilogram","troy_oz"]},"unit_price":{"type":"string"},"gross_proceeds":{"type":"string"},"delivery_cost":{"type":"string"},"fees":{"type":"string"},"net_proceeds":{"type":"string"},"disposed_cost":{"type":"string"},"realised_pnl":{"type":"string"},"form":{"type":"string","enum":["bar","coin","other"]},"cgt_status":{"type":"string","enum":["exempt","not_exempt","unknown"]},"allocation_method":{"type":"string","enum":["fifo","explicit"]},"description":{"type":["string","null"]},"allocations":{"$ref":"#/components/schemas/PortfolioTransaction/properties/allocations"}}}}},"PortfolioSaleInput":{"type":"object","additionalProperties":false,"required":["transaction_date","quantity","weight_unit","unit_price","delivery_cost","fees","form","cgt_status"],"properties":{"metal":{"type":"string","enum":["gold","silver","palladium","copper","platinum"],"default":"gold","description":"Omitted metal defaults to gold. A transaction metal cannot be changed by editing."},"transaction_date":{"type":"string","format":"date","description":"Real UTC calendar date, today or earlier. Selected lots must predate or equal it."},"quantity":{"type":"string","pattern":"^\\d+(?:\\.\\d{1,8})?$","example":"1.005"},"weight_unit":{"type":"string","enum":["gram","g","kilogram","kg","troy_oz","toz"]},"unit_price":{"type":"string","example":"2500.125"},"delivery_cost":{"type":"string","example":"12.345678945"},"fees":{"type":"string","example":"1.005"},"form":{"type":"string","enum":["bar","coin","other"]},"cgt_status":{"type":"string","enum":["exempt","not_exempt","unknown"]},"description":{"type":"string","maxLength":500},"allocations":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"required":["lot_id","quantity_grams"],"properties":{"lot_id":{"type":"string","format":"uuid","description":"Stable identifier from GET /v1/portfolio/lots."},"quantity_grams":{"type":"string","pattern":"^\\d+(?:\\.\\d{1,15})?$","description":"Exact grams to dispose from this lot; must not exceed its remaining quantity and all allocated quantities must sum exactly to the sale quantity."}}},"description":"Opt-in explicit allocation. Every selected lot must belong to the account, match the sale metal, form and CGT treatment, predate or equal the sale date, and have sufficient remaining quantity. Any missing, foreign, duplicated, incompatible, over-allocated, or under-allocated lot fails the whole sale without mutation."}}},"PortfolioOpenLot":{"type":"object","additionalProperties":false,"required":["metal","lot_id","purchase_transaction_id","transaction_date","form","cgt_status","remaining_quantity_grams","remaining_cost_basis"],"properties":{"metal":{"type":"string","enum":["gold","silver","palladium","copper","platinum"]},"lot_id":{"type":"string","format":"uuid"},"purchase_transaction_id":{"type":"string","format":"uuid"},"transaction_date":{"type":"string","format":"date"},"form":{"type":"string","enum":["bar","coin","other"]},"cgt_status":{"type":"string","enum":["exempt","not_exempt","unknown"]},"remaining_quantity_grams":{"type":"string","description":"Remaining open quantity in grams as a 15-place decimal string."},"remaining_cost_basis":{"type":"string","description":"Remaining open cost basis as an 8-place decimal string."}}},"PortfolioLotsResponse":{"type":"object","additionalProperties":false,"required":["status","lots"],"properties":{"status":{"type":"string","const":"success"},"lots":{"type":"array","items":{"$ref":"#/components/schemas/PortfolioOpenLot"}}}},"PortfolioTransactionLot":{"type":"object","additionalProperties":false,"required":["id","metal","open_quantity_grams","open_cost_basis"],"properties":{"metal":{"type":"string","enum":["gold","silver","palladium","copper","platinum"]},"id":{"type":"string","format":"uuid"},"open_quantity_grams":{"type":"string","description":"Open quantity in grams as a decimal string."},"open_cost_basis":{"type":"string","description":"Open cost basis as a decimal string."}}},"PortfolioTransaction":{"type":"object","additionalProperties":false,"required":["metal","type","version","id","transaction_date","created_at","entered_quantity","weight_unit","quantity_grams","unit_price","gross_cost","delivery_cost","fees","total_cost","cost_per_gram","form","cgt_status","allocation_method","description","lots","allocations"],"properties":{"metal":{"type":"string","enum":["gold","silver","palladium","copper","platinum"]},"type":{"type":"string","enum":["purchase","sale"]},"version":{"type":"integer","minimum":1,"description":"Resource version for optimistic concurrency. It matches the quoted ETag response header and increments on every successful edit."},"id":{"type":"string","format":"uuid"},"transaction_date":{"type":"string","format":"date"},"created_at":{"type":"string","format":"date-time"},"entered_quantity":{"type":"string","description":"Submitted and normalized values use decimal strings."},"weight_unit":{"type":"string","enum":["gram","kilogram","troy_oz"]},"quantity_grams":{"type":"string","description":"Normalized metal quantity as a decimal string."},"unit_price":{"type":"string","description":"Unit price as an 8-place decimal string."},"gross_cost":{"type":"string","description":"Gross cost as an 8-place decimal string."},"delivery_cost":{"type":"string","description":"Delivery cost as an 8-place decimal string."},"fees":{"type":"string","description":"Fees as an 8-place decimal string."},"total_cost":{"type":"string","description":"Total cost as an 8-place decimal string."},"cost_per_gram":{"type":"string","description":"Cost per gram as an 8-place decimal string."},"form":{"type":"string","enum":["bar","coin","other"]},"cgt_status":{"type":"string","enum":["exempt","not_exempt","unknown"]},"allocation_method":{"type":"string","enum":["fifo","explicit"],"description":"How the sale selected its lots: fifo by default, or explicit when committed lot allocations were supplied."},"description":{"type":["string","null"]},"lots":{"type":"array","items":{"$ref":"#/components/schemas/PortfolioTransactionLot"}},"gross_proceeds":{"type":"string","description":"Gross sale proceeds as an 8-place decimal string."},"net_proceeds":{"type":"string","description":"Net sale proceeds after delivery and fees."},"disposed_cost":{"type":"string","description":"FIFO cost basis disposed by a sale."},"realised_pnl":{"type":"string","description":"Net proceeds less FIFO disposed cost."},"allocations":{"type":"array","items":{"type":"object","required":["metal","purchase_transaction_id","lot_id","quantity_grams","cost_basis"],"properties":{"metal":{"type":"string","enum":["gold","silver","palladium","copper","platinum"]},"purchase_transaction_id":{"type":"string","format":"uuid"},"lot_id":{"type":"string","format":"uuid"},"quantity_grams":{"type":"string"},"cost_basis":{"type":"string"}}},"description":"Committed allocations ordered by purchase date, creation time, then ID. Present for both FIFO and explicit sales."}}},"PortfolioTransactionPage":{"type":"object","additionalProperties":false,"required":["status","transactions","next_cursor"],"properties":{"status":{"type":"string","const":"success"},"transactions":{"type":"array","items":{"$ref":"#/components/schemas/PortfolioTransaction"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page, or null."}}},"PortfolioTransactionResponse":{"type":"object","additionalProperties":false,"required":["status","transaction"],"properties":{"status":{"type":"string","const":"success"},"transaction":{"$ref":"#/components/schemas/PortfolioTransaction"}}},"PortfolioTransactionDeletedResponse":{"type":"object","additionalProperties":false,"required":["status","deleted_transaction_id"],"properties":{"status":{"type":"string","const":"success"},"deleted_transaction_id":{"type":"string","format":"uuid","description":"Identifier of the removed transaction."}}},"PortfolioGainsResponse":{"type":"object","additionalProperties":false,"required":["status","period","buckets","total","metals"],"properties":{"status":{"type":"string","const":"success"},"period":{"type":"object","additionalProperties":false,"required":["kind","label","start","end"],"description":"The inclusive date window resolved from the supplied period filter.","properties":{"kind":{"type":"string","enum":["calendar_year","uk_tax_year"]},"label":{"type":"string","example":"2025-26"},"start":{"type":"string","format":"date","example":"2025-04-06"},"end":{"type":"string","format":"date","example":"2026-04-05"}}},"buckets":{"type":"object","additionalProperties":false,"required":["exempt","not_exempt","unknown"],"description":"Realised gains grouped by the CGT status recorded on each sale, as exact decimal strings.","properties":{"exempt":{"type":"string","description":"Sales declared CGT-exempt."},"not_exempt":{"type":"string","description":"Sales declared not exempt."},"unknown":{"type":"string","description":"Sales whose CGT treatment is unknown."}}},"metals":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["metal","total"],"properties":{"metal":{"type":"string","enum":["gold","silver","palladium","copper","platinum"]},"total":{"type":"string"}}}},"total":{"type":"string","description":"Sum of all three buckets as an exact decimal string."}}},"MetalPriceResponse":{"type":"object","additionalProperties":false,"required":["status","metric","metal","currency","unit","start","end","series"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"price"},"metal":{"type":"string","enum":["gold","silver","palladium","copper","platinum"],"example":"gold"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"USD"},"unit":{"type":"string","enum":["troy_oz","gram","kilogram"],"example":"troy_oz"},"start":{"type":["string","null"],"format":"date","description":"Requested inclusive start date; null for the latest price."},"end":{"type":["string","null"],"format":"date","description":"Requested inclusive end date; null for the latest price."},"series":{"type":"array","minItems":1,"maxItems":1,"items":{"$ref":"#/components/schemas/MetalPriceSeries"}}}},"MetalPriceSeries":{"description":"A `DataSeries` with id `<metal>_price`. Latest: one observation dated with its full UTC timestamp, `frequency: hourly`, `method: latest`. Range: one observation per UTC weekday dated YYYY-MM-DD, `frequency: daily`, `method: weekday_close`. Values are decimal strings in the requested unit.","allOf":[{"$ref":"#/components/schemas/DataSeries"},{"type":"object","properties":{"id":{"type":"string","example":"gold_price"},"label":{"type":"string","example":"Gold spot price"},"unit":{"type":"string","enum":["troy_oz","gram","kilogram"]},"frequency":{"type":"string","enum":["hourly","daily"]},"method":{"type":"string","enum":["latest","weekday_close"]},"conversion":{"$ref":"#/components/schemas/SeriesConversion"},"coverage":{"$ref":"#/components/schemas/MetalHistoryCoverage"}},"if":{"properties":{"method":{"const":"weekday_close"}},"required":["method"]},"then":{"required":["coverage"]}}]},"MetalHistoryCoverage":{"type":"object","additionalProperties":false,"required":["earliest","latest","observation_count"],"description":"Usable stored weekday closes before request time, independent of the requested range. Bounds and count do not establish uninterrupted history or current data freshness.","properties":{"earliest":{"type":["string","null"],"format":"date"},"latest":{"type":["string","null"],"format":"date"},"observation_count":{"type":"integer","minimum":0}}},"SeriesConversion":{"type":"object","additionalProperties":false,"required":["snapshot_at","stale","attribution","attribution_url"],"description":"Provenance of a projected-currency series, derived from the canonical USD price and a daily Bullion API conversion snapshot. Omitted for native currencies.","properties":{"snapshot_at":{"type":"string","format":"date-time","description":"Newest daily conversion snapshot used by the series observations."},"stale":{"type":"boolean","description":"True when any observation used a conversion snapshot more than seven UTC calendar days older than the price it converts."},"attribution":{"type":"string","const":"Exchange Rates By UniRateAPI"},"attribution_url":{"type":"string","format":"uri","const":"https://unirateapi.com/"}}},"CaratResponse":{"type":"object","additionalProperties":false,"required":["status","currency","unit","as_of","karats"],"properties":{"status":{"type":"string","const":"success"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"unit":{"type":"string","const":"gram"},"as_of":{"type":"string","format":"date-time"},"karats":{"type":"object","additionalProperties":false,"required":["24k","23k","22k","21.6k","21k","18k","16k","14k","12k","10k","9k","8k","6k"],"properties":{"24k":{"type":"string","pattern":"^\\d+\\.\\d{8}$"},"23k":{"type":"string","pattern":"^\\d+\\.\\d{8}$"},"22k":{"type":"string","pattern":"^\\d+\\.\\d{8}$"},"21.6k":{"type":"string","pattern":"^\\d+\\.\\d{8}$"},"21k":{"type":"string","pattern":"^\\d+\\.\\d{8}$"},"18k":{"type":"string","pattern":"^\\d+\\.\\d{8}$"},"16k":{"type":"string","pattern":"^\\d+\\.\\d{8}$"},"14k":{"type":"string","pattern":"^\\d+\\.\\d{8}$"},"12k":{"type":"string","pattern":"^\\d+\\.\\d{8}$"},"10k":{"type":"string","pattern":"^\\d+\\.\\d{8}$"},"9k":{"type":"string","pattern":"^\\d+\\.\\d{8}$"},"8k":{"type":"string","pattern":"^\\d+\\.\\d{8}$"},"6k":{"type":"string","pattern":"^\\d+\\.\\d{8}$"}}}}},"ChangePoint":{"type":"object","additionalProperties":false,"required":["date","value"],"properties":{"date":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"value":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","description":"Final cached price of the UTC day in the requested unit; a decimal string.","example":"3320.1"}}},"ChangeResponse":{"type":"object","additionalProperties":false,"required":["status","metric","metal","currency","unit","start","end","change","change_percent"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"change"},"metal":{"type":"string","enum":["gold","silver","palladium","copper","platinum"]},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"unit":{"type":"string","enum":["troy_oz","gram","kilogram"]},"start":{"$ref":"#/components/schemas/ChangePoint"},"end":{"$ref":"#/components/schemas/ChangePoint"},"change":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","description":"End value minus start value in the requested unit; a decimal string.","example":"12.5"},"change_percent":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","description":"Percentage change relative to the start price, rounded to four decimal places.","example":"0.3781"}}},"GovernmentDebtSeries":{"allOf":[{"$ref":"#/components/schemas/DataSeries"},{"type":"object","required":["scope","basis","unit","frequency","period_type","method","definition","coverage"],"properties":{"coverage":{"type":"object","required":["earliest","latest"],"description":"Full usable stored history by observation period end, independent of the request window.","properties":{"earliest":{"type":"string","format":"date"},"latest":{"type":"string","format":"date"}}},"scope":{"type":"string","enum":["central_government","general_government","public_sector"]},"basis":{"type":"string","enum":["consolidated_gross_debt","debt_held_by_the_public","gross_debt","net_debt","nonfinancial_public_sector_debt"]},"unit":{"type":"string","enum":["aud_millions","cad_millions","chf_millions","eur_millions","gbp_millions","isk_millions","jpy_millions","nok_millions","pen_millions","percent_of_gdp","qar_millions","sgd_millions","usd_millions"]},"frequency":{"type":"string","enum":["monthly","quarterly","annual"]},"period_type":{"type":"string","enum":["point_in_time","month","quarter","fiscal_year"]},"method":{"type":"string","enum":["reported","derived_ratio","derived_cumulative"]},"definition":{"type":"string","description":"Plain-language definition, including the sign convention."},"derivation":{"type":"object","description":"Formula and inputs of a `derived_ratio` or `derived_cumulative` series; omitted for reported series.","required":["formula","inputs"],"properties":{"formula":{"type":"string"},"inputs":{"type":"array","minItems":1,"items":{"type":"object","required":["source_id","source_series_id","description"],"properties":{"source_id":{"type":"string"},"source_series_id":{"type":"string"},"description":{"type":"string"}}}}}}}}]},"GovernmentDebtResponse":{"type":"object","required":["status","metric","country","country_name","start","end","series"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"government_debt"},"country":{"type":"string","enum":["US","GB","AU","IS","EA","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"]},"country_name":{"type":"string","example":"United States"},"start":{"type":["string","null"],"format":"date"},"end":{"type":["string","null"],"format":"date"},"series":{"type":"array","items":{"$ref":"#/components/schemas/GovernmentDebtSeries"}}}},"GovernmentDebtCollectionResponse":{"type":"object","required":["status","metric","countries"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"government_debt"},"countries":{"type":"array","items":{"type":"object","required":["country","country_name","series"],"properties":{"country":{"type":"string","enum":["US","GB","AU","IS","EA","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"]},"country_name":{"type":"string","example":"United States"},"series":{"type":"array","items":{"$ref":"#/components/schemas/GovernmentDebtSeries"}}}}}}},"GovernmentBorrowingSeries":{"allOf":[{"$ref":"#/components/schemas/DataSeries"},{"type":"object","required":["scope","basis","unit","frequency","period_type","method","definition","coverage"],"properties":{"coverage":{"type":"object","required":["earliest","latest"],"description":"Full usable stored history by observation period end, independent of the request window.","properties":{"earliest":{"type":"string","format":"date"},"latest":{"type":"string","format":"date"}}},"scope":{"type":"string","enum":["central_government","general_government","public_sector"]},"basis":{"type":"string","enum":["net_borrowing","net_lending_or_borrowing","surplus_or_deficit"]},"unit":{"type":"string","enum":["cad_millions","chf_millions","eur_millions","gbp_millions","isk_millions","nok_millions","usd_millions"]},"frequency":{"type":"string","enum":["monthly","quarterly","annual"]},"period_type":{"type":"string","enum":["point_in_time","month","quarter","fiscal_year"]},"method":{"type":"string","enum":["reported","derived_ratio","derived_cumulative"]},"definition":{"type":"string","description":"Plain-language definition, including the sign convention."},"derivation":{"type":"object","description":"Formula and inputs of a `derived_ratio` or `derived_cumulative` series; omitted for reported series.","required":["formula","inputs"],"properties":{"formula":{"type":"string"},"inputs":{"type":"array","minItems":1,"items":{"type":"object","required":["source_id","source_series_id","description"],"properties":{"source_id":{"type":"string"},"source_series_id":{"type":"string"},"description":{"type":"string"}}}}}}}}]},"GovernmentBorrowingResponse":{"type":"object","required":["status","metric","country","country_name","start","end","series"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"government_borrowing"},"country":{"type":"string","enum":["US","GB","IS","EA","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"]},"country_name":{"type":"string","example":"United States"},"start":{"type":["string","null"],"format":"date"},"end":{"type":["string","null"],"format":"date"},"series":{"type":"array","items":{"$ref":"#/components/schemas/GovernmentBorrowingSeries"}}}},"GovernmentBorrowingCollectionResponse":{"type":"object","required":["status","metric","countries"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"government_borrowing"},"countries":{"type":"array","items":{"type":"object","required":["country","country_name","series"],"properties":{"country":{"type":"string","enum":["US","GB","IS","EA","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"]},"country_name":{"type":"string","example":"United States"},"series":{"type":"array","items":{"$ref":"#/components/schemas/GovernmentBorrowingSeries"}}}}}}},"DebtInterestSeries":{"allOf":[{"$ref":"#/components/schemas/DataSeries"},{"type":"object","required":["scope","basis","unit","frequency","period_type","method","definition","coverage"],"properties":{"coverage":{"type":"object","required":["earliest","latest"],"description":"Full usable stored history by observation period end, independent of the request window.","properties":{"earliest":{"type":"string","format":"date"},"latest":{"type":"string","format":"date"}}},"scope":{"type":"string","enum":["central_government","general_government"]},"basis":{"type":"string","enum":["interest_expenditure","interest_payable"]},"unit":{"type":"string","enum":["cad_millions","eur_millions","gbp_millions","isk_millions","nok_millions"]},"frequency":{"type":"string","enum":["monthly","quarterly","annual"]},"period_type":{"type":"string","enum":["point_in_time","month","quarter","fiscal_year"]},"method":{"type":"string","enum":["reported","derived_ratio","derived_cumulative"]},"definition":{"type":"string","description":"Plain-language definition, including the sign convention."},"derivation":{"type":"object","description":"Formula and inputs of a `derived_ratio` or `derived_cumulative` series; omitted for reported series.","required":["formula","inputs"],"properties":{"formula":{"type":"string"},"inputs":{"type":"array","minItems":1,"items":{"type":"object","required":["source_id","source_series_id","description"],"properties":{"source_id":{"type":"string"},"source_series_id":{"type":"string"},"description":{"type":"string"}}}}}}}}]},"DebtInterestResponse":{"type":"object","required":["status","metric","country","country_name","start","end","series"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"debt_interest"},"country":{"type":"string","enum":["GB","IS","EA","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"]},"country_name":{"type":"string","example":"United States"},"start":{"type":["string","null"],"format":"date"},"end":{"type":["string","null"],"format":"date"},"series":{"type":"array","items":{"$ref":"#/components/schemas/DebtInterestSeries"}}}},"DebtInterestCollectionResponse":{"type":"object","required":["status","metric","countries"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"debt_interest"},"countries":{"type":"array","items":{"type":"object","required":["country","country_name","series"],"properties":{"country":{"type":"string","enum":["GB","IS","EA","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"]},"country_name":{"type":"string","example":"United States"},"series":{"type":"array","items":{"$ref":"#/components/schemas/DebtInterestSeries"}}}}}}},"MarketIndicatorObservation":{"type":"object","additionalProperties":false,"required":["date","value","period_start"],"properties":{"date":{"type":"string","format":"date","description":"Year end (31 December).","example":"2022-12-31"},"value":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","description":"Metric tonnes as a decimal string.","example":"3160"},"period_start":{"type":"string","format":"date","description":"Year start (1 January).","example":"2022-01-01"},"estimated":{"type":"boolean","description":"Present when USGS identifies an observation as estimated; true means the published value or year is an estimate."}}},"MarketIndicatorSeries":{"type":"object","additionalProperties":false,"required":["id","label","unit","frequency","method","geography","category","definition","collected_at","freshness","source","observations"],"properties":{"id":{"type":"string","description":"Series id, unique within the response.","example":"world-mine-production"},"label":{"type":"string","example":"World gold mine production"},"unit":{"type":"string","enum":["metric_tonnes"]},"frequency":{"type":"string","enum":["annual"]},"method":{"type":"string","enum":["reported"]},"geography":{"type":"string","enum":["world","US"],"description":"Whether the series is a global measure or a United States indicator."},"category":{"type":"string","enum":["supply","recycling_indicator","consumption_indicator","trade_indicator"],"description":"What the series indicates; none is a total-demand or market-balance measure."},"definition":{"type":"string","description":"What the series measures, including its limits."},"collected_at":{"type":["string","null"],"format":"date-time","description":"When Bullion API last successfully collected the source; null before the first collection.","example":"2026-10-07T07:55:04.000Z"},"freshness":{"type":"string","enum":["current","stale"],"description":"Whether collection is up to date. `stale` means the scheduled collection is overdue; it does not describe the age of the data, which USGS publishes with a lag of several years."},"source":{"type":"object","additionalProperties":false,"required":["attribution","notice"],"description":"Institution attribution and reuse terms only; upstream dataset identity is not exposed.","properties":{"attribution":{"type":"string","example":"Source: U.S. Geological Survey."},"notice":{"type":"string","example":"U.S. Geological Survey data are in the U.S. public domain. Credit: U.S. Geological Survey. The USGS does not endorse this product. These are partial market indicators, not a complete supply-and-demand balance: world figures cover mine production only, and recycling, consumption and trade figures are for the United States."}}},"observations":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/MarketIndicatorObservation"}}}},"MarketIndicatorsResponse":{"type":"object","additionalProperties":false,"required":["status","metric","metal","start","end","series"],"properties":{"status":{"type":"string","enum":["success"]},"metric":{"type":"string","example":"gold-mine-production"},"metal":{"type":"string","enum":["gold","silver"]},"start":{"type":["string","null"],"format":"date"},"end":{"type":["string","null"],"format":"date"},"series":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/MarketIndicatorSeries"}}}},"MonetarySeries":{"allOf":[{"$ref":"#/components/schemas/DataSeries"},{"type":"object","required":["scope","basis","period_type","definition","adjustment","stock_semantics","accounting_basis","observation_basis","source_unit","source_unit_factor","source"],"properties":{"scope":{"type":"string"},"basis":{"type":"string"},"unit":{"type":"string","enum":["percent","aud","cad","dkk","eur","gbp","myr","nok","sgd","uah","usd"]},"frequency":{"type":"string","enum":["weekly","monthly","quarterly","annual"]},"method":{"type":"string","enum":["latest","monthly_average","month_end","derived_monthly_average","survey_expectation","derived_growth","reported","derived_ratio","derived_cumulative"],"description":"Current methodology for the latest period only. For historical periods, use each observation method and methodology_history."},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 denomination of the underlying monetary quantity, when applicable."},"period_type":{"type":"string","enum":["point_in_time","week","month","quarter","fiscal_year"]},"definition":{"type":"string","description":"Source-specific definition of this series."},"adjustment":{"type":"string","enum":["seasonally_adjusted","not_seasonally_adjusted","not_specified","not_applicable"]},"stock_semantics":{"type":"string","enum":["period_end","period_average","not_specified","not_applicable"],"description":"Current stock semantics for the latest period only. For historical periods, use each observation and methodology_history."},"methodology_history":{"type":"array","description":"Inclusive, continuous, cadence-aligned methodology periods. effective_through is inclusive; null means the latest methodology continues. The top-level method and stock_semantics describe only the latest methodology.","items":{"$ref":"#/components/schemas/MonetaryMethodologyEpoch"}},"observations":{"type":"array","description":"Each observation includes the method and stock semantics resolved for its period.","items":{"$ref":"#/components/schemas/MonetaryObservation"}},"accounting_basis":{"type":"string","enum":["accounting","statistical","not_specified","not_applicable"],"description":"Published balance-sheet presentation: financial-statement accounting or statistical. This describes the published series, not the underlying systems used to compile it; not_specified is used when the source does not identify the presentation."},"observation_basis":{"type":"string","enum":["source_period","reference_period"],"description":"Whether a date identifies the source period directly or is only a canonical index for a source reference period."},"source_unit":{"type":"string","enum":["percent","currency_units","currency_thousands","currency_millions","currency_billions","currency_trillions"],"description":"The native unit in which the source publishes the value before normalization."},"source_unit_factor":{"type":"string","pattern":"^\\d+$","description":"Exact decimal-string factor multiplied by the source value to obtain the served base-currency unit."},"derivation":{"type":"object","required":["formula","inputs"],"properties":{"formula":{"type":"string"},"inputs":{"type":"array","minItems":1,"items":{"type":"object","required":["source_id","source_series_id","description"],"properties":{"source_id":{"type":"string"},"source_series_id":{"type":"string"},"description":{"type":"string"}}}}}}}}]},"MonetaryMethodologyEpoch":{"type":"object","additionalProperties":false,"required":["effective_from","effective_through","method","stock_semantics","description"],"description":"A source-verified, inclusive period range. Adjacent ranges cover the registered cadence without overlap or gaps; null effective_through denotes the current period.","properties":{"effective_from":{"type":"string","format":"date"},"effective_through":{"type":["string","null"],"format":"date"},"method":{"type":"string","enum":["latest","monthly_average","month_end","derived_monthly_average","survey_expectation","derived_growth","reported","derived_ratio","derived_cumulative"]},"stock_semantics":{"type":"string","enum":["period_end","period_average","not_specified","not_applicable"]},"description":{"type":"string","minLength":1}}},"MonetaryObservation":{"allOf":[{"$ref":"#/components/schemas/SeriesObservation"},{"type":"object","required":["method","stock_semantics"],"properties":{"method":{"type":"string","enum":["latest","monthly_average","month_end","derived_monthly_average","survey_expectation","derived_growth","reported","derived_ratio","derived_cumulative"]},"stock_semantics":{"type":"string","enum":["period_end","period_average","not_specified","not_applicable"]},"methodology_description":{"type":"string","description":"Source-verified description of the methodology applied to this observation period."}}}]},"MoneySupplyResponse":{"type":"object","required":["status","metric","country","country_name","start","end","series"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"money_supply"},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"country_name":{"type":"string"},"start":{"type":["string","null"],"format":"date"},"end":{"type":["string","null"],"format":"date"},"series":{"type":"array","items":{"$ref":"#/components/schemas/MonetarySeries"}}}},"MoneySupplyCollectionResponse":{"type":"object","required":["status","metric","countries"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"money_supply"},"countries":{"type":"array","items":{"type":"object","required":["country","country_name","series"],"properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$"},"country_name":{"type":"string"},"series":{"type":"array","items":{"$ref":"#/components/schemas/MonetarySeries"}}}}}}},"CentralBankBalanceSheetResponse":{"type":"object","required":["status","metric","country","country_name","start","end","series"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"central_bank_balance_sheet"},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"country_name":{"type":"string"},"start":{"type":["string","null"],"format":"date"},"end":{"type":["string","null"],"format":"date"},"series":{"type":"array","items":{"$ref":"#/components/schemas/MonetarySeries"}}}},"CentralBankBalanceSheetCollectionResponse":{"type":"object","required":["status","metric","countries"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"central_bank_balance_sheet"},"countries":{"type":"array","items":{"type":"object","required":["country","country_name","series"],"properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$"},"country_name":{"type":"string"},"series":{"type":"array","items":{"$ref":"#/components/schemas/MonetarySeries"}}}}}}},"CentralBankReserveQualityFlag":{"type":"object","additionalProperties":false,"required":["date","code"],"properties":{"date":{"type":"string","format":"date","example":"2025-12-31"},"code":{"type":"string","const":"inconsistent_source_values","description":"Total reserves are below reserves excluding gold, or a component is negative, so the derived series omit this year."}}},"CentralBankReserveSeries":{"allOf":[{"$ref":"#/components/schemas/DataSeries"},{"type":"object","description":"Reserve series never carry `source`; reserve source metadata stays out of responses.","properties":{"id":{"type":"string","enum":["total_reserves_usd","reserves_excluding_gold_usd","gold_reserve_value_usd","gold_share_pct","annual_gold_value_change_usd"]},"unit":{"type":"string","enum":["usd","percent"]},"frequency":{"type":"string","const":"annual"},"method":{"type":"string","enum":["reported","derived"]},"notes":{"type":"string","description":"How a derived series is calculated, with its caveats. Derived series only."},"quality_flags":{"type":"array","description":"Returned years whose source values are inconsistent. Reported series only; omitted when empty.","items":{"$ref":"#/components/schemas/CentralBankReserveQualityFlag"}}}}]},"CentralBankReservesCountryResponse":{"type":"object","additionalProperties":false,"required":["status","metric","country","country_name","start","end","series"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"central_bank_reserves"},"country":{"type":"string","pattern":"^[A-Z]{2}$","example":"GB"},"country_name":{"type":"string","example":"United Kingdom"},"start":{"type":["string","null"],"format":"date"},"end":{"type":["string","null"],"format":"date"},"series":{"type":"array","items":{"$ref":"#/components/schemas/CentralBankReserveSeries"}}}},"CentralBankReservesCollectionResponse":{"type":"object","additionalProperties":false,"required":["status","metric","countries"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"central_bank_reserves"},"countries":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["country","country_name","series"],"properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$","example":"GB"},"country_name":{"type":"string","example":"United Kingdom"},"series":{"type":"array","items":{"$ref":"#/components/schemas/CentralBankReserveSeries"}}}}}}},"CentralBankGoldSeries":{"allOf":[{"$ref":"#/components/schemas/DataSeries"},{"type":"object","required":["measure","cadence","holdings_basis","stale","provenance","reuse_notice"],"properties":{"id":{"type":"string","description":"The measure and cadence, with a _derived suffix for derived holdings, for example holdings_tonnes_monthly, reported_value_usd_millions_weekly or holdings_tonnes_monthly_derived.","example":"holdings_tonnes_monthly"},"measure":{"type":"string","enum":["holdings_tonnes","holdings_million_fine_troy_oz","holdings_change_tonnes","reported_value_usd_millions","reported_value_change_usd_millions","reported_value_eur_millions","reported_value_pln_millions","reported_value_inr_crores","reported_value_sar_millions","reported_value_sgd_millions"],"description":"holdings_change_tonnes is a stock change, not purchases or sales. reported_value_change_usd_millions is the change in value as published. holdings_tonnes is labelled as converted when normalized from reported weight, or derived when calculated from reported value. reported_value_sgd_millions is a combined gold and foreign-exchange reserve value, not a gold-only figure."},"cadence":{"type":"string","enum":["monthly","weekly","fortnightly","quarterly","irregular"]},"holdings_basis":{"type":"string","enum":["reported","derived"],"description":"reported means the quantity originates in source-reported physical weight; the tonnes series may be a fixed-factor conversion from a reported ounce weight. derived means calculated from reported valuation and gold price."},"stale":{"type":"boolean","description":"True when the newest successful refresh behind the series is more than 45 days old, or when its newest observation is more than six months older than the country’s newest observation in any series (for example a discontinued derivation); stale observations stay visible."},"provenance":{"type":"object","additionalProperties":false,"required":["name","methodology","updated_at"],"properties":{"name":{"type":"string","example":"Synthetic example"},"methodology":{"type":"string"},"updated_at":{"type":["string","null"],"format":"date"}}},"reuse_notice":{"type":"string","description":"Reuse terms covering every observation in the returned series range; derived stock changes also cover the prior observation used. Availability and conditions vary by series.","example":"Synthetic example: Underlying source information may be available free of charge from its original publisher. Identify any changes made to the original source information. Bullion API charges for caching, normalization, and delivery. Source terms and Bullion API plan terms apply; standard plans do not authorize raw-data redistribution or resale."}}}]},"CentralBankGoldCountryResponse":{"type":"object","required":["status","metric","country","country_name","start","end","series"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"central_bank_gold"},"country":{"type":"string","example":"DE"},"country_name":{"type":"string","example":"Germany"},"start":{"type":["string","null"],"format":"date"},"end":{"type":["string","null"],"format":"date"},"series":{"type":"array","items":{"$ref":"#/components/schemas/CentralBankGoldSeries"}}}},"CentralBankGoldCollectionResponse":{"type":"object","required":["status","metric","countries"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"central_bank_gold"},"countries":{"type":"array","items":{"type":"object","required":["country","country_name","series"],"properties":{"country":{"type":"string","example":"DE"},"country_name":{"type":"string","example":"Germany"},"series":{"type":"array","items":{"$ref":"#/components/schemas/CentralBankGoldSeries"}}}}}}},"CentralBankGoldBadRequestError":{"type":"object","required":["status","error"],"properties":{"status":{"type":"string","const":"error"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_country","missing_params","invalid_date","invalid_range"]},"message":{"type":"string"}}}}},"CentralBankBadRequestError":{"type":"object","additionalProperties":false,"required":["status","error"],"properties":{"status":{"type":"string","const":"error"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_country","invalid_date","invalid_range","missing_params"]},"message":{"type":"string"}}}}},"CountryDatasets":{"type":"object","required":["country","country_name","aliases","datasets"],"properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$","example":"GB"},"country_name":{"type":"string","example":"United Kingdom"},"aliases":{"type":"array","description":"Accepted lower-case path aliases, such as `uk` for GB and `eu` for EA.","items":{"type":"string","example":"uk"}},"datasets":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["metric","path"],"properties":{"metric":{"type":"string","enum":["policy_rates","inflation","bond_yields","government_debt","government_borrowing","debt_interest","money_supply","central_bank_balance_sheet","central_bank_gold","central_bank_reserves"]},"path":{"type":"string","example":"/v1/inflation/gb"}}}}}},"CountriesResponse":{"type":"object","additionalProperties":false,"required":["status","countries"],"properties":{"status":{"type":"string","const":"success"},"countries":{"type":"array","items":{"$ref":"#/components/schemas/CountryDatasets"}}}},"CountryResponse":{"allOf":[{"type":"object","required":["status"],"properties":{"status":{"type":"string","const":"success"}}},{"$ref":"#/components/schemas/CountryDatasets"}]},"InvalidCountryError":{"type":"object","additionalProperties":false,"required":["status","error"],"properties":{"status":{"type":"string","const":"error"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","const":"invalid_country"},"message":{"type":"string"}}}}},"UsageResponse":{"type":"object","required":["plan","limit","used","remaining","reset_at","subscription","recent","email","email_verified"],"properties":{"plan":{"type":"string","enum":["free","pro","business"]},"limit":{"type":"integer","description":"Monthly request cap for the plan."},"used":{"type":"integer","description":"Requests used this month."},"remaining":{"type":"integer"},"reset_at":{"type":"string","format":"date-time"},"subscription":{"type":"object","required":["status"],"properties":{"status":{"type":["string","null"],"description":"Stripe subscription status, or null on the free plan."}}},"recent":{"type":"array","description":"The 50 most recent API requests, newest first.","items":{"$ref":"#/components/schemas/RecentRequest"}},"email":{"type":"string","format":"email"},"email_verified":{"type":"boolean"}}},"RecentRequest":{"type":"object","required":["endpoint","method","status_code","response_ms","requested_at"],"properties":{"endpoint":{"type":"string","example":"/v1/gold/price?currency=USD"},"method":{"type":"string","example":"GET"},"status_code":{"type":"integer","example":200},"response_ms":{"type":"integer"},"requested_at":{"type":"string","format":"date-time"}}},"HealthResponse":{"type":"object","required":["status","db_reachable","last_refresh_at","currencies_with_data","fx_snapshot_status","last_fx_snapshot_at","projected_currencies_with_data"],"properties":{"status":{"type":"string","const":"ok"},"db_reachable":{"type":"boolean"},"last_refresh_at":{"type":["string","null"],"format":"date-time","description":"ISO 8601 time of the last successful cache refresh."},"currencies_with_data":{"type":"array","items":{"type":"string"},"description":"Base currencies with at least one cached metal price."},"fx_snapshot_status":{"type":"string","enum":["disabled","unavailable","fresh","partial","stale"],"description":"Freshness state for the enabled projected-currency FX snapshot."},"last_fx_snapshot_at":{"type":["string","null"],"format":"date-time","description":"Completion time of the latest accepted daily FX snapshot, or null when unavailable."},"projected_currencies_with_data":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{3}$"},"description":"Enabled projected currencies with all five metal prices materialised with FX provenance."}}},"SeriesObservation":{"type":"object","additionalProperties":false,"required":["date","value"],"properties":{"date":{"type":"string","description":"Period end as YYYY-MM-DD, or the observation instant for intraday data. For weekly monetary reference periods, the canonical Sunday is an index and not the stock measurement date.","example":"2024-01-31"},"value":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","description":"Decimal string; never a JSON number.","example":"4.06"},"period_start":{"type":"string","description":"Start of a flow period, or Monday boundary for a reference-period ISO week; omitted for point-in-time values.","example":"2024-01-01"},"original_reference_period":{"type":"string","pattern":"^\\d{4}-W\\d{2}$","description":"Original ISO week label when date is only the canonical weekly period index, not an observation instant.","example":"2026-W01"},"status":{"type":"string","enum":["actual","provisional","revised"],"description":"Official source status where published; omitted when the source provides no status.","example":"provisional"},"method":{"type":"string","enum":["latest","monthly_average","month_end","derived_monthly_average","survey_expectation","derived_growth","reported","derived_ratio","derived_cumulative"],"description":"Period-resolved method; required for monetary observations."},"stock_semantics":{"type":"string","enum":["period_end","period_average","not_specified","not_applicable"],"description":"Period-resolved monetary stock semantics, when applicable."},"methodology_description":{"type":"string","description":"Source-verified explanation of the methodology applied to this observation period."}}},"SeriesSource":{"type":"object","additionalProperties":false,"required":["id","series_id","attribution"],"description":"Source of the series. For a derived series `id` is the collecting or deriving source, not the sole provenance; see `attribution` and, where present, the series `derivation`.","properties":{"id":{"type":"string","example":"us_treasury"},"series_id":{"type":"string","description":"Upstream series identifier."},"attribution":{"type":"string","example":"U.S. Department of the Treasury"},"notice":{"type":"string","description":"Applicable source reuse, adaptation, non-endorsement or paid-access notice, when required."}}},"DataSeries":{"type":"object","required":["id","label","unit","frequency","method","observations"],"properties":{"id":{"type":"string","example":"treasury_nominal_yield_10y"},"label":{"type":"string","example":"10-year Treasury yield (nominal)"},"unit":{"type":"string","example":"percent"},"frequency":{"type":"string","example":"monthly"},"method":{"type":"string","example":"monthly_average"},"source":{"$ref":"#/components/schemas/SeriesSource","description":"Omitted for central-bank reserve and gold holdings data. For a derived series `source.id` is the collecting or deriving source, not the sole provenance; see `attribution` and, where present, `derivation`."},"observations":{"type":"array","items":{"$ref":"#/components/schemas/SeriesObservation"}}}},"PolicyRatesSeries":{"allOf":[{"$ref":"#/components/schemas/DataSeries"},{"type":"object","required":["source"],"properties":{"frequency":{"type":"string","const":"daily"}}}]},"InflationSeries":{"allOf":[{"$ref":"#/components/schemas/DataSeries"},{"type":"object","required":["basis","source"],"properties":{"basis":{"type":"string","enum":["year_over_year","breakeven","implied","expectation"]},"tenor":{"type":"string","enum":["12m","2y","5y","10y","30y"],"description":"Maturity of a breakeven or implied rate, or the horizon of a survey expectation."}}}]},"BondYieldsSeries":{"allOf":[{"$ref":"#/components/schemas/DataSeries"},{"type":"object","required":["basis","tenor","source"],"properties":{"basis":{"type":"string","enum":["nominal","real"]},"tenor":{"type":"string","enum":["2y","5y","10y","30y"]}}}]},"PolicyRatesResponse":{"type":"object","required":["status","metric","country","country_name","start","end","series"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"policy_rates"},"country":{"type":"string","pattern":"^[A-Z]{2}$","example":"US"},"country_name":{"type":"string","example":"United States"},"start":{"type":["string","null"],"format":"date"},"end":{"type":["string","null"],"format":"date"},"series":{"type":"array","items":{"$ref":"#/components/schemas/PolicyRatesSeries"}}}},"PolicyRatesCollectionResponse":{"type":"object","required":["status","metric","countries"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"policy_rates"},"countries":{"type":"array","items":{"type":"object","required":["country","country_name","series"],"properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$","example":"US"},"country_name":{"type":"string","example":"United States"},"series":{"type":"array","items":{"$ref":"#/components/schemas/PolicyRatesSeries"}}}}}}},"InflationResponse":{"type":"object","required":["status","metric","country","country_name","start","end","series"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"inflation"},"country":{"type":"string","pattern":"^[A-Z]{2}$","example":"US"},"country_name":{"type":"string","example":"United States"},"start":{"type":["string","null"],"format":"date"},"end":{"type":["string","null"],"format":"date"},"series":{"type":"array","items":{"$ref":"#/components/schemas/InflationSeries"}}}},"InflationCollectionResponse":{"type":"object","required":["status","metric","countries"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"inflation"},"countries":{"type":"array","items":{"type":"object","required":["country","country_name","series"],"properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$","example":"US"},"country_name":{"type":"string","example":"United States"},"series":{"type":"array","items":{"$ref":"#/components/schemas/InflationSeries"}}}}}}},"BondYieldsResponse":{"type":"object","required":["status","metric","country","country_name","start","end","series"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"bond_yields"},"country":{"type":"string","pattern":"^[A-Z]{2}$","example":"US"},"country_name":{"type":"string","example":"United States"},"start":{"type":["string","null"],"format":"date"},"end":{"type":["string","null"],"format":"date"},"series":{"type":"array","items":{"$ref":"#/components/schemas/BondYieldsSeries"}}}},"BondYieldsCollectionResponse":{"type":"object","required":["status","metric","countries"],"properties":{"status":{"type":"string","const":"success"},"metric":{"type":"string","const":"bond_yields"},"countries":{"type":"array","items":{"type":"object","required":["country","country_name","series"],"properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$","example":"US"},"country_name":{"type":"string","example":"United States"},"series":{"type":"array","items":{"$ref":"#/components/schemas/BondYieldsSeries"}}}}}}},"ErrorEnvelope":{"type":"object","additionalProperties":false,"required":["status","error"],"properties":{"status":{"type":"string","const":"error"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["dependency_not_ready","config_error","billing_state_conflict","annual_billing_unavailable","billing_interval_change_conflict","billing_interval_change_expired","billing_interval_change_failed","billing_interval_change_invalid","billing_interval_change_origin_forbidden","billing_interval_change_revalidation_conflict","billing_interval_change_processing","plan_change_conflict","plan_change_expired","plan_change_failed","plan_change_invalid","billing_cancellation_conflict","billing_cancellation_failed","billing_cancellation_invalid","conflicting_credentials","data_unavailable","email_not_verified","invalid_api_key","invalid_country","invalid_currency","invalid_date","invalid_range","invalid_series_filter","invalid_unit","invalid_window","method_not_allowed","missing_api_key","missing_params","no_data","not_found","plan_required","quota_exceeded","rate_limited","unauthenticated","api_key_not_found","insufficient_scope","invalid_portfolio_permission","invalid_price_alert","invalid_digest_preference","price_alert_exists","price_alert_limit","price_alert_not_found","price_alert_conflict","portfolio_not_found","portfolio_currency_locked","missing_idempotency_key","invalid_purchase","invalid_sale","invalid_allocation","idempotency_conflict","invalid_cursor","invalid_limit","invalid_filter","invalid_calendar_year","invalid_tax_year","missing_period","conflicting_periods","transaction_not_found","stale_transaction","transaction_in_use","sale_date_invalid","insufficient_holdings","conflicting_params","invalid_period","no_change_data","invalid_change_baseline","health_degraded","runtime_unavailable","unknown_metal","internal_error","render_error","invalid_json","invalid_email","invalid_request","invalid_token","expired_token"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable message."}},"additionalProperties":true}}},"ChangeBadRequestError":{"type":"object","additionalProperties":false,"required":["status","error"],"properties":{"status":{"type":"string","const":"error"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["missing_params","conflicting_params","invalid_date","invalid_range","invalid_period","invalid_currency","invalid_unit"]},"message":{"type":"string"}}}}},"ChangeNoDataError":{"type":"object","additionalProperties":false,"required":["status","error"],"properties":{"status":{"type":"string","const":"error"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","const":"no_change_data"},"message":{"type":"string"}}}}},"ChangeBaselineError":{"type":"object","additionalProperties":false,"required":["status","error"],"properties":{"status":{"type":"string","const":"error"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","const":"invalid_change_baseline"},"message":{"type":"string"}}}}},"CaratBadRequestError":{"type":"object","additionalProperties":false,"required":["status","error"],"properties":{"status":{"type":"string","const":"error"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_currency","invalid_date"]},"message":{"type":"string"}}}}},"NoDataError":{"type":"object","additionalProperties":false,"required":["status","error"],"properties":{"status":{"type":"string","const":"error"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","const":"no_data"},"message":{"type":"string"}}}}},"QuotaExceededError":{"type":"object","additionalProperties":false,"required":["status","error"],"properties":{"status":{"type":"string","const":"error"},"error":{"type":"object","additionalProperties":false,"required":["code","message","plan","used","limit","reset_at"],"properties":{"code":{"type":"string","const":"quota_exceeded"},"message":{"type":"string","example":"Your monthly usage limit has been reached. Please upgrade your subscription plan."},"plan":{"type":"string","enum":["free","pro","business"]},"used":{"type":"integer"},"limit":{"type":"integer"},"reset_at":{"type":"string","format":"date-time"}}}}},"RateLimitedError":{"type":"object","additionalProperties":false,"required":["status","error"],"properties":{"status":{"type":"string","const":"error"},"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","const":"rate_limited"},"message":{"type":"string","example":"Rate limit exceeded"}}}}}}}}