okx-cex-portfolio

OKX CEX ポートフォリオ＆アカウント CLI

OKX 取引所での口座残高、ポジション、損益、請求履歴、手数料、資金移動を扱います。API 認証情報が必要です。

事前確認

コマンドを実行する前に、../_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 account balance
   

セキュリティ：チャットで認証情報を受け取ることは絶対に避けてください。設定には okx config init を使用するよう案内してください。

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

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

手順 A — 認証情報を確認する

両方の情報源を確認してください（判定表は事前確認の手順 2を参照）。okx auth status --json だけでは不十分です。apiKey フィールドは常に false で、TOML 設定を反映しません。

okx config show --json      # authoritative for API-key presence
okx auth status --json      # authoritative for OAuth session state

次の順序で判定し、最初に一致したものを適用してください。

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

手順 B — 取引モードを確認する

決定ルール：

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

モードの適用方法は、認証方法（手順 A で検出）によって異なります。

認証方法	ライブ（実盤）	デモ（シミュレーション取引）
API Key	--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

# API Key user
okx --profile okx-prod  account balance     # 实盘
okx --profile okx-demo  account balance     # 模拟盘

# OAuth user
okx account balance                          # 实盘 (default)
okx --demo account balance                   # 模拟盘

ルール：

• 読み取りコマンド（残高、ポジション、請求履歴など）：使用したモードを必ず明記する
• 書き込みコマンド（transfer、set-position-mode）：実行前にモードを必ず確認する（「認証情報とプロファイルの確認」の手順 B を参照）。特に資金移動では、モードを間違えると別の口座を操作することになります。
• コマンド実行後のすべての応答に、[mode: live] または [mode: demo] を付記する

スキルの振り分け

• 市場データ（価格、チャート、板、資金調達率）には okx-cex-market を使用
• 口座残高、損益、ポジション、手数料、資金移動には okx-cex-portfolio（このスキル）を使用
• 通常の現物／スワップ／先物／アルゴ注文には okx-cex-trade を使用
• グリッド取引および DCA 取引ボットには okx-cex-bot を使用

クイックスタート

# One-shot full asset snapshot (recommended first command)
okx account balance-all
okx account balance-all --no-valuation
okx account balance-all --valuationCcy BTC

# Trading account balance (all currencies with balance > 0)
okx account balance

# Check USDT balance only
okx account balance USDT

# Funding account balance
okx account asset-balance

# All open positions, every product
okx account positions

# Positions for one product only — always narrow when the user named a product
okx account positions --instType SWAP     # SWAP | FUTURES | OPTION | MARGIN | EVENTS

# Closed position history with realized PnL
okx account positions-history

# Recent account bills (last 100)
okx account bills

# My trading fee tier
okx account fees --instType SPOT

# Transfer 100 USDT from funding (6) to trading (18)
okx account transfer --ccy USDT --amt 100 --from 6 --to 18

コマンド一覧

読み取りコマンド

#	コマンド	タイプ	説明
1	okx account balance-all [ccy]	READ	取引＋資金調達（＋評価額）を1回の呼び出しで取得する一括スナップショット
2	okx account balance [ccy]	READ	取引口座のエクイティ、利用可能額、凍結額
3a	okx account asset-balance [ccy]	READ	資金調達口座の残高（通貨別一覧）
3b	okx account asset-balance [ccy] --valuation [--valuationCcy <ccy>]	READ	同じ情報に加え、取引／資金調達／Earn全体の資産評価額。評価通貨のデフォルトはUSDTです。--valuationCcy BTCで変更できます
4	okx account positions [--instType <type>] [--instId <id>]	READ	未決済のコントラクト／スワップポジション。ユーザーが商品を指定した場合（「自分のスワップポジション」「先物ポジション」「オプションポジション」など）は、--instType <type>（SWAP | FUTURES | OPTION | MARGIN | EVENTS）を指定するか、その商品の専用コマンド（okx swap positions、okx futures positions、okx option positions）を使用してください。ユーザーが本当にすべてのポジションを求めている場合に限り、フィルターを省略します。フィルターなしの一覧は大きくなり、商品ごとの絞り込みをモデルに任せることになるため、誤りが起こりやすくなります
5	okx account positions-history	READ	決済済みポジション＋実現損益
6	okx account bills	READ	口座の取引明細（入金、出金、取引）
7	okx account fees --instType <type>	READ	自分の取引手数料ランク（メイカー／テイカー）
8	okx account config	READ	口座レベル、ポジションモード、UID
9	okx account max-size --instId <id> --tdMode <mode>	READ	現在価格での最大買付／売却数量
10	okx account max-avail-size --instId <id> --tdMode <mode>	READ	次の注文に利用できる数量
11	okx account max-withdrawal [ccy]	READ	通貨ごとの最大出金可能額

