okx-cex-trade

OKX CEX 取引 CLI

OKX 取引所での現物、無期限スワップ、受渡先物、オプション、イベント契約の注文管理に対応しています。注文の発注、キャンセル、変更、監視のほか、オプションチェーンやグリークスの照会、二値結果型イベント契約（Yes/No、Up/Down）の取引、テイクプロフィット／ストップロスやトレーリングストップの設定、レバレッジやポジションの管理ができます。API 認証情報が必要です。

CLI と MCP ツール名の違い — サブコマンドにはハイフンではなくスペースを使います（okx swap algo place、okx bot grid create）。MCP ツール識別子（swap_place_algo_order）をハイフンでつないだ CLI コマンド（okx swap place-algo）に変換しないでください。「Unknown command」というエラーで拒否されます。モジュールごとの対応表は references/<module>-commands.md にあります。

実行前の確認

コマンドを実行する前に、../_shared/preflight.md の手順に従ってください。 ステップ 2 の参照値には、このファイルのフロントマターにある metadata.version を使用してください。

前提条件

1. okx CLI をインストールします：

   npm install -g @okx_ai/okx-trade-cli
   

2. 認証情報を設定します：

   okx config init   # select site -> follow browser OAuth flow
   

3. デモモード（実資金を使わないシミュレーション取引）でテストします：

   okx --demo spot orders
   

セキュリティ：チャットで認証情報を受け取らないでください。設定には okx config init を使うようユーザーに案内してください。

認証情報とプロファイルの確認

認証が必要なコマンドを実行する前に、この確認を行ってください。 認証方式は実行前の確認のステップ 2 で検出され、セッション中は保持されます。

ステップ A — 認証情報を確認する

両方のコマンドを実行してください。okx auth status --json の apiKey フィールドは認証バイナリの内部状態であり、~/.okx/config.toml に API キーのプロファイルがあるかどうかにかかわらず、常に false です。API キーの有無を確認する唯一の信頼できる情報源は okx config show --json です。

okx config show --json      # reveals API-key profiles (TOML config)
okx auth status --json      # reveals OAuth session state (auth-binary state)

次の順に適用し、最初に該当した項目を使用してください。

• config show --json に空でない api_key フィールドを持つプロファイルがある → API キーモード。ステップ B に進みます。
• API キーのプロファイルがなく、かつ auth status --json が "status":"logged_in" を返す → OAuth モード。ステップ B に進みます。
• API キーのプロファイルがなく、かつ "status":"pending" → ログイン処理中です。完了するまで待ちます。
• API キーのプロファイルがなく、かつ "status":"not_logged_in" → すべての操作を停止し、okx-cex-auth スキルを読み込んでログイン手順に従い、完了するまで待ちます。

ステップ B — 取引モードを確認する

選択ルール：

1. 現在のメッセージで意図が明確（例：「real」／「実盤」／「live」→ ライブ、「test」／「模拟」／「demo」→ デモ）→ そのモードを使用し、ユーザーに伝えます
2. 現在のメッセージに明示的な指定がない → 会話の文脈から以前の選択を確認します：
   • 見つかった → その選択を再利用し、ユーザーに伝えます
   • 見つからない → "Live (実盘) or Demo (模拟盘)?" と尋ね、回答があるまで待ちます

モードの適用方法は、認証方式（ステップ A で検出）によって異なります：

認証方式	ライブ（実盤）	デモ（模拟盘）
API キー	--profile <live-profile>	--profile <demo-profile>
OAuth	(フラグ不要。デフォルトはライブです)	--demo

• API キーを使う場合：okx config show --json を実行して、利用可能なプロファイル名と demo の設定を確認します。適切なプロファイルを選ぶには --profile <name> を使用してください。
• OAuth を使う場合：ライブ取引ではフラグを省略し、シミュレーション取引では --demo を追加します。モードの切り替えに --profile を使用しないでください。

認証エラーへの対処

認証エラー（エラーに「401」、「Session expired」、または「Run okx auth login first」が含まれる場合）：

1. 直ちに停止します。同じコマンドを再試行しないでください
2. ユーザーに「認証に失敗しました。セッションの有効期限が切れている可能性があります。」と伝えます
3. okx-cex-auth スキルを読み込んで、再認証の手順に従います
4. 再認証が成功したら、元のコマンドを再試行します

デモモードとライブモード

