# @coinmarketcap/sdk 中文文档

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

版本：5\.0\.1
npm 元数据更新时间：2026-10-30T04:09:27.133Z
中文译文更新时间：2026-11-10T10:38:47.270Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40coinmarketcap/sdk
原文对照：https://npmcn.com/package/%40coinmarketcap/sdk/?lang=original
项目主页：https://coinmarketcap.com/api/documentation/
源码仓库：https://github.com/OpenCMC/coinmarketcap-api-typescript

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

- 包体积（解压后）：2.7 MB，181 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-08-06T16:25:58.411Z
- 最新版本发布：2026-10-30T04:09:26.941Z
- 近 30 天下载量：4651（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

官方 CoinMarket Cap Pro API 类型Script/JavaScript SDK

## 安装

```sh
npm install @coinmarketcap/sdk
```

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

## README

# @ coinmarketcap/ sdk

[![npm version](https://img.shields.io/npm/v/@coinmarketcap/sdk.svg)](https://www.npmjs.com/package/@coinmarketcap/sdk) [![node](https://img.shields.io/node/v/@coinmarketcap/sdk.svg)](https://nodejs.org/)

官方类型SDK [CoinMarket Cap Pro API 密码](https://coinmarketcap.com/api/documentation/)。 。 。 .

## 安装

```bash
npm install @coinmarketcap/sdk
# or
yarn add @coinmarketcap/sdk
# or
pnpm add @coinmarketcap/sdk
```

## 快速启动

```typescript
import { CoinMarketCap } from "@coinmarketcap/sdk";

const cmc = new CoinMarketCap({ apiKey: process.env.CMC_PRO_API_KEY! });

// Use the namespace API — discover endpoints by category with autocomplete
const { data, error } = await cmc.api.cryptocurrency.quotesLatest({
  query: { id: "1,1027" }, // 1 = BTC, 1027 = ETH
});

if (data) {
  console.log(data);
}
```

## 使用量

### 命名空间 API( 建议)

所有终点按类别分类 `cmc.api`数字 :

```typescript
import { CoinMarketCap } from "@coinmarketcap/sdk";

const cmc = new CoinMarketCap({ apiKey: "your-key" });

await cmc.api.cryptocurrency.quotesLatest({ query: { id: "1" } });
await cmc.api.cryptocurrency.listingsLatest({ query: { limit: 10 } });
await cmc.api.globalMetrics.quotesLatest({});
await cmc.api.exchange.info({ query: { id: "270" } });
```

### 空函数( 外部客户端)

您也可以导入单个函数并明确通过客户端:

```typescript
import {
  CoinMarketCap,
  getV1CryptocurrencyQuotesLatest,
} from "@coinmarketcap/sdk";

const cmc = new CoinMarketCap({ apiKey: "your-key" });

const { data } = await getV1CryptocurrencyQuotesLatest({
  client: cmc.client,
  query: { id: "1", convert: "USD" },
});
```

### 全球模式( 净值)

对于简单的脚本, `init()` 配置全局客户端, 这样光线函数不会通过 `client`数字 :

```typescript
import { init, getV1CryptocurrencyQuotesLatest } from "@coinmarketcap/sdk";

const cmc = init({ apiKey: "your-key" });

// Namespace works on the returned instance
await cmc.api.cryptocurrency.quotesLatest({ query: { id: "1" } });

// Bare functions also work (use the global client)
await getV1CryptocurrencyQuotesLatest({ query: { id: "1" } });
```

### 配置选项

```typescript
const cmc = new CoinMarketCap({
  // Required for 'pro' mode
  apiKey: "your-api-key",

  // Optional
  environment: "pro", // 'pro' (default) or 'public'
  baseUrl: undefined, // Override base URL entirely
  timeout: 30000, // Request timeout in ms (default: 30s)
  maxRetries: 2, // Auto-retry count (default: 2)
  fetch: customFetch, // Custom fetch implementation
});
```

### 公共( 无关键) 模式

使用没有 API 密钥的 公共 API 来获取 :

```typescript
import { CoinMarketCap } from "@coinmarketcap/sdk";

const cmc = new CoinMarketCap({ environment: "public" });

await cmc.api.cryptocurrency.listingsLatest({ query: { limit: 10 } });
```

## 处理错误

SDK为常见的HTTP故障提供打入错误分类:

```typescript
import {
  CoinMarketCap,
  CMCError,
  RateLimitError,
  AuthenticationError,
} from "@coinmarketcap/sdk";

const cmc = new CoinMarketCap({ apiKey: "your-key" });

const { data, error } = await cmc.api.cryptocurrency.quotesLatest({
  query: { id: "1" },
});

if (error) {
  if (error instanceof RateLimitError) {
    console.log("Rate limited, retry after:", error.headers.get("Retry-After"));
  } else if (error instanceof AuthenticationError) {
    console.log("Invalid API key");
  } else if (error instanceof CMCError) {
    console.log(`API error ${error.status}:`, error.message);
  }
}
```

### 错误类型

| 身份代码 | 错误类 |
| --- | --- |
| 400个 | `BadRequestError` |
| 401 (中文(简体) ) | `AuthenticationError` |
| 403 (韩语) | `ForbiddenError` |
| 404 (韩语) | `NotFoundError` |
| 429个 | `RateLimitError` |
| 5 (简体中文) | `InternalServerError` |
| 网络 | `APIConnectionError` |
| 超时 | `APITimeoutError` |

### 投出错误

或者,您可以抛出错误而不是返回错误 :

```typescript
import { CoinMarketCap, RateLimitError } from "@coinmarketcap/sdk";

const cmc = new CoinMarketCap({ apiKey: "your-key" });

try {
  const { data } = await cmc.api.cryptocurrency.quotesLatest({
    query: { id: "1" },
    throwOnError: true,
  });
  console.log(data);
} catch (err) {
  if (err instanceof RateLimitError) {
    // handle rate limit
  }
}
```

## 自动检索

以可重试状态代码失败的请求会自动重试 :

-   **可重试**:408,409,429,500,502,503,504,网络出错和超时
-   **默认**: 2次复试,初始延迟500ms,最多可达8s
-   **429个答复**: 尊重 `Retry-After` 标题, 以最大延迟( 8s) 为封顶, 因此一个大值无法拖住调用
-   **人身安全**: 在每次重试中正确重放请求对象( 包含 POST 端点)

禁用重试 :

```typescript
const cmc = new CoinMarketCap({
  apiKey: "your-key",
  maxRetries: 0,
});
```

## 超时

默认30秒后请求超时 :

```typescript
const cmc = new CoinMarketCap({
  apiKey: "your-key",
  timeout: 10_000, // 10 seconds
});
```

超时 `APITimeoutError`。 。 。 .

## 取消

通过一个 `AbortSignal` 取消飞行中的请求。 呼叫取消为 立即获得荣誉,而永不尝试

```typescript
const controller = new AbortController();
const promise = cmc.api.cryptocurrency.quotesLatest({
  query: { symbol: "BTC" },
  signal: controller.signal,
});
controller.abort(); // rejects with an AbortError
```

## 可用终点

所有端点都可以通过 `cmc.api.<category>.<method>()`。见 [日记](https://npmcn.com/package/%40coinmarketcap/sdk/api.md) 详细参考.

类别包括:

-   `cmc.api.cryptocurrency` - 引文、上市、市场对等、OHLCV、类别
-   `cmc.api.exchange` ——交换信息,上市,市场对等
-   `cmc.api.globalMetrics` ——全球统计、恐惧和贪婪指数
-   `cmc.api.content` - 新闻,员额
-   `cmc.api.community` - 趋势标志、专题
-   `cmc.api.token` ——DEX令牌数据,集合,交易
-   `cmc.api.derivatives` - 衍生物市场数据
-   `cmc.api.cmcIndex` - CMC 20/100指数

您也可以直接导入光线函数 :

```typescript
import {
  getV1CryptocurrencyListingsLatest,
  getV1CryptocurrencyInfo,
  getV1CryptocurrencyMap,
  // ... 100+ more endpoints
} from "@coinmarketcap/sdk";
```

## 版本

SDK跟着 [语义版本](https://semver.org/)主要版本删除或 重命名方法,或以可以打破的方式更改返回类型或响应字段 已存在的代码。 一个小版本会添加端点或字段. 补丁版本修复错误 .

类型脚本( T)`@coinmarketcap/sdk`)和平松(原变种`coinmarketcap-sdk`) SDK 发布 和相同的版本编号。 SDK版本与API是分开的 端点版本( e)`/v1`, (中文(简体) ), `/v2`, (中文(简体) ), `/v3`) (中文(简体) ). 每个 [变化](https://npmcn.com/package/%40coinmarketcap/sdk/CHANGELOG.md) 条目名称 OpenAPI spec 发行时从中构建并列出其断开的更改.

## 所需资源

-   节点.js 18
-   TypeScript QQ 5.0(用于 TypeScript 用户)

## 许可证

麻省理工学院

## 常见问题

### @coinmarketcap/sdk 是什么？

官方 CoinMarket Cap Pro API 类型Script/JavaScript SDK

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

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

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

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

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

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

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

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

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

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

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

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

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

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