📖 Introduction

forex stands for Foreign Exchange, and its purpose is not FX trading.

Please use it with caution for investment-related decisions.

Get daily exchange rates in the browser or terminal for free and without rate limits.

See documentation or demo.

⚙️ Installation

npm install @kabeep/forex --save
Copy

yarn add @kabeep/forex
Copy

pnpm add @kabeep/forex
Copy

🚀 Usage

CommonJS

const { ForexClient, ForexClientOptions } = require('@kabeep/forex');

const client = new ForexClinet({} as ForexClientOptions);
Copy

ESModule

import { ForexClient, type ForexClientOptions } from '@kabeep/forex';

const client = new ForexClinet({} as ForexClientOptions);
Copy

Interface ForexClientOptions:

Parameter	Type	Optional	Default	Description
baseCurrency	string	true	-	The base currency code
minified	boolean	true	true	Minified JSON format
timeout	number	true	5000	Request timeout (milliseconds)
headers	HeadersInit	true	{}	Request header

---

Methods: getCurrencies(date, options)

Fetches the list of available currencies.

const client = new ForexClient();
// => {
//    code: 200,
//    message: 'OK',
//    data: [
//        { code: 'eur', name: 'Euro' },
//        { code: 'usd', name: 'US Dollar' },
//        { code: 'cny', name: 'Chinese Yuan Renminbi' },
//        { code: 'btc', name: 'Bitcoin', }
//        ... More items
//    ]
// }
client.getCurrencies('latest');

// or
client.getCurrencies(new Date(2024, 11, 1));
Copy

Parameter	Type	Optional	Default	Description
date	Date | "latest"	true	"latest"	The date for fetching currencies, or "latest" for the most recent
options	RequestInit	true	{}	Additional request options

Returns: Promise<HttpResponse<AvailableCurrency[]>>

Key	Type	Required	Description
code	number	true	HTTP response status codes
message	string	true	HTTP response status messages
data	AvailableCurrency[]	false	List of available currency

Interface: AvailableCurrency

Key	Type	Required	Description
code	string	true	Code of currency
name	string	false	Name of currency

---

Methods: getRates(code, date, options)

Fetches the exchange rates for a specific currency.

const client = new ForexClient();
// => {
//    code: 200,
//    message: 'OK',
//    data: [
//        { code: 'eur', rate: 100_000 },
//        { code: 'usd', rate: 100_000 },
//        { code: 'cny', rate: 100_000 },
//        ... More items
//    ]
// }
client.getRates('USD');

// or
client.getRates('US');
Copy

Parameter	Type	Optional	Default	Description
code	string	true	this.options.baseCurrency	The currency code or locale code to get rates for
date	Date | "latest"	true	"latest"	The date for fetching currencies, or "latest" for the most recent
options	RequestInit	true	{}	Additional request options

Returns: Promise<HttpResponse<ExchangeRate[]>>

Key	Type	Required	Description
code	number	true	HTTP response status codes
message	string	true	HTTP response status messages
data	ExchangeRate[]	false	List of exchange rates

Interface: ExchangeRate

Key	Type	Required	Description
code	string	true	Code of currency
rate	number	false	Rate of currency

---

Methods: getRate(baseCode, destCode, date, options)

Fetches the exchange rate between two currencies.

const client = new ForexClient();
// => {
//    code: 200,
//    message: 'OK',
//    data: 0.94759027
// }
client.getRate('USD', 'EUR');

// => {
//    code: 200,
//    message: 'OK',
//    data: 7.78004385
// }
client.getRate('US', 'HK');
Copy

Parameter	Type	Optional	Default	Description
baseCode	string	true	this.options.baseCurrency	The base currency code or locale code
destCode	string	true	-	The destination currency code or locale code
date	Date | "latest"	true	"latest"	The date for fetching currencies, or "latest" for the most recent
options	RequestInit	true	{}	Additional request options

Returns: Promise<HttpResponse<number>>

Key	Type	Required	Description
code	number	true	HTTP response status codes
message	string	true	HTTP response status messages
data	number	false	The exchange rate

---

Methods: getCode(localeCode)

Get a valid currency code based on ISO 3166-1 code.

const client = new ForexClient();
// => 'USD'
client.getCode('US');

// => 'CNH'
client.getCode('HK');

// => 'CNY'
client.getCode('RMB');
Copy

Parameter	Type	Optional	Default	Description
localeCode	string	false	-	The locale code to get currency code for

Returns: string

The corresponding currency code.

---

Methods: convert(baseCode, destCode, amount, date, options)

Converts an amount from one currency to another.

const client = new ForexClient();
// => {
//    code: 200,
//    message: 'OK',
//    data: 9.48
// }
client.convert('USD', 'EUR', 10);

// => {
//    code: 200,
//    message: 'OK',
//    data: 72.67
// }
client.convert('US', 'HK', 10);
Copy

Parameter	Type	Optional	Default	Description
baseCode	string	true	this.options.baseCurrency	The base currency code or locale code
destCode	string	true	-	The destination currency code or locale code
amount	number	true	0	The amount to convert
date	Date | "latest"	true	"latest"	The date for fetching currencies, or "latest" for the most recent
options	RequestInit	true	{}	Additional request options

Returns: Promise<HttpResponse<number>>

Key	Type	Required	Description
code	number	true	HTTP response status codes
message	string	true	HTTP response status messages
data	number	false	The converted amount

🏅 Credits

• exchange-api - This package would not exist without this.

🔗 Related

• forex-cli - 💱 A Node.js Library to convert foreign exchange in terminal.

🤝 Contribution

Contributions via Pull Requests or Issues are welcome.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.