FrankfurterApi

FrankfurterApi is an exchange-rate provider that uses Frankfurter for live currency rates.

Unlike ExchangeRateApi, FrankfurterApi does not require an API key.

Import

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

Usage with Exchange

Select FrankfurterApi using Exchange.setProvider():

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

Exchange.setProvider(FrankfurterApi);

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

No Exchange.setApiKey() call is required.

Authentication

FrankfurterApi does not require an API key.

Exchange.setProvider(FrankfurterApi);

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

Constructor

FrankfurterApi follows the exchange-rate provider constructor pattern.

Default Constructor

new FrankfurterApi();

Configuration Object

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

The optional API-key argument exists for compatibility with the provider constructor contract and is ignored by Frankfurter.

Example:

const provider = new FrankfurterApi({
  source: 'USD',
  target: 'EUR',
  amount: 100,
});

Positional Arguments

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

Example:

const provider = new FrankfurterApi('USD', 'EUR', 100);

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.

rate()

rate(): Promise<number>

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

const provider = new FrankfurterApi({
  source: 'USD',
  target: 'EUR',
  amount: 1,
});

const rate = await provider.rate();

convert()

convert(): Promise<number>

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

Frankfurter returns the exchange rate rather than a converted amount, so the provider derives the conversion result using:

conversion result = rate × amount

Example:

const provider = new FrankfurterApi({
  source: 'USD',
  target: 'EUR',
  amount: 100,
});

const result = await provider.convert();

Rate Normalization

Conceptually, the provider normalizes Frankfurter's response into:

{
  conversion_rate: data.rate,
  conversion_result: data.rate * amount,
}

This allows Exchange to use FrankfurterApi without provider-specific logic.

Chainable Provider API

const provider = new FrankfurterApi();

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

Using as an Exchange Provider

Pass the provider class directly to Exchange.setProvider():

Exchange.setProvider(FrankfurterApi);

The rest of the Exchange API remains unchanged:

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

const rate = await Exchange.from('USD').to('EUR').rate();

const formatted = await Exchange.from('USD').to('GBP').convert(100).format();

Switching from ExchangeRateApi

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

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

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

Exchange.setProvider(FrankfurterApi);

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

Errors

Provider and network errors are exposed through ExchangeException.

Because Frankfurter does not require authentication, it does not require the missing-key flow used by ExchangeRateApi.

try {
  const result = await Exchange.from('USD').to('EUR').convert(100);
} catch (error) {
  console.error('Conversion error:', error.message);
}

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
• ExchangeRateApi