okx-cex-portfolio

OKX CEX 投资组合与账户 CLI

在 OKX 交易所查询账户余额、持仓、盈亏、账单和费用，以及转账。需要 API 凭证。

预检

运行任何命令之前，请遵循 ../_shared/preflight.md。 使用此文件 frontmatter 中的 metadata.version 作为步骤 2 的参考。

前置条件

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 Key 模式。继续步骤 B。
• 没有 API Key 配置文件，且 auth status 返回 "status": "logged_in"——OAuth 模式。继续步骤 B。
• 没有 API Key 配置文件，且 auth status 返回 "status": "pending"——登录正在进行，请等待。
• 没有 API Key 配置文件，且 auth status 返回 "status": "not_logged_in"——停止所有操作，加载 okx-cex-auth 技能并按照登录步骤操作，然后等待完成。

步骤 B — 确认交易模式

选择规则：

1. 当前消息意图明确（例如，“real”／“实盘”／“live” → live；“test”／“模拟”／“demo” → demo）→ 使用该模式并告知用户
2. 当前消息未明确说明 → 检查对话上下文中此前是否有选择：
   • 找到 → 沿用该选择，并告知用户
   • 未找到 → 询问："Live (实盘) or Demo (模拟盘)?"——等待用户回答后再继续

根据身份验证方式（在步骤 A 中检测）应用模式：

身份验证方式	Live（实盘）	Demo（模拟盘）
API Key	--profile <live-profile>	--profile <demo-profile>
OAuth	（无需标志，默认使用 live）	--demo

• API Key 用户：运行 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 Key 参数	OAuth 参数
实盘 (live)	真实资金	--profile <live-profile>	（默认，无需标志）
模拟盘 (demo)	模拟资金	--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]	读取	一次性快照：一次调用即可查看交易账户 + 资金账户（+ 估值）
2	okx account balance [ccy]	读取	交易账户权益、可用余额、冻结余额
3a	okx account asset-balance [ccy]	读取	资金账户余额（按币种列出）
3b	okx account asset-balance [ccy] --valuation [--valuationCcy <ccy>]	读取	同上 + 交易账户／资金账户／赚币的资产总估值；计价币种默认为 USDT，可通过 --valuationCcy BTC 覆盖
4	okx account positions [--instType <type>] [--instId <id>]	读取	未平仓合约／永续合约仓位。当用户指定产品时（“我的永续合约仓位”“期货仓位”“期权仓位”），传入 --instType <type>（SWAP | FUTURES | OPTION | MARGIN | EVENTS）——或者使用该产品专属命令（okx swap positions、okx futures positions、okx option positions）。只有当用户确实想查看所有仓位时才省略筛选条件：不加筛选的列表内容更多，且需要模型自行筛选产品，因此更容易出错
5	okx account positions-history	读取	已平仓仓位 + 已实现盈亏
6	okx account bills	读取	账户账本（存款、提款、交易）
7	okx account fees --instType <type>	读取	我的交易费率等级（挂单／吃单）
8	okx account config	读取	账户等级、持仓模式、UID
9	okx account max-size --instId <id> --tdMode <mode>	读取	当前价格下的最大买入／卖出数量
10	okx account max-avail-size --instId <id> --tdMode <mode>	读取	下一笔订单的可用数量
11	okx account max-withdrawal [ccy]	读取	每种币种的最大可提金额

写入命令

#	命令	类型	描述
12	okx account set-position-mode <mode>	写入	切换单向／双向持仓模式
13	okx account transfer	写入	在账户之间划转资金

跨技能工作流

交易前检查余额

用户：“我想买入 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（一次调用即可查看交易账户 + 资金账户 + 估值；建议用于“总资产 / 净资产 / 所有余额”）
• 检查余额 → 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

步骤 2：立即运行读取命令——确认个人资料（步骤 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=交易账户）；先核实来源账户余额

步骤 3：写入后验证

• 执行 set-position-mode 后：运行 okx account config，确认 posMode 已更新
• 执行 transfer 后：运行 okx account balance 和 okx account asset-balance，确认余额已更新

CLI 命令参考

总余额——一次性汇总快照

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

参数	必填	默认值	描述
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] 标记，随后依次显示三个部分（交易账户 / 资金账户 / 估值），最后打印 [source: ...] 页脚，指出数据来源路径。失败的部分会显示 [ERROR: <msg>]。

---

账户余额——交易账户

okx account balance [ccy] [--json]

参数	必填	默认值	描述
ccy	否	-	筛选单一货币（例如 USDT）

返回表格：currency、equity、available、frozen。仅显示余额大于 0 的货币。

---

资产余额——资金账户

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

参数	必填	默认值	描述
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 可强制使用并行查询路径（按账户显示估值明细／非美元估值）。建议优先使用此工具，而不是分别调用 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 的项目；如果没有任何显示，则所有币种的余额均为 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 可将输出包装为 {"env": "<live|demo>", "profile": "<name>", "data": <response>}
• 账户端点的速率限制：每 2 秒 10 个请求
• 显示的持仓属于统一交易账户；资金账户资产单独计算
• 账户类型：6=资金账户（存款/取款），18=统一交易账户（现货 + 衍生品）