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	WRITE	現物注文を発注（指値／価格指定／成行）
2	bithumb trade cancel	WRITE	注文 ID またはクライアント注文 ID で注文をキャンセル
3	bithumb trade get	READ	1 つの注文 ID またはクライアント注文 ID を指定して、単一の注文を取得
4	bithumb trade list	READ	複数の注文を照会、またはフィルターで一覧表示
5	bithumb trade batch-place	WRITE	複数の注文を一度に発注（最大 20 件）
6	bithumb trade batch-cancel	WRITE	複数の注文を一度にキャンセル（最大 30 件）
7	bithumb twap place	WRITE	TWAP 注文を発注（時間加重で執行）
8	bithumb twap list	READ	TWAP 注文履歴を取得
9	bithumb twap cancel	WRITE	有効な TWAP 注文をキャンセル

複数注文の照会： ユーザーが一度に 2 つ以上の注文番号を求めた場合は、trade list --order-ids id1,id2 または --client-order-ids id1,id2（MCP では order_ids／client_order_ids 配列を指定した trade_get_orders）を使用してください。1 回の呼び出しで最大 100 件まで指定できます。それを超える場合は、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 を無効にしたりしないでください）。セッションごとに 1 回実行します。すでに確認済みの場合は省略してください。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 Cross-Skill Workflowsにも記載されています。

ステップ 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 list クエリではなく、trade get --order-id <id> による単一注文の直接照会で状態を確認してください — 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 でまとめて照会します。

ステップ 5 — order_id ↔ client_order_id のルーティングフォールバック

Bithumb の client_order_id には**形式の制約（1～36 文字。英字、数字、ハイフン、アンダースコアのみ）**がありますが、この制約の範囲内で、ユーザーは Bithumb の order_id のパターン（C で始まり、その後に数字が続く形式。例：C0101000000002157190）と同じ値を設定できます — order_id も同じ文字種を使います。入力文字列だけではどちらの 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 回目の試行で一致した場合は、結果の上に韓国語で 1 行の注記を追加します：「client-order-id로 매칭됨」。これにより、入力された値が実際には client_order_id だったことがユーザーに伝わります。

CLI コアは自動でフォールバックしません。 フォールバックはこのガイドにおけるエージェントの責任であり、明示的な呼び出しを 2 回行って処理します。--order-id を渡した CLI の直接利用では、そのまま実行され、404 がそのまま返されます。

---

エッジケース

• 注文タイプ：limit には --price と --volume が必要です。price は成行買いで、--price は支出する KRW の合計額です（数量は不要）。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 内）で確認できます。