{"_id":"@allratestoday/central-bank","name":"@allratestoday/central-bank","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@allratestoday/central-bank","version":"1.0.0","description":"Official exchange rates published by 100+ central banks and tax authorities (ECB, Fed, BOJ, HMRC, US Treasury). Works without an API key. Zero dependencies.","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"build":"tsup src/index.ts --format cjs,esm --dts","test":"vitest run","test:watch":"vitest","prepublishOnly":"npm run build"},"keywords":["central-bank","exchange-rate","currency","forex","fx","ecb","hmrc","vat","tax","accounting","allratestoday"],"author":{"name":"AllRatesToday","email":"info@allratestoday.com"},"license":"MIT","homepage":"https://allratestoday.com/central-bank-rates-api/","repository":{"type":"git","url":"git+https://github.com/AllRates-Today/exchange-rates-api.git","directory":"sdks/javascript-central-bank"},"bugs":{"url":"https://github.com/AllRates-Today/exchange-rates-api/issues"},"engines":{"node":">=18"},"devDependencies":{"tsup":"^8.0.0","typescript":"^5.0.0","vitest":"^4.1.4"},"gitHead":"8f3924b74de749dfd25a91e1daff00fa716fb420","_id":"@allratestoday/central-bank@1.0.0","_nodeVersion":"22.22.1","_npmVersion":"9.2.0","dist":{"integrity":"sha512-L3qR7Ust7eamTJYMU2AEn8jBn7q4v/C2wC3jdPDabK+2JFEvyv9ymaC3BvFpewn+DX4bASoW10Uxmw++r6rJNg==","shasum":"6c492f0e4cab7f50a58cb97a4b31c01972797fe3","tarball":"https://registry.npmjs.org/@allratestoday/central-bank/-/central-bank-1.0.0.tgz","fileCount":7,"unpackedSize":31494,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC33R/ImglExpHU97Sy34DyJ2Wz1ljGb7lKGNBhQk4tMAIhAMgBT1YNKLMNlJcBuwXT6nxAoAhqDGQqQSJPClBKzL/D"}]},"_npmUser":{"name":"chathurangac8","email":"basnayakac8@gmail.com"},"directories":{},"maintainers":[{"name":"chathurangac8","email":"basnayakac8@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/central-bank_1.0.0_1788178960245_0.5185051135755985"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T12:22:40.046Z","1.0.0":"2026-08-31T12:22:40.380Z","modified":"2026-08-31T12:22:40.620Z"},"maintainers":[{"name":"chathurangac8","email":"basnayakac8@gmail.com"}],"description":"Official exchange rates published by 100+ central banks and tax authorities (ECB, Fed, BOJ, HMRC, US Treasury). Works without an API key. Zero dependencies.","homepage":"https://allratestoday.com/central-bank-rates-api/","keywords":["central-bank","exchange-rate","currency","forex","fx","ecb","hmrc","vat","tax","accounting","allratestoday"],"repository":{"type":"git","url":"git+https://github.com/AllRates-Today/exchange-rates-api.git","directory":"sdks/javascript-central-bank"},"author":{"name":"AllRatesToday","email":"info@allratestoday.com"},"bugs":{"url":"https://github.com/AllRates-Today/exchange-rates-api/issues"},"license":"MIT","readme":"# @allratestoday/central-bank\n\n[](https://www.npmjs.com/package/@allratestoday/central-bank)\n[](https://github.com/AllRates-Today/exchange-rates-api/blob/main/LICENSE)\n[](https://www.npmjs.com/package/@allratestoday/central-bank)\n\n**Official exchange rates as published by 100+ central banks and tax authorities — ECB, Federal Reserve, Bank of Japan, HMRC, US Treasury and more.**\n\n```bash\nnpm install @allratestoday/central-bank\n```\n\n```ts\nimport { CentralBankRates } from '@allratestoday/central-bank';\n\nconst cb = new CentralBankRates(); // no API key needed\nconst pair = await cb.latest('ecb', { source: 'USD', target: 'EUR' });\n\nconsole.log(pair.rate, 'published', pair.rate_date);\n// 0.8588851671 published 2026-08-28\n```\n\n## Which rate is this?\n\nNot a market rate. A **published** rate: the number a named institution put out\nfor a given day, fixed once published, carrying that institution's own date.\n\nThat distinction is the whole reason this package exists. Compliance rules\nalmost never say \"use the current market rate\" — they name a publisher and a\ndate. *The ECB reference rate on the invoice date. The HMRC monthly rate for the\nperiod.* The two routinely differ by a percent or more, so a VAT return computed\nfrom a live market rate produces numbers nobody can reconcile.\n\nUse this package for invoices, VAT and tax returns, customs valuation, transfer\npricing, month-end and statutory accounting, and audit evidence.\n\nFor live mid-market rates — price display, checkout, conversion UI — use\n[`@allratestoday/sdk`](https://www.npmjs.com/package/@allratestoday/sdk) instead.\n\n## Works without an API key\n\n`latest()` reads an open, edge-cached endpoint, so the newest published table of\nany source needs no signup:\n\n```ts\nconst cb = new CentralBankRates();\n\nawait cb.latest('ecb'); // full ECB table\nawait cb.latest('hmrc'); // HMRC's published rates\nawait cb.latest('boj', { source: 'USD', target: 'JPY' }); // one pair\n```\n\nA [free API key](https://allratestoday.com/register) (no card) adds historical\ndates, time series, publication calendars and cross-source comparison:\n\n```ts\nconst cb = new CentralBankRates({ apiKey: process.env.ALLRATES_API_KEY });\n```\n\nMethods that need one throw `NeedsApiKeyError` — a subclass of\n`CentralBankError` — with sign-up instructions, before making any request.\n\n## API\n\n| Method | Key? | Returns |\n|---|---|---|\n| `latest(bank, { source?, target? })` | no | Newest published table, or one pair from it |\n| `sources()` | yes | Every covered institution with coverage dates |\n| `forDate(bank, on, { source?, target? })` | yes | The table in force on a date |\n| `history(bank, { symbol?, from?, to? })` | yes | Date-by-date official series |\n| `availability(bank, { year? })` | yes | Which dates the institution actually published |\n| `compare(source, target)` | yes | One pair across every institution, with spread stats |\n\nDates accept `\"YYYY-MM-DD\"` or a `Date`.\n\n## Three things that will bite you\n\n**1. `rate_date` is the answer, not the date you asked for.** Most institutions\npublish on business days only. Ask for a Sunday and you get the previous\npublication, with `rate_date` saying which day it really is. Record that date —\nit is the audit trail.\n\n```ts\nconst table = await cb.forDate('ecb', '2026-01-04'); // a Sunday\ntable.rate_date; // '2026-01-02'\n```\n\n**2. `derived: true` means the institution did not publish that pair.** It was\ncross-computed within that institution's own table. Fine for display; say so if\nthe number goes into a filing, and never derive one institution's rate from\nanother's — an ECB rate crossed through USD is not an HMRC rate.\n\n**3. Cadence differs by source.** The Fed's H.10 is weekly, the SNB publishes\nmonthly averages, the US Treasury is quarterly, most central banks are daily.\nCheck `sources()` before assuming yesterday's rate exists.\n\n## Worked example: converting an invoice\n\n```ts\nimport { CentralBankRates } from '@allratestoday/central-bank';\n\nconst cb = new CentralBankRates({ apiKey: process.env.ALLRATES_API_KEY });\n\n/** Convert at the HMRC rate in force on the invoice date. */\nasync function invoiceTotalInGbp(amountUsd: number, invoiceDate: string) {\n const published = await cb.forDate('hmrc', invoiceDate, { source: 'USD', target: 'GBP' });\n // Return the publication date alongside the number: it is what an auditor\n // will ask for, and it is not necessarily the invoice date.\n return {\n total: Math.round(amountUsd * published.rate * 100) / 100,\n rateDate: published.rate_date,\n };\n}\n```\n\n## Also available\n\n- **Live mid-market rates:** [`@allratestoday/sdk`](https://www.npmjs.com/package/@allratestoday/sdk)\n- **Python:** [`allratestoday-central-bank`](https://pypi.org/project/allratestoday-central-bank/)\n- **Single-source packages:** `ecb-exchange-rate`, `hmrc-exchange-rate` and 100+ others\n- **MCP server** for AI agents: `npx -y @allratestoday/central-bank-mcp`\n- **Claude Code plugin:** `/plugin marketplace add AllRates-Today/claude-code-plugin`\n\n## Links\n\n- Coverage and docs: \n- API reference: \n- Support: support@allratestoday.com\n\nMIT licensed. Rates are served as published by the named institution; AllRatesToday is not affiliated with any of them.\n","readmeFilename":"README.md","_rev":"1-26395f382c3fab421bc579863a9893de"}