Back to Details

bithumb-trade

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Bithumb CEX Trading CLI

Bithumb CEX 交易CLI

Place, cancel, and monitor single or batch spot orders; run TWAP (Time-Weighted Average Price) orders for large positions. Requires API credentials. All orders are real funds — Bithumb has no demo/simulated mode.
下单、取消及监控单笔或批量现货订单；针对大额仓位执行TWAP（时间加权平均价格）订单。需要API凭证。所有订单均使用真实资金——Bithumb无演示/模拟模式。

Tool Routing

工具路由

Writes are CLI-first: prefer the documented 
bithumb ...
CLI; fall back to MCP only when the CLI is unavailable/fails or the user asks for MCP. The CLI carries safety mechanisms MCP lacks (per-profile read-only gating, account isolation, terminal reproducibility). Read-only queries: either path is fine.
写入操作优先使用CLI：优先使用文档中记录的
bithumb ...
CLI；仅当CLI不可用/失败或用户要求使用MCP时，才退而使用MCP。CLI具备MCP所没有的安全机制（基于配置文件的只读限制、账户隔离、终端可复现性）。只读查询：两种方式均可。

Prerequisites

前置条件

  • Install: 
    npm install -g @bithumb-official/bithumb-cli
  • Credentials: 
    BITHUMB_ACCESS_KEY
    / 
    BITHUMB_SECRET_KEY
    env vars, or 
    ~/.bithumb/config.toml
    .
  • 安装：
    npm install -g @bithumb-official/bithumb-cli
  • 凭证：设置环境变量
    BITHUMB_ACCESS_KEY
    / 
    BITHUMB_SECRET_KEY
    ，或配置文件
    ~/.bithumb/config.toml
    。

Skill Routing

技能路由

Market data → 
bithumb-market
; assets/wallet/API keys → 
bithumb-account
; deposits → 
bithumb-deposit
; withdrawals → 
bithumb-withdraw
; audit logs/diagnostics → 
bithumb-system
; orders → this skill.
市场数据 → 
bithumb-market
；资产/钱包/API密钥 → 
bithumb-account
；充值 → 
bithumb-deposit
；提现 → 
bithumb-withdraw
；审计日志/诊断 → 
bithumb-system
；订单操作 → 本技能。

Credential Check (before any authenticated command)

凭证检查（执行任何认证命令前）

  1. Run 
    bithumb system diagnose
    . If it fails, STOP — do not retry. Inform the user (in Korean): 
    "인증 실패. API 키가 유효하지 않거나 만료되었을 수 있습니다."
    and guide them to set 
    BITHUMB_ACCESS_KEY
    /
    BITHUMB_SECRET_KEY
    or check 
    ~/.bithumb/config.toml
    . Re-run 
    bithumb system diagnose
    after they update, then retry the original operation.
  2. If OK, verify trading permissions for the target market with 
    bithumb account order-chance --market <m>
    (also confirms balance, fee rates, order limits).
  1. 运行
    bithumb system diagnose
    。如果失败，立即停止——不要重试。用韩语告知用户：
    "인증 실패. API 키가 유효하지 않거나 만료되었을 수 있습니다."
    并引导他们设置
    BITHUMB_ACCESS_KEY
    /
    BITHUMB_SECRET_KEY
    或检查
    ~/.bithumb/config.toml
    。用户更新后重新运行
    bithumb system diagnose
    ，然后重试原操作。
  2. 如果检查通过，使用
    bithumb account order-chance --market <m>
    验证目标市场的交易权限（同时确认余额、手续费率、订单限额）。

Command Index

命令索引