書き込みコマンド

#	コマンド	タイプ	説明
12	okx account set-position-mode <mode>	WRITE	ネット／ヘッジのポジションモードを切り替えます
13	okx account transfer	WRITE	口座間で資金を振り替えます

スキル横断ワークフロー

取引前の残高確認

ユーザー：「0.1 BTCを買いたいのですが、USDTは足りますか？」

1. okx-cex-portfolio okx account balance-all                 → one-shot trading + funding + valuation snapshot
   → check trading.details (available in trading account)
   → if trading balance < needed: check funding.details — may need to transfer
2. okx-cex-market    okx market ticker BTC-USDT              → check current price
        ↓ user approves
3. okx-cex-trade     okx spot place --instId BTC-USDT --side buy --ordType market --sz 0.1

ボット開始前の残高確認

ユーザー：「1000 USDTでBTCグリッドボットを始めたいです」

1. okx-cex-portfolio okx account balance-all                 → one-shot trading + funding + valuation snapshot
   → check trading.details ≥ 1000 (funds must be in trading account for grid bot)
   → if funding.details has the USDT instead: use account transfer first
2. okx-cex-market    okx market candles BTC-USDT --bar 4H --limit 50  → determine price range
        ↓ user approves
3. okx-cex-bot       okx bot grid create --instId BTC-USDT --algoOrdType grid \
                       --minPx 90000 --maxPx 100000 --gridNum 10 --quoteSz 1000

純資産の簡易確認

ユーザー：「総残高はいくらですか？」／「总资产多少?」

1. okx-cex-portfolio okx account balance-all                 → returns {trading, funding, valuation, meta}
   → valuation.totalBal = total net worth in USDT
   → trading.totalEq = trading account equity
   → funding.details = per-currency funding balances
   → meta.partialFailure = true if any section failed (still returns available data)

未決済ポジションと損益を確認する

ユーザー：「現在のポジションと、その損益状況を見せてください」

1. okx-cex-portfolio okx account positions                  → open positions with UPL
2. okx-cex-portfolio okx account positions-history          → recently closed positions
3. okx-cex-market    okx market ticker BTC-USDT-SWAP        → check current price vs entry

振替して取引する

ユーザー：「資金調達口座から500 USDTを移して、BTCを取引したいです」

1. okx-cex-portfolio okx account asset-balance USDT         → confirm funding balance ≥ 500
        ↓ user approves
2. okx-cex-portfolio okx account transfer --ccy USDT --amt 500 --from 6 --to 18
3. okx-cex-portfolio okx account balance USDT               → confirm trading balance updated
        ↓ ready to trade
4. okx-cex-trade     okx spot place ...

注文前に最大ポジションサイズを確認する

ユーザー：「クロスマージンでBTCをいくら買えますか？」

1. okx-cex-portfolio okx account balance                    → total equity
2. okx-cex-portfolio okx account max-size --instId BTC-USDT-SWAP --tdMode cross  → max buy/sell size
3. okx-cex-market    okx market ticker BTC-USDT-SWAP        → current price reference

操作フロー

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

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

各コマンドの結果の後に必ず： 応答に[mode: live]または[mode: demo]を付加します

ステップ1：口座操作を特定する

• すべての残高を一度に確認 → okx account balance-all（取引＋資金調達＋評価額を1回の呼び出しで取得。「总资产 / net worth / all balances」にはこちらを推奨）
• 残高を確認 → okx account balance（取引エクイティのみ）、okx account asset-balance（資金調達口座の残高）、またはokx account asset-balance --valuation（すべての口座の合計をUSDTで表示）
• 未決済ポジションを表示 → okx account positions
• 決済済みポジション＋損益を表示 → okx account positions-history
• 取引履歴を表示 → okx account bills
• 手数料ランクを確認 → okx account fees
• 口座設定を確認 → okx account config
• 注文サイズを計算 → okx account max-sizeまたはokx account max-avail-size
• 出金限度額を確認 → okx account max-withdrawal
• 資金を振り替え → okx account transfer
• ポジションモードを変更 → okx account set-position-mode

Step 2: 読み取りコマンドをすぐに実行 — プロファイルを確認（Step 0）してから書き込みを行う

読み取りコマンド（1〜10）：確認は不要です。すぐに実行してください。

