Exchange Rate API — @allratestoday/sdk

Real-time mid-market currency exchange rates for Node.js and browsers. The most elegant way to access 160+ currencies.

🚀 Why Choose This Client?

• ⚡ Lightning Fast — Zero runtime dependencies, pure TypeScript performance
• 📡 Real-Time Data — Rates updated every 60 seconds
• 💹 Mid-Market Rates — No retail spread or markup baked in
• 🌍 160+ Currencies — Major, minor, and exotic currency pairs
• 🏛️ Official Rates Too — latest tables from 122 central banks and 4 tax authorities via officialRates(), no key needed
• 🔷 Type-Safe — Full TypeScript support with intelligent autocomplete
• 🌐 Universal — Works seamlessly in Node.js 18+ and modern browsers
• 🧑‍💻 Developer-Friendly — Simple API, extensive documentation, and great DX

🔑 Get Your API Key

Ready to start? Get your free API key from allratestoday.com/register.

📦 Installation

npm install @allratestoday/sdk

yarn add @allratestoday/sdk

pnpm add @allratestoday/sdk

🏁 Quick Start

Get up and running in seconds:

import AllRatesToday from '@allratestoday/sdk';

// Set your API key
const client = new AllRatesToday({ apiKey: 'YOUR_API_KEY' });

// Get latest exchange rates
const { rates } = await client.latest({ base: 'USD', symbols: ['EUR', 'GBP', 'JPY'] });
console.log(rates);

📚 API Reference

• Latest Rates — Get current exchange rates
• Historical Data — Fetch rates for specific dates
• Currency Conversion — Convert between currencies
• Time Series — Get rates over date ranges
• Available Currencies — List all supported currencies
• Single Rate — Get one currency pair
• Historical by Period — Preset period lookups

Latest Exchange Rates

Get the most current exchange rates with a single call:

// Get all rates from USD
const data = await client.latest();
console.log(data);

// Target specific currencies
const data = await client.latest({ base: 'USD', symbols: ['CHF', 'GBP', 'JPY'] });
console.log(data);

Response:

{
  base: 'USD',
  date: '2026-04-09T14:30:00Z',
  rates: {
    CHF: 0.8821,
    GBP: 0.7891,
    JPY: 151.42
  }
}

Historical Exchange Rates

Historical methods (forDate, timeSeries, getHistoricalRates and convert with a date) need a paid plan from €4.99/month. Free and trial keys get latest rates only and receive a 403 historical_requires_paid_plan for history.

Travel back in time to get rates from any date:

// Using a string date
const data = await client.forDate('2026-01-15', { base: 'USD', symbols: ['EUR'] });
console.log(data);

// Using a Date object
const data = await client.forDate(new Date('2026-01-15'), { base: 'EUR', symbols: ['USD', 'GBP'] });
console.log(data);

Response:

{
  base: 'USD',
  date: '2026-01-15',
  rates: {
    EUR: 0.9187
  }
}

Currency Conversion

Convert any amount between currencies — including historical conversions (paid plans):

// Current conversion
const result = await client.convert('USD', 'EUR', 1000);
console.log(result);

Response:

{
  from: 'USD',
  to: 'EUR',
  amount: 1000,
  result: 923.4,
  rate: 0.9234
}

// Historical conversion — what was $1,000 worth on Jan 15?
const result = await client.convert('USD', 'EUR', 1000, { date: '2026-01-15' });
console.log(result);

Response:

{
  from: 'USD',
  to: 'EUR',
  amount: 1000,
  result: 918.7,
  rate: 0.9187,
  date: '2026-01-15'
}

Available Currencies

Discover all 160+ supported currency symbols and names:

const data = await client.symbols();
console.log(data);

Response:

{
  symbols: {
    AED: 'United Arab Emirates Dirham',
    AFN: 'Afghan Afghani',
    ALL: 'Albanian Lek',
    AMD: 'Armenian Dram',
    AUD: 'Australian Dollar',
    BDT: 'Bangladeshi Taka',
    BRL: 'Brazilian Real',
    CAD: 'Canadian Dollar',
    CHF: 'Swiss Franc',
    CNY: 'Chinese Yuan',
    EUR: 'Euro',
    GBP: 'British Pound Sterling',
    INR: 'Indian Rupee',
    JPY: 'Japanese Yen',
    KRW: 'South Korean Won',
    USD: 'United States Dollar',
    // ...160+ currencies
  }
}