#CommandTypeDescription
1
bithumb trade place
WRITEPlace spot order (limit / price / market)
2
bithumb trade cancel
WRITECancel order by order-id or client-order-id
3
bithumb trade get
READGet a SINGLE order by one order-id / client-order-id
4
bithumb trade list
READQuery MULTIPLE orders or list by filters
5
bithumb trade batch-place
WRITEPlace multiple orders at once (max 20)
6
bithumb trade batch-cancel
WRITECancel multiple orders at once (max 30)
7
bithumb twap place
WRITEPlace TWAP order (time-weighted execution)
8
bithumb twap list
READGet TWAP order history
9
bithumb twap cancel
WRITECancel active TWAP order
Querying multiple orders: When the user asks for two or more order numbers at once, use 
trade list --order-ids id1,id2
or 
--client-order-ids id1,id2
(MCP 
trade_get_orders
with the 
order_ids
/
client_order_ids
array) — a single call (up to 100 ids; for more, split into batches of 100). Do NOT call 
trade get
repeatedly per id. The server defaults to 
state=wait
; to include done/cancelled add 
--states wait,done,cancel
. 
watch
cannot be mixed with 
wait
/
done
/
cancel
(query separately with 
--state watch
); 
--state
/
--states
cannot be used together.
For full parameter details load the reference files in Step 1 below.
#命令类型描述
1
bithumb trade place
写入创建现货订单（限价/定价/市价）
2
bithumb trade cancel
写入通过order-id或client-order-id取消订单
3
bithumb trade get
读取通过单个order-id/client-order-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一批次。请勿针对每个ID重复调用
trade get
。服务器默认
state=wait
；如需包含已完成/已取消订单，添加
--states wait,done,cancel
。
watch
状态不能与
wait
/
done
/
cancel
混合查询（需单独使用
--state watch
查询）；
--state
/
--states
不能同时使用。
如需完整参数详情，请加载下方步骤1中的参考文件。

Operation Flow

操作流程

Step 0 — Credential Check

步骤0 — 凭证检查

See Credential Check above before any authenticated command.

🛑 Mandatory Pre-flight Checklist — 
trade place
/ 
batch-place
/ 
twap place

