Bitget Agent SDK

bitget-agent-sdk — Bitget 官方 AI 交易 TypeScript SDK

Bitget Unified Trading Account（UTA / v3）REST API 的基础 TypeScript SDK — 将其封装为可供 AI 调用的 Intent 工具，并支持 HMAC-SHA256 签名和客户端限速。

快速开始 · 功能 · 用法 · 模块 · 测试 · 错误处理 · 常见问题

---

概述

@bitget-ai/bitget-agent-sdk 是 Bitget Agent Hub 生态系统的基础 TypeScript SDK。它提供：

• 89 项 UTA 操作，附带完整的 JSON Schema
• 14 个精选 Intent 动词，适用于 AI 工具调用框架，另提供 raw 和 discover 元工具
• HMAC-SHA256 请求签名和客户端限速
• 无运行时依赖 — 轻量且支持摇树优化（"sideEffects": false）

bitget-agent-cli 和 bitget-agent-mcp 均基于此 SDK 构建。

面向开发者：用于构建量化策略、自定义 MCP 服务、大模型工具调用管道或自动化交易机器人。 不是开发者？ 请使用更高层的产品：用于终端 AI 的 bitget-agent-cli + bitget-agent-skill、用于桌面 AI 的 bitget-agent-mcp，以及无需账户即可进行市场分析的 bitget-signal。这些产品均不需要直接使用此 SDK。

---

快速开始

安装

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

基本用法

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 文件，也不会将凭据写入磁盘：

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

也可以将凭据内联传入 loadConfig({ apiKey, secretKey, passphrase, ... })。

---

功能

它能为你做什么

功能	替代方案
89 个 UTA 操作，通过 14 个精选 Intent 动词提供，一次调用即可挂载到任何 LLM 框架	手动封装端点并保持同步
safeInvoke — 每次调用都会返回 { ok, … }，绝不抛出异常	为每次工具调用都编写自己的 try/catch
discover — 服务面会向模型描述自身，按需深入探索	仅为提示词单独维护工具目录
请求签名（HMAC-SHA256）+ 客户端限流 + 类型化错误	自行重新实现 Bitget 的身份验证规范
安全模式：readOnly + paperTrading，高风险操作需要显式传入 confirm	编写自己的防护措施，避免意外下真实订单

主要导出项

// 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 子路径导出的所有内容都遵循 semver。未从这些路径导出的内容均为内部内容，可能随时变更，恕不另行通知。

---

用法

控制工具范围与安全性

loadConfig 接受以下常用选项：

选项	默认值	效果
surface	"intent"	"intent"（默认值）会提供精选动词、raw 和 discover。"full" 还会为每个操作提供一个一对一工具。
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	每个请求的超时时间，单位为 ms（或 BITGET_TIMEOUT_MS）。

每个工具都带有一个 riskLevel，级别依次为 read < write < high。高风险操作会自行进行门控：在你传入 confirm 之前，会返回 { confirmationRequired: true } 预览，防止 Agent 在首轮对话中执行破坏性调用。此机制适用于所有路径——精选动词、一对一操作工具以及 raw 逃生通道，都会经过同一个安全检查点。

在运行时探索

discover 让模型逐步了解服务面，无需你在提示词中附带单独的工具目录：

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	交易对行情、订单簿、K 线、资金费率、未平仓量、参考数据读取
order	trade	下单／修改／撤单、当前及历史订单、成交记录
position	trade	未平仓头寸、杠杆和保证金模式、头寸历史记录
strategy_order	trade	触发单／止盈止损单／计划委托
account_overview	account	余额、资产、账单
account_config	account	账户模式、保证金和杠杆设置
transfer_funds	account	内部转账和子账户转账
deposit	account	充值地址和记录
withdraw	account	提现和记录
funds_records	account	充值／提现／转账历史记录
repayment	account	负债还款
subaccount	account	创建／列出／管理子账户
loan	cryptoloans	借款、还款、抵押品、借款记录
tax	tax	交易税记录

另外还有两个始终可用的元工具：

• raw — 用于绕过精选动词的备用入口。当你需要完全遵循 1:1 契约时，可通过 operationId 直接调用任意操作。它经过与精选动词相同的安全门——readOnly、dryRun 和高风险操作所需的 confirm 均仍然适用，因此 raw 扩大了覆盖范围，但绝不会跳过破坏性操作的确认。
• discover — 检查当前启用的界面（见上文）。这两个工具在所有界面和所有模式下均可用。

---

模块

默认配置加载 account + trade + market，涵盖日常交易。使用 loadConfig({ modules: "all" }) 加载全部模块，或选择指定子集：

