bithumb-trade

Bithumb CEX 交易 CLI

提交、取消和监控单笔或批量现货订单；为大额持仓执行 TWAP（时间加权平均价格）订单。需要 API 凭据。所有订单都会使用真实资金——Bithumb 没有演示／模拟模式。

工具路由

写入操作优先使用 CLI：优先使用文档中说明的 bithumb ... CLI；仅当 CLI 不可用／失败或用户要求使用 MCP 时，才回退到 MCP。CLI 具备 MCP 不具备的安全机制（按配置文件进行只读限制、账户隔离、终端可复现性）。只读查询可使用任一路径。

前提条件

• 安装：npm install -g @bithumb-official/bithumb-cli
• 凭据：环境变量 BITHUMB_ACCESS_KEY / BITHUMB_SECRET_KEY，或 ~/.bithumb/config.toml。

技能路由

市场数据 → bithumb-market；资产／钱包／API 密钥 → bithumb-account；充币 → bithumb-deposit；提币 → bithumb-withdraw；审计日志／诊断 → bithumb-system；订单 → 本技能。

凭据检查（在执行任何需要身份验证的命令之前）

1. 运行 bithumb system diagnose。如果失败，立即停止——不要重试。 用韩语告知用户："인증 실패. API 키가 유효하지 않거나 만료되었을 수 있습니다."，并指导他们设置 BITHUMB_ACCESS_KEY/BITHUMB_SECRET_KEY 或检查 ~/.bithumb/config.toml。用户更新后，再次运行 bithumb system diagnose，然后重试原操作。
2. 如果检查通过，使用 bithumb account order-chance --market <m> 验证目标市场的交易权限（同时确认余额、费率和订单限制）。

命令索引

#	命令	类型	描述
1	bithumb trade place	写入	提交现货订单（限价／定额／市价）
2	bithumb trade cancel	写入	按订单 ID 或客户端订单 ID 取消订单
3	bithumb trade get	读取	按单个订单 ID／客户端订单 ID 获取单笔订单
4	bithumb trade list	读取	查询多笔订单或按筛选条件列出订单
5	bithumb trade batch-place	写入	一次提交多笔订单（最多 20 笔）
6	bithumb trade batch-cancel	写入	一次取消多笔订单（最多 30 笔）
7	bithumb twap place	写入	提交 TWAP 订单（按时间加权执行）
8	bithumb twap list	读取	获取 TWAP 订单历史记录
9	bithumb twap cancel	写入	取消活动中的 TWAP 订单

查询多笔订单： 用户一次要求查询两笔或更多订单时，使用 trade list --order-ids id1,id2 或 --client-order-ids id1,id2（MCP trade_get_orders 配合 order_ids/client_order_ids 数组）——单次调用即可（最多 100 个 ID；超过时分批，每批 100 个）。不要针对每个 ID 反复调用 trade get。服务默认使用 state=wait；若要包含已完成／已取消的订单，请添加 --states wait,done,cancel。watch 不能与 wait/done/cancel 混用（请使用 --state watch 单独查询）；--state/--states 不能同时使用。

完整参数说明请加载下方步骤 1 中的参考文件。

---

操作流程

步骤 0 — 凭证检查

在运行任何需要身份验证的命令前，请参阅上文的凭证检查。

🛑 强制预检清单 — trade place / batch-place / twap place

执行任何写入订单前，必须按顺序运行以下所有步骤。即使用户说“直接买”，也不得跳过。步骤 3 和步骤 4 之间必须停下并征求用户明确确认。

#	命令	用途
0	bithumb config show --json	只读检查（首先运行）。 读取当前生效配置的 read_only。如果为 true，立即停止，不要运行步骤 1–2。列出可写入的配置，并请用户使用 --profile <name> 重新运行（绝不绕过只读限制——不要自动选择配置、切换配置或自行禁用 read_only）。每个会话仅需检查一次：如果已检查过，则跳过。参阅 read-only-gate.md。
1	bithumb account order-chance --market <m>	确认可用余额、手续费率以及订单数量上下限
2	bithumb market ticker <m>	确认当前价格（与用户预期价格对比）
3	（批量下单时）向用户逐字读回 JSON 文件内容；（TWAP 时）计算切片数量 = duration/frequency，并对照步骤 1 中的最小订单数量进行检查
3b	对于每个 limit 订单，无论价格是计算得出、按百分比推算，还是用户直接指定（例如“以 123,456 买入”），都必须检查价格是否符合价格最小变动单位。 如果不符合，使用 order-commands.md 价格最小变动单位表四舍五入至最接近的有效价格，并在步骤 4 中同时显示原始值和调整后的值。仅当价格已符合最小变动单位时才可跳过。
4	🤚 停下。请用户确认：市场、方向、订单类型、价格、数量、名义金额
5	bithumb trade place --order-type ...（或 batch-place / twap place）	执行
6	bithumb trade get --order-id <id>（或 trade list、twap list）	验证状态

此流程也列于 bithumb-account 跨技能工作流。

