Bitkub Trading Mcp

安装

要求： Node.js ≥ 20（运行 node --version 检查）。无需克隆或构建——MCP 客户端会在首次启动时通过 npx 下载软件包。

快速安装 — Claude Code CLI（推荐）

一条命令，无需编辑 JSON。

仅获取公开数据（无需 API 密钥）

如果你只需要市场数据——价格、订单簿、蜡烛图、公开行情流——可以完全跳过 env 代码块：

claude mcp add bitkub-trading-mcp -- npx -y bitkub-trading-mcp

9 个公开 REST 工具和 1 个公开 WebSocket 行情工具可立即使用。12 个安全 REST 工具和 2 个私有 WebSocket 工具会注册，但每次调用都会返回身份验证错误，并说明如何添加密钥。

使用 API 密钥（完整功能——你的钱包或订单与成交交易）

将两个占位值替换为真实的 Bitkub 密钥和密钥串。生成方法请参阅添加 API 密钥。

claude mcp add bitkub-trading-mcp \
  -e BITKUB_API_KEY=your_real_key_here \
  -e BITKUB_API_SECRET=your_real_secret_here \
  -- npx -y bitkub-trading-mcp

在所有项目中启用

在上述任一命令中添加 -s user：

claude mcp add bitkub-trading-mcp -s user -- npx -y bitkub-trading-mcp

运行其中任一命令后，先运行 /exit，再重新运行 claude。使用 /mcp 验证。

手动安装（Claude Desktop 或手动编辑配置）

如果你使用 Claude Desktop，或更愿意手动编辑配置文件，请按照以下三个步骤操作。

1. 打开 MCP 客户端配置文件

客户端	配置文件路径
Claude Code（所有平台）	~/.claude.json（Linux/macOS/WSL）或 %USERPROFILE%\.claude.json（Windows）
Claude Desktop — macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop — Windows	%APPDATA%\Claude\claude_desktop_config.json
Claude Desktop — Linux	~/.config/Claude/claude_desktop_config.json

如果文件尚不存在，请创建文件，并将 { "mcpServers": {} } 作为内容。

2. 添加 bitkub-trading-mcp 代码块

在 mcpServers 对象中添加以下条目。如果你已经配置了其他 MCP 服务，请用逗号分隔——这是一个普通的 JSON 对象。

{
  "mcpServers": {
    "bitkub-trading-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "bitkub-trading-mcp"],
      "env": {
        "BITKUB_API_KEY": "your_api_key_here",
        "BITKUB_API_SECRET": "your_api_secret_here"
      }
    }
  }
}

将两个 your_..._here 占位值替换为真实的 Bitkub 密钥和密钥串——生成方法请参阅下文的添加 API 密钥。

3. 重启客户端并验证

• Claude Code： 运行 /exit，然后重新运行 claude。接着运行 /mcp。
• Claude Desktop： 完全退出应用（Windows 上右键单击系统托盘图标 → 退出；macOS 上按 Cmd+Q），然后重新启动。

你应该会看到 bitkub-trading-mcp 已连接，并提供 24 个工具。首次启动时会从 npm 下载软件包（约 5–10 秒）；之后的启动会使用缓存版本。

如果未设置 BITKUB_API_KEY/BITKUB_API_SECRET，公开工具仍可使用；安全工具会注册，但每次调用都会返回身份验证错误，并说明如何添加 env 代码块。

添加 API 密钥

公开 REST 工具和公开行情 WebSocket 工具无需密钥即可使用。12 个安全 REST 工具和 2 个私有 WebSocket 工具需要在 MCP 客户端配置的 env 代码块中设置 Bitkub API 密钥和密钥串——绝不要将其作为工具参数传入。大模型永远不会看到密钥串。

1. 在 Bitkub 上生成密钥

1. 前往 https://www.bitkub.com/en/api-management，如果系统提示，请登录。
2. 点击 Create new API key。
3. 建议：仅启用只读权限——取消勾选 Trade 和 Withdraw 权限范围。该服务仅提供只读端点，因此授予密钥写入权限只会扩大攻击面。
4. 关闭对话框前，复制 API Key 和 API Secret（密钥只会显示一次）。

2. 粘贴到 env 代码块中

将上方所选安装选项中的两个 your_..._here 占位符替换为真实的密钥和密钥密码。保存并重启 MCP 客户端。

3. 验证密钥是否正常工作

如果你已检出源代码：

cd /path/to/bitkub-trading-mcp
eval "$(bun -e 'const c=await Bun.file(`${process.env.HOME}/.claude.json`).json();const e=c.mcpServers[`bitkub-trading-mcp`].env;console.log(`export BITKUB_API_KEY=${e.BITKUB_API_KEY}\nexport BITKUB_API_SECRET=${e.BITKUB_API_SECRET}`)')" && bun scripts/test-auth.ts

