@fxrateapi/sdk

Official TypeScript/JavaScript SDK for fxrateapi.com — exchange rates, currency conversion, and time series data from ECB, FRED, and OXR.

Installation

npm install @fxrateapi/sdk
# or
pnpm add @fxrateapi/sdk
# or
yarn add @fxrateapi/sdk

Quick start

import { FxRateApiClient } from "@fxrateapi/sdk";

const client = new FxRateApiClient({ apiKey: "fxr_your_key_here" });

// Latest rates
const { base, date, rates } = await client.latest({ base: "USD", symbols: ["EUR", "GBP", "JPY"] });
console.log(rates.EUR); // 0.847

// Convert 1000 USD → EUR
const { result, rate } = await client.convert({ from: "USD", to: "EUR", amount: 1000 });
console.log(result); // 847.4

// Historical (immutable, cache forever)
const hist = await client.historical("2020-03-16", { base: "USD" });

// Time series (max 366 days)
const ts = await client.timeseries({ start: "2024-01-01", end: "2024-03-31", base: "USD", symbols: ["EUR"] });
for (const [day, r] of Object.entries(ts.rates)) {
  console.log(day, r.EUR);
}

API

new FxRateApiClient(options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Your fxr_ prefixed API key | | baseUrl | string | https://api.fxrateapi.com/v1/ | Override for local dev or preview | | timeout | number | 10000 | Request timeout in milliseconds | | retry | RetryOptions \| false | { attempts: 3, initialDelay: 300 } | Retry config. Pass false to disable. | | fetch | typeof fetch | globalThis.fetch | Custom fetch implementation |

Methods

| Method | Description | |--------|-------------| | client.latest(params?) | Latest exchange rates | | client.convert(params) | Currency conversion (latest or historical) | | client.historical(date, params?) | Rates for a specific date | | client.timeseries(params) | Daily rates over a date range (max 366 days) | | client.symbols() | All supported currency codes | | client.sources() | Data source metadata | | client.status() | Health check (no auth required) | | client.usage() | Current billing period usage |

Error handling

import { FxRateApiResponseError, FxRateApiTimeoutError, FxRateApiNetworkError } from "@fxrateapi/sdk";

try {
  await client.latest({ base: "INVALID" });
} catch (err) {
  if (err instanceof FxRateApiResponseError) {
    // Structured API error (4xx / 5xx)
    console.log(err.status);    // 422
    console.log(err.code);      // "fx_invalid_symbol"
    console.log(err.why);       // human-readable reason
    console.log(err.howToFix);  // suggestion
  } else if (err instanceof FxRateApiTimeoutError) {
    console.log("Request timed out after", err.timeout, "ms");
  } else if (err instanceof FxRateApiNetworkError) {
    console.log("Network unreachable:", err.message);
  }
}

Get an API key

Sign up at app.fxrateapi.com. Free tier includes 1,000 requests/month.

License

MIT