• ccy フィルター：USDT、BTC、ETH などの通貨記号を使用します
• 手数料／ポジションには --instType：SPOT、SWAP、FUTURES、OPTION
• 請求履歴には --archive：デフォルトの期間より古い記録にアクセスします
• 最大サイズには --tdMode：cash（現物）、cross、または isolated

書き込みコマンド（11〜12）：実行前に一度確認してください。

• set-position-mode：モードを確認します（net = 一方向、long_short_mode = ヘッジモード）。切り替えると、保有中のポジションに影響する場合があります
• transfer：--ccy、--amt、--from、--to を確認します（口座タイプ：6=資金調達、18=取引）。事前に送金元の残高を確認してください

Step 3: 書き込み後に確認する

• set-position-mode の後：okx account config を実行し、posMode が更新されたことを確認します
• transfer の後：okx account balance と okx account asset-balance を実行し、残高が更新されたことを確認します

CLI コマンドリファレンス

全残高 — 1回の実行で集計スナップショットを取得

okx account balance-all [ccy] [--accounts trading,funding] [--no-valuation] [--no-aggregate] [--valuationCcy <ccy>] [--json]

Param	Required	Default	Description
ccy	いいえ	-	通貨で絞り込みます（カンマ区切り）。取引口座と資金調達口座のクエリにのみ適用されます。
--accounts	いいえ	trading,funding	クエリする口座をカンマ区切りで指定します
--no-valuation	いいえ	-	口座間の評価額算出をスキップします（デフォルトでは評価額が含まれます）
--no-aggregate	いいえ	-	サーバー側の集計ではなく、直接並列処理を強制します。口座ごとの評価額の内訳が必要な場合、または USD 以外の --valuationCcy を指定する場合に使用します（集計処理では評価額が USD 建てになります）。
--valuationCcy	いいえ	USDT	評価額の表示通貨

このコマンドは、まずサーバー側の集計エンドポイントを呼び出し、利用できない場合は直接並列クエリに自動的にフォールバックします。どちらの場合も出力形式は同じです。

{ trading, funding, valuation, meta } を返します。各セクションには available: boolean が含まれます。

• trading：totalEq、adjEq、details[]（通貨ごとの詳細）
• funding：details[]（通貨ごとの ccy、bal、availBal、frozenBal）
• valuation：valuationCcy、totalBal、details[]（口座ごとの内訳は並列処理の場合のみ設定されます。強制するには --no-aggregate を使用します）
• meta：requestedAt（ISO 8601）、elapsedMs、partialFailure、source（aggregate または fallback）、site

--json を指定しない場合、meta.partialFailure=true なら [PARTIAL] バナーが表示され、その後に3つのセクション（取引／資金調達／評価額）が続き、どの処理経路でデータを取得したかを示す [source: ...] フッターが表示されます。失敗したセクションには [ERROR: <msg>] が表示されます。

---

口座残高 — 取引口座

okx account balance [ccy] [--json]

Param	Required	Default	Description
ccy	いいえ	-	単一の通貨（例：USDT）に絞り込みます

currency、equity、available、frozen の表を返します。残高が 0 より大きい通貨のみ表示されます。

---

資産残高 — 資金調達口座

okx account asset-balance [ccy] [--valuation] [--valuationCcy <ccy>] [--json]

Param	Required	Default	Description
ccy	いいえ	-	特定の通貨（例：USDT）に絞り込みます。評価額の表示通貨には影響しません
--valuation	いいえ	false	すべての口座タイプ（取引／資金調達／運用）を対象とした資産評価額の合計も表示します
--valuationCcy	いいえ	USDT	資産評価額の合計を表示する通貨（例：USDT、BTC）。--valuation を指定した場合にのみ使用されます。

ccy、bal、availBal、frozenBal を返します。残高が 0 より大きい通貨のみ表示されます。

--valuation を指定すると、さらに totalBal と口座タイプごとの内訳（classic／earn／funding／trading）を含む評価額サマリー表が表示されます。数値は --valuationCcy 建てです（デフォルトは USDT）。

重要：ccy（残高フィルター）と --valuationCcy（評価額の表示通貨）は独立したパラメーターです。ccy=BTC を指定すると残高一覧は BTC の行に絞り込まれますが、評価額の通貨は変わりません。BTC 建ての合計を表示するには、--valuationCcy BTC を明示的に設定してください。

---

ポジション — 保有中のポジション

okx account positions [--instType <type>] [--instId <id>] [--json]