PASS 表示密钥和签名流程已成功通过 Bitkub 端到端验证。

否则，只需问 Claude “我的 Bitkub 钱包里有什么？”——如果它返回余额，就说明密钥正常工作。

公共工具

工具	端点
bitkub_status	GET /api/status
bitkub_servertime	GET /api/v3/servertime（毫秒）
bitkub_symbols	GET /api/v3/market/symbols
bitkub_ticker	GET /api/v3/market/ticker?sym= — 省略 sym 即可在一次调用中获取所有交易对
bitkub_bids	GET /api/v3/market/bids?sym=&lmt=
bitkub_asks	GET /api/v3/market/asks?sym=&lmt=
bitkub_depth	GET /api/v3/market/depth?sym=&lmt=
bitkub_trades	GET /api/v3/market/trades?sym=&lmt=
bitkub_tv_history	GET /tradingview/history?symbol=&resolution=&from=&to=

安全工具（只读，需要身份验证）

凡是存在对应的 Bitkub v4 接口，均使用 v4；仅在 v4 尚未提供相应接口时才保留 v3。v4 使用带查询参数的 GET；v3 大多使用带请求体的 POST。v3 和 v4 的身份验证签名方式相同。

工具	版本	方法	接口	参数（经 zod 验证）
bitkub_balances	v4	GET	/api/v4/wallet/balances	segment?（"funding"）
bitkub_crypto_addresses	v4	GET	/api/v4/crypto/addresses	page?（≥1）、limit?（1–200）、symbol?、network?、memo?
bitkub_crypto_deposits	v4	GET	/api/v4/crypto/deposits	page?、limit?（1–200）、symbol?、status?、created_start?、created_end?（ISO 8601）
bitkub_crypto_withdraws	v4	GET	/api/v4/crypto/withdraws	与 bitkub_crypto_deposits 参数格式相同（只读历史记录）
bitkub_fiat_accounts	v4	GET	/api/v4/fiat/accounts	page?（1–100）、limit?（1–100）——必须成对提供
bitkub_fiat_deposits	v4	GET	/api/v4/fiat/deposit/history	page?、limit?（1–100）——必须成对提供
bitkub_fiat_withdraws	v4	GET	/api/v4/fiat/withdraw/history	page?、limit?（1–100）——必须成对提供（只读历史记录）
bitkub_my_open_orders	v3	GET	/api/v3/market/my-open-orders	sym
bitkub_my_order_history	v3	GET	/api/v3/market/my-order-history	sym、p?、lmt?、start?、end?
bitkub_order_info	v3	GET	/api/v3/market/order-info	sym、id、sd、hash?
bitkub_user_limits	v3	POST	/api/v3/user/limits	（无）
bitkub_user_trading_credits	v3	POST	/api/v3/user/trading-credits	（无）

身份验证签名（v3 和 v4）：X-BTK-APIKEY、X-BTK-TIMESTAMP（Unix 毫秒）、X-BTK-SIGN = {ts}{METHOD}{path}{?query | body} 的 HMAC-SHA256，十六进制小写。对于 POST 请求，签名使用在线路上发送的确切 JSON 字节。

参考资料：https://github.com/bitkub/bitkub-official-api-docs/blob/master/restful-api.md · https://github.com/bitkub/bitkub-official-api-docs/blob/master/restful-api-v4.md

WebSocket 工具（快照）

每次调用都会打开一个 WebSocket，在限定时长内收集事件，然后关闭。无状态 — 不会建立长期订阅，也不会发送 MCP 通知。

工具	流	身份验证	默认 / 最长时长
bitkub_ws_ticker_snapshot	market.ticker.<sym>（公开）	无	10 s / 60 s
bitkub_ws_order_updates	order_update（私有）	必需	30 s / 120 s
bitkub_ws_match_updates	match_update（私有）	必需	30 s / 120 s

参数（适用于每个工具）：

• duration_ms? — 整数，单位为毫秒。默认值和上限见上表。
• bitkub_ws_ticker_snapshot.sym — 必填（例如 btc_thb）。
• bitkub_ws_order_updates.sym / bitkub_ws_match_updates.sym — 可选，用于按 data.symbol 进行后置筛选。

响应格式：

{
  "events": [/* raw Bitkub payloads, in receive order */],
  "count": 0,
  "duration_ms_actual": 30000,
  "stream": "order_update",
  "started_at": "2026-05-10T17:00:00.000Z",
  "ended_at":   "2026-05-10T17:00:30.000Z"
}