Time Series Data

Get exchange rates over a date range for trend analysis and charting (paid plans):

const data = await client.timeSeries('2026-01-01', '2026-03-31', {
  base: 'USD',
  symbols: ['EUR', 'GBP'],
});
console.log(data);

Response:

{
  base: 'USD',
  startDate: '2026-01-01',
  endDate: '2026-03-31',
  rates: {
    '2026-01-01': {
      EUR: 0.9187,
      GBP: 0.7834
    },
    '2026-01-02': {
      EUR: 0.9195,
      GBP: 0.7841
    },
    '2026-01-03': {
      EUR: 0.9201,
      GBP: 0.7856
    },
    // ...
  }
}

Single Rate

Get a single exchange rate between two currencies:

const rate = await client.getRate('USD', 'EUR');
console.log(rate);

Response:

{
  from: { currency: 'USD', amount: 1 },
  to: { currency: 'EUR', amount: 0.9234 },
  rate: 0.9234,
  source: 'wise'
}

// With amount
const rate = await client.getRate('USD', 'EUR', 500);
console.log(`$500 = €${rate.to.amount}`);

Official Central-Bank & Tax-Authority Rates (no key needed)

The methods above return live mid-market rates. For the official rate an institution published — what invoices, VAT returns, customs declarations and audits require — use officialRates(). It covers 122 central banks plus HMRC, the US Treasury, Swiss BAZG and India's CBIC, and the latest table needs no API key:

const client = new AllRatesToday(); // no key

// Full ECB reference table
const table = await client.officialRates('ecb');
console.log(table.rate_date, table.rates); // [{ base: 'EUR', quote: 'USD', type: 'reference', value: 1.17 }, …]

// One pair (cross-computed inside the bank's own table if not published directly → `derived: true`)
const usd = await client.officialRates('ecb', { source: 'EUR', target: 'USD' });
console.log(`ECB ${usd.rate_date}: 1 EUR = ${usd.rate} USD`);

// Which sources exist, and which are behind their publication schedule
const { sources } = await client.officialSources();
console.log(sources.map((s) => `${s.code} ${s.latest}${s.stale ? ' (stale)' : ''}`));

Always cite the returned rate_date — it is the institution's publication date, not the time of your call. Dated tables and history need a paid plan and use /api/v1/central-bank/{bank}/{date}; publication calendars work on any key. See the central bank rates API.

Historical Rates by Period

Get historical rates using preset periods — no date math needed (paid plans):

const history = await client.getHistoricalRates('USD', 'EUR', '30d');
console.log(history);

Response:

{
  source: 'USD',
  target: 'EUR',
  period: '30d',
  current: { rate: 0.9234, time: '2026-04-09T14:30:00Z' },
  rates: [
    { rate: 0.9198, time: '2026-03-10T00:00:00Z' },
    { rate: 0.9210, time: '2026-03-11T00:00:00Z' },
    // ...
  ]
}

Available periods: 1d | 7d | 30d | 1y

🔧 Configuration

const client = new AllRatesToday({
  apiKey: 'YOUR_API_KEY',          // Required — get one free at allratestoday.com/register
  baseUrl: 'https://allratestoday.com', // Optional — API base URL
  timeout: 10000,                       // Optional — request timeout in ms
});

🔀 Per-Request API Key Override

Every method supports a per-request API key override — useful for multi-tenant apps:

const client = new AllRatesToday({ apiKey: 'default_key' });

// Override for a specific request
const data = await client.latest({ apiKey: 'other_users_key' });
const result = await client.convert('USD', 'EUR', 100, { apiKey: 'tenant_key' });
const { symbols } = await client.symbols({ apiKey: 'another_key' });

🛡️ Error Handling

All errors are thrown as AllRatesTodayError with an optional HTTP status code:

import AllRatesToday, { AllRatesTodayError } from '@allratestoday/sdk';

try {
  const rate = await client.getRate('USD', 'INVALID');
} catch (err) {
  if (err instanceof AllRatesTodayError) {
    console.log(err.message); // "Currency not found"
    console.log(err.status);  // 404
  }
}

🔷 TypeScript

The SDK is written in TypeScript and ships full type definitions. All interfaces are exported:

