{"id":27290947,"url":"https://github.com/kabeep/forex","last_synced_at":"2026-02-26T23:33:43.322Z","repository":{"id":266159375,"uuid":"896107103","full_name":"kabeep/forex","owner":"kabeep","description":"💱 A JavaScript foreign exchange library via fawazahmed0's API.","archived":false,"fork":false,"pushed_at":"2025-03-03T10:03:11.000Z","size":181,"stargazers_count":2,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-05T13:14:11.946Z","etag":null,"topics":["currency","currency-rates","exchange","foreign-exchange","forex"],"latest_commit_sha":null,"homepage":"https://kabeep.github.io/forex/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kabeep.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-11-29T15:00:19.000Z","updated_at":"2024-12-12T08:10:17.000Z","dependencies_parsed_at":"2024-12-02T22:31:31.429Z","dependency_job_id":"a7000957-7e9a-490a-99be-5d8de1959adf","html_url":"https://github.com/kabeep/forex","commit_stats":null,"previous_names":["kabeep/forex"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/kabeep/forex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kabeep%2Fforex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kabeep%2Fforex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kabeep%2Fforex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kabeep%2Fforex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kabeep","download_url":"https://codeload.github.com/kabeep/forex/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kabeep%2Fforex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29877017,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T22:37:10.609Z","status":"ssl_error","status_checked_at":"2026-02-26T22:37:09.019Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["currency","currency-rates","exchange","foreign-exchange","forex"],"created_at":"2025-04-11T21:39:42.444Z","updated_at":"2026-02-26T23:33:43.303Z","avatar_url":"https://github.com/kabeep.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003ch1\u003eforex\u003c/h1\u003e\n\n💱 A JavaScript foreign exchange library via `fawazahmed0`'s API.\n\n[![NodeJS][node-image]][node-url]\n[![License][license-image]][license-url]\n[![NPM][npm-image]][npm-url]\n[![Codecov][codecov-image]][codecov-url]\n[![BundlePhobia][bundle-phobia-image]][bundle-phobia-url]\n[![CircleCI][circleci-image]][circleci-url]\n\nEnglish | [简体中文][zh-cn-url]\n\n![Insights][insights-url]\n\n\u003c/div\u003e\n\n## 📖 Introduction\n\n\u003e `forex` stands for `Foreign Exchange`, and its purpose is not `FX` trading.\n\u003e \n\u003e Please use it with caution for investment-related decisions.\n\nGet daily exchange rates in the browser or terminal for free and without rate limits.\n\nSee [documentation][docs-url] or [demo][demo-url].\n\n## ⚙️ Installation\n\n```bash\nnpm install @kabeep/forex --save\n```\n\n```bash\nyarn add @kabeep/forex\n```\n\n```bash\npnpm add @kabeep/forex\n```\n\n## 🚀 Usage\n\n**CommonJS**\n\n```typescript\nconst { ForexClient, ForexClientOptions } = require('@kabeep/forex');\n\nconst client = new ForexClinet({} as ForexClientOptions);\n```\n\n**ESModule**\n\n```typescript\nimport { ForexClient, type ForexClientOptions } from '@kabeep/forex';\n\nconst client = new ForexClinet({} as ForexClientOptions);\n```\n\n**Interface `ForexClientOptions`:**\n\n| Parameter      | Type          | Optional | Default | Description                    |\n|----------------|---------------|:--------:|---------|--------------------------------|\n| `baseCurrency` | `string`      |   true   | -       | The base currency code         |\n| `minified`     | `boolean`     |   true   | `true`  | Minified JSON format           |\n| `timeout`      | `number`      |   true   | `5000`  | Request timeout (milliseconds) |\n| `headers`      | `HeadersInit` |   true   | `{}`    | Request header                 |\n\n---\n\n#### Methods: `getCurrencies(date, options)`\n\nFetches the list of available currencies.\n\n```typescript\nconst client = new ForexClient();\n// =\u003e {\n//    code: 200,\n//    message: 'OK',\n//    data: [\n//        { code: 'eur', name: 'Euro' },\n//        { code: 'usd', name: 'US Dollar' },\n//        { code: 'cny', name: 'Chinese Yuan Renminbi' },\n//        { code: 'btc', name: 'Bitcoin', }\n//        ... More items\n//    ]\n// }\nclient.getCurrencies('latest');\n\n// or\nclient.getCurrencies(new Date(2024, 11, 1));\n```\n\n| Parameter | Type                 | Optional | Default    | Description                                                         |\n|-----------|----------------------|:--------:|------------|---------------------------------------------------------------------|\n| `date`    | `Date` \\| `\"latest\"` |   true   | `\"latest\"` | The date for fetching currencies, or `\"latest\"` for the most recent |\n| `options` | `RequestInit`        |   true   | `{}`       | Additional request options                                          |\n\n**Returns: `Promise\u003cHttpResponse\u003cAvailableCurrency[]\u003e\u003e`**\n\n| Key       | Type                  | Required | Description                   |\n|-----------|-----------------------|:--------:|-------------------------------|\n| `code`    | `number`              |   true   | HTTP response status codes    |\n| `message` | `string`              |   true   | HTTP response status messages |\n| `data`    | `AvailableCurrency[]` |  false   | List of available currency    |\n\n**Interface: `AvailableCurrency`**\n\n| Key    | Type     | Required | Description      |\n|--------|----------|:--------:|------------------|\n| `code` | `string` |   true   | Code of currency |\n| `name` | `string` |  false   | Name of currency |\n\n---\n\n#### Methods: `getRates(code, date, options)`\n\nFetches the exchange rates for a specific currency.\n\n```typescript\nconst client = new ForexClient();\n// =\u003e {\n//    code: 200,\n//    message: 'OK',\n//    data: [\n//        { code: 'eur', rate: 100_000 },\n//        { code: 'usd', rate: 100_000 },\n//        { code: 'cny', rate: 100_000 },\n//        ... More items\n//    ]\n// }\nclient.getRates('USD');\n\n// or\nclient.getRates('US');\n```\n\n| Parameter | Type                 | Optional | Default                     | Description                                                         |\n|-----------|----------------------|:--------:|-----------------------------|---------------------------------------------------------------------|\n| `code`    | `string`             |   true   | `this.options.baseCurrency` | The currency code or locale code to get rates for                   |\n| `date`    | `Date` \\| `\"latest\"` |   true   | `\"latest\"`                  | The date for fetching currencies, or `\"latest\"` for the most recent |\n| `options` | `RequestInit`        |   true   | `{}`                        | Additional request options                                          |\n\n**Returns: `Promise\u003cHttpResponse\u003cExchangeRate[]\u003e\u003e`**\n\n| Key       | Type             | Required | Description                   |\n|-----------|------------------|:--------:|-------------------------------|\n| `code`    | `number`         |   true   | HTTP response status codes    |\n| `message` | `string`         |   true   | HTTP response status messages |\n| `data`    | `ExchangeRate[]` |  false   | List of exchange rates        |\n\n**Interface: `ExchangeRate`**\n\n| Key    | Type     | Required | Description      |\n|--------|----------|:--------:|------------------|\n| `code` | `string` |   true   | Code of currency |\n| `rate` | `number` |  false   | Rate of currency |\n\n---\n\n#### Methods: `getRate(baseCode, destCode, date, options)`\n\nFetches the exchange rate between two currencies.\n\n```typescript\nconst client = new ForexClient();\n// =\u003e {\n//    code: 200,\n//    message: 'OK',\n//    data: 0.94759027\n// }\nclient.getRate('USD', 'EUR');\n\n// =\u003e {\n//    code: 200,\n//    message: 'OK',\n//    data: 7.78004385\n// }\nclient.getRate('US', 'HK');\n```\n\n| Parameter  | Type                 | Optional | Default                     | Description                                                         |\n|------------|----------------------|:--------:|-----------------------------|---------------------------------------------------------------------|\n| `baseCode` | `string`             |   true   | `this.options.baseCurrency` | The base currency code or locale code                               |\n| `destCode` | `string`             |   true   | -                           | The destination currency code or locale code                        |\n| `date`     | `Date` \\| `\"latest\"` |   true   | `\"latest\"`                  | The date for fetching currencies, or `\"latest\"` for the most recent |\n| `options`  | `RequestInit`        |   true   | `{}`                        | Additional request options                                          |\n\n**Returns: `Promise\u003cHttpResponse\u003cnumber\u003e\u003e`**\n\n| Key       | Type     | Required | Description                   |\n|-----------|----------|:--------:|-------------------------------|\n| `code`    | `number` |   true   | HTTP response status codes    |\n| `message` | `string` |   true   | HTTP response status messages |\n| `data`    | `number` |  false   | The exchange rate             |\n\n---\n\n#### Methods: `getCode(localeCode)`\n\nGet a valid currency code based on ISO 3166-1 code.\n\n```typescript\nconst client = new ForexClient();\n// =\u003e 'USD'\nclient.getCode('US');\n\n// =\u003e 'CNH'\nclient.getCode('HK');\n\n// =\u003e 'CNY'\nclient.getCode('RMB');\n```\n\n| Parameter    | Type     | Optional | Default | Description                              |\n|--------------|----------|:--------:|---------|------------------------------------------|\n| `localeCode` | `string` |  false   | -       | The locale code to get currency code for |\n\n**Returns: `string`**\n\nThe corresponding currency code.\n\n---\n\n#### Methods: `convert(baseCode, destCode, amount, date, options)`\n\nConverts an amount from one currency to another.\n\n```typescript\nconst client = new ForexClient();\n// =\u003e {\n//    code: 200,\n//    message: 'OK',\n//    data: 9.48\n// }\nclient.convert('USD', 'EUR', 10);\n\n// =\u003e {\n//    code: 200,\n//    message: 'OK',\n//    data: 72.67\n// }\nclient.convert('US', 'HK', 10);\n```\n\n| Parameter  | Type                 | Optional | Default                     | Description                                                         |\n|------------|----------------------|:--------:|-----------------------------|---------------------------------------------------------------------|\n| `baseCode` | `string`             |   true   | `this.options.baseCurrency` | The base currency code or locale code                               |\n| `destCode` | `string`             |   true   | -                           | The destination currency code or locale code                        |\n| `amount`   | `number`             |   true   | `0`                         | The amount to convert                                               |\n| `date`     | `Date` \\| `\"latest\"` |   true   | `\"latest\"`                  | The date for fetching currencies, or `\"latest\"` for the most recent |\n| `options`  | `RequestInit`        |   true   | `{}`                        | Additional request options                                          |\n\n**Returns: `Promise\u003cHttpResponse\u003cnumber\u003e\u003e`**\n\n| Key       | Type     | Required | Description                   |\n|-----------|----------|:--------:|-------------------------------|\n| `code`    | `number` |   true   | HTTP response status codes    |\n| `message` | `string` |   true   | HTTP response status messages |\n| `data`    | `number` |  false   | The converted amount          |\n\n## 🏅 Credits\n\n- [exchange-api][exchange-api-url] - This package would not exist without this.\n\n## 🔗 Related\n\n- [forex-cli][forex-cli-url] - 💱 A Node.js Library to convert foreign exchange in terminal.\n\n## 🤝 Contribution\n\nContributions via Pull Requests or [Issues][issues-url] are welcome.\n\n## 📄 License\n\nThis project is licensed under the MIT License. See the [LICENSE][license-url] file for details.\n\n[node-image]: https://img.shields.io/node/v/%40kabeep%2Fforex?color=lightseagreen\n[node-url]: https://nodejs.org\n[npm-image]: https://img.shields.io/npm/d18m/%40kabeep%2Fforex?color=cornflowerblue\n[npm-url]: https://www.npmjs.com/package/@kabeep/forex\n[codecov-image]: https://img.shields.io/codecov/c/github/kabeep/forex?logo=codecov\u0026color=mediumvioletred\n[codecov-url]: https://codecov.io/gh/kabeep/forex\n[bundle-phobia-image]: https://img.shields.io/bundlephobia/minzip/@kabeep/forex\n[bundle-phobia-url]: https://bundlephobia.com/package/@kabeep/forex\n[circleci-image]: https://dl.circleci.com/status-badge/img/gh/kabeep/forex/tree/master.svg?style=shield\n[circleci-url]: https://dl.circleci.com/status-badge/redirect/gh/kabeep/forex/tree/master\n[insights-url]: https://repobeats.axiom.co/api/embed/1f8180692870dfd0a67e8cd0503bab7fb8f92223.svg \"Repobeats analytics image\"\n[docs-url]: https://kabeep.github.io/forex\n[demo-url]: https://kabeep.github.io/forex/documents/demo.html\n[exchange-api-url]: https://github.com/fawazahmed0/exchange-api\n[forex-cli-url]: https://github.com/kabeep/forex-cli\n[issues-url]: https://github.com/kabeep/forex/issues\n[license-image]: https://img.shields.io/github/license/kabeep/forex?color=slateblue\n[license-url]: LICENSE\n[en-us-url]: README.md\n[zh-cn-url]: README.zh-CN.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkabeep%2Fforex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkabeep%2Fforex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkabeep%2Fforex/lists"}