OKX CEX 投資組合與帳戶 CLI
查詢 OKX 交易所的帳戶餘額、持倉、盈虧、帳單、手續費及資金轉移。需提供 API 憑證。
前置需求
- 安裝
okxCLI:npm install -g @okx_ai/okx-trade-cli - 設定憑證:
或設定環境變數:okx config initexport OKX_API_KEY=your_key export OKX_SECRET_KEY=your_secret export OKX_PASSPHRASE=your_passphrase - 使用模擬盤測試:
okx --profile demo account balance
憑證與設定檔檢查
在執行任何需要認證的命令前,都必須先執行此檢查。
步驟 A — 驗證憑證
okx config show # 驗證設定狀態(輸出會遮蔽敏感資訊)
- 如果命令回傳錯誤或顯示未設定:停止所有操作,引導使用者執行
okx config init,並等待設定完成後再重試。 - 如果憑證已設定:繼續步驟 B。
步驟 B — 確認設定檔(必要)
--profile 是所有需要認證命令的必要參數。切勿隱含地新增設定檔。
| 值 | 模式 | 資金 |
|---|---|---|
live | 實盤 | 真實資金 |
demo | 模擬盤 | 模擬資金 |
解決規則:
- 當前訊息意圖明確(例如「real」/「實盤」/「live」→
live;「test」/「模擬」/「demo」→demo)→ 使用該設定檔並告知使用者:"正在使用 --profile live (實盤)"或"正在使用 --profile demo (模擬盤)" - 當前訊息沒有明確宣告 → 檢查對話上下文是否有先前的設定檔:
- 有找到 → 使用它,告知使用者:
"繼續使用稍早的 --profile live (實盤)" - 未找到 → 詢問:
"實盤 (Live) 還是模擬盤 (Demo)?"— 等待使用者回覆後再繼續
- 有找到 → 使用它,告知使用者:
處理 401 認證錯誤
如果任何命令回傳 401 / 認證錯誤:
- 立即停止 — 不要重試同一個命令
- 告知使用者:「認證失敗 (401)。您的 API 憑證可能無效或已過期。」
- 引導使用者透過本機編輯器直接編輯檔案來更新憑證:
更新相關設定檔下的~/.okx/config.tomlapi_key、secret_key、passphrase欄位。 請勿將新憑證貼到對話中。 - 在使用者確認檔案已更新後,執行
okx config show進行驗證(輸出會遮蔽敏感資訊) - 然後才重試原始操作
模擬盤與實盤模式
設定檔是切換實盤/模擬盤的唯一控制項 — 只有兩個選項:
--profile | 模式 | 資金 |
|---|---|---|
live | 實盤 | 真實資金 |
demo | 模擬盤 | 模擬資金 |
okx --profile live account balance # 實盤
okx --profile demo account balance # 模擬盤 (simulated balance)
規則:
- 讀取命令(餘額、持倉、帳單等):務必說明使用了哪個設定檔
- 寫入命令(
transfer、set-position-mode):執行前必須確認設定檔(請參閱「憑證與設定檔檢查」的步驟 B);尤其是轉帳 — 設定檔錯誤意味著帳戶錯誤 - 每個命令的回應後都必須附加:
[profile: live]或[profile: demo] - 請勿使用
--demo標誌 — 請改用--profile
技能路由
- 市場數據(價格、圖表、深度、資金費率)→ 使用
okx-cex-market - 帳戶餘額、損益、持倉、手續費、轉帳 → 使用
okx-cex-portfolio(此技能) - 一般的現貨/合約/交割/演算法委託單 → 使用
okx-cex-trade - 網格和 DCA 交易機器人 → 使用
okx-cex-bot
快速入門
# 交易帳戶餘額(所有餘量大於 0 的貨幣)
okx account balance
# 僅查詢 USDT 餘額
okx account balance USDT
# 資金帳戶餘額
okx account asset-balance
# 所有未平倉持倉
okx account positions
# 已平倉持倉歷史記錄(含已實現損益)
okx account positions-history
# 最近的帳戶帳單(最近 100 筆)
okx account bills
# 我的交易手續費等級
okx account fees --instType SPOT
# 從資金帳戶 (18) 轉帳 100 USDT 到交易帳戶 (6)
okx account transfer --ccy USDT --amt 100 --from 18 --to 6
命令索引
讀取命令
| # | 命令 | 類型 | 說明 |
|---|---|---|---|
| 1 | okx account balance [ccy] | 讀取 | 交易帳戶權益、可用、凍結 |
| 2 | okx account asset-balance [ccy] | 讀取 | 資金帳戶餘額 |
| 3 | okx account positions | 讀取 | 未平倉合約/期貨持倉 |
| 4 | okx account positions-history | 讀取 | 已平倉持倉 + 已實現損益 |
| 5 | okx account bills | 讀取 | 帳戶分類帳(充值、提現、交易) |
| 6 | okx account fees --instType <type> | 讀取 | 我的交易手續費等級(maker/taker) |
| 7 | okx account config | 讀取 | 帳戶等級、持倉模式、UID |
| 8 | okx account max-size --instId <id> --tdMode <mode> | 讀取 | 當前價格下的最大買/賣數量 |
| 9 | okx account max-avail-size --instId <id> --tdMode <mode> | 讀取 | 下一個委託單的可用數量 |
| 10 | okx account max-withdrawal [ccy] | 讀取 | 每種貨幣的最大可提現金額 |
寫入命令
| # | 命令 | 類型 | 說明 |
|---|---|---|---|
| 11 | okx account set-position-mode <mode> | 寫入 | 切換逐倉/全倉持倉模式 |
| 12 | okx account transfer | 寫入 | 在帳戶之間轉移資金 |
跨技能工作流程
交易前餘額檢查
使用者:「我想買 0.1 BTC — 我的 USDT 夠嗎?」
1. okx-cex-portfolio okx account balance USDT → 檢查可用權益
2. okx-cex-market okx market ticker BTC-USDT → 檢查當前價格
↓ 使用者批准
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 USDT → 確認可用資金 ≥ 1000
2. okx-cex-market okx market candles BTC-USDT --bar 4H --limit 50 → 確定價格範圍
↓ 使用者批准
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 positions → 未平倉持倉及其未實現損益
2. okx-cex-portfolio okx account positions-history → 最近已平倉持倉
3. okx-cex-market okx market ticker BTC-USDT-SWAP → 檢查當前價格與入場價的比較
轉帳與交易
使用者:「從我的資金帳戶移動 500 USDT 來交易 BTC」
1. okx-cex-portfolio okx account asset-balance USDT → 確認資金帳戶餘額 ≥ 500
↓ 使用者批准
2. okx-cex-portfolio okx account transfer --ccy USDT --amt 500 --from 18 --to 6
3. okx-cex-portfolio okx account balance USDT → 確認交易帳戶餘額已更新
↓ 準備交易
4. okx-cex-trade okx spot place ...
入場前檢查最大持倉數量
使用者:「使用全倉保證金,我可以買多少 BTC?」
1. okx-cex-portfolio okx account balance → 總權益
2. okx-cex-portfolio okx account max-size --instId BTC-USDT-SWAP --tdMode cross → 最大買/賣數量
3. okx-cex-market okx market ticker BTC-USDT-SWAP → 當前價格參考
操作流程
步驟 0 — 憑證與設定檔檢查
在任何需要認證的命令之前:
決定設定檔(必要):
- 選項:
live(實盤)或demo(模擬盤)— 只有這兩個值
- 當前訊息意圖明確(例如「real」/「實盤」/「live」→ live;「test」/「模擬」/「demo」→ demo)→ 使用它,告知使用者:
"正在使用 --profile live (實盤)" - 當前訊息沒有明確宣告 → 檢查對話上下文是否有先前的設定檔:
- 有找到 → 使用它,告知使用者:
"繼續使用稍早的 --profile live (實盤)" - 未找到 → 詢問:
"實盤 (Live) 還是模擬盤 (Demo)?"— 等待回覆
- 有找到 → 使用它,告知使用者:
如果未設定憑證: 引導使用者執行 okx config init,停止所有交易操作
每次命令結果後: 在回應中附加 [profile: live] 或 [profile: demo]
步驟 1:識別帳戶操作
- 檢查餘額 →
okx account balance(交易帳戶)或okx account asset-balance(資金帳戶) - 檢視未平倉持倉 →
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
步驟 2:立即執行讀取命令 — 確認設定檔(步驟 0)後再執行寫入命令
讀取命令(1–10):立即執行,無需確認。
ccy過濾條件:使用貨幣符號,例如USDT、BTC、ETH- 手續費/持倉的
--instType:SPOT、SWAP、FUTURES、OPTION - 帳單的
--archive:存取預設時間範圍之外的較舊記錄 - max-size 的
--tdMode:cash(現貨)、cross或isolated
寫入命令(11–12):執行前先確認一次。
set-position-mode:確認模式 (net= 單向持倉,long_short_mode= 雙向持倉);切換可能影響未平倉持倉transfer:確認--ccy、--amt、--from、--to(帳戶類型:6=交易帳戶,18=資金帳戶);先驗證來源帳戶餘額
步驟 3:寫入後驗證
set-position-mode後:執行okx account config以確認posMode已更新transfer後:執行okx account balance和okx account asset-balance以確認餘額已更新
CLI 命令參考
帳戶餘額 — 交易帳戶
okx account balance [ccy] [--json]
| 參數 | 必要 | 預設值 | 說明 |
|---|---|---|---|
ccy | 否 | - | 過濾為單一貨幣(例如 USDT) |
回傳表格:currency、equity、available、frozen。僅顯示餘量大於 0 的貨幣。
資產餘額 — 資金帳戶
okx account asset-balance [ccy] [--json]
| 參數 | 必要 | 預設值 | 說明 |
|---|---|---|---|
ccy | 否 | - | 過濾為單一貨幣 |
回傳:ccy、bal、availBal、frozenBal。僅顯示餘量大於 0 的貨幣。
持倉 — 未平倉持倉
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 | 交易帳戶餘額 |
account_get_asset_balance | 資金帳戶餘額 |
account_get_positions | 未平倉持倉 |
account_get_positions_history | 已平倉持倉歷史 |
account_get_bills | 帳單/分類帳 |
account_get_fees | 手續費等級 |
account_get_config | 帳戶設定 |
account_get_max_size | 最大委託單數量 |
account_get_max_avail_size | 最大可用數量 |
account_get_max_withdrawal | 最大提現金額 |
account_set_position_mode | 設定持倉模式 |
account_transfer | 轉移資金 |