/okx-cex-portfolio

name: okx-cex-portfolio
description: "This skill should be used when the user asks about 'account balance', 'how much USDT do I have', 'my funding account', 'show my positions', 'open positions', 'position P&L', 'unrealized PnL', 'closed positions', 'position history', 'realized PnL', 'account bills', 'transaction history', 'trading fees', 'fee tier', 'account config', 'max order size', 'how much can I buy', 'withdrawable amount', 'transfer funds', 'move USDT to trading account', or 'switch position mode'. Also use for '总资产', 'full balance', 'all assets', 'total holdings', 'net worth', 'how much do I have in total', 'show all my balances', 'all account balances', 'asset overview', 'aggregated balance', 'asset snapshot', '资产快照'. Requires API credentials. Do NOT use for market prices (use okx-cex-market), placing/cancelling orders (use okx-cex-trade), or grid/DCA bots (use okx-cex-bot)."
license: MIT
metadata:
  author: okx
  version: "1.4.1"
  homepage: "https://www.okx.com"
  agent:
    requires:
      bins: ["okx"]
    install:
      - id: npm
        kind: node
        package: "@okx_ai/okx-trade-cli@1.4.1"
        bins: ["okx"]
        label: "Install okx CLI (npm)"

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`](../_shared/preflight.md). Use `metadata.version` from this file's frontmatter as the reference for Step 2.

Prerequisites

1. Install `okx` CLI:

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

2. Configure credentials:

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

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

   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](../_shared/preflight.md) Step 2 and remembered for the session.

Step A — Verify credentials

Check **both** sources (see [preflight Step 2](../_shared/preflight.md#step-2--detect-auth-method-once-per-session) 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):**

| Auth method | Live (实盘) | Demo (模拟盘) | |---|---|---| | **API Key** | `--profile <live-profile>` | `--profile <demo-profile>` | | **OAuth** | *(no flag needed, live is default)* | `--demo` |

• **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

| Mode | Funds | API Key param | OAuth param | |---|---|---|---| | 实盘 (live) | Real funds | `--profile <live-profile>` | *(default, no flag)* | | 模拟盘 (demo) | Simulated funds | `--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                   # 模拟盘

**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