{"_id":"@allratestoday/fx-rates","name":"@allratestoday/fx-rates","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.1":{"name":"@allratestoday/fx-rates","version":"1.0.1","description":"Lightweight Node.js library and CLI for real-time mid-market currency exchange rates. 160+ currencies from Refinitiv (Reuters) and interbank feeds via the AllRatesToday API.","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","bin":{"fx-rates":"dist/cli.js"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"build":"tsup src/index.ts src/cli.ts --format cjs,esm --dts --clean","test":"node --test test/*.test.mjs"},"keywords":["exchange","currency","currency-converter","forex","fx","fx-rates","exchange-rate","money","finance","real-time","currency-conversion","mid-market","refinitiv","reuters","allratestoday","api","cli"],"author":{"name":"AllRatesToday","email":"support@allratestoday.com","url":"https://allratestoday.com"},"license":"MIT","homepage":"https://allratestoday.com","repository":{"type":"git","url":"git+https://github.com/cahthuranag/fx-rates.git"},"bugs":{"url":"https://github.com/cahthuranag/fx-rates/issues"},"engines":{"node":">=18"},"devDependencies":{"@types/node":"^25.6.0","tsup":"^8.0.0","typescript":"^5.3.0"},"publishConfig":{"access":"public"},"_id":"@allratestoday/fx-rates@1.0.1","_nodeVersion":"22.22.1","_npmVersion":"9.2.0","dist":{"integrity":"sha512-8jC/mcanqJizin151tOI547Ux8pyKKqVkumSg3EXHqA2SWW8RyC0GlC1V0wbzOy1Y7aRnNjbsU/PH3lpIE0hBA==","shasum":"a416c3da20ad705fc3685657df57fb5bd7038689","tarball":"https://registry.npmjs.org/@allratestoday/fx-rates/-/fx-rates-1.0.1.tgz","fileCount":12,"unpackedSize":32222,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIH7xln7bHSZ0yTjf1/zcrHRzvvG7/CAkGYea52pAf4OkAiEA14xY4Xo0urhdodhjKN396Zg6h82o7iQmlbolkuDZeNU="}]},"_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/fx-rates_1.0.1_1787947801310_0.11626821670585041"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-28T20:10:01.099Z","1.0.1":"2026-08-28T20:10:01.487Z","modified":"2026-08-28T20:10:01.719Z"},"maintainers":[{"name":"chathurangac8","email":"basnayakac8@gmail.com"}],"description":"Lightweight Node.js library and CLI for real-time mid-market currency exchange rates. 160+ currencies from Refinitiv (Reuters) and interbank feeds via the AllRatesToday API.","homepage":"https://allratestoday.com","keywords":["exchange","currency","currency-converter","forex","fx","fx-rates","exchange-rate","money","finance","real-time","currency-conversion","mid-market","refinitiv","reuters","allratestoday","api","cli"],"repository":{"type":"git","url":"git+https://github.com/cahthuranag/fx-rates.git"},"author":{"name":"AllRatesToday","email":"support@allratestoday.com","url":"https://allratestoday.com"},"bugs":{"url":"https://github.com/cahthuranag/fx-rates/issues"},"license":"MIT","readme":"> Scoped mirror of [`fx-rates`](https://www.npmjs.com/package/fx-rates) published by the AllRatesToday org — same code, same versions.\n\n# 📈 fx-rates\n\n[![npm version](https://img.shields.io/npm/v/fx-rates)](https://www.npmjs.com/package/fx-rates)\n[![npm downloads](https://img.shields.io/npm/dm/fx-rates)](https://www.npmjs.com/package/fx-rates)\n[![license](https://img.shields.io/npm/l/fx-rates)](./LICENSE)\n\nLightweight Node.js library and CLI for **real-time mid-market currency exchange rates** — 160+ currencies sourced from **Refinitiv (Reuters)** and interbank feeds via the [AllRatesToday API](https://allratestoday.com).\n\n- ⚡ **Real-time** rates, not daily snapshots\n- 🌍 **160+ currencies** including majors, emerging-market, precious metals (XAU, XAG)\n- 📦 **Zero runtime dependencies** (uses native `fetch`)\n- 🖥️ Works as a **Node library AND CLI**\n- 🔒 Mid-market rates (no retail markup)\n\n---\n\n## 📦 Installation\n\n```bash\nnpm install @allratestoday/fx-rates\n```\n\nOr with yarn / pnpm:\n\n```bash\nyarn add @allratestoday/fx-rates\npnpm add @allratestoday/fx-rates\n```\n\n---\n\n## 🔑 Get a free API key\n\nThis package calls the authenticated AllRatesToday API. Grab a free key at\n**[allratestoday.com/register](https://allratestoday.com/register/)** — no credit card required.\n\nExport it once:\n\n```bash\nexport ALLRATESTODAY_API_KEY=\"art_live_...\"\n```\n\nOr pass it explicitly to each call (see below).\n\n---\n\n## 🚀 Usage\n\n### Node.js — get a rate\n\n```js\nimport { rate } from \"fx-rates\";\n\nconst r = await rate(\"USD\", \"INR\");\nconsole.log(r);\n// {\n//   date: \"2026-04-20\",\n//   base: \"USD\",\n//   target: \"INR\",\n//   rate: 83.2145\n// }\n```\n\n### Node.js — convert an amount\n\n```js\nimport { convert } from \"fx-rates\";\n\nconst out = await convert(100, \"USD\", \"EUR\");\nconsole.log(out);\n// {\n//   from: { currency: \"USD\", amount: 100 },\n//   to:   { currency: \"EUR\", amount: 92.34 },\n//   rate: 0.9234,\n//   date: \"2026-04-20\"\n// }\n```\n\n### Pass the API key explicitly\n\n```js\nconst r = await rate(\"GBP\", \"USD\", { apiKey: \"art_live_...\" });\n```\n\n### TypeScript\n\n```ts\nimport { rate, RateResult, RateOptions } from \"fx-rates\";\n\nconst opts: RateOptions = { timeoutMs: 5000 };\nconst r: RateResult = await rate(\"EUR\", \"JPY\", opts);\n```\n\n### Custom fetch (Node < 18 or test doubles)\n\n```js\nimport { rate } from \"fx-rates\";\nimport fetch from \"node-fetch\";\n\nconst r = await rate(\"USD\", \"INR\", { fetch });\n```\n\n---\n\n## 💻 CLI\n\nInstall globally:\n\n```bash\nnpm install -g fx-rates\n```\n\nThen:\n\n```bash\n$ fx-rates USD INR\n{\n  \"date\": \"2026-04-20\",\n  \"base\": \"USD\",\n  \"target\": \"INR\",\n  \"rate\": 83.2145\n}\n```\n\nConvert an amount (third positional argument):\n\n```bash\n$ fx-rates USD EUR 250\n{\n  \"from\": { \"currency\": \"USD\", \"amount\": 250 },\n  \"to\":   { \"currency\": \"EUR\", \"amount\": 230.85 },\n  \"rate\": 0.9234,\n  \"date\": \"2026-04-20\"\n}\n```\n\nPipe into `jq`:\n\n```bash\n$ fx-rates GBP USD | jq '.rate'\n1.3512\n```\n\n---\n\n## 📚 API reference\n\n### `rate(base, target, options?)`\n\nFetch the latest mid-market rate for a single pair.\n\n| Param    | Type    | Description                                  |\n|----------|---------|----------------------------------------------|\n| `base`   | string  | ISO 4217 code of the source currency (`\"USD\"`, `\"EUR\"`, `\"XAU\"`, …) |\n| `target` | string  | ISO 4217 code of the target currency         |\n| `options`| object  | Optional (see below)                         |\n\nReturns `Promise<RateResult>`:\n\n```ts\ninterface RateResult {\n  date: string;    // ISO date, e.g. \"2026-04-20\"\n  base: string;    // \"USD\"\n  target: string;  // \"INR\"\n  rate: number;    // 83.2145\n}\n```\n\n### `convert(amount, from, to, options?)`\n\nMultiply an amount by the current rate.\n\n### `RateOptions`\n\n```ts\ninterface RateOptions {\n  apiKey?: string;       // defaults to process.env.ALLRATESTODAY_API_KEY\n  baseUrl?: string;      // override for staging / self-hosted proxies\n  fetch?: typeof fetch;  // custom fetch implementation\n  timeoutMs?: number;    // default 15000\n}\n```\n\n### Errors\n\nAll errors are thrown as `AllRatesTodayError` with a `.status` field (HTTP status where applicable):\n\n```js\nimport { rate, AllRatesTodayError } from \"fx-rates\";\n\ntry {\n  await rate(\"USD\", \"XXX\");\n} catch (err) {\n  if (err instanceof AllRatesTodayError) {\n    console.error(err.status, err.message);\n  }\n}\n```\n\n---\n\n## 🌍 Supported currencies\n\n160+ currencies including majors (USD, EUR, GBP, JPY, CHF, CAD, AUD, NZD), emerging-market currencies (INR, CNY, BRL, MXN, TRY, ZAR, SGD, HKD, KRW, THB, PHP, PKR, BDT, LKR, NGN, GHS, KES, AED, SAR, EGP), and precious metals (XAU, XAG).\n\nFull list: [`allratestoday.com/api/v1/symbols`](https://allratestoday.com/api/v1/symbols).\n\n---\n\n## 🔗 Related projects\n\n- [`moneyify`](https://www.npmjs.com/package/moneyify) – Cashify-compatible converter with the same auto-fetch backing. Use when you need conversion math, expression parsing (`\"10 USD to EUR\"`), or big.js precision.\n- [`@allratestoday/sdk`](https://www.npmjs.com/package/@allratestoday/sdk) – Full-featured SDK with historical data, batch requests, and webhooks.\n- [`react-currency-localizer-realtime`](https://www.npmjs.com/package/react-currency-localizer-realtime) – React hooks and components for auto-localized pricing.\n- [`allratestoday`](https://allratestoday.com) – The REST API that powers this package.\n\n---\n\n## 🤖 AI disclosure\n\nThis project contains code generated by Large Language Models (LLMs), under human supervision and proofreading. All published versions are reviewed, tested, and released by a human maintainer.\n\n---\n\n## 📄 License\n\n[MIT](./LICENSE) © [AllRatesToday](https://allratestoday.com) — maintained by [Chathuranga Basnayaka](https://github.com/cahthuranag).\n","readmeFilename":"README.md","_rev":"1-f9cb09b75568222d8fb3ead9e16f9f35"}