https://github.com/kabeep/forex
đą A JavaScript foreign exchange library via fawazahmed0's API.
https://github.com/kabeep/forex
currency currency-rates exchange foreign-exchange forex
Last synced: 5 months ago
JSON representation
đą A JavaScript foreign exchange library via fawazahmed0's API.
- Host: GitHub
- URL: https://github.com/kabeep/forex
- Owner: kabeep
- License: mit
- Created: 2024-11-29T15:00:19.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-03-03T10:03:11.000Z (over 1 year ago)
- Last Synced: 2025-10-05T13:14:11.946Z (10 months ago)
- Topics: currency, currency-rates, exchange, foreign-exchange, forex
- Language: TypeScript
- Homepage: https://kabeep.github.io/forex/
- Size: 177 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
forex
đą A JavaScript foreign exchange library via `fawazahmed0`'s API.
[![NodeJS][node-image]][node-url]
[![License][license-image]][license-url]
[![NPM][npm-image]][npm-url]
[![Codecov][codecov-image]][codecov-url]
[![BundlePhobia][bundle-phobia-image]][bundle-phobia-url]
[![CircleCI][circleci-image]][circleci-url]
English | [įŽäŊä¸æ][zh-cn-url]
![Insights][insights-url]
## đ 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][docs-url] or [demo][demo-url].
## âī¸ Installation
```bash
npm install @kabeep/forex --save
```
```bash
yarn add @kabeep/forex
```
```bash
pnpm add @kabeep/forex
```
## đ Usage
**CommonJS**
```typescript
const { ForexClient, ForexClientOptions } = require('@kabeep/forex');
const client = new ForexClinet({} as ForexClientOptions);
```
**ESModule**
```typescript
import { ForexClient, type ForexClientOptions } from '@kabeep/forex';
const client = new ForexClinet({} as ForexClientOptions);
```
**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.
```typescript
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));
```
| 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>`**
| 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.
```typescript
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');
```
| 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>`**
| 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.
```typescript
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');
```
| 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>`**
| 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.
```typescript
const client = new ForexClient();
// => 'USD'
client.getCode('US');
// => 'CNH'
client.getCode('HK');
// => 'CNY'
client.getCode('RMB');
```
| 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.
```typescript
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);
```
| 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>`**
| 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][exchange-api-url] - This package would not exist without this.
## đ Related
- [forex-cli][forex-cli-url] - đą A Node.js Library to convert foreign exchange in terminal.
## đ¤ Contribution
Contributions via Pull Requests or [Issues][issues-url] are welcome.
## đ License
This project is licensed under the MIT License. See the [LICENSE][license-url] file for details.
[node-image]: https://img.shields.io/node/v/%40kabeep%2Fforex?color=lightseagreen
[node-url]: https://nodejs.org
[npm-image]: https://img.shields.io/npm/d18m/%40kabeep%2Fforex?color=cornflowerblue
[npm-url]: https://www.npmjs.com/package/@kabeep/forex
[codecov-image]: https://img.shields.io/codecov/c/github/kabeep/forex?logo=codecov&color=mediumvioletred
[codecov-url]: https://codecov.io/gh/kabeep/forex
[bundle-phobia-image]: https://img.shields.io/bundlephobia/minzip/@kabeep/forex
[bundle-phobia-url]: https://bundlephobia.com/package/@kabeep/forex
[circleci-image]: https://dl.circleci.com/status-badge/img/gh/kabeep/forex/tree/master.svg?style=shield
[circleci-url]: https://dl.circleci.com/status-badge/redirect/gh/kabeep/forex/tree/master
[insights-url]: https://repobeats.axiom.co/api/embed/1f8180692870dfd0a67e8cd0503bab7fb8f92223.svg "Repobeats analytics image"
[docs-url]: https://kabeep.github.io/forex
[demo-url]: https://kabeep.github.io/forex/documents/demo.html
[exchange-api-url]: https://github.com/fawazahmed0/exchange-api
[forex-cli-url]: https://github.com/kabeep/forex-cli
[issues-url]: https://github.com/kabeep/forex/issues
[license-image]: https://img.shields.io/github/license/kabeep/forex?color=slateblue
[license-url]: LICENSE
[en-us-url]: README.md
[zh-cn-url]: README.zh-CN.md