如果 WS 在时间窗口结束前关闭，响应还会包含 closed_early: true 和 closed_reason: "..."。

竞态条件说明： 私有流只会传送在发送 subscribe 之后发生的事件。如果你想观察订单的完整生命周期，请在下单时并行调用 bitkub_ws_order_updates — 或在下单后调用 bitkub_order_info，以获取权威的最终状态。

并发上限： Bitkub 每个 API 密钥最多允许 5 个并发私有 WebSocket 连接。服务端会检测“并发连接过多”导致的关闭，并提供清晰的提示。

排除的流（有意排除）： 公开的 market.trade.* 通道（Bitkub 将于 2026-05-18 弃用）以及公开的订单簿通道（使用数字 pairing_id 而非交易对符号；REST bitkub_depth 更适合此用途）。

参考资料：https://github.com/bitkub/bitkub-official-api-docs/blob/master/websocket-api.md · https://github.com/bitkub/bitkub-official-api-docs/blob/master/private-websocket.md

使用示例

Claude 会根据你用日常语言提出的要求调用工具。“你说的话”一列展示会触发工具的提示词示例；“调用的工具”一列展示底层实际调用的工具（你可以通过 /mcp → 工具历史进行验证）。所有示例均假设服务已注册并连接。

公开 REST — 市场数据（无需密钥）

你说的话	调用的工具	备注
“Bitkub 的 API 现在正常吗？”	bitkub_status	手动下单前先检查平台运行状况。
“BTC/THB 当前价格是多少？”	bitkub_ticker，参数为 sym=btc_thb	一次性获取当前时点价格和 24 小时涨跌幅。
“比较 BTC、ETH、ADA、USDT 的价格”（任意多交易对查询）	bitkub_ticker，不传参数 — 一次调用即可返回所有交易对	不要按交易对循环调用；批量调用速度更快，也能避免触发速率限制。
“显示 ETH/THB 的前 10 个买单”	bitkub_bids，参数为 sym=eth_thb, lmt=10	未成交买单（买盘）。卖单请使用 bitkub_asks。
“BTC/THB 的订单簿深度如何？显示前 20 档。”	bitkub_depth，参数为 sym=btc_thb, lmt=20	汇总买盘和卖盘 — 最适合用于价差分析。
“列出 USDT/THB 最近的 50 笔交易”	bitkub_trades，参数为 sym=usdt_thb, lmt=50	最近成交的交易（时间戳、价格、方向、数量）。
“列出 Bitkub 上所有可用的交易对”	bitkub_symbols	不确定准确的 sym 字符串时很有用。
“获取过去 24 小时的 BTC/THB 小时 K 线”	bitkub_tv_history，参数为 symbol=BTC_THB, resolution=60, from=<ts>, to=<ts>	用于绘图的 OHLCV 数据。分辨率：1, 5, 15, 60, 240, 1D。
“服务器当前时间是多少？”	bitkub_servertime	如果签名请求失败，可用于检查时钟偏差。

私有 REST — 您的账户（需要密钥，只读）

您可以这样说	调用的工具	备注
“我的 Bitkub 钱包里有什么？”	bitkub_balances	v4 端点。返回每种资产的币种、可用余额、预留余额和总额。
“列出我的 BTC/THB 未完成订单”	bitkub_my_open_orders with sym=btc_thb	仅显示当前有效订单。
“显示我最近 20 笔 BTC/THB 订单，包括已成交和已取消的订单”	bitkub_my_order_history with sym=btc_thb, lmt=20	完整历史记录，支持分页。
“告诉我订单 ID 123456（买入）的状态”	bitkub_order_info with sym=btc_thb, id=123456, sd=buy	查询特定订单的权威当前状态。
“我的用户交易限额是多少？”	bitkub_user_limits	每日／每月 THB 交易量上限。
“我有多少交易额度？”	bitkub_user_trading_credits	Bitkub 交易额度余额（用于抵扣手续费）。
“列出我保存的加密货币充值地址”	bitkub_crypto_addresses with limit=50	v4。可按 symbol、network、memo 筛选。
“显示我过去 30 天的加密货币充值记录”	bitkub_crypto_deposits with created_start=2026-04-10T00:00:00Z, limit=100	v4，支持按日期筛选。最长时间范围为 90 天。
“显示我本月的加密货币提现记录”	bitkub_crypto_withdraws with created_start=2026-05-01T00:00:00Z	v4，结构与充值记录相同。
“列出我已登记的银行账户”	bitkub_fiat_accounts with page=1, limit=20	必须同时提供 page 和 limit — 两者都提供或都不提供。
“我的法币充值记录”	bitkub_fiat_deposits with page=1, limit=20	同样必须配对提供。
“我的法币提现记录”	bitkub_fiat_withdraws with page=1, limit=20	同样必须配对提供。

