📈 fx-rates

Lightweight 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.

• ⚡ Real-time rates, not daily snapshots
• 🌍 160+ currencies including majors, emerging-market, precious metals (XAU, XAG)
• 📦 Zero runtime dependencies (uses native fetch)
• 🖥️ Works as a Node library AND CLI
• 🔒 Mid-market rates (no retail markup)

📦 Installation

npm install fx-rates

Or with yarn / pnpm:

yarn add fx-rates
pnpm add fx-rates

🔑 Get a free API key

This package calls the authenticated AllRatesToday API. Grab a free key at allratestoday.com/register — no credit card required.

Export it once:

export ALLRATESTODAY_API_KEY="art_live_..."

Or pass it explicitly to each call (see below).

🚀 Usage

Node.js — get a rate

import { rate } from "fx-rates";

const r = await rate("USD", "INR");
console.log(r);
// {
//   date: "2026-04-20",
//   base: "USD",
//   target: "INR",
//   rate: 83.2145
// }

Node.js — convert an amount

import { convert } from "fx-rates";

const out = await convert(100, "USD", "EUR");
console.log(out);
// {
//   from: { currency: "USD", amount: 100 },
//   to:   { currency: "EUR", amount: 92.34 },
//   rate: 0.9234,
//   date: "2026-04-20"
// }

Pass the API key explicitly

const r = await rate("GBP", "USD", { apiKey: "art_live_..." });

TypeScript

import { rate, RateResult, RateOptions } from "fx-rates";

const opts: RateOptions = { timeoutMs: 5000 };
const r: RateResult = await rate("EUR", "JPY", opts);

Custom fetch (Node < 18 or test doubles)

import { rate } from "fx-rates";
import fetch from "node-fetch";

const r = await rate("USD", "INR", { fetch });

💻 CLI

Install globally:

npm install -g fx-rates

Then:

$ fx-rates USD INR
{
  "date": "2026-04-20",
  "base": "USD",
  "target": "INR",
  "rate": 83.2145
}

Convert an amount (third positional argument):

$ fx-rates USD EUR 250
{
  "from": { "currency": "USD", "amount": 250 },
  "to":   { "currency": "EUR", "amount": 230.85 },
  "rate": 0.9234,
  "date": "2026-04-20"
}

Pipe into jq:

$ fx-rates GBP USD | jq '.rate'
1.3512

📚 API reference

rate(base, target, options?)

Fetch the latest mid-market rate for a single pair.

| Param | Type | Description | |----------|---------|----------------------------------------------| | base | string | ISO 4217 code of the source currency ("USD", "EUR", "XAU", …) | | target | string | ISO 4217 code of the target currency | | options| object | Optional (see below) |

Returns Promise<RateResult>:

interface RateResult {
  date: string;    // ISO date, e.g. "2026-04-20"
  base: string;    // "USD"
  target: string;  // "INR"
  rate: number;    // 83.2145
}

convert(amount, from, to, options?)

Multiply an amount by the current rate.

RateOptions

interface RateOptions {
  apiKey?: string;       // defaults to process.env.ALLRATESTODAY_API_KEY
  baseUrl?: string;      // override for staging / self-hosted proxies
  fetch?: typeof fetch;  // custom fetch implementation
  timeoutMs?: number;    // default 15000
}

Errors

All errors are thrown as AllRatesTodayError with a .status field (HTTP status where applicable):

import { rate, AllRatesTodayError } from "fx-rates";

try {
  await rate("USD", "XXX");
} catch (err) {
  if (err instanceof AllRatesTodayError) {
    console.error(err.status, err.message);
  }
}

🌍 Supported currencies

160+ 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).

Full list: allratestoday.com/api/v1/symbols.

🔗 Related projects

• 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.
• @allratestoday/sdk – Full-featured SDK with historical data, batch requests, and webhooks.
• react-currency-localizer-realtime – React hooks and components for auto-localized pricing.
• allratestoday – The REST API that powers this package.

🤖 AI disclosure

This 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.

📄 License

MIT © AllRatesToday — maintained by Chathuranga Basnayaka.