A typed client for indicative FX reference rates from exchangerate.dev. Read latest and historical rates, currency pairs, indices, and account usage, or convert amounts between currencies. These rates are not for settlement or trading.
Requires Node.js 22 or newer. This server-side package has no dependencies.
npm install @nusantara-ventures/exchangerateSet EXCHANGERATE_API_KEY in your server environment. Use an ES module:
import { Exchangerate } from "@nusantara-ventures/exchangerate";
const client = new Exchangerate();
const latest = await client.rates.latest({
base: "USD",
symbols: ["EUR", "IDR"],
});
console.log(latest.rates["EUR"]);
console.log(latest.meta.request_id);
const converted = await client.convert.amount("USD", "IDR", { amount: "100" });
console.log(converted);Supply apiKey in the constructor options to configure a key explicitly. The
default base URL is https://api.exchangerate.dev; override it with
EXCHANGERATE_BASE_URL or baseUrl. Keep credentials in server code. Pass
symbols as an array of currency codes.
Decimal values use exact strings with type Decimal. Rates arrive as JSON
numbers and become exact decimal text without floating-point conversion,
including exponent forms. Pass amounts as strings. Every response carries
meta with request_id and rate-limit values from headers.
Unauthorized, RateLimited, NotFound, and BadRequest extend ApiError.
API errors expose status, code, detail, and request_id. RateLimited
also carries retry_after. All client errors derive from ExchangerateError.
Import these classes from the package root.
Requests retry up to twice by default for short-window rate limits and temporary unavailability. Quota exhaustion is not retried.
Use rates.rangeIter({ ... }), rates.timeseriesIter({ ... }), and
indices.timeseriesIter(slug, { ... }) with for await...of to consume items
across pages. The corresponding methods without Iter return a single page.
Links: Documentation
MIT licensed