モード	資金	API キーパラメーター	OAuth パラメーター
実際の取引（ライブ）	実資金 — 取り消し不可	--profile <live-profile>	(デフォルト、フラグなし)
シミュレーション取引（デモ）	シミュレーション — 実資金なし	--profile <demo-profile>	--demo

ルール：

1. 認証が必要なコマンドでは、毎回取引モードを指定する必要があります — 「認証情報とプロファイルの確認」のステップ B で判定します
2. コマンド実行後のすべての応答に、[mode: live] または [mode: demo] を追加する必要があります

スキルのルーティング

• 市場データ（価格、チャート、板、資金調達率）には、okx-cex-market を使用します
• 口座残高、損益、ポジション、手数料、振替には、okx-cex-portfolio を使用します
• 通常の現物／スワップ／先物／オプション／アルゴ注文には、okx-cex-trade（このスキル）を使用します
• イベントコントラクトの閲覧／検索（取引可能なもの、件数、アクティブなものの一覧）には、okx-cex-trade と okx event browse ／ okx event series を使用します
• イベントコントラクトの取引（予測市場注文の発注／キャンセル／変更）には、okx-cex-trade と okx event place ／ okx event cancel ／ okx event amend を使用します
• グリッド取引や DCA 取引ボットには、okx-cex-bot を使用します

重要：イベントコントラクトや予測市場に関する文脈でユーザーが「コントラクト」について尋ねた場合は、このスキルにルーティングしてください。okx-cex-portfolio にはルーティングしないでください。Portfolio はイベントコントラクトを扱いません。対象は口座残高、ポジション、損益、振替のみです。

デリバティブの sz の扱い

⚠ 重要：注文前に必ずコントラクトの額面を確認してください

SWAP／FUTURES／OPTION の注文を発注する前に、market_get_instruments を呼び出して ctVal（コントラクトの額面）を取得してください。コントラクトサイズを推測しないでください。銘柄によって異なります（例：ETH-USDT-SWAP = 0.1 ETH／コントラクト、BTC-USDT-SWAP = 0.01 BTC／コントラクト）。

ctVal を使用して、以下を行います。

• ユーザーが意図するポジションサイズから、正しいコントラクト数を計算する
• 注文を送信する前に必要証拠金を確認する
• 実際のポジション価値 sz × ctVal × price をユーザーに示す

SWAP および FUTURES 注文

USDT 建ての数量指定に使える 3 つの tgtCcy モード：

--tgtCcy	sz の意味	換算式	例：「500U」、レバレッジ 10 倍
base_ccy（デフォルト）	コントラクト数	換算なし	500 コントラクト
quote_ccy	USDT 建ての想定元本	floor(sz / (ctVal * lastPx))	想定元本 500 USDT
margin	USDT 建ての証拠金額	floor(sz * lever / (ctVal * lastPx))	証拠金 500 USDT = 想定元本 5000 USDT

ユーザーが USDT の金額を指定した場合（例：「200U」、「500 USDT」、「$1000」）： → 曖昧です — 想定元本または証拠金額のどちらを意味するか判断できません。 続行する前に、必ずユーザーに確認してください。

• 想定元本：sz = USDT 建てのポジション価値（例：500 USDT で、想定元本が 500 USDT のコントラクトを直接購入）
• 証拠金額：実際のポジション = sz × レバレッジ（例：レバレッジ 10 倍で証拠金 500 USDT の場合、想定元本は 5000 USDT） 続行する前に、ユーザーの回答を待ってください。
• 想定元本の場合 → --tgtCcy quote_ccy を使用します
• 証拠金額の場合 → --tgtCcy margin を使用します

ユーザーがコントラクト数を指定した場合（例：「2 张」、「5 contracts」）： → まず market_get_instruments で ctVal を確認し、その後コントラクト数を --sz に指定します。ユーザーに「X コントラクト = 原資産の X × ctVal、合計価値 ≈ $Y」と確認してください。

ユーザーが単位のない数値のみを指定した場合（スワップ／先物）： → 曖昧です — 続行する前に、必ずユーザーに確認してください。

• コントラクト数：X コントラクト（各コントラクトの価値は原資産の ctVal）
• USDT 建ての想定元本：USDT 建てのポジション価値
• USDT 建ての証拠金額：証拠金額（実際のポジション = X × レバレッジ） 続行する前に、ユーザーの回答を待ってください。