步骤 1 — 确定订单类型并加载参考文档

用户意图	要加载的参考文档
单笔订单：下单、取消、查询	{baseDir}/references/order-commands.md
批量订单：下单或取消多个订单	{baseDir}/references/batch-commands.md
TWAP 订单：按时间加权执行	{baseDir}/references/twap-commands.md

步骤 2 — 确认写入参数

读取操作（trade get/list、twap list）：立即运行，无需确认。

写入操作（下单、取消、批量操作、TWAP）：先应用只读检查（本会话已检查过则跳过），然后一次性确认关键详情：

• 下单：--market、--side、--order-type（规范参数；--ord-type 是已弃用的别名）、--volume/--price
• 取消：--order-id 或 --client-order-id
• 批量下单 / 取消：批次中的所有订单 / 订单 ID
• TWAP 下单：--market、--side、--duration、--frequency、总金额

步骤 3 — 写入后验证

• trade place 后：运行 bithumb trade get --order-id <id> 确认状态
• trade cancel 后：运行 bithumb trade list 确认已取消
• batch-place 后：运行 bithumb trade list 确认所有订单
• twap place 后：运行 bithumb twap list 确认 TWAP 已激活

步骤 4 — 处理 order_not_found

当 trade cancel 或 batch-cancel 返回 order_not_found 时，务必通过直接的单笔查询 trade get --order-id <id> 确认状态，而不是使用 trade list 查询——trade list --state done/cancel --limit N 可能会因超出限制或未指定市场筛选条件而漏掉该订单。

单笔取消失败时，运行 bithumb trade get --order-id <id>：

• state: done → 用韩语告知用户："이미 체결된 주문입니다. 취소 불가합니다."
• state: cancel → 用韩语告知用户："이미 취소된 주문입니다."
• 查询本身失败（order_not_found）→ 执行 步骤 5（ID 路由回退）。

批量取消部分失败时，针对每个失败的 ID 运行 trade get --order-id <id>，或使用 bithumb trade list --order-ids id1,id2,... --states wait,done,cancel 一次查询这些 ID。

步骤 5 — order_id ↔ client_order_id 路由回退

Bithumb 的 client_order_id 有格式限制（1–36 个字符；只能使用字母、数字、连字符和下划线），但在此限制范围内，用户可以将其设置为与 Bithumb order_id 格式相同（C 前缀 + 数字，例如 C0101000000002157190）——order_id 使用相同的字符集。无法仅凭输入字符串区分这两个标识符，因此不要猜测。

对于单笔订单的 trade get 或 trade cancel：

1. 如果用户明确指定了 client-order-id → 立即使用 --client-order-id 执行。不进行回退。
2. 否则（用户只说“订单 ID”/“订单编号”，或单独提供一个 ID）：
   • **（第 1 次）**先使用 --order-id <value> 执行。
   • **（第 2 次）**如果没有结果（order_not_found / 404），使用相同的值重试，并改用 --client-order-id <value>。
   • **（两次都失败）**用韩语告知用户："이 ID가 현재 계정의 주문이 아니거나, 잘못된 ID이거나, client-order-id 형식이지만 등록되지 않은 값일 수 있습니다."
3. 如果第 2 次尝试匹配成功，在结果上方添加一行说明（用韩语）："client-order-id로 매칭됨"，让用户知道其输入实际是一个 client_order_id。

CLI 核心不会自动回退。 回退由本指南的 Agent 负责，需通过两次明确调用完成。直接使用 CLI 的用户如果传入 --order-id，命令会按原样执行，并原样返回 404。

---

边缘情况

• 订单类型：limit 需要 --price + --volume；price = 市价买入，--price 是要花费的韩元总额（无需数量）；market = 市价卖出，--volume 是币的数量（无需价格）。
• 方向：bid = 买入，ask = 卖出。
• 市场代码：KRW-BTC（报价币-基础币），不是 BTC-KRW。
• 批量限制：batch-place 最多 20 笔，batch-cancel 最多 30 笔。
• TWAP：持续时间为 300–43200 秒（5 分钟–12 小时）；执行频率只能是 15、20、30、60、120 秒之一。
• 客户端订单 ID：可选的 --client-order-id。限制（由服务端强制执行）：1–36 个字符；只能使用字母、数字、连字符（-）和下划线（_）。超出长度限制或包含其他字符时会返回 invalid_parameter；调用前请先向用户说明。
• 订单状态：wait（未完成）、watch（已预留）、done（已成交）、cancel（已取消）。
• 仅支持现货：不支持杠杆、保证金、期货或期权。

全局说明

• 查询订单（trade list / trade get）并向用户展示结果时，务必包含每笔订单的 order_id——用户之后需要用它查询或取消订单。
• 所有写入命令都需要有效的 API 凭据。Bithumb 没有演示模式——每笔订单都涉及真实资金，因此下单前务必核实详情。
• 在任何命令中添加 --json，即可获取原始 Bithumb API 响应。
• 使用 bithumb system audit（位于 bithumb-system 中）查看过往操作。