# VitalityNode Rates API > Exchange rates with a proof. Official rates on a date from 86 publisher tables (central banks of the currency's own country, tax and customs offices, the U.S. Treasury, the UN), the same for every day of a period in one request, official averages over a year or a month (IRS yearly averages, HMRC yearly averages, ECB and Bank of Canada annual and monthly averages), HMRC monthly rates and market prices right now from Hyperliquid spot. Every answer names its source and links a stored copy of the original document with its SHA-256, so the number can be checked without trusting this service. - Base URL: `https://vitalitynode.com/api/v1` - MCP server for assistants (Claude, ChatGPT and others): `https://vitalitynode.com/mcp/rates` - the same numbers as tools, see "MCP server" below. - Machine-readable schema: `https://vitalitynode.com/api/v1/openapi.json` - Every source with its country, currencies, history and terms: `GET /official/sources` (JSON). - Method: `GET` only, query parameters only, JSON responses (`format=short` or `plain` for less). - API catalog (RFC 9727): `https://vitalitynode.com/.well-known/api-catalog`; access and keys: `https://vitalitynode.com/auth.md`. - Send a User-Agent that names your client; the API records it to count agent use. There is no other tracking; what a request leaves in the journal is listed in the privacy policy. - Terms of use: `https://vitalitynode.com/terms/` (rates are returned as published, for information only, not tax or financial advice); privacy policy: `https://vitalitynode.com/privacy/`. - CORS: `GET` from any origin (`Access-Control-Allow-Origin: *`, no credentials), rate-limit and `format=plain` headers exposed; `POST /feedback` is not open cross-origin. ## Rules to rely on 1. A rate answers: how many `quote` for 1 `base`. EUR/USD means `base=EUR"e=USD` and returns USD per 1 EUR. 2. `source` is optional. Default: `ecb`. The source actually used is always in `query.source` and in `result.inputs[].dataset`. 3. The source is never substituted. If the chosen source does not publish the pair, the answer is an error whose message lists the sources that do. A rate from another publisher is never returned instead. 4. `date` is optional. Default: today in UTC. If the source has no rate valid on that date (weekend, holiday, not published yet today), the answer is the latest earlier rate from the same source (at most 14 days older for daily tables, 62 for monthly, 190 for quarterly; older is 400 `stale_publication`), with `method: "fallback_previous"` and `rate_date` set to the date the rate was published for. Otherwise `method: "published"`. Exception, averages (`irs-yearly`, `ecb-annual`, `ecb-monthly`, `boc-annual`, `boc-monthly`, `hmrc-yearly-dec`, `hmrc-yearly-mar`): `date` picks the period that contains it, and there is no fallback. An average not published yet for that period is 400 `period_not_published`; the message names the latest published period. Default `date` (today) usually falls in an unpublished period, so pass `period` (below) or a date inside the period. `period` (YYYY or YYYY-MM) can replace `date`: it means the last day of that year or month. For averages this selects the period: `period=2025` is the 2025 average, `period=2026-10` the October 2026 average, and for `hmrc-yearly-mar` `period=2026-03` is the 12 months to 31 March 2026. `date` and `period` together are 400 `invalid_parameters`. The query echo shows both (`query.period`, and `query.date` resolved). 5. Numbers are decimal strings, never floats. Keep them as strings; do not round them again. 6. A value taken as published is returned unchanged (`derivation.type: "as_published"`, `rounding: null`). A computed value is rounded to 6 significant digits but not fewer than 6 decimal places, `ROUND_HALF_UP`; the rule is in `result.rounding`. 7. Publishers disagree on the same day, and each is right by its own method (different time of day, cadence, purpose). Choose the publisher the user's rule requires; do not average them. 8. `official` here means published by a public body, not always by the state whose currency it is. `result.issuer_of` lists which of the two currencies the publisher's own state (or currency union) issues: `["RUB"]` for the Bank of Russia on USD/RUB, `[]` for the UN Treasury on USD/SOS or the ECB on USD/JPY. Empty means the publisher's own rate for its own purposes, not the currency's official rate. The official vs street rates below use only the rate a state declares for its own currency. ## Simplest answers - `GET /official/rate?base=EUR"e=USD&format=plain` → `1.1165` (text, just the number; date, source and proof link in the headers `X-Rate-Date`, `X-Rate-Source`, `X-Rate-Method`, `X-Proof-URL`). - `GET /official/rate?base=EUR"e=USD&format=short` → `{"base": "EUR", "quote": "USD", "rate": "1.1165", "date": "2026-11-06", "method": "fallback_previous", "source": "ecb", "issuer_of": ["EUR"], "attribution": "Source: ECB statistics.", "proof": "https://vitalitynode.com/lab/rates/proof/.json"}`; averages and quarterly rates add `"period"` (for example `"2025"`). - A rate for every day of a period, one request: `GET /official/series?base=EUR"e=USD&from=2026-01-01&to=2026-11-10` (up to 366 days; `format=csv` for a file). - Default (`format=full`) is the whole proof, described below. `short` also works for `/official/rates` (several currencies); `plain` is for one currency. - Errors keep their status: JSON for `full` and `short`, `code: message` text for `plain`. - Code that needs a rate: fetch once a day, keep the last good value if the call fails, store `source` and `date` next to the number. Ready snippets (Python, JavaScript, shell): https://vitalitynode.com/api/v1/docs/ (section "Instead of a hardcoded rate"). ## Which source for which task What each publisher says its rates are for. Which rate a specific filing requires is the user's call; when unsure, say which source you used (the answer names it). | Task | `source` | Request | |---|---|---| | A rate on a date, no rule given | `ecb` (default) | `base=EUR"e=USD&date=2026-11-06` | | U.S. tax return, income received during the year: IRS yearly average | `irs-yearly` | `base=USD"e=EUR&source=irs-yearly&period=2025` | | FBAR: U.S. Treasury rate for the last day of the year | `us-treasury` | `base=USD"e=EUR&source=us-treasury&date=2026-01-01` (the rate with effective date 2025-12-31) | | U.S. government reporting rate for a quarter | `us-treasury` | `date` inside the quarter | | UK: HMRC yearly average, year to 31 March | `hmrc-yearly-mar` | `base=GBP"e=USD&source=hmrc-yearly-mar&period=2026-03` | | UK: HMRC yearly average, calendar year | `hmrc-yearly-dec` | `period=2025` | | UK: HMRC monthly rate (customs and VAT) | `hmrc-monthly` | `period=2026-11` or a `date` | | Canada: rate on the day an amount arose (the CRA points to Bank of Canada rates) | `boc` | `base=USD"e=CAD&source=boc&date=...` | | Canada: amounts paid at various times in the year (CRA: annual average) | `boc-annual` | `period=2025` | | Euro accounts: average over a month or a year | `ecb-monthly`, `ecb-annual` | `period=2026-10`, `period=2025` | | Noon buying rate in New York (certified for U.S. customs) | `frb-h10` | `date` | | Czech koruna | `cnb` | `date` | | Peru: SUNAT tax rate (tipo de cambio SUNAT), selling | `sunat` | `base=USD"e=PEN&source=sunat&date=...`; before 2026-11-13 use `sbs-venta` on the previous business day | | Indonesia: JISDOR reference rate (kurs BI) | `bi-jisdor` | `base=USD"e=IDR&source=bi-jisdor&date=...` | | Crypto price right now | `/market/quote` | `base=BTC"e=USDT` | | A rate for every day of a year | any | `/official/series?base=USD"e=TRY&source=tcmb&from=2025-01-01&to=2025-12-31` | | Which tables exist for a country or a currency | | `/official/sources` (filter by `country` or `currencies`) | Several currencies at once: `GET /official/rates` with `quote=EUR,GBP,JPY` (below). ## GET /official/rate Official rate of one publisher on one date, with its proof. | Parameter | Required | Format | Default | Notes | |---|---|---|---|---| | `base` | yes | ISO 4217 code, case-insensitive | | The currency being priced | | `quote` | yes | ISO 4217 code | | The currency of the price | | `source` | no | `ecb` or any code from Sources below (`GET /official/sources`) | `ecb` | Publisher table | | `date` | no | `YYYY-MM-DD` | today in UTC | Not before the source's history start; not in the future (checked against UTC+14, so "today" anywhere on Earth is accepted) | | `period` | no | `YYYY` or `YYYY-MM` | | Instead of `date`: the last day of that year or month; selects the period of an average | | `format` | no | `full`, `short`, `plain` | `full` | `short`: rate, date, source, proof link; `plain`: only the number | How the value is derived (`result.derivation.type`): | Type | When | Formula | |---|---|---| | `as_published` | The source publishes `quote` per 1 `base` | `obs_value` | | `per_unit` | The source publishes per N units (CNB: CZK per 100 THB) | `obs_value / N` | | `inverse` | The source publishes the other direction | `N / obs_value` | | `cross` | Neither currency is the source's pivot; both are published against it | (pivot per 1 `base`) / (pivot per 1 `quote`), two inputs | Validity of a published value (`inputs[].valid_from` to `inputs[].valid_to`): - `ecb`, `frb-h10`, `boc`: the day it was published for. - `cnb`: valid until the next fixing; a Friday fixing covers Saturday and Sunday, so a Sunday request is `published`, not `fallback_previous`. - `us-treasury`: quarterly; a rate with effective date E covers E + 1 day to the end of that quarter. - `un-ore`: monthly; a rate covers its effective date to the end of that month and stays valid until the next rate for that currency. - Tables marked "valid until the next publication" in Sources below (most central banks): a rate stays valid until the next publication, so weekends and holidays are `published`. ### Response 200 ``` proof_version 1 kind "official" request id (UUID of the journal entry), at (UTC time), channel ("api") query base, quote, source, date - as resolved, defaults filled in result base, quote rate decimal string meaning "1 EUR = 1.1165 USD" method "published" | "fallback_previous" rate_date date of the publication the rate comes from issuer_of which of base and quote the publisher's own state issues ([] if neither) derivation type, formula, note rounding rule, places, mode - or null when as_published inputs[] one item, or two for a cross (role "base_leg", "quote_leg"; otherwise "only") agency, jurisdiction, dataset, dataset_name attribution credit line required by the publisher terms_url publisher's terms of use notice publisher's caveat, or null series_key publisher's series code, e.g. "EXR.D.USD.EUR.SP00.A" measure, unit e.g. "USD per 1 EUR" time_period, valid_from, valid_to obs_value the number exactly as published obs_status, decimals publication_url URL of this value at the publisher publication_date recorded_at when this value entered the database document url (where it was downloaded), sha256, retrieved_at, last_modified, download_url (stored copy; null with copy_note when the publisher's terms forbid copies) ``` ### Sources | `source` | Publisher: table | Country | Pivot | History from | Latest value | Cadence | Notes | |---|---|---|---|---|---|---|---| | `dab` | Da Afghanistan Bank: Exchange rates (USD, cash selling) | Afghanistan | AFN | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. AFN per 1 USD, cash selling rate. | | `boa-al` | Bank of Albania: Official exchange rate (USD) | Albania | ALL | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. ALL per 1 USD, official (fixed) rate. | | `boa-dz` | Bank of Algeria: Daily exchange rate (USD) | Algeria | DZD | 2024-11-01 | 2026-11-17 | Daily | Business days. DZD per 1 USD. The bank's site keeps only the current day; history comes from Internet Archive copies of that page, and days between copies carry the last published value. | | `bna` | Banco Nacional de Angola: Reference exchange rate (mid) | Angola | AOA | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. AOA per 1 USD. | | `bcra` | Banco Central de la República Argentina: Reference exchange rate, Communication A 3500 | Argentina | ARS | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days, after the close of the wholesale market. Wholesale reference rate, ARS per 1 USD. | | `cba` | Central Bank of Armenia: Exchange rate (USD) | Armenia | AMD | 2024-11-01 | 2026-11-16 | Daily, valid until the next publication | Business days. AMD per 1 USD. | | `rba` | Reserve Bank of Australia: Exchange rates (USD) | Australia | AUD | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. Published as USD per 1 AUD (WM/Reuters 4pm Sydney fix); AUD per USD is the inverse. | | `cbar` | Central Bank of the Republic of Azerbaijan: Official exchange rate (USD) | Azerbaijan | AZN | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. AZN per 1 USD, official rate. | | `nbrb` | National Bank of the Republic of Belarus: Official exchange rate (USD) | Belarus | BYN | 2024-11-01 | 2026-11-18 | Daily, valid until the next publication | Business days. BYN per 1 USD. | | `bcb-bo` | Banco Central de Bolivia: Official exchange rate (TCO) | Bolivia, Plurinational State of | BOB | 2026-06-27 | 2026-11-17 | Daily, valid until the next publication | Business days. BOB per 1 USD. The TCO (weighted median of banks' dollar purchases from clients) replaced the fixed rate on 2026-06-27; the series starts there. | | `bob-bw` | Bank of Botswana: Exchange rates (USD) | Botswana | BWP | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. Published as USD per 1 BWP with 4 decimals; BWP per USD is the inverse (precision about 0.07%). | | `bcb-ptax` | Banco Central do Brasil: PTAX exchange rate (selling) | Brazil | BRL | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. BRL per 1 USD, PTAX selling rate. | | `boc` | Bank of Canada: Daily exchange rates | Canada | CAD | 2017-01-03 | 2026-11-17 | Daily | Once each business day by 16:30 ET. Indicative rates, released by the Bank of Canada for statistical and analytical purposes only. | | `boc-annual` | Bank of Canada: Annual exchange rates (annual average) | Canada | CAD | 2017-01-01 | 2025-01-01 | Yearly average | On the last business day of the year by 12:30 ET. Indicative annual averages, for statistical and analytical purposes only. | | `boc-monthly` | Bank of Canada: Monthly exchange rates (monthly average) | Canada | CAD | 2017-01-01 | 2026-10-01 | Monthly average | After the end of the month. Indicative monthly averages, for statistical and analytical purposes only. | | `bcch-observado` | Banco Central de Chile: Dólar observado (USD) | Chile | CLP | 2024-11-01 | 2026-11-18 | Daily, valid until the next publication | Banking days; computed from the previous banking day's transactions. CLP per 1 USD, the 'dólar observado' of the Central Bank of Chile, published in the Diario Oficial; dated by the day it applies to. | | `cfets` | China Foreign Exchange Trade System: Central parity of the RMB (USD) | China | CNY | 2024-11-01 | 2026-11-18 | Daily, valid until the next publication | Business days. CNY per 1 USD, central parity announced by CFETS as authorized by the People's Bank of China. | | `trm` | Superintendencia Financiera de Colombia: TRM (Tasa Representativa del Mercado) | Colombia | COP | 2024-11-01 | 2026-11-18 | Daily, valid until the next publication | Business days. COP per 1 USD; a TRM covers its validity period, so Friday's rate covers the weekend. | | `bcc-cd` | Banque Centrale du Congo: Indicative exchange rate (USD) | Congo, The Democratic Republic of the | CDF | 2024-11-01 | 2026-11-18 | Daily, valid until the next publication | Business days. CDF per 1 USD, indicative rate (cours moyen). | | `bcc` | Banco Central de Cuba: Official exchange rate (state sector) | Cuba | CUP | 2025-12-19 | 2026-11-17 | Daily, valid until the next publication | Daily. CUP per 1 USD for the state sector (24). The bank also publishes 120 and a floating rate; they are not stored. | | `cnb` | Czech National Bank: Central bank exchange rate fixing | Czech Republic | CZK | 1991-01-01 | 2026-11-18 | Daily, valid until the next publication | Every working day at around 2:30 p.m. CET; valid for that day and the following Saturday, Sunday or public holiday. | | `danmarks-nationalbank` | Danmarks Nationalbank: Exchange rates | Denmark | DKK | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days, after the ECB concertation. DKK per 100 units. History of USD from StatBank Denmark (table DNVALD, data of Danmarks Nationalbank). | | `nbe` | National Bank of Ethiopia: Indicative exchange rate (weighted average) | Ethiopia | ETB | 2024-11-01 | 2026-11-18 | Daily, valid until the next publication | Business days. Float since July 2024: banks set their own rates; the NBE rate is indicative. ETB per 1 USD. | | `ecb` | European Central Bank: Euro foreign exchange reference rates | Euro area | EUR | 1999-01-04 | 2026-11-18 | Daily | Around 16:00 CET on TARGET business days. The ECB publishes these reference rates for information purposes only and strongly discourages using them for transactions. | | `ecb-annual` | European Central Bank: Euro foreign exchange reference rates, annual average | Euro area | EUR | 1999-01-01 | 2025-01-01 | Yearly average | After the end of the year. Average of the ECB daily reference rates over the year. The ECB publishes reference rates for information purposes only. | | `ecb-monthly` | European Central Bank: Euro foreign exchange reference rates, monthly average | Euro area | EUR | 1999-01-01 | 2026-10-01 | Monthly average | After the end of the month. Average of the ECB daily reference rates over the month. The ECB publishes reference rates for information purposes only. | | `cbg` | Central Bank of The Gambia: Indicative exchange rate (USD) | Gambia | GMD | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. GMD per 1 USD, the central bank's indicative rate. | | `nbg` | National Bank of Georgia: Official exchange rate (USD) | Georgia | GEL | 2024-11-01 | 2026-11-18 | Daily, valid until the next publication | Business days. GEL per 1 USD; set the day before it applies. | | `bog-gh` | Bank of Ghana: Interbank exchange rate (USD, mid) | Ghana | GHS | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. GHS per 1 USD, interbank mid rate. | | `banguat` | Banco de Guatemala: Reference exchange rate (USD) | Guatemala | GTQ | 2024-11-01 | 2026-11-18 | Daily, valid until the next publication | Business days. GTQ per 1 USD, reference rate; buying and selling are equal; weekends repeat the last business day. | | `mnb` | Magyar Nemzeti Bank: Official exchange rate (USD) | Hungary | HUF | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. HUF per 1 USD. | | `sedlabanki` | Central Bank of Iceland: Official exchange rate (USD, mid) | Iceland | ISK | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. ISK per 1 USD, mid rate. | | `rbi-ref` | Reserve Bank of India: Reference rate (USD) | India | INR | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. INR per 1 USD, reference rate computed and published by FBIL (Financial Benchmarks India), the administrator appointed by the Reserve Bank of India; taken from the RBI reference rate archive. | | `bi-jisdor` | Bank Indonesia: JISDOR reference rate (USD) | Indonesia | IDR | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. IDR per 1 USD, JISDOR (Jakarta Interbank Spot Dollar Rate), the reference rate of Bank Indonesia. | | `cbi-ir` | Central Bank of the Islamic Republic of Iran: Exchange reference rates (USD) | Iran, Islamic Republic of | IRR | 2024-11-01 | 2026-11-17 | Daily | Business days. IRR per 1 USD. Iran has several state rates; this is the central bank's reference table. History before the last 7 days is weekly: days between points carry the last published value. | | `cbi-iq` | Central Bank of Iraq: Price basis of the dollar (USD) | Iraq | IQD | 2024-11-01 | 2026-11-03 | Daily, valid until the next publication | Business days. IQD per 1 USD, the central bank's price basis. | | `boi` | Bank of Israel: Representative exchange rate (USD) | Israel | ILS | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. ILS per 1 USD. | | `boj` | Bank of Japan: US dollar/yen central rate, Tokyo market | Japan | JPY | 2024-11-01 | 2026-11-16 | Daily, valid until the next publication | Business days. JPY per 1 USD. | | `nbk` | National Bank of Kazakhstan: Official exchange rate (USD) | Kazakhstan | KZT | 2024-11-01 | 2026-11-18 | Daily, valid until the next publication | Business days. KZT per 1 USD. | | `kcs-weekly` | Korea Customs Service: Weekly customs exchange rate (USD) | Korea, Republic of | KRW | 2025-11-09 | 2026-11-15 | Weekly | Weekly, valid Sunday to Saturday; checked daily. KRW per 1 USD, weekly customs rate of the Korea Customs Service for imports, valid Sunday to Saturday: the average of the previous week's Monday-Friday basic rate, so it lags the market by about a week. Weeks to 2026-11-08: file from the UNI-PASS weekly rates page, downloaded 2026-11-12. | | `cbk-kw` | Central Bank of Kuwait: Exchange rate (USD) | Kuwait | KWD | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. Published in fils per 1 USD (1 KWD = 1000 fils); stored as KWD per 1000 USD. | | `nbkr` | National Bank of the Kyrgyz Republic: Official exchange rate (USD) | Kyrgyzstan | KGS | 2024-11-01 | 2026-11-18 | Daily, valid until the next publication | Business days. KGS per 1 USD. | | `bol-la` | Bank of the Lao P.D.R.: Reference rate (USD) | Lao People's Democratic Republic | LAK | 2024-11-01 | 2026-11-18 | Daily, valid until the next publication | Business days. LAK per 1 USD, reference rate. | | `cbl-lr` | Central Bank of Liberia: Buying and selling rates (USD, selling) | Liberia | LRD | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. LRD per 1 USD, selling rate. | | `cbl-ly` | Central Bank of Libya: Currency exchange rates (USD, average) | Libya | LYD | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. LYD per 1 USD, average of buy and sell. | | `bfm-mg` | Banky Foiben'i Madagasikara: Interbank market weighted average rate (USD) | Madagascar | MGA | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. MGA per 1 USD, weighted average of the interbank foreign exchange market (MID). | | `rbm-mw` | Reserve Bank of Malawi: Exchange rates (USD, middle) | Malawi | MWK | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. MWK per 1 USD, middle rate. | | `bnm-my` | Bank Negara Malaysia: Kuala Lumpur USD/MYR Reference Rate | Malaysia | MYR | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. MYR per 1 USD. | | `bcm` | Banque Centrale de Mauritanie: Reference exchange rate | Mauritania | MRU | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. MRU per 1 USD; the published fluctuation band is not a rate and is not stored. | | `banxico-fix` | Banco de México: FIX exchange rate (USD) | Mexico | MXN | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Banking days, determined about 12:00 Mexico City time. MXN per 1 USD, FIX determined by Banco de México and published in the Diario Oficial de la Federación; used to settle obligations in US dollars payable in Mexico. Dated by the day of determination. | | `bnm-md` | National Bank of Moldova: Official exchange rate (USD) | Moldova, Republic of | MDL | 2024-11-01 | 2026-11-18 | Daily, valid until the next publication | Business days. MDL per 1 USD. | | `cbn-nfem` | Central Bank of Nigeria: NFEM official exchange rate (weighted average) | Nigeria | NGN | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. The CBN states the NFEM weighted average is the official rate for the day. NGN per 1 USD. | | `norges-bank` | Norges Bank: Exchange rates (USD) | Norway | NOK | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days, ECB concertation time 14:15 CET. NOK per 1 USD. | | `bcp-py` | Banco Central del Paraguay: Reference exchange rate (USD) | Paraguay | PYG | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. PYG per 1 USD, weighted average of interbank spot trades (8:30-13:00). | | `bcrp` | Banco Central de Reserva del Perú: Interbank exchange rate, selling | Peru | PEN | 2024-11-01 | 2026-11-16 | Daily, valid until the next publication | Business days. PEN per 1 USD. | | `sbs-venta` | Banco Central de Reserva del Perú: SBS banking system rate, selling (USD) | Peru | PEN | 2024-11-01 | 2026-11-16 | Daily, valid until the next publication | Business days; BCRP adds a day with a 1-2 day delay. PEN per 1 USD, the weighted average selling rate of the Peruvian banking system published by the SBS (series PD04640PD in BCRPData), dated by the trading day. SUNAT applies it on the next business day. | | `sunat` | SUNAT (Superintendencia Nacional de Aduanas y de Administración Tributaria): SUNAT exchange rate, selling (USD) | Peru | PEN | 2026-11-13 | 2026-11-17 | Daily, valid until the next publication | Business days; the SBS rate of the previous business day. PEN per 1 USD, the exchange rate SUNAT publishes for tax purposes (selling, venta): the SBS weighted average of the previous business day. Collected from 2026-11-13; for earlier dates use source=sbs-venta on the previous business day. | | `bsp` | Bangko Sentral ng Pilipinas: Peso per US dollar rate | Philippines | PHP | 2024-11-01 | 2026-11-18 | Daily, valid until the next publication | Business days. PHP per 1 USD, weighted average of the USD/PHP market on the last trading day, dated by the BSP bulletin. | | `nbp-a` | Narodowy Bank Polski: Table A average exchange rates (USD) | Poland | PLN | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. PLN per 1 USD, table A mid. | | `bnr` | Banca Națională a României: Reference exchange rates | Romania | RON | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. RON per unit (or per the stated multiplier). | | `cbr` | Bank of Russia: Official exchange rates | Russian Federation | RUB | 2024-11-01 | 2026-11-18 | Daily, valid until the next publication | Set on business days for the next day. RUB per the stated number of units. | | `bnr-rw` | National Bank of Rwanda: Exchange rate (USD, average) | Rwanda | RWF | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. RWF per 1 USD, average rate. | | `nbs` | National Bank of Serbia: Official middle exchange rate (USD) | Serbia | RSD | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. RSD per 1 USD, official middle rate. | | `sarb` | South African Reserve Bank: Rand per US dollar (weighted average, 10:30) | South Africa | ZAR | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. Weighted average of the banks' daily rates at about 10:30. ZAR per 1 USD. | | `riksbank` | Sveriges Riksbank: Exchange rate USD, midday | Sweden | SEK | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. SEK per 1 USD. | | `bazg-sell` | Federal Office for Customs and Border Security (FOCBS): Daily exchange rate, sell (USD) | Switzerland | CHF | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days, about 07:00 Zurich time. CHF per 1 USD, daily exchange rate (sell) of the Swiss Federal Office for Customs and Border Security, used for customs declarations and import VAT. The Swiss National Bank publishes no daily rate. No stored copies: the publisher's terms forbid them, the proof links the original. | | `cbs-sy` | Central Bank of Syria: Official exchange bulletin (USD, selling) | Syrian Arab Republic | SYP | 2026-01-01 | 2026-11-05 | Daily, valid until the next publication | Business days. New Syrian pounds per 1 USD (1 new pound = 100 old), selling rate of the official bulletin; bulletins in new pounds start on 2026-01-04. | | `cbc-tw` | Central Bank of the Republic of China (Taiwan): Closing exchange rate NTD/USD | Taiwan, Province of China | TWD | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. TWD per 1 USD, closing rate of the Taipei interbank foreign exchange market. | | `nbt` | National Bank of Tajikistan: Official exchange rate (USD) | Tajikistan | TJS | 2024-11-01 | 2026-11-18 | Daily, valid until the next publication | Business days. TJS per 1 USD. | | `bot-tz` | Bank of Tanzania: Exchange rates (USD, mean) | Tanzania, United Republic of | TZS | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. TZS per 1 USD, mean of buying and selling. | | `bot-th` | Bank of Thailand: Reference rate, weighted-average interbank (USD) | Thailand | THB | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. THB per 1 USD, daily weighted-average interbank exchange rate, the Bank of Thailand's reference rate. | | `cbtt` | Central Bank of Trinidad and Tobago: Daily exchange rates (USD, selling) | Trinidad and Tobago | TTD | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. TTD per 1 USD, weighted average selling rate. | | `bct` | Banque Centrale de Tunisie: Interbank average exchange rate (USD) | Tunisia | TND | 2024-11-01 | 2026-11-16 | Daily, valid until the next publication | Business days. TND per 1 USD, average rate of the interbank market. | | `tcmb` | Central Bank of the Republic of Türkiye: Indicative exchange rates (forex buying) | Türkiye | TRY | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days, 15:30 Istanbul time. Forex buying rate, used for valuation under Turkish law. TRY per the stated number of units. | | `nbu` | National Bank of Ukraine: Official exchange rate of the hryvnia | Ukraine | UAH | 2024-11-01 | 2026-11-18 | Daily, valid until the next publication | Set on business days for the next day. UAH per 1 USD. | | `hmrc-monthly` | HM Revenue & Customs: Monthly exchange rates | United Kingdom | GBP | 2021-01-01 | 2026-11-01 | Monthly | Published in advance, on the penultimate Thursday of the previous month. HMRC monthly rates for customs and VAT, set in advance for the whole month. | | `hmrc-yearly-dec` | HM Revenue & Customs: Average exchange rates, year to 31 December | United Kingdom | GBP | 2020-01-01 | 2025-01-01 | Yearly average | Published on 31 December. Mean of the HMRC monthly exchange rates over the 12 months to the publication date. HMRC publishes these rates for customs and VAT. | | `hmrc-yearly-mar` | HM Revenue & Customs: Average exchange rates, year to 31 March | United Kingdom | GBP | 2019-04-01 | 2025-04-01 | Yearly average | Published on 31 March; covers April of the previous year to March. Mean of the HMRC monthly exchange rates over the 12 months to the publication date. HMRC publishes these rates for customs and VAT. | | `un-ore` | United Nations Treasury: UN Operational Rates of Exchange | United Nations | USD | 2026-11-01 | 2026-11-15 | Monthly, valid until the next publication | Set for each month; each rate carries its own effective date. Only the current month is published. Rates the United Nations uses for its own transactions, per 1 USD. | | `frb-h10` | Board of Governors of the Federal Reserve System: H.10 Foreign Exchange Rates (noon buying rates in New York) | United States | USD | 1971-01-04 | 2026-11-13 | Daily | Weekly, on Mondays at 4:15 p.m. ET (Tuesday after a federal holiday), for the previous business week. Daily values are released once a week, so the latest days of the current week are not available yet. | | `irs-yearly` | Internal Revenue Service: Yearly Average Currency Exchange Rates | United States | USD | 2021-01-01 | 2025-01-01 | Yearly average | Once a year, early in the following year; the page keeps the last five years. The IRS has no official exchange rate and generally accepts any posted rate used consistently. To convert foreign currency to U.S. dollars, divide by the rate. | | `us-treasury` | U.S. Department of the Treasury, Bureau of the Fiscal Service: Treasury Reporting Rates of Exchange | United States | USD | 2001-04-01 | 2026-10-31 | Quarterly | Quarterly, with amendments when a rate deviates by 10% or more. Validity is applied as published guidance reads: a rate with effective date E covers E + 1 day to the end of that quarter. | | `bcu` | Banco Central del Uruguay: Interbank exchange rate (USD) | Uruguay | UYU | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. UYU per 1 USD, interbank rate (DLS. USA BILLETE); buying and selling are equal. | | `cbu` | Central Bank of the Republic of Uzbekistan: Official exchange rate (USD) | Uzbekistan | UZS | 2024-11-01 | 2026-11-18 | Daily, valid until the next publication | Business days. UZS per 1 USD. | | `bcv` | Banco Central de Venezuela: Official exchange rate | Venezuela, Bolivarian Republic of | VES | 2024-11-01 | 2026-11-18 | Daily | Business days; the page shows the rate for the value date. VES per 1 USD from the central bank home page; history from its copies in the Internet Archive (about one every few days). | | `boz-zm` | Bank of Zambia: Average exchange rates (USD, selling) | Zambia | ZMW | 2024-11-01 | 2026-11-17 | Daily, valid until the next publication | Business days. ZMW per 1 USD, official daily average rate, selling. | Collected on each table's schedule, plus a catch-up run of all sources at 03:00 UTC. Currencies each source covers (any pair between two of them, or with the pivot, can be asked): `GET /official/sources` (field `currencies`), or `GET /official/sources?source=ecb` for one table. Some codes exist only in history (for example DEM, FRF, CYP before the euro); a date after the currency stopped being published returns `fallback_previous` to its last rate, check `rate_date`. Year-end Treasury rate (what FBAR asks for: the rate for the last day of the calendar year): `us-treasury` with `date=YYYY-12-31` returns the previous quarter's rate, because a rate with effective date E applies from E + 1 day. The rate with effective date 2025-12-31 is returned for `date=2026-01-01` (check `inputs[].time_period`: `2025-12-31`). The IRS yearly averages are a different thing and are not the FBAR rate. HMRC files print both directions (units per £1 and the sterling value of one unit, 4 decimals). The API uses units per £1 as published; the other direction is calculated, so `base=EUR"e=GBP&source=hmrc-yearly-dec&period=2025` is 0.853461 (1 / 1.1717), while the HMRC file shows 0.8535. Source quirks kept as published: the IRS wrote the 2024 euro rate as `0,924`; the answer's `rate` is `0.924`, the input keeps `obs_value: "0,924"` with `obs_status: "comma"`. The IRS 2021 ruble value `.73.686` is not a number and is not loaded (`no_data`). ECB averages carry up to 16 decimals and are returned exactly as published. ### Verify a proof 1. Download `result.inputs[].document.download_url`. When it is null, the publisher's terms forbid copies (`copy_note`): take the original at `document.url`; it may have changed since `retrieved_at`. 2. Compute SHA-256 of the bytes; it must equal `document.sha256`. 3. Find `obs_value` for `series_key` and `time_period` in the file. 4. Repeat the arithmetic from `derivation.formula` and the rounding from `result.rounding`. The original is also at `document.url` at the publisher; it may have changed since `retrieved_at`, the stored copy has not. ## GET /official/rates Several currencies in one request. Same parameters as `/official/rate`, but `quote` lists up to 30 currencies separated by commas; repeats are dropped. `GET /official/rates?base=USD"e=EUR,GBP,JPY&source=irs-yearly&period=2025` ``` {"results": [ {"quote": "EUR", "proof": { ...the same object /official/rate returns... }, "error": null}, {"quote": "GBP", "proof": { ... }, "error": null}, {"quote": "XXX", "proof": null, "error": {"code": "unknown_currency", "message": "..."}} ]} ``` Each currency is answered on its own and counts as one request toward the daily limit; the per-minute limit counts the whole batch once. 400 `invalid_parameters` if `quote` is empty or lists more than 30. ## GET /official/series The rate of one table for every calendar day of a period, in one request. Each day is the number `/official/rate` returns for that date. | Parameter | Required | Format | Default | |---|---|---|---| | `base`, `quote`, `source` | as in `/official/rate` | | `source=ecb` | | `from` | no | `YYYY-MM-DD` | 29 days before `to` | | `to` | no | `YYYY-MM-DD` | today in UTC | | `format` | no | `json`, `csv` | `json` | At most 366 days (400 `invalid_parameters` above that; ask for several periods). Counts as one request toward the daily limit. ``` query base, quote, source, from, to meaning "USD per 1 EUR" source code, name, agency, jurisdiction, attribution, terms_url, notice, copies_allowed rounding the rule for computed values (as in /official/rate) days[] date, rate, method ("published" | "fallback_previous"), rate_date, derivation, inputs[] (role, series_key, unit, time_period, obs_value, document = SHA-256) or date, rate: null, error: "no_data" | "stale_publication" | "period_not_published" errors what each error code in days[] means documents SHA-256 -> url, retrieved_at, download_url (null with copy_note when copies are forbidden) ``` Weekends and holidays are filled the same way as `/official/rate` (`fallback_previous` with `rate_date`, or `published` for tables valid until the next publication). Averages repeat the period's value on each of its days. CSV columns: `date, base, quote, rate, method, rate_date, error, source, published_values, documents`; the header `X-Attribution` carries the publisher's credit line. ## GET /official/sources Every table: `code` (the `source` value), `name`, `publisher`, `publisher_kind` (`central_bank`, `tax`, `customs`, `treasury`, `regulator`), `country`, `country_name`, `pivot` (the table's own currency), `issuer` (true when the publisher belongs to the state or currency union that issues the pivot), `frequency`, `validity` (`period` or `until_next`), `average`, `periods` (average tables and `hmrc-monthly`: every published period, newest first, as `{"period": "2025", "label": "2025"}` or `{"period": "2026-03", "label": "April 2025 to March 2026"}`; `null` for other tables), `history_from`, `last_published`, `currencies`, `schedule`, `notice`, `legal_note`, `attribution`, `terms_url`, `terms_note`, `copies_allowed`, `homepage_url`. Next to `sources`: `currency_names`, the name of every currency in them (`{"EUR": "Euro", ...}`). `?source=ecb` returns one table. Not counted toward the limits. ## GET /market/quote Market price right now, fetched from the venue at request time. Not for fiat pairs: use `/official/rate`. | Parameter | Required | Values | Default | |---|---|---|---| | `base` | yes | `BTC`, `ETH`, `USDT`, `USDC` | | | `quote` | yes | same | | | `venue` | no | `hyperliquid` | `hyperliquid` | | `on_unavailable` | no | `error`, `fallback` | `error`; with one venue both give 503 | - `result`: `last` (last trade), `bid`, `ask`, `mid`, `meaning`, `venue`, `derivation` (`as_published`, `inverse` or `cross` through USDC), `rounding`, `inputs[]`. - `inputs[]`: `venue_pair` (for example `UBTC/USDC`: on Hyperliquid BTC and ETH are wrapped tokens, see `note`), `last_trade` (`price`, `id`, `hash`, `time`, `side`), `bid`, `ask`, `venue_time`, `received_at`, `raw` (`sha256`, `download_url` of the venue's responses as received). - The same answer is reused for 2 seconds. If the venue does not respond: 503 `venue_unavailable`, never a price from somewhere else. - Spot order book only; not the venue's oracle or mark price. ## POST /feedback Found a wrong number, a missing currency or a broken answer? Tell us; a person reads every message. ``` POST /feedback Content-Type: application/json {"message": "IRS 2024 EUR: the IRS page shows 0,924, you return 0.924", "request_id": "", "email": "optional, for a reply"} ``` 202 `{"status": "received", "id": 17}`. Up to 4000 characters; up to 10 messages a day per key or address (429 above that). No key needed. ## Official vs street rates (beta): GET /atlas/... Per country: the official rate the state itself declares, the street rate (median of trading platforms for the day, USDT taken as 1 USD), the gap between them, and the value lost against USD over a period. Beta: the numbers are still being checked. Same key as above; own daily counter: 1000 requests a day without a key, 10000 with one. Every call, a CSV file included, is one request. | Question | Call | |---|---| | Official and street rate and the gap for every country on a day | `GET /api/v1/atlas/map/gap?date=2026-11-10` | | Which currencies lost the most value this year | `GET /api/v1/atlas/map/risk?period=ytd` (sort by `value_lost`) | | Value lost over 30, 90, 180 or 360 days | `GET /api/v1/atlas/map/risk?period=90` | | The same as a CSV file | add `&format=csv` | | One country with the sources of each number | `GET /api/v1/atlas/countries/NG?period=360` | | Daily series for a currency, up to 400 days | `GET /api/v1/atlas/currencies/NGN/days?from=2026-01-01&to=2026-11-10` | | Facts of the day about market-economy currencies: carry over 360 days, a new street gap, a sharp move, a central bank rate change | `GET /api/v1/atlas/facts?date=2026-11-14` | | US dollar stablecoins (USDT, USDC and 7 more) against the US dollar itself: last full hour and last full day, with venues | `GET /api/v1/atlas/stablecoins` | | Daily series for a stablecoin against the US dollar, up to 400 days | `GET /api/v1/atlas/stablecoins/USDT/days?from=2026-01-01&to=2026-11-16` | - Without `date`: the last full past day (today is still being collected). - Facts: one line of text per fact and the same numbers as the maps and country pages; `rules` says what each kind means. A day with nothing new gives an empty list. Facts, not advice. - Stablecoins: the price is the median of candle closes on Kraken, Bitstamp, Coinbase Exchange and Gemini, pairs against USD only; `deviation_pct` = (price - 1) x 100. `status`: `ok` (two or more venues), `single_venue`, `venues_disagree`, `no_liquid_usd_market` (the coin trades mostly against USDT and USDC). Each venue: `close`, `volume_usd`, `used`, `reason` (`low_volume`, `outlier`, `venues_disagree`), `sha256` of the response and `request_url`; no copies. `rules` gives the thresholds. Observed prices, not advice. - `official` is only what the state itself declares: its own table (`origin: issuer`) or a peg set by law (`legal_parity`). Rates other bodies publish for a currency (the UN, other central banks) are not used here. - `local_names` (one country): what people in the country call the official and the street rate, e.g. `"dólar blue"` in Argentina. Empty lists when we have none. - Every country (one country and map rows): `kind` (`country`, `territory`, `uninhabited`), `currency_name`, `currency_role` (`own`, `union`, `uses` another state's currency, `parallel`). Map rows also carry `street_note`: which street sources were not used for the day and why. - One country also gives: `value_lost_street` (the street rate and its date at the start and the end of the period, daily street rate only), `legal_parity` (`currency_amount` `currency` = `anchor_amount` `anchor`, with `source_url`; when the official rate is a peg set by law), `monthly_street` (WFP and FEWS NET monthly points over the period, in end-of-period units, with `source`), `redenominations` with `source_url`, `day_fact` (`version`, `computed_at`, `formula` of the day's record). - No number: `null` and `na` with `code` and `text`. Codes: `no_official_rate` (issuer table not connected yet), `state_publishes_no_rate`, `no_street_rate`, `street_rate_not_used`, `no_street_rate_for_period`, `start_rate_not_used`, `street_official_disagree`, `possible_redenomination`, `bad_day`, `uses_usd`, `no_currency`. - Gap = street / official − 1. Value lost = 1 − rate(start) / rate(end); below zero the currency gained. `group` is the colour group of the map; `legend` lists the bounds. - Freely traded currencies are checked against the official rate: a street source more than 10% off it is not used, and value lost is n/a when street and official disagree by more than 5 points over the period. - Proof: an official rate links the document it comes from (`download_url` to our copy, or `original_url` with `copy_note` when the source's terms do not allow copies) and carries the source's `attribution`. Street inputs are our numbers per platform and the SHA-256 of the raw response; raw platform responses are not published. - Attribution for the atlas numbers: "Source: VitalityNode exchange rate data". ## Keys and limits - No key: counted per IP address. With a key: per account. Send `Authorization: Bearer `. Get a key: sign in at https://vitalitynode.com/lab/rates/keys/ | | No key | Free account | |---|---|---| | Official requests | 1,000 a day | 10,000 a day | | Market requests | 20 a month | 100 a month | | Per minute | 10 | 30 | - Days and months are calendar periods in UTC. Successful responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`. - Above about 60 requests a minute from one IP address, with or without a key, the web server answers 429 with an HTML page (not JSON, no `Retry-After`). Wait a few seconds and repeat. ## Paid answers (x402) Above the free limit the API does not refuse: it answers `402 Payment Required` with a price in USDC on the Base network (x402 v2, the price is in the `PAYMENT-REQUIRED` header). A client with an x402 SDK (`@x402/fetch`, Python `x402`) pays and repeats the request with `PAYMENT-SIGNATURE`; the answer is the usual one, plus `PAYMENT-RESPONSE` with the transaction hash. No key or account is needed to pay. | What | Price | |---|---| | A request above the daily free limit: `/official/rate`, `/official/rates`, `/official/series`, `/atlas/countries/{code}`, `/atlas/currencies/{code}/days` | 0.005 USD | | A daily atlas series longer than 60 days (`/atlas/currencies/{code}/days`), from the first request | 0.01 USD | - An answer with an error (400, 404, 503) is not charged: the payment is not settled. A payment signature is accepted once. - Not for sale: world maps above the limit (429 as before), market prices, data about Iran and Cuba, requests from countries under comprehensive sanctions. - Terms: https://vitalitynode.com/terms/ (section 5a). The payer's wallet address and the transaction are recorded: https://vitalitynode.com/privacy/. ## MCP server `https://vitalitynode.com/mcp/rates` - remote MCP server, read only, no account needed. Transport: Streamable HTTP, stateless, JSON responses (no SSE stream; `GET` is 405). Protocol versions 2024-11-05 to 2025-11-25. An API key, if you have one, goes in `Authorization: Bearer ` as for the HTTP API; without it the client is anonymous by IP. The tools call the same handlers as the HTTP API: the same numbers, proofs, journal and daily limits. | Tool | What it answers | HTTP equivalent | |---|---|---| | `official_rate` | Rate of a named publisher on a date or for a period (`base`, `quote`, `source`, `date`, `period`); several quotes as `EUR,GBP` | `/official/rate`, `/official/rates` (`format=short`) | | `official_series` | The rate for every day of a period, up to 366 days | `/official/series` (days without the published values; those are in the HTTP answer) | | `list_sources` | Publisher tables, filtered by `country` or `currency` | `/official/sources` | | `country_rates` | Atlas for a country: official rate, street (black market) rate, gap, value lost, sources | `/atlas/countries/{code}` | | `world_rankings` | `kind=gap`: largest official vs street gaps; `kind=risk`: biggest value lost over a period; top in detail, every country in short | `/atlas/map/gap`, `/atlas/map/risk` | | `currency_days` | Atlas daily series for a currency, up to 60 days | `/atlas/currencies/{code}/days` | - MCP takes no payments yet: what is paid on HTTP (above the free daily limit, an atlas series longer than 60 days) comes back as a tool error with the price and the HTTP address to pay with x402. - Connect in Claude: Settings -> Connectors -> Add custom connector, URL `https://vitalitynode.com/mcp/rates`. Other clients: add a remote (HTTP) MCP server with the same URL. ## Errors JSON: `{"error": {"code": "...", "message": "..."}}`; 429 from the application also has `limit` and `resets_at`. | Status | `code` | Meaning | |---|---|---| | 400 | `invalid_parameters` | Missing or malformed parameter; dates are `YYYY-MM-DD` | | 400 | `unknown_currency` | Not an ISO 4217 code known here | | 400 | `unknown_source` | Not one of the sources; the message lists them | | 400 | `unsupported_pair` | The source does not publish the pair, directly or through its pivot; the message lists sources that do | | 400 | `stale_publication` | The source's last publication for this pair is too old for the date (more than 14 days for daily tables, 62 monthly, 190 quarterly): the source stopped publishing it or paused; the message gives the last date | | 400 | `period_not_published` | An average source has nothing for the period that contains `date` yet; the message names the latest published period | | 400 | `same_currency` | `base` equals `quote` | | 400 | `date_in_future` | | | 400 | `date_before_history` | The message gives the source's first date | | 400 | `market_pair_unavailable` | Pair not traded on the venue; fiat pairs belong to `/official/rate` | | 400 | `unknown_venue` | | | 401 | `invalid_api_key` | Unknown or revoked key; requests without a header are anonymous instead | | 402 | | Payment required: above the free limit or a long atlas series; the price is in the `PAYMENT-REQUIRED` header (see Paid answers) | | 404 | `not_found` | No API endpoint at this path; API paths have no trailing slash. The message links the docs | | 429 | `rate_limited` | Limit reached; `resets_at` says when | | 503 | `no_data` | The source has no publication on or before the date in the database yet | | 503 | `venue_unavailable` | The market venue did not respond | ## Examples Values below are real answers of 2026-11-08 (a Sunday), shortened. `GET /official/rate?base=EUR"e=USD` ``` query: {"base": "EUR", "quote": "USD", "source": "ecb", "date": "2026-11-08"} result: {"rate": "1.1165", "meaning": "1 EUR = 1.1165 USD", "method": "fallback_previous", "rate_date": "2026-11-06", "derivation": {"type": "as_published", "formula": "rate = obs_value"}, "rounding": null, "inputs": [{"series_key": "EXR.D.USD.EUR.SP00.A", "unit": "USD per 1 EUR", "obs_value": "1.1165", "document": {"sha256": "55c9fe87...", "download_url": "https://vitalitynode.com/lab/rates/documents/55c9fe87..."}}]} ``` `GET /official/rate?base=USD"e=EUR&source=ecb&date=2026-11-06` ``` result: {"rate": "0.895656", "method": "published", "rate_date": "2026-11-06", "derivation": {"type": "inverse", "formula": "rate = 1 / obs_value"}, "rounding": {"rule": "6 significant digits, at least 6 decimal places", "places": 6, "mode": "ROUND_HALF_UP"}} ``` `GET /official/rate?base=USD"e=THB&source=ecb` ``` result: {"rate": "33.550381", "derivation": {"type": "cross", "formula": "rate = (1 / base_leg.obs_value) / (1 / quote_leg.obs_value) # EUR per 1 USD / EUR per 1 THB"}, "inputs": [{"role": "base_leg", "unit": "USD per 1 EUR", "obs_value": "1.1165"}, {"role": "quote_leg", "unit": "THB per 1 EUR", "obs_value": "37.459"}]} ``` `GET /official/rate?base=THB"e=CZK&source=cnb` ``` result: {"rate": "0.649700", "method": "published", "rate_date": "2026-11-06", "derivation": {"type": "per_unit", "formula": "rate = obs_value / 100"}, "inputs": [{"unit": "CZK per 100 THB", "obs_value": "64.970", "valid_to": "2026-11-08"}]} ``` The same pair, EUR/USD, from each source on that Sunday: | `source` | `rate` | `rate_date` | `derivation.type` | |---|---|---|---| | `ecb` | 1.1165 | 2026-11-06 | `as_published` | | `frb-h10` | 1.1163 | 2026-10-30 | `as_published` (next weekly release not out yet) | | `boc` | 1.114717 | 2026-11-06 | `cross` through CAD | | `us-treasury` | 1.135074 | 2026-10-01 | `inverse` of the quarterly 0.881 EUR per USD | `GET /official/rate?base=EUR"e=USD&date=2026-12-01` → 400 `date_in_future`. Averages (real answers of 2026-11-08): | Request | `rate` | Period | `derivation.type` | |---|---|---|---| | `base=USD"e=EUR&source=irs-yearly&date=2025-06-30` | 0.886 | 2025 | `as_published` | | `base=EUR"e=USD&source=irs-yearly&date=2025-06-30` | 1.128668 | 2025 | `inverse` | | `base=EUR"e=USD&source=ecb-annual&date=2025-03-01` | 1.1299831372549 | 2025 | `as_published` | | `base=EUR"e=USD&source=ecb-monthly&date=2026-10-15` | 1.1201590909090908 | 2026-10 | `as_published` | | `base=USD"e=CAD&source=boc-annual&date=2025-07-01` | 1.3978 | 2025 | `as_published` | | `base=EUR"e=USD&source=irs-yearly` (today, 2026) | 400 `period_not_published`: latest published period 2025 | | | | `base=USD"e=EUR&source=irs-yearly&period=2025` | 0.886 | 2025 | `as_published` | | `base=GBP"e=EUR&source=hmrc-yearly-dec&period=2025` | 1.1717 | 2025 | `as_published` | | `base=GBP"e=USD&source=hmrc-yearly-mar&period=2026-03` | 1.3378 | 2025-04-01 to 2026-03-31 | `as_published` | | `base=GBP"e=EUR&source=hmrc-monthly&period=2026-11` | 1.1930 | 2026-11 | `as_published` | ## Not available - Period-end rates (quarter close, year end) as a separate table, HMRC spot rates, and averages from publishers not listed above. - "As known on date X": recording time is stored (`recorded_at`) but cannot be queried. - Live market prices for fiat currencies, and THB/USDT. Daily street rates per country: the atlas, see above.