⚠ インバースコントラクト（*-USD-SWAP、*-USD-YYMMDD）：tgtCcy=quote_ccy と tgtCcy=margin も使用できます（注：インバース銘柄では quote_ccy は USDT ではなく USD です）。必ず次のように注意を促してください：「これはインバースコントラクトです。証拠金と損益は USDT ではなく BTC で決済されます。」

オプション注文

ユーザーがオプションのUSDT金額を指定した場合は、--tgtCcy quote_ccy（想定元本）または--tgtCcy margin（証拠金コスト）を使用し、金額を--szとして渡します。システムが自動的にコントラクト数に換算します。注意：オプションのコントラクトは通常、額面金額が大きいため（例：ctVal=1 BTC ≈ $84,000）、1コントラクトの最小USDT金額は高額です。オプションの売り手（cross／isolated tdMode）の場合、marginモードではレバレッジが自動的に考慮されます。

クイックスタート

# Market buy 0.01 BTC (spot)
okx spot place --instId BTC-USDT --side buy --ordType market --sz 0.01

# Buy $10 worth of SOL (spot, USDT amount)
okx spot place --instId SOL-USDT --side buy --ordType market --sz 10 --tgtCcy quote_ccy

# Limit sell 0.01 BTC at $100,000 (spot)
okx spot place --instId BTC-USDT --side sell --ordType limit --sz 0.01 --px 100000

# Long 1 contract BTC perp (cross margin)
okx swap place --instId BTC-USDT-SWAP --side buy --ordType market --sz 1 \
  --tdMode cross --posSide long

# Long 1000 USDT notional value of BTC perp (auto-convert to contracts)
okx swap place --instId BTC-USDT-SWAP --side buy --ordType market --sz 1000 \
  --tgtCcy quote_ccy --tdMode cross --posSide long

# Long with 500 USDT margin at current leverage (e.g. 10x → 5000 USDT notional)
okx swap place --instId BTC-USDT-SWAP --side buy --ordType market --sz 500 \
  --tgtCcy margin --tdMode cross --posSide long

# Long 1 contract with attached TP/SL (one step)
okx swap place --instId BTC-USDT-SWAP --side buy --ordType market --sz 1 \
  --tdMode cross --posSide long \
  --tpTriggerPx 105000 --tpOrdPx=-1 --slTriggerPx 88000 --slOrdPx=-1

# Close BTC perp long position entirely at market
okx swap close --instId BTC-USDT-SWAP --mgnMode cross --posSide long

# Set 10x leverage on BTC perp (cross)
okx swap leverage --instId BTC-USDT-SWAP --lever 10 --mgnMode cross

# Set TP/SL on a spot BTC position
okx spot algo place --instId BTC-USDT --side sell --ordType oco --sz 0.01 \
  --tpTriggerPx 105000 --tpOrdPx=-1 \
  --slTriggerPx 88000 --slOrdPx=-1

# Place trailing stop on BTC perp long (callback 2%)
okx swap algo trail --instId BTC-USDT-SWAP --side sell --sz 1 \
  --tdMode cross --posSide long --callbackRatio 0.02

# View open spot orders
okx spot orders

# View open swap positions
okx swap positions

# Cancel a spot order
okx spot cancel --instId BTC-USDT --ordId <ordId>

# --- Event Contract ---
# List event series
okx event series

# Browse live markets in a series
okx event markets BTC-ABOVE-DAILY --state live

# Place event contract order
okx event place --instId BTC-ABOVE-DAILY-260224-1600-70000 --side buy --outcome YES --sz 10

コマンド一覧

現物注文（12コマンド）

#	コマンド	種類	説明
1	okx spot place	WRITE	現物注文を発注します（market/limit/post_only/fok/ioc）
2	okx spot cancel	WRITE	現物注文をキャンセルします
3	okx spot amend	WRITE	現物注文の価格またはサイズを変更します
4	okx spot algo place	WRITE	現物TP/SLアルゴ注文を発注します
5	okx spot algo amend	WRITE	現物TP/SLの価格を変更します
6	okx spot algo cancel	WRITE	現物アルゴ注文をキャンセルします
7	okx spot algo trail	WRITE	現物トレーリングストップ注文を発注します
8	okx spot orders	READ	現物の未約定注文または過去の注文を一覧表示します
9	okx spot get	READ	単一の現物注文の詳細を表示します
10	okx spot fills	READ	現物取引の約定履歴を表示します
11	okx spot algo orders	READ	現物TP/SLアルゴ注文を一覧表示します
12	okx spot leverage	WRITE	現物マージン取引（借入）用のレバレッジを設定します。ペア単位（--instId）または通貨単位のクロス（--ccy。借入有効化済み／複数通貨／ポートフォリオマージンでは必須）