Before any write order, run all of the following in order. Do not skip even if the user says "just buy it". Stop and ask for explicit user confirmation between step 3 and step 4.
#CommandPurpose
0
bithumb config show --json
Read-only gate (run first). Read the effective profile's 
read_only
. If 
true
, stop here — do not run steps 1–2. List write-capable profiles and ask the user to re-run with 
--profile <name>
(never bypass read-only — do not auto-select a profile, switch profiles, or disable 
read_only
yourself). Once-per-session: skip if already checked. See read-only-gate.md.
1
bithumb account order-chance --market <m>
Confirm available balance, fee rate, min/max order size
2
bithumb market ticker <m>
Confirm current price (vs. user's intended price)
3(for batch) read the JSON file aloud back to the user; (for TWAP) compute slice count = 
duration/frequency
and check against minimum order size from step 1
3bFor every 
limit
order, check the price against the price tick — regardless of whether it was calculated, derived by percentage, or stated directly by the user (e.g. "buy at 123,456"). If not tick-aligned, round to the nearest valid tick using the order-commands.md price tick table, and display both original and adjusted values in step 4. Skip only when already tick-aligned.
4🤚 Stop. Ask user to confirm: market, side, order_type, price, volume, total notional
5
bithumb trade place --order-type ...
(or 
batch-place
/ 
twap place
)		Execute
6
bithumb trade get --order-id <id>
(or 
trade list
, 
twap list
)		Verify state
Mirrored in bithumb-account Cross-Skill Workflows.
执行任何认证命令前，请先参考上方的凭证检查部分。

🛑 强制前置检查清单 — 
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跨技能工作流中有镜像说明。

Step 1 — Identify order type and load reference

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

User intentReference to load
Single order: place, cancel, query
{baseDir}/references/order-commands.md
Batch orders: place or cancel multiple
{baseDir}/references/batch-commands.md
TWAP orders: time-weighted execution
{baseDir}/references/twap-commands.md
用户意图需加载的参考文件
单笔订单：创建、取消、查询
{baseDir}/references/order-commands.md
批量订单：创建或取消多笔订单
{baseDir}/references/batch-commands.md
TWAP订单：时间加权执行
{baseDir}/references/twap-commands.md

Step 2 — Confirm write parameters

步骤2 — 确认写入参数

Reads (
trade get
/
list
, 
twap list
): run immediately, no confirmation.
Writes (place, cancel, batch, TWAP): first apply the read-only gate (skip if already checked this session), then confirm key details once:
  • Place: 
    --market
    , 
    --side
    , 
    --order-type
    (canonical; 
    --ord-type
    is a deprecated alias), 
    --volume
    /
    --price
  • Cancel: 
    --order-id
    or 
    --client-order-id
  • Batch place / cancel: all orders / order IDs in the batch
  • TWAP place: 
    --market
    , 
    --side
    , 
    --duration
    , 
    --frequency
    , total amount
读取操作（
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
    、总金额

Step 3 — Verify after writes

步骤3 — 写入操作后验证

  • After 
    trade place
    : 
    bithumb trade get --order-id <id>
    to confirm status
  • After 
    trade cancel
    : 
    bithumb trade list
    to confirm cancellation
  • After 
    batch-place
    : 
    bithumb trade list
    to confirm all orders
  • After 
    twap place
    : 
    bithumb twap list
    to confirm TWAP is active
  • 执行
    trade place
    后：运行
    bithumb trade get --order-id <id>
    确认状态
  • 执行
    trade cancel
    后：运行
    bithumb trade list
    确认已取消
  • 执行
    batch-place
    后：运行
    bithumb trade list
    确认所有订单状态
  • 执行
    twap place
    后：运行
    bithumb twap list
    确认TWAP订单已激活

Step 4 — Handling 
order_not_found

步骤4 — 处理
order_not_found
错误

When 
trade cancel
or 
batch-cancel
returns 
order_not_found
, always confirm state with a direct single lookup 
trade get --order-id <id>
, not a 
trade list
query — 
trade list --state done/cancel --limit N
can miss the order by exceeding the limit or omitting the market filter.
On a failed single cancel, run 
bithumb trade get --order-id <id>
:
  • state: done
    → tell the user (in Korean): 
    "이미 체결된 주문입니다. 취소 불가합니다."
  • state: cancel
    → tell the user (in Korean): 
    "이미 취소된 주문입니다."
  • lookup itself fails (
    order_not_found
    ) → apply Step 5 (ID routing fallback).
On partial batch-cancel failures, run 
trade get --order-id <id>
per failed id, or look them up together with 
bithumb trade list --order-ids id1,id2,... --states wait,done,cancel
.
当
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
批量查询。

Step 5 — 
order_id
↔ 
client_order_id
routing fallback

步骤5 — 
order_id
↔ 
client_order_id
路由回退

A Bithumb 
client_order_id
has a format constraint (1–36 chars; letters, digits, hyphens, underscores only), but within that constraint a user can make one identical to a Bithumb 
order_id
pattern (
C
prefix + digits, e.g. 
C0101000000002157190
) — 
order_id
uses the same character set. You cannot tell the two identifiers apart from the input string alone, so do not guess.
For single-order 
trade get
or 
trade cancel
:
  1. If the user explicitly names a 
    client-order-id
    → run with 
    --client-order-id
    immediately. No fallback.
  2. Otherwise (user just says "order ID" / "order number", or gives an id alone):
    • (1st) run with 
      --order-id <value>
      first.
    • (2nd) if no result (
      order_not_found
      / 404), retry the same value with 
      --client-order-id <value>
      .
    • (both fail) tell the user (in Korean): 
      "이 ID가 현재 계정의 주문이 아니거나, 잘못된 ID이거나, client-order-id 형식이지만 등록되지 않은 값일 수 있습니다."
  3. If the 2nd attempt matches, add a one-line note above the result (in Korean): 
    "client-order-id로 매칭됨"
    , so the user knows their input was actually a client_order_id.
The CLI core does not auto-fallback. The fallback is this guide's (the agent's) responsibility, done as two explicit calls. A direct CLI user who passes 
--order-id
runs as-is and gets the 404 verbatim.
Bithumb的
client_order_id
有格式限制（1–36字符；仅允许字母、数字、连字符、下划线），但用户可以设置与Bithumb
order_id
格式相同的
client_order_id
（以
C
开头+数字，例如
C0101000000002157190
）——
order_id
使用相同字符集。无法仅通过输入字符串区分这两种标识符，因此请勿猜测。
针对单笔订单的
trade get
或
trade cancel
操作：
  1. 如果用户明确指定为
    client-order-id
    → 立即使用
    --client-order-id
    参数执行。无回退逻辑。
  2. 其他情况（用户仅说“订单ID”/“订单号”，或仅提供一个ID）：
    • （第一次尝试） 首先使用
      --order-id <value>
      执行。
    • （第二次尝试） 如果无结果（
      order_not_found
      / 404），使用同一值以
      --client-order-id <value>
      重试。
    • （两次均失败） 用韩语告知用户：
      "이 ID가 현재 계정의 주문이 아니거나, 잘못된 ID이거나, client-order-id 형식이지만 등록되지 않은 값일 수 있습니다."
  3. 如果第二次尝试匹配成功，在结果上方添加一行韩语说明：
    "client-order-id로 매칭됨"
    ，让用户知道他们输入的实际上是client_order_id。