模块	操作数	默认启用	描述
account	39	✅	余额和资产、账户设置、转账、充值／提现、资金记录、子账户
trade	17	✅	订单下达和管理（现货 + 合约）、头寸、成交记录
market	16	✅	公共市场数据——交易对行情、订单簿、K 线、资金费率、未平仓量
strategy	5	—	策略委托——触发单、止盈止损单、计划委托
cryptoloans	11	—	加密货币抵押贷款——借款、还款、抵押品、记录
tax	1	—	交易税记录
总计（可见）	89	72

经典账户用户：如果你使用的是 Bitget 经典账户，则需要先通过 API 创建 Agent 子账户，然后使用该子账户的 API 密钥调用 MCP / CLI / Skill 工具。创建 Agent 子账户 →

---

测试

从 @bitget-ai/bitget-agent-sdk/testing 子路径导入内存中的 Bitget API 模拟器，用于集成测试——无需真实 API 密钥：

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 分支处理：

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 缩小类型范围：

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) 将捕获到的任意错误转换为 safeInvoke 生成的相同 { ok: false, error: { … } } 负载。

---

安全性

• 凭据仅从环境变量读取：通过 export BITGET_API_KEY=... 读取 API 密钥——SDK 不会解析 .env 文件，也绝不会将凭据写入磁盘。
• 本地签名：所有经过身份验证的请求都会在进程内使用 HMAC-SHA256 签名，然后再发送至 Bitget API——不会涉及第三方服务。
• 客户端限速：内置节流机制可防止循环调用触及 Bitget API 的限制。

---

兼容性

Node.js	≥ 20.0.0
模块格式	仅限 ESM（"type": "module"）。已启用 Tree-shaking（"sideEffects": false）。
TypeScript	包内附带类型，无需安装 @types/...。模块解析方式为 NodeNext。
依赖项	零运行时依赖。
Bitget API	Bitget 统一交易账户（UTA / v3）。

---

文档

• 核心内发现。 discover 工具会返回实时、适配配置的工具界面，以及每项操作的契约；无需维护外部目录以保持同步。
• Bitget API 参考。 bitget.com/api-doc

---

相关项目

包	用途
bitget-agent-cli	终端 AI 工具（基于 SDK 构建）
bitget-agent-mcp	桌面 AI MCP 服务（基于 SDK 构建）
bitget-agent-skill	AI 推理指南
bitget-signal	市场分析技能
agent-hub	生态系统入口

---

常见问题

bitget-agent-sdk 是什么？

bitget-agent-sdk 是 Bitget 官方的基础 TypeScript SDK，涵盖 89 项 UTA 操作，支持 HMAC-SHA256 签名、客户端限流，并提供可挂载到任意大模型工具调用框架的 14 种动词 Intent 界面。bitget-agent-cli 和 bitget-agent-mcp 均基于此 SDK 构建，因此它是整个 Bitget Agent Hub 生态系统的基础层。

这个 SDK 面向哪些开发者用例？

构建量化交易策略、自定义 MCP 服务、大模型工具调用流水线、自动交易机器人，以及任何需要以编程方式访问 Bitget UTA API 的 TypeScript 或 JavaScript 项目。

这与直接调用 Bitget REST API 有何不同？

SDK 可处理 HMAC-SHA256 请求签名、客户端限流和类型化错误类。它提供 14 个精选 Intent 动词以及 raw 逃生口，均可挂载到任意大模型工具调用框架中。safeInvoke 会为每次调用提供统一的 { ok, … } 格式，无需自行用 try/catch 包装每个处理程序。

此 SDK 支持 CommonJS 吗？

不支持，仅限 ESM（"type": "module"）。需要 Node.js ≥ 20 和 NodeNext 模块解析方式。

如何仅加载特定模块？

传入逗号分隔的列表，例如 loadConfig({ modules: "account,trade" })；若要加载所有模块，则使用 loadConfig({ modules: "all" })。

我使用的是 Bitget 经典账户，可以使用此 SDK 吗？

可以，但经典账户需要先通过 API 创建一个 Agent 子账户，然后使用该子账户的 API 密钥来使用 MCP / CLI / Skill 工具。查看创建 Agent 子账户 API →

这是 Bitget 官方提供的吗？可以免费使用吗？

是的。这是 Bitget 在 MIT 许可证下发布的官方开源 SDK，可免费使用。

---

许可证

MIT — Bitget Agent SDK

_{Bitget 官方 Agent Hub 工具 · 交易栈 · 基础层。基于此 SDK 构建的工具：agent-cli · agent-mcp · agent-skill}