コマンド構文、パラメータ表、例外ケースの詳細については、{baseDir}/references/spot-commands.mdを参照してください。

スワップ／パーペチュアル注文（15コマンド）

#	コマンド	種類	説明
13	okx swap place	WRITE	パーペチュアルスワップ注文を発注します
14	okx swap cancel	WRITE	スワップ注文をキャンセルします
15	okx swap amend	WRITE	スワップ注文の価格またはサイズを変更します
16	okx swap close	WRITE	成行でポジション全体を決済します
17	okx swap leverage	WRITE	銘柄のレバレッジを設定します
18	okx swap algo place	WRITE	スワップTP/SLアルゴ注文を発注します
19	okx swap algo trail	WRITE	スワップのトレーリングストップ注文を発注します
20	okx swap algo amend	WRITE	スワップアルゴ注文を変更します
21	okx swap algo cancel	WRITE	スワップアルゴ注文をキャンセルします
22	okx swap positions	READ	オープン中のパーペチュアルスワップポジションを表示します
23	okx swap orders	READ	スワップの未約定注文または過去の注文を一覧表示します
24	okx swap get	READ	単一のスワップ注文の詳細を表示します
25	okx swap fills	READ	スワップ取引の約定履歴を表示します
26	okx swap get-leverage	READ	現在のレバレッジ設定を表示します
27	okx swap algo orders	READ	スワップアルゴ注文を一覧表示します

コマンド構文、パラメータ表、例外ケースの詳細については、{baseDir}/references/swap-commands.mdを参照してください。

先物／受渡注文（15 コマンド）

#	Command	Type	Description
28	okx futures place	WRITE	受渡先物注文を発注
29	okx futures cancel	WRITE	受渡先物注文をキャンセル
30	okx futures amend	WRITE	受渡先物注文の価格または数量を変更
31	okx futures close	WRITE	先物ポジション全体を成行で決済
32	okx futures leverage	WRITE	先物銘柄のレバレッジを設定
33	okx futures algo place	WRITE	先物の TP/SL アルゴ注文を発注
34	okx futures algo trail	WRITE	先物のトレーリングストップ注文を発注
35	okx futures algo amend	WRITE	先物アルゴ注文を変更
36	okx futures algo cancel	WRITE	先物アルゴ注文をキャンセル
37	okx futures orders	READ	受渡先物注文を一覧表示
38	okx futures positions	READ	受渡先物のオープンポジション
39	okx futures fills	READ	受渡先物の約定履歴
40	okx futures get	READ	個別の受渡先物注文の詳細
41	okx futures get-leverage	READ	現在の先物レバレッジ設定
42	okx futures algo orders	READ	先物アルゴ注文を一覧表示

コマンド構文、パラメータ表、特殊ケースの詳細については、{baseDir}/references/futures-commands.md を参照してください。

オプション注文（10 コマンド）

#	Command	Type	Description
43	okx option instruments	READ	オプションチェーン：原資産に対して利用可能な契約を一覧表示
44	okx option greeks	READ	原資産別のインプライド・ボラティリティとグリークス（デルタ／ガンマ／セータ／ベガ）
45	okx option place	WRITE	オプション注文を発注（コールまたはプット、買いまたは売り）
46	okx option cancel	WRITE	未約定のオプション注文をキャンセル
47	okx option amend	WRITE	オプション注文の価格または数量を変更
48	okx option batch-cancel	WRITE	オプション注文を最大 20 件まとめてキャンセル
49	okx option orders	READ	オプション注文を一覧表示（ライブ／履歴／アーカイブ）
50	okx option get	READ	個別のオプション注文の詳細
51	okx option positions	READ	ライブのグリークス付きオープンオプションポジション
52	okx option fills	READ	オプション取引の約定履歴

コマンド構文、USDT から契約数への換算式、tdMode のルール、特殊ケースの詳細については、{baseDir}/references/options-commands.md を参照してください。

イベント契約注文（9 コマンド）