CLI核心不支持自动回退。 回退逻辑是本指南（Agent）的责任，需通过两次显式调用实现。直接使用CLI的用户如果传入
--order-id
参数，将按原参数执行并直接返回404错误。

Edge Cases

边缘情况

  • Order types: 
    limit
    requires 
    --price
    + 
    --volume
    ; 
    price
    = market buy, 
    --price
    is the total KRW to spend (no volume); 
    market
    = market sell, 
    --volume
    is the coin quantity (no price).
  • Side: 
    bid
    = buy, 
    ask
    = sell.
  • Market code: 
    KRW-BTC
    (quote-base), not 
    BTC-KRW
    .
  • Batch limits: max 20 per 
    batch-place
    , max 30 per 
    batch-cancel
    .
  • TWAP: duration 300–43200 s (5 min–12 h); frequency one of 
    15
    , 
    20
    , 
    30
    , 
    60
    , 
    120
    s.
  • Client order ID: optional 
    --client-order-id
    . Constraint (server-enforced): 1–36 chars; letters, digits, hyphens (
    -
    ), underscores (
    _
    ) only    . Over-length or other characters → 
    invalid_parameter
    ; surface this before calling.
  • Order states: 
    wait
    (open), 
    watch
    (reserved), 
    done
    (filled), 
    cancel
    (cancelled).
  • Spot-only: no leverage, margin, futures, or options.
  • 订单类型：
    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
    （已取消）。
  • 仅支持现货：不支持杠杆、保证金、期货或期权。

Global Notes

全局说明

  • When you query orders (
    trade list
    / 
    trade get
    ) and present the result to the user, always include each order's 
    order_id
    — they need it to look up or cancel the order later.
  • All write commands require valid API credentials. Bithumb has no demo mode — every order is real funds, so always verify details before placing.
  • Add 
    --json
    to any command for the raw Bithumb API response.
  • Review past operations with 
    bithumb system audit
    (in 
    bithumb-system
    ).
  • 当您查询订单（
    trade list
    / 
    trade get
    ）并向用户展示结果时，务必包含每个订单的
    order_id
    ——用户后续需要用它来查询或取消订单。
  • 所有写入命令都需要有效的API凭证。Bithumb无演示模式——所有订单均使用真实资金，因此创建订单前务必验证所有细节。
  • 在任何命令后添加
    --json
    参数可获取Bithumb API的原始响应。
  • 使用
    bithumb system audit
    （属于
    bithumb-system
    技能）查看过往操作记录。