okx/agent-skills/okx-cex-portfolio

OKX CEX Portfolio & Account CLI

Account balance, positions, P&L, bills, fees, and fund transfers on OKX exchange. Requires API credentials.

Preflight

Before running any command, follow `../_shared/preflight.md`. Use metadata.version from this file's frontmatter as the reference for Step 2.

Prerequisites

1. Install okx CLI:

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

1. Configure credentials:

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

1. Test with demo mode (simulated trading, no real funds):

``bash okx --demo account balance ``

Security: NEVER accept credentials in chat. Guide users to okx config init for setup.

Credential & Profile Check

Run this check before any authenticated command. The auth method is detected during preflight Step 2 and remembered for the session.

Step A — Verify credentials

Check both sources (see preflight Step 2 for the decision table). okx auth status --json alone is insufficient — its apiKey field is always false and does NOT reflect the TOML config.

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

Branch in this order — first match wins:

• config show has any profile with a non-empty api_key — API Key mode. Proceed to Step B.
• No API-key profile AND auth status returns "status": "logged_in" — OAuth mode. Proceed to Step B.
• No API-key profile AND auth status returns "status": "pending" — login in progress, wait.
• No API-key profile AND auth status returns "status": "not_logged_in" — stop all operations, load okx-cex-auth skill and follow login steps, wait for completion.

Step B — Confirm trading mode

Resolution rules:

1. Current message intent is clear (e.g. "real" / "实盘" / "live" → live; "test" / "模拟" / "demo" → demo) → use it and inform the user
2. Current message has no explicit declaration → check conversation context for a previous choice:

• Found → reuse it, inform user
• Not found → ask: "Live (实盘) or Demo (模拟盘)?" — wait for answer before proceeding

How to apply the mode depends on auth method (detected in Step A):

• API Key users: run okx config show --json to discover available profile names and their demo settings. Use --profile <name> to select the correct one.
• OAuth users: omit flags for live trading; add --demo for simulated trading. Do not use --profile to switch modes.

Handling Authentication Errors

Authentication error (error contains "401", "Session expired", or "Run okx auth login first"):

1. Stop immediately — do not retry the same command
2. Inform the user: "Authentication failed. Your session may have expired."
3. Load okx-cex-auth skill and follow the re-authentication steps
4. After successful re-authentication, retry the original command

Demo vs Live Mode

# 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                   # 模拟盘

Rules:

• Read commands (balance, positions, bills, etc.): always state which mode was used
• Write commands (transfer, set-position-mode): mode must be confirmed before execution (see "Credential & Profile Check" Step B); transfer especially — wrong mode means wrong account
• Every response after a command must append: [mode: live] or [mode: demo]

Skill Routing

• For market data (prices, charts, depth, funding rates) → use okx-cex-market
• For account balance, P&L, positions, fees, transfers → use okx-cex-portfolio (this skill)
• For regular spot/swap/futures/algo orders → use okx-cex-trade
• For grid and DCA trading bots → use okx-cex-bot

Quickstart

# 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

Command Index

Read Commands

Write Commands

Cross-Skill Workflows

Pre-trade balance check

User: "I want to buy 0.1 BTC — do I have enough 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

Pre-bot balance check

User: "I want to start a BTC grid bot with 1000 USDT"

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

Net worth quick view

User: "What's my total balance?" / "总资产多少?"

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)

Review open positions and P&L

User: "Show me my current positions and how they're performing"

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

Transfer and trade

User: "Move 500 USDT from my funding account to trade 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 ...

Check max position size before entering

User: "How much BTC can I buy with cross margin?"

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

Operation Flow

Step 0 — Credential & Profile Check

Before any authenticated command: see Credential & Profile Check. Determine auth method and trading mode before executing.

After every command result: append [mode: live] or [mode: demo] to the response

Step 1: Identify account action

• Check all balances at once → okx account balance-all (trading + funding + valuation in one call; recommended for "总资产 / net worth / all balances")
• Check balance → okx account balance (trading equity only) or okx account asset-balance (funding balances) or okx account asset-balance --valuation (total across all accounts in USDT)
• View open positions → okx account positions
• View closed positions + PnL → okx account positions-history
• View transaction history → okx account bills
• Check fee tier → okx account fees
• Check account settings → okx account config
• Calculate order size → okx account max-size or okx account max-avail-size
• Check withdrawal limit → okx account max-withdrawal
• Transfer funds → okx account transfer
• Change position mode → okx account set-position-mode

Step 2: Run read commands immediately — confirm profile (Step 0) then writes

Read commands (1–10): run immediately, no confirmation needed.

• ccy filter: use currency symbol like USDT, BTC, ETH
• --instType for fees/positions: SPOT, SWAP, FUTURES, OPTION
• --archive for bills: access older records beyond the default window
• --tdMode for max-size: cash (spot), cross, or isolated

Write commands (11–12): confirm once before executing.