#	Command	Type	Description
53	okx event browse	READ	タイプ別に分類されたアクティブなイベント契約を閲覧（シリーズとライブ市場を 1 回の呼び出しで表示）
54	okx event series	READ	イベントシリーズを一覧表示（例：BTC-ABOVE-DAILY、BTC-UPDOWN-15MIN）
55	okx event events <seriesId>	READ	シリーズ内のイベントを一覧表示
56	okx event markets <seriesId>	READ	市場を一覧表示。期限切れのものには結果と決済値を含む
57	okx event place ...	WRITE	イベント注文を発注（結果の指定が必須）
58	okx event amend <instId> <ordId>	WRITE	イベント注文を変更（価格／数量）
59	okx event cancel <instId> <ordId>	WRITE	イベント注文をキャンセル
60	okx event orders	READ	保留中または過去の注文
61	okx event fills	READ	約定履歴

コマンド構文、パラメータ表、特殊ケースの詳細については、{baseDir}/references/event-commands.md を参照してください。

操作フロー

ステップ 0 — 認証情報とプロファイルの確認

認証が必要なコマンドを実行する前に、認証情報とプロファイルの確認 を参照してください。実行前に認証方法と取引モードを確認します。

各コマンドの結果の後に [mode: live] または [mode: demo] を追加します。

ステップ 1 — 銘柄タイプとアクションの特定

現物（instId の形式：BTC-USDT）：

• 注文の発注／キャンセル／変更 → okx spot place/cancel/amend
• TP/SL 条件付き注文 → okx spot algo place/amend/cancel
• トレーリングストップ → okx spot algo trail
• 照会 → okx spot orders/get/fills/algo orders スワップ/無期限契約（instId 形式: BTC-USDT-SWAP）:
• 注文の発注/キャンセル/修正 → okx swap place/cancel/amend
• ポジションの決済 → okx swap close
• レバレッジ → okx swap leverage / okx swap get-leverage
• TP/SL 条件注文 → okx swap algo place/amend/cancel
• トレーリングストップ → okx swap algo trail
• 照会 → okx swap positions/orders/get/fills/get-leverage/algo orders

先物/受渡（instId 形式: BTC-USDT-<YYMMDD>）:

• 注文の発注/キャンセル/修正 → okx futures place/cancel/amend
• ポジションの決済 → okx futures close
• レバレッジ → okx futures leverage / okx futures get-leverage
• TP/SL 条件注文 → okx futures algo place/amend/cancel
• トレーリングストップ → okx futures algo trail
• 照会 → okx futures orders/positions/fills/get/get-leverage/algo orders

オプション（instId 形式: BTC-USD-250328-95000-C または ...-P）:

• ステップ 1（必須）: 有効な instId を検索 → okx option instruments --uly BTC-USD
• ステップ 2（推奨）: IV と Greeks を確認 → okx option greeks --uly BTC-USD
• 発注/キャンセル/修正 → okx option place/cancel/amend
• 一括キャンセル → okx option batch-cancel --orders '[...]'
• 照会 → okx option orders/get/positions/fills
• tdMode: 買い手は cash、売り手は cross または isolated

イベントコントラクト:

銘柄 ID（instId、API フィールド）の形式: 「Price Above Target」/「One Touch」コントラクトの場合は {UNDERLYING}-{TYPE}-{YYMMDD}-{HHMM}-{STRIKE}（例: BTC-ABOVE-DAILY-260224-1600-70000）、「Price Direction (Up/Down)」コントラクトの場合は {UNDERLYING}-{TYPE}-{YYMMDD}-{START}-{END}（例: BTC-UPDOWN-15MIN-260224-1600-1615）。銘柄 ID は必ず okx event markets <seriesId> から取得してください — 推測したりプレースホルダーを使用したりしないでください。

シリーズ ID（seriesId、API フィールド）: 人間が読める形式（例: BTC-ABOVE-DAILY、BTC-UPDOWN-15MIN）または内部的なランダム文字列（例: FMQRZ）。どちらも以降のコマンドで有効です。okx event series から取得してください。

イベントコントラクトの取引フロー:

1. 検索 → okx event browse（推奨。1 回の呼び出しでシリーズとライブマーケットを返します）または okx event series — 結果をタイプ別にグループ化して提示し、名前付きシリーズを強調し、必ずシリーズ ID を表示します
2. ライブマーケットを閲覧 → okx event markets <seriesId> --state live — 取引可能な各コントラクトの銘柄 ID を取得します。ライブ価格が表示される場合、それはイベントコントラクトの価格（0.01〜0.99）であり、原資産の価格ではありません — 活発に取引されている際の市場が織り込む確率を反映します
3. イベントの詳細を確認 → okx event events <seriesId>
4. 確認 + 発注 → okx event place <instId> <side> <outcome> <sz> — ユーザーが明示的に確認した後にのみ実行します
5. 追跡 → okx event orders --status open / okx account positions --instType EVENTS
6. 決済または売却 → okx event place <instId> sell <outcome> <sz> で売却するか、--state expired を待ちます