公共 WebSocket — 实时行情（无需密钥）

您可以这样说	调用的工具	备注
“采样 BTC/THB 价格 10 秒。它是在上涨还是下跌？”	bitkub_ws_ticker_snapshot with sym=btc_thb, duration_ms=10000	返回行情更新数组；Claude 会计算首尾变化。
“观察 ETH/THB 30 秒，并告诉我波动情况”	bitkub_ws_ticker_snapshot with sym=eth_thb, duration_ms=30000	市价买入前很有用，可以查看实际价差变化。
“BTC 刚才是不是突然上涨了？采样 15 秒。”	bitkub_ws_ticker_snapshot with sym=btc_thb, duration_ms=15000	可捕捉 REST 轮询会错过的短时波动。

注意：活动较少时，Bitkub 有时会在短短几秒后关闭公共行情数据流。发生这种情况时，响应会包含 closed_early: true — 如有需要，Claude 可以重新运行。

私有 WebSocket — 订单 / 成交流（需要密钥）

你的说法	调用的工具	说明
“监控我的账户 60 秒，并报告任何订单事件”	使用 duration_ms=60000 调用 bitkub_ws_order_updates	捕获 new → open → partial_filled → filled → canceled 状态变化。
“只监控 BTC/THB 订单更新，持续 90 秒”	使用 sym=btc_thb, duration_ms=90000 调用 bitkub_ws_order_updates	sym 会按 data.symbol 对事件进行后置筛选。
“等待 60 秒，告诉我执行了哪些交易”	使用 duration_ms=60000 调用 bitkub_ws_match_updates	每笔成交对应一次撮合。汇总平均成交价和总手续费。
“比较接下来 90 秒内做市方与吃单方的成交率”	使用 duration_ms=90000 调用 bitkub_ws_match_updates	每笔撮合都有 is_maker 字段。

竞态条件处理方案。 私有 WS 只会传送订阅后发生的事件 — 要捕获订单的完整生命周期：

“以 2.7M 的价格限价买入 0.0001 BTC，并行监控 order_updates 60 秒。然后调用 bitkub_order_info 确认最终状态。”

在 Claude 的一次交互中，这三个工具调用会并行触发。WS 会捕获大部分生命周期事件；REST order_info 调用则会提供权威的最终状态，以防遗漏较早发生的事件。

注意：此服务不包含下单功能 — 你需要另行添加交易服务（或在 Bitkub 上手动下单）。对于通过其他方式提交的订单，监控 + 验证模式仍然适用。

组合工作流（在一条提示词中调用多个工具）

工作流	使用的工具（并行）
“显示 BTC/THB 深度、最近 50 笔交易，并监控行情快照 10 秒。告诉我现在是不是买入的好时机。”	bitkub_depth + bitkub_trades + bitkub_ws_ticker_snapshot
“审查我最近 24 小时的情况：当前余额、从昨天起的所有加密货币存款，以及任何未完成订单。”	bitkub_balances + bitkub_crypto_deposits（使用 created_start）+ bitkub_my_open_orders（按交易对）
“我的订单在 UI 中卡在 ‘open’ 状态。获取它的 REST 状态，并监控 order_updates 30 秒，看看有没有变化。”	bitkub_order_info + bitkub_ws_order_updates

安全性

• 设计上只读。 此服务有意不实现下单、取消订单、发起提现或生成地址功能。仅开放数据检索端点。
• 使用只读 Bitkub API 密钥。 Bitkub 的 API 密钥权限模型允许将密钥限制为只读操作 — 请这样设置。服务本身不会拒绝任何操作，但遵循最小权限原则的密钥可在交易所层面提供可靠保障，即使发生异常也不例外。
• 不会将凭据作为工具参数接收。 凭据仅读取自 process.env，来源是 MCP 客户端的 env 块。LLM 无法看到密钥。
• 不会记录密钥。 stderr 上的诊断信息只会说明是否存在凭据，不会显示其值。
• 如需轮换密钥，请更新客户端配置中的 env 块并重启 MCP 客户端；无需更改服务代码。

说明

• 所有响应均原样传递 Bitkub 的 JSON（不映射字段）。
• Bitkub 信封错误（error != 0）会作为 MCP 工具错误返回，并保留原始错误代码。
• HTTP 非 2xx 响应会连同状态码和响应正文一起返回。
• 诊断信息仅写入 stderr — stdout 专用于 MCP 传输。