rate-api-js

Official JavaScript/TypeScript client for Rate-API.com. Works in Node 18+ and modern browsers (uses the global fetch). Zero dependencies.

Install

npm install rate-api-js

Usage

import { RateApiClient, RateApiError } from 'rate-api-js';

const client = new RateApiClient('YOUR_API_KEY');

const rates = await client.latest('USD', ['EUR', 'GBP']);
console.log(rates.rates.EUR);

const result = await client.convert('USD', 'EUR', 100);      // Pro+
const hist = await client.historical('2026-01-13', 'USD', ['EUR']); // Pro+
const pair = await client.pair('USD', 'EUR');
const crypto = await client.crypto(['BTC', 'ETH']);          // Pro+
const usage = await client.usage();                          // current-month usage vs quota
const health = await client.health();                        // public

try {
  await client.convert('USD', 'ZZZ', 100);
} catch (e) {
  if (e instanceof RateApiError) console.error(e.message, e.status); // 400 invalid_target_currency
}

Methods

latest · convert · pair · historical · crypto · currencies · usage · quota · health

Errors

Every failure throws RateApiError (or a subclass), so a single catch (e) { if (e instanceof RateApiError) … } handles everything:

import { RateApiClient, RateApiError, RateLimitError } from 'rate-api-js';

try {
  await client.latest('USD', ['EUR']);
} catch (e) {
  if (e instanceof RateLimitError) {
    await new Promise((r) => setTimeout(r, e.retryAfter * 1000)); // honour the server's backoff
  } else if (e instanceof RateApiError) {
    console.error(e.status, e.type, e.requestId); // HTTP status, error.type slug, X-Request-Id
  }
}

| Class | When | Extra fields | |---|---|---| | RateApiError | any API/HTTP error | status (HTTP code; undefined on network/timeout), type (stable error.type slug), requestId (X-Request-Id — quote it when contacting support) | | RateLimitError | HTTP 429 | retryAfter (seconds to wait) | | RateApiTimeoutError | request exceeded timeoutMs | — |

Configuration

new RateApiClient(apiKey, baseUrl?, timeoutMs?, maxRetries?)

| Argument | Default | Notes | |---|---|---| | baseUrl | https://rate-api.com/api/v1 | pass …/api/v2 to target v2 directly | | timeoutMs | 15000 | end-to-end deadline per attempt (covers headers and body) | | maxRetries | 2 | automatically retries 429/503/network/timeout with exponential backoff, honouring the server's Retry-After header |

License

MIT

Stocks, metals and key status (Pro plan and up)

await client.stocks(['AAPL', 'MSFT']);   // latest closes, USD
await client.metals(['XAU', 'XAG']);     // per troy ounce, USD
await client.status();                   // is this key still good?