currency-rate-fetcher

Fetch up-to-date foreign exchange rates from one of three providers:

• ECB – the European Central Bank daily XML feed (default).
• FloatRates (FRC) – daily XML feed from floatrates.com, available per base currency.
• Open Exchange Rates (OXR) – JSON API; free tier provides USD base data (requires an app id).

Installation

npm install currency-rate-fetcher

Usage

const { fetchCurrencies, fetchCurrency } = require("currency-rate-fetcher");

// Full table for the default (ECB) provider
const snapshot = await fetchCurrencies(); // provider defaults to "ecb", base defaults to "EUR"

// Switch provider and base currency
const usdRates = await fetchCurrencies("oxr", "USD", { appId: process.env.OXR_TOKEN });

// Ask for a single currency value (throws if missing)
const nokFromEcb = await fetchCurrency("ecb", "NOK"); // -> { currency: "NOK", value: <number> }

fetchCurrencies(provider = "ecb", baseCurrency = "EUR", options = {})

Returns a Promise resolving to:

{
  "status": "OK",
  "fetchedAt": "2025-10-18T14:21:19.298Z",
  "source": "<provider URL>",
  "date": "2025-10-17",
  "base": "EUR",
  "rates": {
    "EUR": 1,
    "USD": 1.1,
    "...": "..."
  }
}

Provider-specific notes:

• ecb – accepts options.currencyUrl to override the XML endpoint, or options.fetcher to supply a custom HTTP getter.
• frc – accepts options.url or options.fetcher; base currency determines the FloatRates URL (https://www.floatrates.com/daily/<base>.xml).
• oxr – requires options.appId (or environment variable OXR_APP_ID / OPEN_EXCHANGE_RATES_APP_ID). Always requests USD data and cross-converts if another base is requested. You can override the API endpoint via options.baseUrl. The example script also honours OXR_TOKEN for convenience.

fetchCurrency(provider = "ecb", currency = "NOK", baseCurrency = "EUR", options = {})

Resolves to { currency: "NOK", value: <number> }. The helper simply calls fetchCurrencies under the hood, so the same options apply.

CLI test helper

A simple example script is included at examples/test-currency.js:

node examples/test-currency.js ecb NOK
node examples/test-currency.js frc USD
OXR_TOKEN=your_app_id node examples/test-currency.js oxr NOK

It prints both the full snapshot and the single currency lookup for quick verification.

License

MIT