エッジケース:

• 確定結果: okx event markets <seriesId> --state expired — 別途 ended ツールはありません

イベントコントラクトの sz ルール:

• 成行注文（ordType=market）: --sz はクォート通貨の金額です。
• 指値注文（ordType=limit / post_only）: --sz はコントラクト数（整数）です。各コントラクトはクォート通貨 1 単位で決済され、コントラクトあたりのコスト = px（イベントコントラクト価格、0.01〜0.99）です。例: px=0.5 で 10 コントラクトのコストは 5 です。
• px の意味: px はイベントコントラクトの価格（0.01〜0.99）であり、原資産の価格ではありません。活発に取引されている際は、市場が織り込む確率を反映します。例: px=0.6 は、市場がそのイベントをおよそ 60% と価格付けしていることを意味します。
• Outcome の表示: 期限切れ/結果のビューでは翻訳された値が表示されます。price_up_down の場合、YES/NO を UP/DOWN として扱ってください。

イベントコントラクトのワークフローとステップごとの例については、{baseDir}/references/event-workflows.md をお読みください。

スキル横断的なワークフローとステップごとの例については、{baseDir}/references/workflows.md をお読みください。

Step 2 — プロフィールを確認し、書き込みパラメーターを確認する

読み取りコマンド（注文、ポジション、約定、get、get-leverage、アルゴ注文）：すぐに実行します。

• --history フラグ：デフォルトでは有効／未決済のみです。ユーザーが履歴を明示的に求めた場合にのみ --history を使用します
• アルゴ注文の --ordType：conditional = TP または SL のどちらか一方、oco = TP と SL の両方をまとめて設定
• スワップ／先物の --tdMode：cross または isolated。現物では常に cash を使用します（自動設定）
• ヘッジモードの --posSide：long または short。ネットモードでは省略します

書き込みコマンド（注文、キャンセル、変更、決済、レバレッジ、アルゴ注文）：実行前に、注文の主要な詳細を一度確認します。

• 現物の注文：--instId、--side、--ordType、--sz（および建値通貨での金額の場合は --tgtCcy quote_ccy）を確認します
• スワップ／先物の注文：--instId、--side、--sz、--tdMode を確認します。さらに、ユーザーがUSDT金額を指定した場合は、注文モードを明示的に確認します。--tgtCcy quote_ccy（想定元本。sz = ポジション価値）または --tgtCcy margin（証拠金コスト。実際のポジション = sz * レバレッジ）のどちらを使うかを確認してください。使用するモードを必ず伝えます。
• オプションの注文：--instId、--side、--sz、--tdMode を確認します（USDT金額の場合は --tgtCcy quote_ccy または --tgtCcy margin も確認します。システムが自動換算します）。TP/SLは設定しないでください
• イベントコントラクトの注文：--instId、--side、--outcome、--sz、--ordType を確認します。成行注文ではszは建値通貨での金額、指値注文ではszはコントラクト数で、--px が必須です
• スワップ／先物の決済：--instId、--mgnMode、--posSide を確認します
• レバレッジ：新しいレバレッジと、既存ポジションへの影響を確認します。よくある400エラーを避けるための事前チェック：（a）--lever は正の数値で、銘柄の最大値以内である必要があります（okx market instruments → lever を参照）。（b）ヘッジポジションモードで --mgnMode isolated の場合、--posSide が必須です。各サイド（long、short）を個別に設定する必要があり、一方を設定してももう一方には自動適用されません。（c）ポートフォリオマージン口座では、SWAP/FUTURES の cross レバレッジを調整できません。OKXに拒否されます。不明な場合は、まず okx account config を実行して acctLv を確認してください。レバレッジ設定に失敗した場合（エラーに「cancel orders or stop bots」と記載されている場合）：次の優先順位でトラブルシューティングします。（1）まず保留中のアルゴ注文を照会します（swap/futures algo-orders --status pending）。これが最も一般的なブロッカーです。（2）アルゴ注文がない場合に限り、稼働中のボットを確認します（bot grid-orders）。注文を自動的にキャンセルしたり、ボットを停止したりしないでください。調査結果を提示し、ユーザーの判断に委ねます
• アルゴ注文（TP/SL）：トリガー価格を確認します。成行執行には --tpOrdPx=-1 を使用します
• アルゴトレール：--callbackRatio（例：0.02 = 2%）または --callbackSpread を確認します

