ExchangeRateApi

ExchangeRateApi is the default exchange-rate provider used by Exchange.

It uses ExchangeRate-API for live currency conversion and preserves the existing API-key based workflow.

Import

import { Exchange, ExchangeRateApi } from '@toneflix/money';

Usage with Exchange

ExchangeRateApi is the default provider, so you do not need to select it explicitly.

import { Exchange } from '@toneflix/money';

Exchange.setApiKey('your-api-key-here');

const result = await Exchange.from('USD').to('EUR').convert(100);

You can also select it explicitly:

import { Exchange, ExchangeRateApi } from '@toneflix/money';

Exchange.setProvider(ExchangeRateApi);
Exchange.setApiKey('your-api-key-here');

const result = await Exchange.from('USD').to('EUR').convert(100);

Authentication

ExchangeRateApi requires an API key.

You can configure the API key programmatically:

Exchange.setApiKey('your-api-key-here');

Or through the environment:

EXCHANGERATE_API_KEY=your-api-key-here

The provider also supports these environment fallbacks:

VITE_EXCHANGERATE_API_KEY=your-api-key-here
NEXT_EXCHANGERATE_API_KEY=your-api-key-here

An API key passed directly to the provider takes precedence over environment configuration.

Constructor

ExchangeRateApi supports multiple constructor signatures.

Default Constructor

new ExchangeRateApi();

Creates a provider using the default configuration:

{
  source: 'USD',
  target: 'EUR',
  amount: 1,
}

Configuration Object

new ExchangeRateApi(
  config: ExchangeRateInput,
  apiKey?: string,
)

Example:

const provider = new ExchangeRateApi(
  {
    source: 'USD',
    target: 'EUR',
    amount: 100,
  },
  'your-api-key',
);

Positional Arguments

new ExchangeRateApi(
  source: CurrencyCode,
  target: CurrencyCode,
  amount: number,
  apiKey?: string,
)

Example:

const provider = new ExchangeRateApi('USD', 'EUR', 100, 'your-api-key');

Methods

source()

source(value: CurrencyCode): this

Set the source currency and return the provider instance for chaining.

target()

target(value: CurrencyCode): this

Set the target currency and return the provider instance for chaining.

amount()

amount(value: number): this

Set the amount to convert and return the provider instance for chaining.

convert()

convert(): Promise<number>

Convert the configured amount from the source currency to the target currency.

const provider = new ExchangeRateApi(
  {
    source: 'USD',
    target: 'EUR',
    amount: 100,
  },
  'your-api-key',
);

const result = await provider.convert();

rate()

rate(): Promise<number>

Get the exchange rate between the configured source and target currencies.

const provider = new ExchangeRateApi(
  {
    source: 'USD',
    target: 'EUR',
    amount: 1,
  },
  'your-api-key',
);

const rate = await provider.rate();

Chainable Provider API

const provider = new ExchangeRateApi();

const result = await provider.source('USD').target('EUR').amount(100).convert();

Using as an Exchange Provider

ExchangeRateApi implements the exchange-rate provider contract and can be passed directly to Exchange.setProvider().

Exchange.setProvider(ExchangeRateApi);

Errors

If no API key can be resolved, the provider throws an ExchangeException with the missing-key error type.

try {
  const result = await Exchange.from('USD').to('EUR').convert(100);
} catch (error) {
  if (error.type === 'missing-key') {
    console.error('Please configure an ExchangeRate-API key');
  }
}

Provider Contract

interface ExchangeRateContract {
  source(value: CurrencyCode): this;
  target(value: CurrencyCode): this;
  amount(value: number): this;
  convert(): Promise<number>;
  rate(): Promise<number>;
}

Related

• Exchange Class
• Currency Conversion
• FrankfurterApi