# Agent Hub

**不用打开交易所，说一句话，AI 帮你直接在 Claude、Cursor、Codex 里操作你的 Bitget 账户交易美股和加密货币。**

以本地进程方式运行在你的设备上 · API Key 经 HMAC-SHA256 在本机签名，不经任何第三方服务器 · MIT 开源

:::info{title="最新版本"}
本文档内容可能未反映最新版本，最新变更以 [GitHub 仓库](https://github.com/Bitget-AI/agent_hub) 为准。
:::

[GitHub](https://github.com/Bitget-AI/agent_hub)  · [获取 API Key](https://www.bitget.com/zh-CN/account/newapi) · [Telegram 社群](https://telegram.me/+o1tYqQ_lXxllYjgy)

## 文档目录

```text
Bitget AgentHub
│
├── 能做什么
├── 选择安装路径
│
├── 具体的安装指南
│   ├── MCP Server    ← Claude Desktop / Cursor / Windsurf / Codex
│   ├── CLI · bgc     ← Claude Code / Codex CLI / OpenClaw
│   ├── Skill         ← 配合 CLI，教 AI 何时调用、如何调用
│   ├── Signal        ← 实时数据获取 + AI 分析，无需账户
│   └── SDK           ← 开发者自建集成
│
├── 安全须知
└── FAQ
```

## 能做什么

:::tip{title="适合谁"}
Agenthub 适合想用 AI 交易加密货币和代币化美股的用户：AI 辅助看盘 · 分析行情 · 执行操作 · 管理账户 · 写策略 · 做研究。
:::

用 AI 做交易这件事，最麻烦的不是策略，是要在 AI 和交易所之间反复切换——问完 AI 再去手动下单，看完行情再回来对话。AgentHub 把这两步合并：你只需要在 AI 里说一句话，剩下的它来做。

| 你对 AI 说 | 实际发生的事 |
|-|-|
| 「市价买 0.1 BTC」「开 BTC 多仓 10 倍杠杆」 | 现货 / 合约下单 |
| 「查余额」「把 500U 划到合约账户」 | 账户查询 & 资金划转 |
| 「BTC 现价」「4h K 线」「资金费率」 | 实时行情（无需 API Key） |
| 「现在是恐慌还是贪婪？」「今天有什么重要消息？」 | 市场分析（无需账户） |

:::warning{title="风险提示"}
AI 可能误判，下单结果由你负责。强烈建议先用模拟盘演练。
:::

## 选择你的安装路径

根据你用的 AI 工具选择：

:::info{title="说明"}
同一路径下的安装方式对所有列出的工具通用。比如 CLI 的安装命令，在 Claude Code、Codex、OpenClaw 上步骤完全一样，运行后会自动识别并部署到你已安装的工具。
:::

| 我用的是… | 对应路径 | 一键安装 |
|-|-|-|
| Claude Desktop · Cursor · Windsurf · ChatGPT Desktop · Codex | MCP Server | `npx -y @bitget-ai/bitget-agent-mcp` |
| Claude Code · Codex CLI · OpenClaw | CLI · bgc | `npx @bitget-ai/bitget-agent-installer upgrade-all --target all` |
| 只需市场分析，不交易 | Signal | `npx @bitget-ai/bitget-signal --target all` |
| 不确定 / 全部都要 | 全套 | `npx @bitget-ai/bitget-agent-installer upgrade-all --target all` |

:::tip{title="注意"}
表格中 MCP Server 的一键命令只是启动 MCP 进程，并不会自动写入你的 AI 工具配置文件。你仍需手动（或让 AI）完成配置文件的修改，具体步骤见下方 MCP Server 章节。
:::

**前置条件**：[Node.js ≥ 20](https://nodejs.org/)（运行 `node -v` 确认版本）

## MCP Server

:::info{title="适用场景"}
如果你用的是有图形界面的 AI 工具（Claude Desktop、Cursor、Windsurf、ChatGPT Desktop、Codex），选这个。你在对话里说的每一条指令都会被转化为对你 Bitget 账户的实际操作。
:::

以下安装步骤对所有工具通用，核心命令 `npx -y @bitget-ai/bitget-agent-mcp` 不变。唯一的区别是配置文件的位置——在 Step 1 的表格里找到你用的工具对应的路径即可。

### 让 AI 帮你配置（推荐）

把下面这段话直接粘贴给你的 AI，它会自动完成配置：

```text title="粘贴给 AI 的指令"
帮我配置 Bitget MCP Server（需要 Node.js 20+）：
先问我用的是哪个 AI 工具（Claude Desktop / Cursor / Windsurf / ChatGPT Desktop），
然后在该工具的 MCP 配置里添加用 `npx -y @bitget-ai/bitget-agent-mcp` 启动的 server，
并填入我的 BITGET_API_KEY、BITGET_SECRET_KEY、BITGET_PASSPHRASE。
配置完成后确认 Bitget 工具已加载（应能看到 market、order、discover 等工具）。
```

### 手动配置

**Step 1** — 打开你的 AI 工具配置文件：

| 工具 | 配置文件路径 |
|-|-|
| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| Cursor | Settings → MCP → Add New Server |
| Windsurf / Continue | 参考各自文档中的 MCP 配置说明 |

**Step 2** — 将以下内容添加到配置文件中（还没有 API Key？前往 [API 管理页面](https://www.bitget.com/en/api-management) → 创建 API Key，勾选 **Read + Trade** 权限，建议先创建 **Demo Key** 用于模拟盘测试）：

```json title="mcp 配置"
{
  "mcpServers": {
    "bitget": {
      "command": "npx",
      "args": ["-y", "@bitget-ai/bitget-agent-mcp"],
      "env": {
        "BITGET_API_KEY": "填入你的 API Key",
        "BITGET_SECRET_KEY": "填入你的 Secret Key",
        "BITGET_PASSPHRASE": "填入你的 Passphrase"
      }
    }
  }
}
```

**Step 3** — 完全退出并重启 AI 工具。

**Step 4** — 在 AI 对话里输入「BTC 现价是多少？」，收到行情数据说明配置成功。

### 按需调整模式

在 args 里追加参数切换：

| 场景 | 追加参数 | 说明 |
|-|-|-|
| 先用模拟盘熟悉 | `"--paper-trading"` | 使用 Demo Key，不动真实资产 |
| 只查询不操作 | `"--read-only"` | 禁止所有下单和划转操作 |
| 只看行情、不需要账户 | `"--modules", "market"` | 无需配置 API Key |

示例——只读模式：

```json title="只读模式"
"args": ["-y", "@bitget-ai/bitget-agent-mcp", "--read-only"]
```

:::tip{title="Cursor 用户"}
Cursor 支持的 MCP 工具总数约为 40 个，Bitget 默认占用约 14 个。如果工具没有完整加载，尝试关闭其他 MCP，或用 `--modules market` 只加载行情模块。
:::

### 代理配置

如果你需要通过 VPN 或代理访问网络，在 MCP 配置的 env 块里加入以下变量（填入你自己的代理地址）：

```json title="代理配置"
"env": {
  "BITGET_API_KEY": "your-api-key",
  "BITGET_SECRET_KEY": "your-secret-key",
  "BITGET_PASSPHRASE": "your-passphrase",
  "HTTPS_PROXY": "你的代理地址，例如 http://127.0.0.1:端口号",
  "NODE_USE_ENV_PROXY": "1"
}
```

:::info{title="为什么要加 NODE_USE_ENV_PROXY"}
`NODE_USE_ENV_PROXY=1` 确保 Node.js 的网络请求也走代理，否则部分请求可能绕过代理。
:::

### 装完后 AI 能做什么

| 模块 | 默认加载 | 涵盖操作 | 是否需要 API Key |
|-|-|-|-|
| `market` | ✅ | 行情价格 · K 线 · 资金费率 · 订单簿 · 持仓量 | 否 |
| `trade` | ✅ | 下单 · 撤单 · 改单 · 查持仓 · 策略单 | 是 |
| `account` | ✅ | 账户余额 · 资金划转 · 充值 · 提现 · 子账户管理 | 是 |
| `strategy` | 按需 | 触发单 · 止盈止损单 · 计划委托 | 是 |
| `cryptoloans` | 按需 | 借币 · 还款 · 质押贷款 | 是 |
| `tax` | 按需 | 税务记录查询 | 是 |

加载额外模块：`"args": ["-y", "@bitget-ai/bitget-agent-mcp", "--modules", "all"]`

### 试试这几句话

```text
BTC 现价是多少？
查一下我的 USDT 余额，再看看有哪些合约持仓
帮我在模拟盘开一个 BTC 多仓，10 倍杠杆，0.01 BTC
先看一下 BTC 现价，再帮我挂一个比现价低 2% 的限价买单
```

## CLI · bgc

:::info{title="适用场景"}
如果你用的是终端类 AI 工具（Claude Code、Codex CLI、OpenClaw），或者希望在终端里直接敲命令操作 Bitget，选这个。
:::

以下安装步骤对所有工具通用，安装命令运行后会自动检测你已安装的工具并分别部署，无需为每个工具单独操作。

### 一键安装

把下面这段话粘贴给你的终端 AI，或直接在终端运行：

```text title="粘贴给终端 AI 的指令"
请执行以下命令安装 Bitget Agent Hub 终端工具（需要 Node.js 20+）：
npx @bitget-ai/bitget-agent-installer upgrade-all --target all
安装完成后帮我验证：运行 `bgc --version` 和 `bgc discover`，把结果告诉我。
```

```bash
npx @bitget-ai/bitget-agent-installer upgrade-all --target all
```

这条命令会安装 bgc CLI、交易 Skill 和市场分析 Skill，并自动部署到 Claude Code / Codex / OpenClaw。

### 配置 API Key

还没有 API Key？前往 [API 管理页面](https://www.bitget.com/en/api-management) → 创建 API Key，勾选 **Read + Trade** 权限，保存好 API Key、Secret Key、Passphrase 三个值。建议先创建 **Demo Key** 配合 `--paper-trading` 练手，再切换实盘。

```bash
export BITGET_API_KEY="你的 API Key"
export BITGET_SECRET_KEY="你的 Secret Key"
export BITGET_PASSPHRASE="你的 Passphrase"
```

:::tip{title="小贴士"}
建议把这三行写入 `~/.zshrc` 或 `~/.bashrc`，避免每次重新配置。查看公开行情不需要 Key，账户操作和下单必须配置。
:::

### 验证安装

```bash
bgc --version         # 查看版本号
bgc discover          # 查看所有可用操作
bgc market --action tickers --category SPOT --symbol BTCUSDT   # 无需 Key，测试行情
```

### 完整工具列表

bgc 通过 14 个意图动词覆盖所有操作：

| 动词 | 说明 | 示例 |
|-|-|-|
| `market` | 行情 · K 线 · 资金费率（公开数据） | `bgc market --action tickers --symbol BTCUSDT` |
| `order` | 下单 · 撤单 · 改单 · 查订单 | `bgc order --action place --side buy --qty 0.1` |
| `position` | 查持仓 · 平仓 · 设杠杆 | `bgc position --action info --category linear` |
| `strategy_order` | 触发单 · 止盈止损 | `bgc strategy_order --action open` |
| `account_overview` | 账户快照（资产 + 持仓 + 手续费） | `bgc account_overview --coin USDT` |
| `transfer_funds` | 账户间资金划转 | `bgc transfer_funds --fromType spot --amount 100` |
| `deposit` | 充值地址 & 记录 | `bgc deposit --action address --coin USDT` |
| `withdraw` | 提现（高风险，需 `--confirm`） | `bgc withdraw --coin USDT --amount 100 --confirm` |
| `loan` | 借币 · 还款 | `bgc loan --action borrow --coin USDT` |
| `subaccount` | 子账户管理 | `bgc subaccount --action list` |
| `tax` | 税务记录 | `bgc tax --action history --year 2024` |
| `discover` | 查看所有可用操作 | `bgc discover --domain trade` |

### 常用命令

```bash
# 查看账户余额
bgc account_overview --coin USDT

# 预览下单（加 --dry-run 不会真正发单）
bgc order --action place --category SPOT --symbol BTCUSDT \
  --side buy --orderType market --qty 0.001 --dry-run

# 查看合约持仓
bgc position --category linear

# 预览资金划转
bgc transfer_funds --action transfer --fromType spot --toType mix_usdt \
  --amount 100 --coin USDT --dry-run
```

**安全标志：**

| 标志 | 作用 |
|-|-|
| `--dry-run` | 预览请求，不实际发送 |
| `--read-only` | 禁止所有写操作 |
| `--paper-trading` | 切换到模拟盘 |
| `--confirm` | 高风险操作（如提现）的二次确认 |

### 代理配置

如果你需要通过 VPN 或代理访问网络，可在环境变量中设置（填入你自己的代理地址）：

```bash
export HTTPS_PROXY="你的代理地址"
```

或在命令中指定 API 基础地址：

```bash
export BITGET_API_BASE_URL="https://api.bitget.com"
```

### 试试这几句话

```text
BTC 现价是多少？
查一下我的 USDT 余额，把 500 USDT 划转到合约账户
在模拟盘开一个 BTC 多仓，10 倍杠杆，0.01 BTC
查一下我的 BTC 持仓，如果没有就在模拟盘开一个 10 倍多仓
```

## Skill

:::info{title="适用场景"}
配合 CLI · bgc 使用，适用于 Claude Code · Codex CLI · OpenClaw。
:::

Skill 是一份装进 AI 工具里的说明文件，告诉 AI 什么时候该调用 bgc、怎么拼命令、写操作前如何提示你确认。没有 Skill，AI 有工具但不知道怎么用。

使用 CLI 一键安装时（upgrade-all）已自动包含，无需单独安装。如需单独部署：

```bash
npx @bitget-ai/bitget-agent-skill --target all
```

| `--target` | 部署到 |
|-|-|
| `claude` | Claude Code |
| `codex` | Codex CLI |
| `openclaw` | OpenClaw |
| `all` | 以上全部 |

部署完成后重启 AI 工具生效。

## Signal（无需账户）

不需要 Bitget 账户，也不需要 API Key。安装后会在本地部署 5 个 Skill 文件，并注册一个远程公开 MCP 数据服务（`https://datahub.noxiaohao.com/mcp`）作为数据源——AI 的分析基于这个服务实时返回的真实数据，不是凭空生成。

五个数据方向：

| 你可以问… | 数据来源 & 能力 |
|-|-|
| 「美联储加息对 BTC 有什么影响？」 | `macro-analyst` — 实时宏观数据，分析利率 · 收益率曲线 · 跨资产相关性 |
| 「鲸鱼最近在往交易所转币吗？」 | `market-intel` — 链上流向 · ETF 资金净流入 · DeFi TVL |
| 「现在市场情绪怎么样？」 | `sentiment-analyst` — 恐慌贪婪指数 · 资金费率 · 多空持仓比 |
| 「BTC 的 RSI 超买了吗？」 | `technical-analysis` — 拉取 K 线后计算 23 个技术指标 |
| 「今天加密市场有什么重要新闻？」 | `news-briefing` — 实时聚合 44 个信息源（媒体 · 社区 · 官方公告） |

### 安装

粘贴给你的 AI，或直接在终端运行：

```text title="粘贴给 AI 的指令"
请执行 `npx @bitget-ai/bitget-signal --target all`（需要 Node.js 20+），
安装 Bitget 市场分析 Skill，完成后提醒我重启 AI 工具。
```

```bash
npx @bitget-ai/bitget-signal --target all
```

安装完成后重启 AI 工具，然后直接提问即可。

:::tip{title="技术指标分析需要 Python 依赖"}
technical-analysis Skill 依赖 pandas 和 numpy，若需使用技术指标能力，请先执行：
:::

```bash
pip install pandas numpy
```

## SDK（开发者）

:::info{title="适用场景"}
如果你是开发者，想在自己的项目里集成 Bitget 交易能力——比如构建自定义 MCP 服务器、量化策略、LLM 工具调用管道或自动化交易机器人——直接用 SDK。
:::

### 安装

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

**环境要求**：Node.js ≥ 20 · ESM only · 零运行时依赖 · 包含 TypeScript 类型

### 快速上手

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

// 从只读开始，安全的默认值
const config = loadConfig({ modules: "all", readOnly: true });
const client = new BitgetRestClient(config);
const tools = buildTools(config);
const ctx = { config, client };

// 查询公开行情，无需 API Key
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);
```

### 配置选项

| 参数 | 默认值 | 说明 |
|-|-|-|
| `surface` | `"intent"` | "intent" 精选动词；"full" 暴露所有 1:1 操作 |
| `modules` | `"account,trade,market"` | 逗号分隔的模块名，或 "all" |
| `readOnly` | `false` | 移除所有写工具，AI 无法下单或划转 |
| `paperTrading` | `false` | 路由到 Bitget Demo 环境，不动真实资金 |
| `baseUrl` | `https://api.bitget.com` | 可通过 BITGET_API_BASE_URL 环境变量覆盖 |

### 运行时探索

不需要提前背操作列表，用 discover 在运行时查看可用工具和参数：

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

await safeInvoke(discover, {}, ctx);                                     // 列出所有域和工具数量
await safeInvoke(discover, { domain: "trade" }, ctx);                    // 查看 trade 域下的工具
await safeInvoke(discover, { tool: "market", action: "tickers" }, ctx);  // 查看具体操作的参数契约
await safeInvoke(discover, { search: "funding" }, ctx);                  // 关键词搜索
```

### 错误处理

推荐用 safeInvoke，永不抛出异常：

```typescript
const res = await safeInvoke(tool, args, ctx);
if (res.ok) {
  // res.data
} else {
  // res.error — 可直接作为 LLM 工具调用的错误响应
}
```

需要精细控制时，使用类型化错误：

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

try {
  await tool.handler(args, ctx);
} catch (err) {
  if (err instanceof RateLimitError) { /* 退避重试 */ }
  else if (err instanceof BitgetApiError) { console.error(err.code, err.message); }
  else if (err instanceof ConfigError) { /* 凭证缺失或无效 */ }
}
```

### 集成测试

SDK 内置 MockServer，无需调用真实 API：

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

const mock = new MockServer();
await mock.start();

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

// 针对 client 编写测试 ...

await mock.stop();
```

更多：[agent-sdk](https://github.com/Bitget-AI/agent-sdk)

## 安全须知

AgentHub 在设计上保证你的凭证不离开本机：API Key 只从环境变量读取，所有请求在本地完成 HMAC-SHA256 签名后直连 [api.bitget.com](http://api.bitget.com)，没有中间层，没有遥测，没有日志上传。

AgentHub 内置了四层保护机制：

| 机制 | 说明 |
|-|-|
| **模拟盘模式** | `--paper-trading` 将所有请求路由到 Bitget Demo 环境，不涉及真实资金 |
| **只读模式** | `--read-only` 在启动时移除所有写工具，AI 物理上无法下单或划转 |
| **预览模式** | `--dry-run` 构建完整请求但不发送，可提前确认参数是否正确 |
| **高风险确认** | 提现、全撤等操作需要显式加 `--confirm`，防止 AI 误触发 |

建议从模拟盘开始，验证行为符合预期后再切换实盘。创建 API Key 时按最小权限原则，不需要提现就不要开启。

## FAQ

**Q: 我的 AI 工具不在列表里，能用吗？**

**A:** 支持 MCP 协议的客户端都可以按桌面 AI 的方式接入；支持调用外部命令的终端 AI 可以使用 bgc 命令行。

**Q: 查行情需要 API Key 吗？**

**A:** 不需要。只有涉及账户（查余额、下单、划转）的操作才需要 Key。

**Q: API Key 会暴露给 AI 吗？**

**A:** 不会。Key 只从本地环境变量读取，不会出现在对话上下文里，也不上传任何服务器。

**Q: Cursor 里 Bitget 工具没加载全？**

**A:** Cursor 有约 40 个工具的总数限制。可以关闭其他 MCP，或在启动参数里加 `--modules market` 只加载行情模块。

**Q: AI 下单前会让我确认吗？**

**A:** 会。Skill 会在执行写操作前显示 `[CAUTION]` 提示并等待你确认。提现等高风险操作还需要额外加 `--confirm` 标志。

**Q: 收费吗？**

**A:** AgentHub 本身 MIT 开源免费。交易产生的手续费按你的 Bitget 账户等级计算。

**Q: 遇到问题去哪反馈？**

**A:** [GitHub Issues](https://github.com/Bitget-AI/agent_hub/issues) · 安全漏洞请发邮件至 [security@bitget.com](mailto:security@bitget.com)，不要在公开渠道发布。

## 相关链接

| 资源 | 地址 |
|-|-|
| Agent Hub（总入口） | https://github.com/Bitget-AI/agent_hub |
| MCP Server | https://github.com/Bitget-AI/agent-mcp |
| CLI（bgc） | https://github.com/Bitget-AI/agent-cli |
| Skill | https://github.com/Bitget-AI/agent-skill |
| Signal | https://github.com/Bitget-AI/bitget-signal |
| SDK（开发者） | https://github.com/Bitget-AI/agent-sdk |
| Bitget API 文档 | https://www.bitget.com/api-doc/common/intro |
| API Key 管理 | https://www.bitget.com/en/api-management |
| Telegram 社群 | https://telegram.me/+o1tYqQ_lXxllYjgy |

:::warning{title="风险提示"}
加密货币与代币化美股交易具有高风险，AI 可能误判。你须自行核对所有信息并承担全部后果。本工具不构成任何投资建议。
:::