パラメーター	必須	デフォルト	説明
--instType	いいえ	-	絞り込み：SWAP、FUTURES、OPTION
--instId	いいえ	-	特定の銘柄に絞り込み

返される項目：instId、instType、side（posSide）、pos、avgPx、upl（未実現損益）、lever。サイズが 0 以外のポジションのみ表示されます。

---

ポジション履歴 — 決済済みポジション

okx account positions-history [--instType <type>] [--instId <id>] [--limit <n>] [--json]

返される項目：instId、direction、openAvgPx、closeAvgPx、realizedPnl、uTime。

---

請求明細 — 口座台帳

okx account bills [--archive] [--instType <type>] [--ccy <ccy>] [--limit <n>] [--json]

パラメーター	必須	デフォルト	説明
--archive	いいえ	false	古い記録にアクセスします（アーカイブエンドポイント）
--instType	いいえ	-	商品タイプで絞り込み
--ccy	いいえ	-	通貨で絞り込み
--limit	いいえ	100	レコード数

返される項目：billId、instId、type、ccy、balChg、bal、ts。

---

手数料 — 取引手数料ティア

okx account fees --instType <type> [--instId <id>] [--json]

パラメーター	必須	デフォルト	説明
--instType	はい	-	SPOT、SWAP、FUTURES、OPTION
--instId	いいえ	-	特定の銘柄（任意）

返される項目：level、maker、taker、makerU、takerU、ts。

---

設定 — 口座設定

okx account config [--json]

返される項目：uid、acctLv（口座レベル）、posMode（net／long_short_mode）、autoLoan、greeksType、level、levelTmp。

---

最大注文サイズ

okx account max-size --instId <id> --tdMode <mode> [--px <price>] [--json]

パラメーター	必須	デフォルト	説明
--instId	はい	-	銘柄 ID
--tdMode	はい	-	cash（現物）、cross、または isolated
--px	いいえ	-	参照価格（省略した場合はマーク価格を使用）

返される項目：instId、maxBuy、maxSell。

---

最大利用可能サイズ

okx account max-avail-size --instId <id> --tdMode <mode> [--json]

返される項目：instId、availBuy、availSell — 次の注文ですぐに利用できるサイズです。

---

最大出金額

okx account max-withdrawal [ccy] [--json]

テーブル形式で返されます：ccy、maxWd、maxWdEx（借入を含む）。絞り込みが指定されていない場合は、すべての通貨が表示されます。

---

ポジションモードの設定

okx account set-position-mode <net|long_short_mode> [--json]

値	動作
net	一方向モード（デフォルト） — ロングとショートが相殺されます
long_short_mode	ヘッジモード — ロングとショートを同時に保有できます

警告：ポジションを保有した状態でモードを切り替えると、予期しない動作が発生する場合があります。まず okx account positions を確認してください。

---

資金の振替

okx account transfer --ccy <ccy> --amt <n> --from <acctType> --to <acctType> \
  [--transferType <type>] [--subAcct <name>] [--json]

パラメーター	必須	デフォルト	説明
--ccy	はい	-	振替する通貨（例：USDT）
--amt	はい	-	振替する金額
--from	はい	-	振替元の口座タイプ：6=資金調達、18=取引
--to	はい	-	振替先の口座タイプ：6=資金調達、18=取引
--transferType	いいえ	0	0=口座内、1=サブアカウントへ、2=サブアカウントから
--subAcct	いいえ	-	サブアカウント名（サブアカウント間の振替で必須）

返される項目：transId、ccy、amt。

---

MCP ツールリファレンス

ツール	説明
account_get_balance_all	取引口座＋資金口座（＋評価額）のスナップショットを一度に取得します。サーバー側の集約エンドポイントを使用し、自動的に並列クエリへフォールバックします。showValuation=true（デフォルト）を指定すると、口座間の合計が含まれます。valuationCcy='USDT' がデフォルトです。preferParallel=true を指定すると、並列処理を強制します（口座ごとの評価額内訳／USD以外の通貨での評価額）。account_get_balance と account_get_asset_balance を個別に呼び出すよりも、こちらを優先してください。
account_get_balance	取引口座の残高
account_get_asset_balance	資金口座の残高。showValuation=true を指定すると、取引口座／資金口座／資産運用口座をまたいだ資産評価額の合計が含まれます。valuationCcy（デフォルトは "USDT"）を使って評価額合計の通貨を指定します。たとえば、valuationCcy="BTC" を指定すると、合計が BTC で返されます。
account_get_positions	保有中のポジション
account_get_positions_history	決済済みポジションの履歴
account_get_bills	口座の明細（最近のもの）
account_get_bills_archive	口座の明細（アーカイブ）
account_get_trade_fee	取引手数料のランク
account_get_config	口座設定
account_get_max_size	最大注文数量
account_get_max_avail_size	最大利用可能数量
account_get_max_withdrawal	最大出金可能額
account_set_position_mode	ポジションモードの設定
account_transfer	口座間の振替

