This guide covers everything you need to use an exchange rate API in JavaScript: a typed Node.js client built on the standard fetch, historical lookups, currency conversion, error handling for every status code, and a Next.js route handler that keeps your fxapi key on the server while your React components get the rates they need.
Setup
Sign up for a free key and put it in your server environment, for example in .env.local for Next.js:
FXAPI_KEY=your-api-key
Every supported Node.js release (22 LTS and newer) has fetch built in, so the examples below have no dependencies. Every request goes to https://api.fxapi.com/v1/... with the key in the apikey header.
TypeScript types for the API responses
The latest, historical and convert endpoints share one response shape (range, fluctuation and average have their own – see the documentation):
// fxapi.ts
export type RateEntry = { code: string; value: number };
export type RatesResponse = {
meta: { last_updated_at: string; base_currency: string };
data: Record<string, RateEntry>;
};
export class FxApiError extends Error {
status: number;
code?: string; // machine-readable error.code, e.g. "quota_exceeded"
errors?: Record<string, string[]>; // 422: messages per parameter
constructor(status: number, message: string, code?: string, errors?: Record<string, string[]>) {
super(`${status}: ${message}`);
this.status = status;
this.code = code;
this.errors = errors;
}
}
An exchange rate API client in JavaScript (Node.js)
// fxapi.ts (continued)
const BASE_URL = "https://api.fxapi.com/v1";
export async function fxGet<T = RatesResponse>(
path: string,
params: Record<string, string | number> = {},
): Promise<T> {
const url = new URL(BASE_URL + path);
for (const [k, v] of Object.entries(params)) url.searchParams.set(k, String(v));
const res = await fetch(url, {
headers: { apikey: process.env.FXAPI_KEY ?? "" },
signal: AbortSignal.timeout(10_000),
});
if (res.ok) return (await res.json()) as T;
const body = await res.json().catch(() => ({}));
const code: string | undefined = body.error?.code;
switch (res.status) {
case 401:
throw new FxApiError(401, "Missing or invalid API key", code);
case 403:
throw new FxApiError(403, "Endpoint or option not in your plan", code);
case 404:
throw new FxApiError(404, "No data for this date or range", code);
case 422:
throw new FxApiError(422, "Validation error", code, body.errors);
case 429:
throw new FxApiError(
429,
code === "rate_limit_exceeded"
? `Per-minute limit reached, retry in ${res.headers.get("Retry-After") ?? 60} s`
: "Monthly quota used up",
code,
);
default:
throw new FxApiError(res.status, body.message ?? "Unexpected response", code);
}
}
The 422 body includes an errors object keyed by parameter, which you can return to your own API callers. A 429 names the limit in error.code: rate_limit_exceeded is the Free plan’s 10 requests per minute (Retry-After says how many seconds to wait), quota_exceeded means the month’s requests are used up.
Get latest exchange rates in Node.js
const latest = await fxGet("/latest", { base_currency: "EUR", currencies: "USD,GBP,CHF" });
console.log(latest.meta.last_updated_at);
console.log(latest.data.USD.value); // USD per 1 EUR
Leave out currencies to get all 190+ currencies in one call, or filter by type=crypto or type=metal. Details: latest endpoint documentation.
Historical rate on a specific date
const hist = await fxGet("/historical", {
date: "2024-12-31",
base_currency: "USD",
currencies: "EUR,JPY",
});
console.log(hist.data.JPY.value);
date can be any day from 1999-01-01 up to yesterday; values are end-of-day rates in UTC. For full series use /v1/range on the Professional plan – see the time series API.
Currency conversion in JavaScript
With the Basic plan or higher, /v1/convert returns converted amounts:
const conv = await fxGet("/convert", { value: 99.5, base_currency: "USD", currencies: "EUR,GBP" });
console.log(conv.data.EUR.value);
On the Free plan, compute the conversion from the latest rates and format it with Intl.NumberFormat, which knows the correct decimals for each currency:
const { data } = await fxGet("/latest", { base_currency: "USD", currencies: "JPY" });
const yen = 99.5 * data.JPY.value;
const fmt = new Intl.NumberFormat("en-US", { style: "currency", currency: "JPY" });
console.log(fmt.format(yen)); // e.g. "¥14,925" – illustrative
For invoices and ledgers, work in integer minor units or a decimal library rather than floats – see currency rounding and precision.
Next.js route handler: keep the API key server-side
Never call fxapi with your key from browser code. Anything shipped to the client – including NEXT_PUBLIC_* variables – is visible to every visitor, who can then spend your quota. Instead, add a route handler that runs on the server and caches the upstream response:
// app/api/rates/route.ts
import { fxGet, FxApiError } from "@/lib/fxapi";
let cache: { body: unknown; at: number } | null = null;
const TTL_MS = 60 * 60 * 1000; // hourly updates on the Basic plan
export async function GET() {
if (cache && Date.now() - cache.at < TTL_MS) {
return Response.json(cache.body, { headers: { "Cache-Control": "public, max-age=300" } });
}
try {
const latest = await fxGet("/latest", { base_currency: "USD" }); // one call, all currencies
cache = { body: latest, at: Date.now() };
return Response.json(latest, { headers: { "Cache-Control": "public, max-age=300" } });
} catch (err) {
if (cache) return Response.json(cache.body); // serve stale rates instead of failing
const status = err instanceof FxApiError ? 502 : 500;
return Response.json({ error: "Rates unavailable" }, { status });
}
}
Your React components then call /api/rates and never see the key. The same pattern works in Express, Fastify, Cloudflare Workers or AWS Lambda: read the key from the environment, call fxapi from the server, cache, and return only what the client needs.
Serverless functions start cold and lose in-memory state, so for high traffic use a shared cache (Redis, Vercel KV, Cloudflare KV) as shown in the caching guide.
Caching and quota
- Match the TTL to your plan’s update interval: daily on Free, hourly on Basic, 60 seconds on Professional and Enterprise (pricing).
- One request, all currencies: fetch everything against one base and derive cross rates locally.
- Cache historical rates forever – a past date’s rate doesn’t change.
- Read the quota headers: successful responses carry
X-RateLimit-Remaining-Quota-MonthandX-Cost;/v1/statusis free to call.
Using the official JavaScript SDK
@everapi/fxapi-js is an ES module with one method per endpoint (status, currencies, latest, historical, convert, range). Each takes an object of query parameters and returns a promise of the parsed JSON:
npm install --save @everapi/fxapi-js
import FxAPI from "@everapi/fxapi-js";
const fxApi = new FxAPI(process.env.FXAPI_KEY);
const latest = await fxApi.latest({ base_currency: "USD", currencies: "EUR" });
const hist = await fxApi.historical({ date: "2024-12-31", currencies: "EUR" });
The SDK resolves with the parsed body whatever the status code, so check that the result has data before you use it – or use the fxGet helper above if you need distinct handling for 401, 403, 422 and 429. For the newer endpoints such as /v1/rate, /v1/matrix or /v1/average, call fxGet directly.
Next steps
- Full API documentation and the OpenAPI spec for generating types.
- Building a multi-currency storefront? Read e-commerce multi-currency pricing.
- Other languages: Python, PHP, Go (Golang).
The examples in this guide use fxapi, a foreign exchange rate API with a free plan of 300 requests a month – no credit card required.
Frequently asked questions
Can I call the exchange rate API directly from the browser?
Which Node.js version do I need?
fetch and AbortSignal.timeout, so the examples need no dependencies. Node.js 24 and newer can also run the .ts files on this page directly, because their types can simply be stripped.How do I convert currencies in JavaScript on the Free plan?
/v1/latest with your source currency as base_currency and multiply the amount by the target rate. /v1/convert does this server-side but needs the Basic plan or higher.How should I format converted amounts?
Intl.NumberFormat with style: 'currency' – it applies the right number of decimals per currency, such as 0 for JPY. See currency rounding and precision.Is there an official JavaScript SDK?
@everapi/fxapi-js on npm. It wraps each endpoint in a method that returns a promise of the parsed JSON.