@financica/ecb-client

Tiny, zero-dependency TypeScript client for the European Central Bank's euro foreign-exchange reference rates, with first-class support for historical single-day lookups and last-business-day fallback.

• Authoritative source. Reads the ECB data API directly (dataflow EXR). No third-party middleman, no API key, no SLA in front of your numbers. ECB reference rates are the rates EU tax authorities accept for currency conversion (VAT Directive art. 91).
• Point-in-time. Ask for a rate "on or before" any date; the ECB only publishes on TARGET business days, so weekends and holidays transparently resolve to the most recent prior business day. The effective date is reported back on every rate.
• Cross rates. Every ECB rate is quoted against the euro; the client crosses two foreign currencies through EUR for you.
• Tiny & typed. Zero runtime dependencies, ESM + CJS, strict types, an injectable fetch, and an in-process snapshot cache.

Install

npm install @financica/ecb-client

Requires Node 18+ (uses the global fetch).

Usage

import { EcbClient } from "@financica/ecb-client";

const ecb = new EcbClient();

// A single rate (units of the currency per 1 EUR) on a given day.
await ecb.getRate("USD", "2024-01-15");
// → { currency: "USD", rate: 1.0945, date: "2024-01-15" }

// Weekends/holidays fall back to the last business day; the effective
// date comes back on the result.
await ecb.getRate("USD", "2024-01-13"); // a Saturday
// → { currency: "USD", rate: 1.0942, date: "2024-01-12" }

// Convert an amount. Non-euro pairs cross through EUR.
await ecb.convert({ amount: 100, from: "USD", to: "EUR", date: "2024-01-15" });
// → { amount: 91.36…, rate: 0.9136…, from: "USD", to: "EUR",
//     requestedDate: "2024-01-15", rateDate: "2024-01-15" }

// Several currencies for one date, in a single request.
const snapshot = await ecb.getRates("2024-01-15", ["USD", "GBP", "CHF"]);
// → { requestedDate: "2024-01-15", rates: [ { currency, rate, date }, … ] }

API

new EcbClient(options?)

| option | default | description | | ----------- | -------------------------------------------- | -------------------------------------------------------- | | baseUrl | https://data-api.ecb.europa.eu/service | ECB data API base URL. | | fetch | global fetch | Custom fetch (testing, proxying). | | cache | unbounded in-process Map | Snapshot cache keyed by request. Pass null to disable. | | timeoutMs | 15000 | Per-request timeout. 0 disables it. |

getRate(currency, date) → Promise<ReferenceRate>

The rate for one currency on (or before) date. date is a YYYY-MM-DD string or a Date. EUR returns a unit rate without a network call. Throws NoRateError when no observation exists on or before the date.

getRates(date, currencies?) → Promise<RateSnapshot>

Rates for several currencies on (or before) date. Omit currencies to fetch every series the ECB publishes — note that discontinued series resolve to their own last-published date, so check each rate's date rather than assuming the requested one.

convert({ amount, from, to, date }) → Promise<ConvertResult>

Convert amount from one currency to another. Identical currencies are a no-op (no request). The result reports the applied rate and the rateDate actually used.

How rates are quoted

Every value is units of the quoted currency per 1 EUR (the ECB convention). So getRate("USD", …).rate === 1.0945 means 1 EUR = 1.0945 USD. To go from USD to EUR, divide; from EUR to USD, multiply; convert() handles both and the cross-currency case.

Caveats

• Business days only. No observation on weekends or TARGET holidays; the client resolves to the last prior business day for you.
• ~30 active currencies, all against EUR. Cross rates are computed through EUR. Discontinued series (e.g. ARS) still return, at a stale date.
• Be a good citizen. The ECB data API is a public good with no SLA. The built-in cache deduplicates repeated lookups; cache aggressively in your app.

License

MIT © Financica