---

入出力の例

「USDT はいくらありますか？」

okx account balance USDT
# → currency: USDT | equity: 5000.00 | available: 4500.00 | frozen: 500.00

「保有中のポジションをすべて表示してください」

okx account positions
# → table: instId, instType, side, pos, avgPx, upl, lever

「取引履歴と実現損益を教えてください」

okx account positions-history
# → table: instId, direction, openAvgPx, closeAvgPx, realizedPnl, uTime

「最近の口座アクティビティを表示してください」

okx account bills --limit 20
# → table: billId, instId, type, ccy, balChg, bal, ts

「SWAP の取引手数料はいくらですか？」

okx account fees --instType SWAP
# → level: VIP1 | maker: -0.0001 | taker: 0.0005

「クロスマージンで BTC をいくら買えますか？」

okx account max-size --instId BTC-USDT-SWAP --tdMode cross
# → instId: BTC-USDT-SWAP | maxBuy: 12.5 | maxSell: 12.5

「資金口座から取引口座へ 200 USDT を振り替えてください」

okx account transfer --ccy USDT --amt 200 --from 6 --to 18
# → Transfer: TXN123456 (USDT 200)

「口座設定を確認してください」

okx account config
# → uid: 123456789 | acctLv: 2 | posMode: net | autoLoan: false

資金はどこにある？

OKX では、資産が複数のサブ口座に分かれています。--valuation の内訳は、次のように対応しています。

口座の種類	details のキー	用途	確認方法
取引口座（統合）	trading	現物、マージン、スワップ、先物、オプション	okx account balance または --valuation の details.trading
資金口座	funding	入出金、未使用資金	okx account asset-balance または --valuation の details.funding
資産運用口座	earn	シンプル運用、ステーキング、貯蓄	--valuation の details.earn
クラシック口座	classic	クラシック口座（旧式で、あまり一般的ではありません）	--valuation の details.classic

ユーザーが「X USDT 持っているのに取引できない」と言った場合の一般的な手順：

1. okx account asset-balance --valuation → 各 details.* フィールドを確認します
2. details.funding の金額が大きく、details.trading の金額が小さい場合 → 資金は資金口座にあります
3. 振替：okx account transfer --ccy USDT --amt <n> --from 6 --to 18
4. 確認：okx account balance USDT → 振替額がエクイティに反映されているはずです

例外的なケース

• 残高が表示されない：残高は 0 より大きいものに絞り込まれます。何も表示されない場合、すべての通貨の残高はゼロです
• ポジションコマンドの結果が空：保有中の契約がありません。現物の保有分はここには表示されません（account balance を使用してください）
• bills --archive：7 日を超える取引を確認するには必要です（デフォルトの期間）。処理に時間がかかる場合があります
• set-position-mode：同じ銘柄でロングとショートの両方のポジションを保有している場合、net に切り替えることはできません
• transfer --from/--to のコード：6=資金口座、18=取引口座です。サブ口座間の振替には、ほかの値もあります
• max-size と max-avail-size：max-size は理論上の最大数量です。max-avail-size では、既存の注文と確保済みマージンが考慮されます
• デモモード：okx --demo account balance（OAuth）または okx --profile <demo-profile> account balance（API Key）では、実際の資金ではなくシミュレーション上の残高が表示されます

全般的な注意事項

• すべての書き込みコマンドには、有効な認証情報（OAuth セッションまたは ~/.okx/config.toml 内の API キー）が必要です
• 認証方式と取引モードは「認証情報とプロファイルの確認」で決定されます。パラメーターのルールについては、そのセクションを参照してください
• すべてのコマンド結果には、監査用の [mode: live] または [mode: demo] タグが含まれます
• --json はデフォルトで OKX API v5 の生のレスポンスを返します。出力を {"env": "<live|demo>", "profile": "<name>", "data": <response>} の形式でラップするには、--env を追加してください
• レート制限：アカウントエンドポイントへのリクエストは 2 秒あたり 10 件です
• 表示されるポジションは統合取引アカウントのものです。資金調達アカウントの資産は別扱いです
• アカウントタイプ：6=資金調達アカウント（入出金）、18=統合取引アカウント（現物＋デリバティブ）