# @allratestoday/sdk 中文文档

规范地址：https://npmcn.com/package/%40allratestoday/sdk/

版本：1\.4\.15
npm 元数据更新时间：2026-11-02T18:19:15.833Z
中文译文更新时间：2026-11-07T02:14:36.373Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40allratestoday/sdk
原文对照：https://npmcn.com/package/%40allratestoday/sdk/?lang=original
项目主页：https://allratestoday.com/
源码仓库：https://github.com/AllRates-Today/exchange-rates-api

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：65.9 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-04-05T17:22:52.665Z
- 最新版本发布：2026-11-02T18:19:15.621Z
- 近 30 天下载量：2073（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：32（近 12 个月 32 个）

## 中文简介

汇率API——Node.js和浏览器的实时中市货币汇率. 160+ 货币,零依赖,自由级.

## 安装

```sh
npm install @allratestoday/sdk
```

也可以使用：`pnpm add @allratestoday/sdk`、`yarn add @allratestoday/sdk`、`bun add @allratestoday/sdk`

## README

# 汇率 API — @allatestoday/ sdk

[![npm version](https://img.shields.io/npm/v/@allratestoday/sdk.svg)](https://www.npmjs.com/package/@allratestoday/sdk) [![codecov](https://codecov.io/gh/AllRates-Today/exchange-rates-api/branch/main/graph/badge.svg)](https://codecov.io/gh/AllRates-Today/exchange-rates-api) [![license](https://img.shields.io/npm/l/@allratestoday/sdk.svg)](https://github.com/AllRates-Today/exchange-rates-api/blob/main/LICENSE) [![TypeScript](https://badges.frapsoft.com/typescript/code/typescript.svg?v=101)](https://www.typescriptlang.org/) [![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](https://www.npmjs.com/package/@allratestoday/sdk) [![Security: Snyk](https://img.shields.io/badge/Security-Snyk-4C4A73?logo=snyk&logoColor=white)](https://snyk.io/test/github/allratestoday/exchange-rates-api)

**用于Node.js和浏览器的实时中市货币汇率. 最优雅的方式进入160+货币.**

## 为什么选择这个客户端?

-   ⚡ **闪电快** ——零运行时依赖性,纯类型脚本性能
-   📡 **实时数据** ——每60秒更新一次
-   💹 **中间市场率** ——无零售推广或打分入烤
-   🌍 **160+ 货币** 主要、次要和异国货币对
-   🏛️ **官方收费率** 最新表格来自 [122个中央银行和4个税务当局](https://allratestoday.com/central-bank-rates-api/institutions/) 通过 `officialRates()`,不需要键
-   🔷 **类型安全** ——智能自动完成的全类型脚本支持
-   🌐 **通用** ——在Node.js 18+和现代浏览器中无缝工作
-   🧑‍💻 **方便开发者** - 简单的API、广泛的文档和伟大的DX

## 获取您的 API 密钥

准备好了吗? 免费 API 密钥从 [allatestoday.com/注册员](https://allratestoday.com/register)。 。 。 .

## \* 安装

```bash
npm install @allratestoday/sdk
```

```bash
yarn add @allratestoday/sdk
```

```bash
pnpm add @allratestoday/sdk
```

## QQ 快速启动

起来,数秒后运行:

```typescript
import AllRatesToday from '@allratestoday/sdk';

// Set your API key
const client = new AllRatesToday({ apiKey: 'YOUR_API_KEY' });

// Get latest exchange rates
const { rates } = await client.latest({ base: 'USD', symbols: ['EUR', 'GBP', 'JPY'] });
console.log(rates);
```

## API 参考

-   [最新比率](https://npmcn.com/package/%40allratestoday/sdk/#readme--latest-exchange-rates) ——获得现行汇率
-   [历史数据](https://npmcn.com/package/%40allratestoday/sdk/#readme--historical-exchange-rates) ——获取特定日期的费率
-   [货币兑换](https://npmcn.com/package/%40allratestoday/sdk/#readme--currency-conversion) - 货币兑换
-   [时间序列](https://npmcn.com/package/%40allratestoday/sdk/#readme--time-series-data) ——按日期范围获取费率
-   [可用货币](https://npmcn.com/package/%40allratestoday/sdk/#readme--available-currencies) - 列出所有支持的货币
-   [单一比率](https://npmcn.com/package/%40allratestoday/sdk/#readme--single-rate) - 得到一对货币
-   [按时期分列的历史](https://npmcn.com/package/%40allratestoday/sdk/#readme--historical-rates-by-period) - 预设期间的检查

* * *

### 最近汇率

获得最新汇率并单调:

```typescript
// Get all rates from USD
const data = await client.latest();
console.log(data);

// Target specific currencies
const data = await client.latest({ base: 'USD', symbols: ['CHF', 'GBP', 'JPY'] });
console.log(data);
```

**回应:**

```javascript
{
  base: 'USD',
  date: '2026-04-09T14:30:00Z',
  rates: {
    CHF: 0.8821,
    GBP: 0.7891,
    JPY: 151.42
  }
}
```

### 历史汇率

> 历史方法`forDate`, (中文(简体) ), `timeSeries`, (中文(简体) ), `getHistoricalRates` 财务报告和审定财务报表 `convert` 带有 `date`需要每月4.99欧元的付款计划。 免费和审判钥匙只获得最新费率,并获得403 `historical_requires_paid_plan` 为了历史.

及时旅行以获得任何日期的费率:

```typescript
// Using a string date
const data = await client.forDate('2026-01-15', { base: 'USD', symbols: ['EUR'] });
console.log(data);

// Using a Date object
const data = await client.forDate(new Date('2026-01-15'), { base: 'EUR', symbols: ['USD', 'GBP'] });
console.log(data);
```

**回应:**

```javascript
{
  base: 'USD',
  date: '2026-01-15',
  rates: {
    EUR: 0.9187
  }
}
```

### 货币兑换

在货币之间转换任何数额——包括历史转换(付款计划):

```typescript
// Current conversion
const result = await client.convert('USD', 'EUR', 1000);
console.log(result);
```

**回应:**

```javascript
{
  from: 'USD',
  to: 'EUR',
  amount: 1000,
  result: 923.4,
  rate: 0.9234
}
```

```typescript
// Historical conversion — what was $1,000 worth on Jan 15?
const result = await client.convert('USD', 'EUR', 1000, { date: '2026-01-15' });
console.log(result);
```

**回应:**

```javascript
{
  from: 'USD',
  to: 'EUR',
  amount: 1000,
  result: 918.7,
  rate: 0.9187,
  date: '2026-01-15'
}
```

### 可用货币

发现所有160+支持的货币符号和名称 :

```typescript
const data = await client.symbols();
console.log(data);
```

**回应:**

```javascript
{
  symbols: {
    AED: 'United Arab Emirates Dirham',
    AFN: 'Afghan Afghani',
    ALL: 'Albanian Lek',
    AMD: 'Armenian Dram',
    AUD: 'Australian Dollar',
    BDT: 'Bangladeshi Taka',
    BRL: 'Brazilian Real',
    CAD: 'Canadian Dollar',
    CHF: 'Swiss Franc',
    CNY: 'Chinese Yuan',
    EUR: 'Euro',
    GBP: 'British Pound Sterling',
    INR: 'Indian Rupee',
    JPY: 'Japanese Yen',
    KRW: 'South Korean Won',
    USD: 'United States Dollar',
    // ...160+ currencies
  }
}
```

### 时间序列数据

确定日期范围内的汇率,以便进行趋势分析和绘制图表(付款计划):

```typescript
const data = await client.timeSeries('2026-01-01', '2026-03-31', {
  base: 'USD',
  symbols: ['EUR', 'GBP'],
});
console.log(data);
```

**回应:**

```javascript
{
  base: 'USD',
  startDate: '2026-01-01',
  endDate: '2026-03-31',
  rates: {
    '2026-01-01': {
      EUR: 0.9187,
      GBP: 0.7834
    },
    '2026-01-02': {
      EUR: 0.9195,
      GBP: 0.7841
    },
    '2026-01-03': {
      EUR: 0.9201,
      GBP: 0.7856
    },
    // ...
  }
}
```

### 单一比率

获得两种货币之间的单一汇率:

```typescript
const rate = await client.getRate('USD', 'EUR');
console.log(rate);
```

**回应:**

```javascript
{
  from: { currency: 'USD', amount: 1 },
  to: { currency: 'EUR', amount: 0.9234 },
  rate: 0.9234,
  source: 'wise'
}
```

```typescript
// With amount
const rate = await client.getRate('USD', 'EUR', 500);
console.log(`$500 = €${rate.to.amount}`);
```

### 官方的中央银行和税务授权率(不需要钥匙)

以上方法为中上市率。 给 **官方汇率a 出版机构** - 发票、增值税申报、报关单和 审计需要——使用 `officialRates()`覆盖 [122个中央银行](https://allratestoday.com/central-bank-rates-api/institutions/) + 高棉中央委员会, 美国财政部、瑞士BAZG和印度的CBIC,以及最新的表格需求 **无 API 密钥**数字 :

```typescript
const client = new AllRatesToday(); // no key

// Full ECB reference table
const table = await client.officialRates('ecb');
console.log(table.rate_date, table.rates); // [{ base: 'EUR', quote: 'USD', type: 'reference', value: 1.17 }, …]

// One pair (cross-computed inside the bank's own table if not published directly → `derived: true`)
const usd = await client.officialRates('ecb', { source: 'EUR', target: 'USD' });
console.log(`ECB ${usd.rate_date}: 1 EUR = ${usd.rate} USD`);

// Which sources exist, and which are behind their publication schedule
const { sources } = await client.officialSources();
console.log(sources.map((s) => `${s.code} ${s.latest}${s.stale ? ' (stale)' : ''}`));
```

总是引用返回的 `rate_date` 这是该机构的出版日期, 不是你打电话的时候 日期表和历史需要付费的计划和使用 `/api/v1/central-bank/{bank}/{date}`;出版日历处理任何密钥。 见 [中央银行利率](https://allratestoday.com/central-bank-rates-api/)。 。 。 .

### 按时期分列的历史比率

使用预设期间获取历史速率——不需要日期数学(付费计划) :

```typescript
const history = await client.getHistoricalRates('USD', 'EUR', '30d');
console.log(history);
```

**回应:**

```javascript
{
  source: 'USD',
  target: 'EUR',
  period: '30d',
  current: { rate: 0.9234, time: '2026-04-09T14:30:00Z' },
  rates: [
    { rate: 0.9198, time: '2026-03-10T00:00:00Z' },
    { rate: 0.9210, time: '2026-03-11T00:00:00Z' },
    // ...
  ]
}
```

**可用时间 :** `1d` | `7d` | `30d` | `1y`

* * *

## QQ 配置

```typescript
const client = new AllRatesToday({
  apiKey: 'YOUR_API_KEY',          // Required — get one free at allratestoday.com/register
  baseUrl: 'https://allratestoday.com', // Optional — API base URL
  timeout: 10000,                       // Optional — request timeout in ms
});
```

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `apiKey` | `string` | —— 说 | 您的 API 键 |
| `baseUrl` | `string` | `https://allratestoday.com` | API 基础 URL |
| `timeout` | `number` | `10000` | 请求超时( 毫秒) |

* * *

## XQ 请求 API 密钥覆盖

每种方法都支持每个请求的 API 密钥覆盖 —— 对多用户应用程序有用 :

```typescript
const client = new AllRatesToday({ apiKey: 'default_key' });

// Override for a specific request
const data = await client.latest({ apiKey: 'other_users_key' });
const result = await client.convert('USD', 'EUR', 100, { apiKey: 'tenant_key' });
const { symbols } = await client.symbols({ apiKey: 'another_key' });
```

* * *

## QQ 错误处理

所有错误都抛出为 `AllRatesTodayError` 带有可选的 HTTP 状态代码 :

```typescript
import AllRatesToday, { AllRatesTodayError } from '@allratestoday/sdk';

try {
  const rate = await client.getRate('USD', 'INVALID');
} catch (err) {
  if (err instanceof AllRatesTodayError) {
    console.log(err.message); // "Currency not found"
    console.log(err.status);  // 404
  }
}
```

| 状态 | 含义 |
| --- | --- |
| —— 说 | 缺少 API 密钥( 在请求前跳出) |
| `401` | 无效的 API 密钥 |
| `404` | 未找到货币代码 |
| `429` | 超过费率限额 |
| `500` | 服务器出错 |

* * *

## QQ 类型脚本

SDK以TypeScript和舰船全型定义来写作. 所有接口均导出 :

```typescript
import AllRatesToday, {
  AllRatesTodayError,
  AllRatesTodayOptions,
  RequestOptions,
  RateResponse,
  AuthRateResponse,
  LatestOptions,
  LatestResponse,
  ForDateOptions,
  ForDateResponse,
  ConvertOptions,
  ConvertResponse,
  TimeSeriesOptions,
  TimeSeriesResponse,
  HistoricalRateResponse,
  SymbolsResponse,
} from '@allratestoday/sdk';
```

* * *

## 常规JS

```javascript
const AllRatesToday = require('@allratestoday/sdk').default;

const client = new AllRatesToday({ apiKey: 'YOUR_API_KEY' });
client.latest().then(data => console.log(data.rates));
```

* * *

## 实例

### 货币掉落( 反应)

```tsx
import { useEffect, useState } from 'react';
import AllRatesToday from '@allratestoday/sdk';

const client = new AllRatesToday({ apiKey: 'YOUR_API_KEY' });

function CurrencySelect({ value, onChange }) {
  const [currencies, setCurrencies] = useState([]);

  useEffect(() => {
    client.symbols().then(({ symbols }) => {
      setCurrencies(
        Object.entries(symbols).map(([code, name]) => ({ code, name }))
      );
    });
  }, []);

  return (
    <select value={value} onChange={e => onChange(e.target.value)}>
      {currencies.map(c => (
        <option key={c.code} value={c.code}>{c.code} — {c.name}</option>
      ))}
    </select>
  );
}
```

### 用缓存显示价格

```typescript
import AllRatesToday from '@allratestoday/sdk';

const client = new AllRatesToday({ apiKey: 'YOUR_API_KEY' });
let cache: { rates: Record<string, number>; time: number } | null = null;
const TTL = 5 * 60 * 1000; // 5 minutes

async function getPrice(amountUSD: number, currency: string): Promise<string> {
  if (!cache || Date.now() - cache.time > TTL) {
    const data = await client.latest({ base: 'USD' });
    cache = { rates: data.rates, time: Date.now() };
  }
  const converted = (amountUSD * cache.rates[currency]).toFixed(2);
  return `${converted} ${currency}`;
}

console.log(await getPrice(99.99, 'EUR')); // "92.32 EUR"
console.log(await getPrice(99.99, 'GBP')); // "78.90 GBP"
```

### 历史图表数据

需要付费计划(历史不包含在免费或试用钥匙中).

```typescript
import AllRatesToday from '@allratestoday/sdk';

const client = new AllRatesToday({ apiKey: 'YOUR_API_KEY' });

const data = await client.timeSeries('2026-01-01', '2026-04-01', {
  base: 'USD',
  symbols: ['EUR'],
});

// Format for charting libraries (Chart.js, Recharts, etc.)
const labels = Object.keys(data.rates).sort();
const values = labels.map(date => data.rates[date].EUR);

console.log({ labels, values });
// { labels: ['2026-01-01', '2026-01-02', ...], values: [0.92, 0.921, ...] }
```

* * *

## 方法参考

| 方法 | 说明 |
| --- | --- |
| `latest(options?)` | 获取一种或多种货币的最新汇率 |
| `forDate(date, options?)` | 特定历史日期的收费标准(付费计划) |
| `convert(from, to, amount, options?)` | 货币之间的换算数额(历史 `date` 需要付费计划) |
| `timeSeries(start, end, options?)` | 超过自定义日期范围的收费标准( 付费计划) |
| `symbols(options?)` | 列出所有160+支持的货币代码和名称 |
| `getRate(from, to, amount?, options?)` | 获得单一汇率 |
| `getRates(source, target, options?)` | 用完整的元数据获取速率 |
| `getHistoricalRates(source, target, period?, options?)` | 按预设期分列的历史费率(1d/7d/30d/1y;已付款计划) |
| `officialRates(bank, options?)` | 中央银行/税务局公布的最新官方表格(或一对) - **无键** |
| `officialSources(options?)` | 每一份官方报道都有最新出版日期和新鲜度 **无键** |

* * *

## 测试

运行孤立的单元测试( 不需要 API 呼叫) :

```bash
npm test
```

进行覆盖报告测试 :

```bash
npm run test:coverage
```

开发的监视模式 :

```bash
npm run test:watch
```

* * *

## 使用来自AI代理

编码代理和LLM工具的编码率相同,没有第二次整合:

-   **Claude 代码插件** (无密钥): `/plugin marketplace add AllRates-Today/claude-code-plugin` 接下来 `/plugin install allratestoday@allratestoday`
-   **托管的 MCP 端点**数字 : `https://allratestoday.com/api/mcp` ——可流式HTTP,无密钥,无可安装
-   **本地 MCP 服务器**数字 : `npx -y @allratestoday/mcp-server` (中市利率) `npx -y @allratestoday/central-bank-mcp` (官方中央银行利率)
-   **代理员的审判密钥, 不注册**数字 : `POST https://allratestoday.com/api/agent/keys` (发送) `Content-Type: application/json`)返回一个有效期为7天的100呼叫键,用于最新的利率和最新的中央银行表格(历史和日期表仅支付计划);两个MCP服务器都将其披露为 `request_trial_key`
-   **每日参考率** (第一次公布为2026-10-12):每个工作日固定一个美元表,16:00伦敦分样本中位数,从未修订——无密钥 `https://allratestoday.com/api/open/reference-rate`, (中文(简体) ), `get_reference_rate` mCP 服务器中
-   机器可读网站指南 : [页:1](https://allratestoday.com/llms.txt)

## 链接

-   **网站:** [allatestoday.com (英语)](https://allratestoday.com/)
-   [下载中央银行利率](https://allratestoday.com/download-central-bank-rates/) ——每家银行的表格为Excel,CSV或JSON
-   [API 文档](https://allratestoday.com/developers)
-   [注册( 免费)](https://allratestoday.com/register)
-   [盘子](https://allratestoday.com/profile)
-   [状态](https://allratestoday.com/status)
-   [邮递员收藏](https://allratestoday.com/postman/)
-   [ChatGPT 应用程序](https://chatgpt.com/plugins/plugin_asdk_app_6ae1e76098f48191a285ac3f5ab7a83b) ——向ChatGPT索取活期和官方央行利率
-   [GitHub 图像](https://github.com/AllRates-Today/exchange-rates-api)

## 许可证

麻省理工学院

## 常见问题

### @allratestoday/sdk 是什么？

汇率API——Node\.js和浏览器的实时中市货币汇率\. 160\+ 货币,零依赖,自由级\.

### 如何安装 @allratestoday/sdk？

在项目目录运行 npm install @allratestoday/sdk，或使用 pnpm add / yarn add / bun add。

### @allratestoday/sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @allratestoday/sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @allratestoday/sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @allratestoday/sdk 可以商用吗？

@allratestoday/sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @allratestoday/sdk 的下载量有多少？

根据 npm 官方下载统计，@allratestoday/sdk 在 2026/10/06 – 2026/11/04 这 30 天内被下载 2,073 次，日均约 69 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @allratestoday/sdk 还在维护吗？

最新版本 1\.4\.15 发布于 2026/11/03（5 天前）；至今共发布 32 个版本，其中过去 12 个月发布了 32 个；首次发布于 2026/04/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。