import AllRatesToday, {
  AllRatesTodayError,
  AllRatesTodayOptions,
  RequestOptions,
  RateResponse,
  AuthRateResponse,
  LatestOptions,
  LatestResponse,
  ForDateOptions,
  ForDateResponse,
  ConvertOptions,
  ConvertResponse,
  TimeSeriesOptions,
  TimeSeriesResponse,
  HistoricalRateResponse,
  SymbolsResponse,
} from '@allratestoday/sdk';

📦 CommonJS

const AllRatesToday = require('@allratestoday/sdk').default;

const client = new AllRatesToday({ apiKey: 'YOUR_API_KEY' });
client.latest().then(data => console.log(data.rates));

💡 Examples

Currency Dropdown (React)

import { useEffect, useState } from 'react';
import AllRatesToday from '@allratestoday/sdk';

const client = new AllRatesToday({ apiKey: 'YOUR_API_KEY' });

function CurrencySelect({ value, onChange }) {
  const [currencies, setCurrencies] = useState([]);

  useEffect(() => {
    client.symbols().then(({ symbols }) => {
      setCurrencies(
        Object.entries(symbols).map(([code, name]) => ({ code, name }))
      );
    });
  }, []);

  return (
    <select value={value} onChange={e => onChange(e.target.value)}>
      {currencies.map(c => (
        <option key={c.code} value={c.code}>{c.code} — {c.name}</option>
      ))}
    </select>
  );
}

Price Display with Caching

import AllRatesToday from '@allratestoday/sdk';

const client = new AllRatesToday({ apiKey: 'YOUR_API_KEY' });
let cache: { rates: Record<string, number>; time: number } | null = null;
const TTL = 5 * 60 * 1000; // 5 minutes

async function getPrice(amountUSD: number, currency: string): Promise<string> {
  if (!cache || Date.now() - cache.time > TTL) {
    const data = await client.latest({ base: 'USD' });
    cache = { rates: data.rates, time: Date.now() };
  }
  const converted = (amountUSD * cache.rates[currency]).toFixed(2);
  return `${converted} ${currency}`;
}

console.log(await getPrice(99.99, 'EUR')); // "92.32 EUR"
console.log(await getPrice(99.99, 'GBP')); // "78.90 GBP"

Historical Chart Data

Needs a paid plan (history is not included in free or trial keys).

import AllRatesToday from '@allratestoday/sdk';

const client = new AllRatesToday({ apiKey: 'YOUR_API_KEY' });

const data = await client.timeSeries('2026-01-01', '2026-04-01', {
  base: 'USD',
  symbols: ['EUR'],
});

// Format for charting libraries (Chart.js, Recharts, etc.)
const labels = Object.keys(data.rates).sort();
const values = labels.map(date => data.rates[date].EUR);

console.log({ labels, values });
// { labels: ['2026-01-01', '2026-01-02', ...], values: [0.92, 0.921, ...] }

📖 Methods Reference

🧪 Testing

Run isolated unit tests (no API calls needed):

npm test

Run tests with coverage report:

npm run test:coverage

Watch mode for development:

npm run test:watch

🤖 Use it from an AI agent

The same rates are available to coding agents and LLM tools without a second integration:

• Claude Code plugin (no key): /plugin marketplace add AllRates-Today/claude-code-plugin then /plugin install allratestoday@allratestoday
• Hosted MCP endpoint: https://allratestoday.com/api/mcp — Streamable HTTP, keyless, nothing to install
• Local MCP servers: npx -y @allratestoday/mcp-server (live mid-market rates) · npx -y @allratestoday/central-bank-mcp (official central-bank rates)
• Trial key for agents, no signup: POST https://allratestoday.com/api/agent/keys (send Content-Type: application/json) returns a 100-call key valid 7 days for latest rates and latest central-bank tables (history and dated tables are paid-plan only); both MCP servers expose it as request_trial_key
• Daily Reference Rate (first published 2026-10-12): one fixed USD table per business day, the 16:00 London median of minute samples, never revised — keyless at https://allratestoday.com/api/open/reference-rate, get_reference_rate in the MCP server
• Machine-readable site guide: llms.txt

🔗 Links

• Website: allratestoday.com
• Download central bank rates — every bank's tables as Excel, CSV or JSON
• API Documentation
• Register (Free)
• Dashboard
• Status
• Postman collection
• ChatGPT app — ask ChatGPT for live and official central bank rates
• GitHub

📜 License

MIT