# @bitget-ai/bitget-agent-sdk 中文文档

规范地址：https://npmcn.com/package/%40bitget-ai/bitget-agent-sdk/

版本：3\.3\.1
npm 元数据更新时间：2026-09-20T05:59:41.284Z
中文译文更新时间：2026-11-08T04:34:59.701Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40bitget-ai/bitget-agent-sdk
原文对照：https://npmcn.com/package/%40bitget-ai/bitget-agent-sdk/?lang=original

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

- 包体积（解压后）：928 kB，19 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-06-09T03:41:11.184Z
- 最新版本发布：2026-09-20T05:59:41.094Z
- 近 30 天下载量：4320（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

Spec驱动的基础SDK用于Bitget统一交易账户(UTA / v3) API. 从openapi.yaml出品——将所有v3端点都曝光为AI可调用工具,并设有内置目录驱动的模拟服务器,用于计量回归测试.

## 安装

```sh
npm install @bitget-ai/bitget-agent-sdk
```

也可以使用：`pnpm add @bitget-ai/bitget-agent-sdk`、`yarn add @bitget-ai/bitget-agent-sdk`、`bun add @bitget-ai/bitget-agent-sdk`

## README

![Bitget Agent SDK — TypeScript foundation library for Bitget UTA v3 API trading bot development](https://npmcn.com/package/%40bitget-ai/bitget-agent-sdk/assets/logo.png)

# bitget-agent-sdk — 官方 Bitget AI 交易类型Script SDK

**Bitget统一交易账户(UTA / v3)的基础TypeScript SDK REST API——被曝光为AI可调用内特工具,HMAC-SHA256签名和客户端比率受限.**

[![Bitget Agent SDK continuous integration build status](https://github.com/Bitget-AI/agent-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/Bitget-AI/agent-sdk/actions/workflows/ci.yml) [![Bitget Agent SDK npm package version](https://img.shields.io/npm/v/%40bitget-ai%2Fbitget-agent-sdk.svg?style=flat-square&color=6f42c1&label=npm)](https://www.npmjs.com/package/@bitget-ai/bitget-agent-sdk) [![Bitget Agent SDK monthly downloads](https://img.shields.io/npm/dm/%40bitget-ai%2Fbitget-agent-sdk.svg?style=flat-square&color=026e00&label=downloads)](https://www.npmjs.com/package/@bitget-ai/bitget-agent-sdk) ![TypeScript type definitions included](https://img.shields.io/npm/types/%40bitget-ai%2Fbitget-agent-sdk.svg?style=flat-square) ![Requires Node.js 20 or higher](https://img.shields.io/badge/Node.js-%E2%89%A520-026e00?style=flat-square) ![Zero runtime dependencies](https://img.shields.io/badge/zero%20runtime%20deps-none-lightgrey?style=flat-square) [![MIT open source license](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://npmcn.com/package/%40bitget-ai/bitget-agent-sdk/LICENSE)

[快速启动](https://npmcn.com/package/%40bitget-ai/bitget-agent-sdk/#readme-quick-start) • 妇女 [特征](https://npmcn.com/package/%40bitget-ai/bitget-agent-sdk/#readme-features) • 妇女 [使用量](https://npmcn.com/package/%40bitget-ai/bitget-agent-sdk/#readme-usage) • 妇女 [模块](https://npmcn.com/package/%40bitget-ai/bitget-agent-sdk/#readme-modules) • 妇女 [测试](https://npmcn.com/package/%40bitget-ai/bitget-agent-sdk/#readme-testing) • 妇女 [处理错误](https://npmcn.com/package/%40bitget-ai/bitget-agent-sdk/#readme-error-handling) • 妇女 [财务问题](https://npmcn.com/package/%40bitget-ai/bitget-agent-sdk/#readme-faq)

* * *

## 概览

`@bitget-ai/bitget-agent-sdk` 这是 **基础类型SDK** (原始内容存档于2018-03-21). Bitget Agent Hub Entertainment. 它规定:

-   **89 空运联盟业务** 带完整的 JSON Schema
-   **14个意向动词** aI工具使用框架,加 `raw` 财务报告和审定财务报表 `discover` 元工具
-   **HMAC-SHA256 请求签署** 和限制客户端利率
-   **零运行时间依赖关系** 轻而易举并具有树能`"sideEffects": false`(中文(简体) )

两者 [`bitget-agent-cli`](https://github.com/Bitget-AI/agent-cli) 财务报告和审定财务报表 [`bitget-agent-mcp`](https://github.com/Bitget-AI/agent-mcp) 是在SDK上方建造的.

> **对于开发者**:构建量子策略,定制MCP服务器,LLM工具-使用管道,或自动交易bots. **不是开发商?** 使用更高水平的表面 : `bitget-agent-cli` + 键 `bitget-agent-skill` 为终端AI, `bitget-agent-mcp` 用于桌面AI, `bitget-signal` 市场分析,不需要账户。 他们都没有直接要求这个SDK.

* * *

## 快速启动

### 安装

```bash
npm install @bitget-ai/bitget-agent-sdk
```

### 基本用途

```typescript
import {
  loadConfig,
  buildTools,
  BitgetRestClient,
  safeInvoke,
} from "@bitget-ai/bitget-agent-sdk";

// Default surface is "intent" (curated verbs + raw + discover).
// Starting with readOnly is a safe default — every write tool is dropped.
const config = loadConfig({ modules: "all", readOnly: true });
const client = new BitgetRestClient(config);
const tools = buildTools(config);
const ctx = { config, client };

console.log(`Loaded ${tools.length} tools`); // intent verbs + raw + discover

// Public market data — no credentials required.
const market = tools.find((t) => t.name === "market")!;
const res = await safeInvoke(
  market,
  { action: "tickers", category: "SPOT", symbol: "BTCUSDT" },
  ctx,
);

if (res.ok) console.log(res.data);
else console.error(res.error);
```

### 设定证书

证书从环境变量读取—— SDK 不解析 `.env` 文件,从不向磁盘写入证书 :

```bash
export BITGET_API_KEY="your-api-key"
export BITGET_SECRET_KEY="your-secret-key"
export BITGET_PASSPHRASE="your-passphrase"
```

或传入内线 `loadConfig({ apiKey, secretKey, passphrase, ... })`。 。 。 .

* * *

## 特征

### 对你有什么好处

| 特性 | 替换什么 |
| --- | --- |
| **89 空运联盟业务** 与 **14个意向动词**,可在一个呼叫中挂起到任何 LLM 框架 | 手滚动端点包装并保持同步 |
| **`safeInvoke`** 每一次通话都决定 `{ ok, … }`,从不扔 | 在自己的尝试/捕获中环绕每个工具调用 |
| **`discover`** ——地表向您模型描述自己,按需要钻入 | 保持单独的工具目录, 仅供提示使用 |
| **请求签名** (HMAC-SHA256) + 客户端利率限制 + 输入出错 | 重新执行 Bitget 自定义 |
| **安全模式**数字 : `readOnly` + 键 `paperTrading`,高风险行动需要明确 `confirm` | 写自己的护栏 防止意外现场命令 |

### 密钥导出

```typescript
// Client + tool primitives
import {
  BitgetRestClient,
  buildTools,
  toToolSpec,
  loadConfig,
  safeInvoke,
  toMcpTool,
} from "@bitget-ai/bitget-agent-sdk";

// Curated verbs, discovery, raw
import {
  COMPOSITE_TOOL_NAMES,
  buildDiscoverTool,
  DISCOVER_TOOL_NAME,
  RAW_TOOL_NAME,
} from "@bitget-ai/bitget-agent-sdk";

// The generated catalog (single source of truth)
import {
  CATALOG,
  CATALOG_SPEC_VERSION,
  CATALOG_OPERATION_COUNT,
  getOperation,
} from "@bitget-ai/bitget-agent-sdk";

// Types
import type {
  BitgetConfig,
  CliOptions,
  Surface,
  ToolSpec,
  ToolContext,
  ToolResult,
  SafeResult,
  ModuleId,
} from "@bitget-ai/bitget-agent-sdk";

// Metadata
import {
  SERVER_NAME,
  SERVER_VERSION,
  API_VARIANT,
  MODULES,
  DEFAULT_MODULES,
} from "@bitget-ai/bitget-agent-sdk";

// Errors — all subclasses of BitgetMcpError
import {
  BitgetMcpError,
  BitgetApiError,
  ConfigError,
  ValidationError,
  RateLimitError,
  AuthenticationError,
  NetworkError,
  toToolErrorPayload,
} from "@bitget-ai/bitget-agent-sdk";
```

从包根或包根中导出的一切 `@bitget-ai/bitget-agent-sdk/testing` 子路径如下 [铸造](https://semver.org/)。没有从这些路径导出的任何内容都是内部的,可能不经通知而改变.

* * *

## 使用量

### 控制工具范围和安全

`loadConfig` 接受这些常用选项:

| 选项 | 默认 | 效果 |
| --- | --- | :-: |
| `surface` | `"intent"` | `"intent"` (默认) 出自所编动词 + `raw` + 键 `discover`。 。 。 . `"full"` 此外,每次操作还发出1:1的工具. |
| `modules` | `"account,trade,market"` | 逗号分隔模块列表,或 `"all"`打开工具的门. |
| `readOnly` | `false` | 丢弃每个写入工具; 只读 。 相互独占 `paperTrading`。 。 。 . |
| `paperTrading` | `false` | 向 Bitget 纸张交易发送订单 。 相互独占 `readOnly`。 。 。 . |
| `baseUrl` | `https://api.bitget.com` | API 基础 URL (或 `BITGET_API_BASE_URL`) (中文(简体) ). |
| `timeoutMs` | `15000` | 以毫秒(或 `BITGET_TIMEOUT_MS`) (中文(简体) ). |

每个工具都带有 `riskLevel` 联 合 国 `read` < `write` < `high`. 高风险业务自出:它们返回a `{ confirmationRequired: true }` 预览直到通过 `confirm`所以特工不能在第一回合就发出毁灭性的呼叫 坚持下去 **每个** 路径——被曲解的动词, 1:1 操作工具,以及 `raw` 逃出舱门,通过一个安全阻塞点.

### 运行时探索

`discover` 让一个模型逐渐地学习表面,而不在提示中传输单独的工具目录:

```typescript
const discover = tools.find((t) => t.name === "discover")!;

await safeInvoke(discover, {}, ctx);                                    // domains + tool counts
await safeInvoke(discover, { domain: "trade" }, ctx);                   // tools in a domain
await safeInvoke(discover, { tool: "market" }, ctx);                    // one tool's full schema
await safeInvoke(discover, { tool: "market", action: "tickers" }, ctx); // one action's exact contract
await safeInvoke(discover, { search: "funding" }, ctx);                 // keyword search
```

### 有意动词( 默认表面)

默认 `intent` 表面暴露 **14个主动词**,启用其模块上的每个门。 这14个单元涵盖一般可用的模块:

| 动词 | 模块 | 范围 |
| --- | --- | :-: |
| `market` | `market` | 计票机、订货簿、蜡烛、供资率、开放利息、参考文献 |
| `order` | `trade` | 设置 / 修改/ 取消命令, 当前和历史命令, 填充 |
| `position` | `trade` | 打开位置、 杠杆和边距模式、 位置历史 |
| `strategy_order` | `trade` | 触发 / TP- SL / 计划命令 |
| `account_overview` | `account` | 余额、资产、账单 |
| `account_config` | `account` | 账户模式、边距和杠杆设置 |
| `transfer_funds` | `account` | 内部和子账户转账 |
| `deposit` | `account` | 存款地址和记录 |
| `withdraw` | `account` | 撤回记录( r) |
| `funds_records` | `account` | 交存/撤回/转让历史 |
| `repayment` | `account` | 偿还债务 |
| `subaccount` | `account` | 子账户创建/ 列表/ 管理 |
| `loan` | `cryptoloans` | 借款、偿还、抵押、贷款记录 |
| `tax` | `tax` | 交易税记录 |

加上两个始终存在的元工具:

-   **`raw`** - 逃生舱 直接调用任何操作 `operationId` 当你想要 准确的1:1合同。 它穿过这里 **同一安全门** 作为主动词—— `readOnly`, (中文(简体) ), `dryRun`和高风险 `confirm` 要求仍然适用,因此 `raw` 宽度 _到达_ 永远不要跳过破坏行动确认.
-   **`discover`** ——回顾活性地表(见上文). 两者都存在于每一个地表和每个模式中.

* * *

## 模块

默认配置文件加载 `account` + 键 `trade` + 键 `market`包括日常交易 装入所有东西 `loadConfig({ modules: "all" })`,或选择一个命名子集:

| 模块 | 业务 | 默认 | 说明 |
| --- | --- | :-: | --- |
| `account` | 页:1 | ✅ | 结余和资产、账户设置、转账、存款/提取、资金记录、分账户 |
| `trade` | 页:1 | ✅ | 订单布局与管理(点+期货),职位,填充 |
| `market` | 16个 | ✅ | 公共市场数据——打勾、订货簿、蜡烛、供资率、开放利息 |
| `strategy` | 页:1 | —— 说 | 战略命令——触发、TP/SL、计划命令 |
| `cryptoloans` | 第11个 | —— 说 | 加密贷款——借款、偿还、抵押、记录 |
| `tax` | 1个 | —— 说 | 交易税记录 |
| **共计(可见)** | **第89条** | **72国** |  |

> **经典账户用户**: 如果您在 Bitget 经典账户上, 您需要先通过 API 创建代理子账户, 然后使用该子账户的 API 密钥来调用 MCP / CLI / 技能工具 . [创建代理子账户](https://www.bitget.com/zh-CN/api-doc/classic/common/vsubaccount/Create-Agent-Subaccount)

* * *

## 测试

从中导入一个模拟比特 API 模拟器 `@bitget-ai/bitget-agent-sdk/testing` 集成测试的子路径——不需要真正的 API 密钥 :

```typescript
import { MockServer, seedState } from "@bitget-ai/bitget-agent-sdk/testing";
import { loadConfig, BitgetRestClient } from "@bitget-ai/bitget-agent-sdk";

const mock = new MockServer();
await mock.start(); // ephemeral port

const config = loadConfig({
  modules: "market",
  baseUrl: mock.baseUrl,
  apiKey: "test",
  secretKey: "test",
  passphrase: "test",
});
const client = new BitgetRestClient(config);

// ... drive your tests against `client` ...

await mock.stop();
```

* * *

## 处理错误

两个互补层面:

**1\. 联合国. `safeInvoke` ——推荐路径.** 从来投出. 分会 `.ok`数字 :

```typescript
const res = await safeInvoke(tool, args, ctx);
if (res.ok) {
  // res.data, res.endpoint, res.requestTime
} else {
  // res.error — a JSON-serialisable payload, ready for an LLM tool-use reply
}
```

**2\. 打字出错——直接拨打接取器时.** 每个 API 失败和配置问题都显示为输入 `Error` 子类 `instanceof`\- 狭:

```typescript
import { BitgetApiError, ConfigError, RateLimitError } from "@bitget-ai/bitget-agent-sdk";

try {
  await tool.handler(args, ctx);
} catch (err) {
  if (err instanceof RateLimitError) {
    // SDK applies client-side rate limiting, but Bitget can still 429 under load — back off and retry
  } else if (err instanceof BitgetApiError) {
    console.error(err.code, err.message);
  } else if (err instanceof ConfigError) {
    // Missing or invalid credentials — surface to the user
  }
}
```

使用 `toToolErrorPayload(err)` 将任何被捕获错误转换成相同的 `{ ok: false, error: { … } }` 有效载数 `safeInvoke` 生产.

* * *

## 警卫

-   **仅来自环境变量的证书**: API 密钥通过 `export BITGET_API_KEY=...` - SDK没有分析 `.env` 文件,从不向磁盘写入证书.
-   **本地签名**:所有经认证的请求在到达Bitget的API之前都会被HMAC-SHA256在程序内签名——没有第三方服务器参与.
-   **限制客户端利率**:内置节流阻断了循环来打出Bitget的API限制.

* * *

## 兼容性

|  |  |
| --- | --- |
| **节点.js** | ≥ 20.0.0 |
| **模块格式** | 仅限无害环境管理`"type": "module"`) (中文(简体) ). 启用了树摇动( T)`"sideEffects": false`) (中文(简体) ). |
| **类型脚本** | 包件中的船舶类型;无 `@types/...` 需要安装 。 模块分辨率为 `NodeNext`。 。 。 . |
| **依赖关系** | 零运行时间依赖关系. |
| **位元 API** | Bitget统一交易账户(UTA / v3). |

* * *

## 文档

-   **核心发现.** 这个 `discover` 工具返回实时、配置意识工具表面和每个操作的合同;没有外部目录可以保持同步.
-   **Bitget API 参考.** [bitget.com/ api-doc 数据](https://www.bitget.com/api-doc/common/intro)

* * *

## 相关项目

| 软件包 | 目的 |
| --- | --- |
| **[bitget - agent - cli 键](https://github.com/Bitget-AI/agent-cli)** | 终端AI工具( 在 SDK 上所建) |
| **[bitget-agent-mcp 选项](https://github.com/Bitget-AI/agent-mcp)** | 桌面 AI MCP 服务器( 在 SDK 上所建) |
| **[bitget - agent - skill 函数](https://github.com/Bitget-AI/agent-skill)** | AI 推理指南 |
| **[位元符号](https://github.com/Bitget-AI/bitget-signal)** | 市场分析技能 |
| **[经纪人 - 按钮](https://github.com/Bitget-AI/agent_hub)** | 生态系统切入点 |

* * *

## 财务问题

### 什么叫"特务"?

`bitget-agent-sdk` 是正式的 Bitget 基础 TypeScript SDK —— 涵盖89个UTA 操作, HMAC- SHA256 签名, 客户端速率限制, 以及 14 个动词 intent 表面可挂入 LLM 工具使用框架 。 两者 `bitget-agent-cli` 财务报告和审定财务报表 `bitget-agent-mcp` 使它成为整个Bitget代理Hub生态系统的基础层.

### 这个SDK是设计用来什么开发商的?

构建定量交易策略,自定义MCP服务器,LLM工具使用管道,自动化交易bots,以及任何需要程序访问Bitget的UTA API的TypeScript或JavaScript项目.

### 这和直接给Bitget REST API打电话有什么不同?

SDK处理HMAC-SHA256请求签名,客户端速率限制,并打出出出错类. 它提供了14个曲折的心动词加上 `raw` 全部装入LLM工具使用框架. `safeInvoke` 给每个呼叫都穿制服 `{ ok, … }` 形状 —— 不需要将每个操作员包裹在尝试/捕获中.

### 这个SDK支持通用JS吗?

不,它只是无害环境管理(`"type": "module"`。要求节点.js 20和 `NodeNext` 模块分辨率.

### 我该怎么装上特定的模块?

通过一个逗号分隔列表,例如. `loadConfig({ modules: "account,trade" })`,或 `loadConfig({ modules: "all" })` 每个模块.

### 我在一个典型的Bitget帐户上——我能用这个吗?

是的,但经典的账户需要先通过API创建代理子账户,然后使用该子账户的API密钥来为MCP / CLI / Skill工具. [查看创建代理子账户 API —](https://www.bitget.com/zh-CN/api-doc/classic/common/vsubaccount/Create-Agent-Subaccount)

### 是Bitget官方提供的,并且可以自由使用?

对 它是由Bitget根据MIT许可证发布的官方开源SDK,可自由使用.

* * *

## 许可证

[麻省理工学院](https://npmcn.com/package/%40bitget-ai/bitget-agent-sdk/LICENSE) SDK探员

官方 Bitget 代理 Hub 工具 ・ 交易堆栈 ・ 基础层 。 建于 SDK 上的表面: 代理- cli ; 代理- mcp ; 代理- 技能

## 常见问题

### @bitget-ai/bitget-agent-sdk 是什么？

Spec驱动的基础SDK用于Bitget统一交易账户\(UTA / v3\) API\. 从openapi\.yaml出品——将所有v3端点都曝光为AI可调用工具,并设有内置目录驱动的模拟服务器,用于计量回归测试\.

### 如何安装 @bitget-ai/bitget-agent-sdk？

在项目目录运行 npm install @bitget-ai/bitget-agent-sdk，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 bitget-mock-server，可以用 npx bitget-mock-server 直接运行。

### @bitget-ai/bitget-agent-sdk 支持 TypeScript 吗？

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

### @bitget-ai/bitget-agent-sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @bitget-ai/bitget-agent-sdk 需要什么版本的 Node\.js？

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

### @bitget-ai/bitget-agent-sdk 可以商用吗？

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

### @bitget-ai/bitget-agent-sdk 的下载量有多少？

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

### @bitget-ai/bitget-agent-sdk 还在维护吗？

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