各コマンドの全パラメーターの詳細については、該当するリファレンスファイルを参照してください。

エラーによって提案された修正の安全措置

OKX API のエラーメッセージが、書き込み操作（注文のキャンセル、ポジションの決済、ボット／戦略の停止、資金の移動など）を伴う修正を提案している場合、その操作を自動的に実行してはなりません。代わりに、次の手順に従ってください。

1. エラーとその提案を、ユーザーにそのまま報告します
2. 診断します — 読み取り専用のクエリを実行し、何が妨げになっているかを特定します（例：algo-orders --status pending、positions、bot grid-orders --status active）
3. 調査結果を提示します — 見つかった内容と、キャンセル／決済／停止が必要になる具体的な項目をユーザーに示します
4. 修正を実行する前に、ユーザーからの明示的な確認を待ちます

これは、次のものを含む、破壊的な操作を提案するメッセージを含むすべてのエラーコードに適用されます。

• 未決済のアルゴ注文または稼働中のボットによってレバレッジの設定がブロックされている場合
• 注文／ポジション／戦略の整理が必要なアカウント設定の変更（例：エラーコード 59000、59002、59007）
• ポジションの決済が必要な証拠金モードの切り替え
• 「cancel」、「close」、「stop」、「transfer … before」などの語句を含むエラー

理由： エラーメッセージには、考えられるすべての妨げが一般的な形で列挙されています。実際の妨げは、多くの場合 1 つの項目（例：単一の TP/SL 注文）にすぎません。エラー文に盲目的に従うと、ユーザーが意図していないポジションの決済やボットの停止につながるおそれがあります。

ステップ 3 — 書き込み後の確認

• spot place の後：okx spot orders を実行して注文が有効か確認するか、成行注文の場合は okx spot fills を実行します
• swap place の後：okx swap orders または okx swap positions を実行して確認します
• swap close の後：okx swap positions を実行してポジションサイズが 0 であることを確認します
• futures place の後：okx futures orders または okx futures positions を実行して確認します
• futures close の後：okx futures positions を実行してポジションサイズが 0 であることを確認します
• spot の algo place/trail の後：okx spot algo orders を実行して algo が有効であることを確認します
• swap の algo place/trail の後：okx swap algo orders を実行して algo が有効であることを確認します
• futures の algo place/trail の後：okx futures algo orders を実行して algo が有効であることを確認します
• キャンセルの後：okx spot orders / okx swap orders / okx futures orders / okx event orders を実行して注文がなくなったことを確認します
• event place の後：okx event orders --status open を実行して注文が保留中であることを確認します
• event cancel の後：okx event orders を実行して注文がなくなったことを確認します

全般的な注意事項

• すべての書き込みコマンドには有効な認証情報（OAuth セッション、または ~/.okx/config.toml 内の API キー）が必要です
• 認証方式と取引モードは「Credential & Profile Check」で判定されます。パラメーターのルールについては、そのセクションを参照してください
• --json はデフォルトで OKX API v5 の生のレスポンスを返します。出力を {"env": "<live|demo>", "profile": "<name>", "data": <response>} でラップするには --env を追加します。有効な環境と認証情報プロファイルを確認する必要がある場合に便利です
• レート制限：UID ごとに 2 秒あたり 60 件の注文操作
• 必要に応じて、バッチ操作（バッチキャンセル、バッチ変更）は MCP ツールから直接利用できます
• ポジションモード（net と long_short_mode）によって、--posSide が必要かどうかが変わります
• ネットワークエラー：コマンドが接続エラーで失敗した場合は、VPN の確認をユーザーに促します：curl -I https://www.okx.com
• 機能の確認：okx list-tools --json を実行すると、すべての CLI コマンド、ツール名、パラメーターを機械可読な JSON 形式で取得できます。--help のテキストを解析せずに、プログラムから列挙する場合に便利です

MCP ツールのリファレンス、出力規約、注文数量の安全ルールについては、{baseDir}/references/templates.md を参照してください。