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

| # | Command | Type | Description |
|---|---|---|---|
| 1 | `okx account balance-all [ccy]` | READ | One-shot snapshot: trading + funding (+ valuation) in one call |
| 2 | `okx account balance [ccy]` | READ | Trading account equity, available, frozen |
| 3a | `okx account asset-balance [ccy]` | READ | Funding account balance (per-currency list) |
| 3b | `okx account asset-balance [ccy] --valuation [--valuationCcy <ccy>]` | READ | Same + total asset valuation across trading/funding/earn; denomination defaults to USDT, override with `--valuationCcy BTC` |
| 4 | `okx account positions [--instType <type>] [--instId <id>]` | READ | Open contract/swap positions. **When the user names a product** ("my swap positions", "futures positions", "option positions"), pass `--instType <type>` (`SWAP` \| `FUTURES` \| `OPTION` \| `MARGIN` \| `EVENTS`) — or use that product's own command (`okx swap positions`, `okx futures positions`, `okx option positions`). Only omit the filter when the user genuinely wants everything: an unfiltered list is larger and leaves the product filtering to the model, which is where mistakes happen |
| 5 | `okx account positions-history` | READ | Closed positions + realized PnL |
| 6 | `okx account bills` | READ | Account ledger (deposits, withdrawals, trades) |
| 7 | `okx account fees --instType <type>` | READ | My trading fee tier (maker/taker) |
| 8 | `okx account config` | READ | Account level, position mode, UID |
| 9 | `okx account max-size --instId <id> --tdMode <mode>` | READ | Max buy/sell size at current price |
| 10 | `okx account max-avail-size --instId <id> --tdMode <mode>` | READ | Available size for next order |
| 11 | `okx account max-withdrawal [ccy]` | READ | Max withdrawable per currency |

### Write Commands

| # | Command | Type | Description |
|---|---|---|---|
| 12 | `okx account set-position-mode <mode>` | WRITE | Switch net/hedge position mode |
| 13 | `okx account transfer` | WRITE | Transfer funds between accounts |

## 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](#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.

- `set-position-mode`: confirm mode (`net` = one-directional, `long_short_mode` = hedge mode); switching may affect open positions
- `transfer`: confirm `--ccy`, `--amt`, `--from`, `--to` (account types: `6`=funding, `18`=trading); verify source balance first

### Step 3: Verify after writes

- After `set-position-mode`: run `okx account config` to confirm `posMode` updated
- After `transfer`: run `okx account balance` and `okx account asset-balance` to confirm balances updated

## CLI Command Reference

### Balance All — One-Shot Aggregate Snapshot

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

Param	Required	Default	Description
ccy	No	-	Filter by currency (comma-separated). Applied to trading + funding queries only.
--accounts	No	trading,funding	Comma-separated accounts to query
--no-valuation	No	-	Skip cross-account valuation (default: valuation included)
--no-aggregate	No	-	Force the direct parallel path instead of the server aggregate. Use when you need the per-account valuation breakdown, or a non-USD --valuationCcy (the aggregate path denominates valuation in USD).
--valuationCcy	No	USDT	Denomination currency for valuation

This command calls a server-side aggregate endpoint first and automatically falls back to direct parallel queries when it is unavailable; the output contract is identical either way.

Returns { trading, funding, valuation, meta }. Each section has available: boolean:

• trading: totalEq, adjEq, details[] (per-currency)
• funding: details[] (per-currency ccy, bal, availBal, frozenBal)
• valuation: valuationCcy, totalBal, details[] (per-account breakdown is only populated on the parallel path; use --no-aggregate to force it)
• meta: requestedAt (ISO 8601), elapsedMs, partialFailure, source (aggregate or fallback), site

When --json is NOT set: prints [PARTIAL] banner if meta.partialFailure=true, followed by three sections (Trading / Funding / Valuation), then a [source: ...] footer showing which path served the data. Failed sections show [ERROR: <msg>].

---

Account Balance — Trading Account

okx account balance [ccy] [--json]

Param	Required	Default	Description
ccy	No	-	Filter to a single currency (e.g., USDT)

Returns table: currency, equity, available, frozen. Only shows currencies with balance > 0.

---

Asset Balance — Funding Account

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

Param	Required	Default	Description
ccy	No	-	Filter to a specific currency (e.g., USDT); does not affect valuation denomination
--valuation	No	false	Also show total asset valuation across all account types (trading/funding/earn)
--valuationCcy	No	USDT	Currency in which to denominate the total asset valuation (e.g., USDT, BTC). Only used when --valuation is set.

Returns: ccy, bal, availBal, frozenBal. Only shows currencies with balance > 0.

With --valuation: additionally prints a valuation summary table with totalBal and per-account-type breakdown (classic/earn/funding/trading). The numbers are denominated in --valuationCcy (default USDT).

Important: ccy (balance filter) and --valuationCcy (valuation denomination) are independent parameters — ccy=BTC filters the balance list to BTC rows but does NOT change the valuation currency; set --valuationCcy BTC explicitly for BTC-denominated totals.

---

Positions — Open Positions

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

Param	Required	Default	Description
--instType	No	-	Filter: SWAP, FUTURES, OPTION
--instId	No	-	Filter to specific instrument

Returns: instId, instType, side (posSide), pos, avgPx, upl (unrealized PnL), lever. Only shows positions with size ≠ 0.

---

Positions History — Closed Positions

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

Returns: instId, direction, openAvgPx, closeAvgPx, realizedPnl, uTime.

---

Bills — Account Ledger

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

Param	Required	Default	Description
--archive	No	false	Access older records (archive endpoint)
--instType	No	-	Filter by instrument type
--ccy	No	-	Filter by currency
--limit	No	100	Number of records

Returns: billId, instId, type, ccy, balChg, bal, ts.

---

Fees — Trading Fee Tier

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

Param	Required	Default	Description
--instType	Yes	-	SPOT, SWAP, FUTURES, OPTION
--instId	No	-	Specific instrument (optional)

Returns: level, maker, taker, makerU, takerU, ts.

---

Config — Account Configuration

okx account config [--json]

Returns: uid, acctLv (account level), posMode (net/long_short_mode), autoLoan, greeksType, level, levelTmp.

---

Max Size — Maximum Order Size

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

Param	Required	Default	Description
--instId	Yes	-	Instrument ID
--tdMode	Yes	-	cash (spot), cross, or isolated
--px	No	-	Reference price (uses mark price if omitted)

Returns: instId, maxBuy, maxSell.

---

Max Available Size

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

Returns: instId, availBuy, availSell — the immediately available size for the next order.

---

Max Withdrawal

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

Returns table: ccy, maxWd, maxWdEx (with borrowing). Shows all currencies if no filter.

---

Set Position Mode

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

Value	Behavior
net	One-directional (default) — long and short net out
long_short_mode	Hedge mode — long and short can coexist

Warning: Switching modes when positions are open may cause unexpected behavior. Check okx account positions first.

---

Transfer Funds

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

Param	Required	Default	Description
--ccy	Yes	-	Currency to transfer (e.g., USDT)
--amt	Yes	-	Amount to transfer
--from	Yes	-	Source account type: 6=funding, 18=trading
--to	Yes	-	Destination account type: 6=funding, 18=trading
--transferType	No	0	0=within account, 1=to sub-account, 2=from sub-account
--subAcct	No	-	Sub-account name (required for sub-account transfers)

Returns: transId, ccy, amt.

---

MCP Tool Reference

Tool	Description
account_get_balance_all	One-shot snapshot of trading + funding (+ valuation), served by a server-side aggregate endpoint with automatic fallback to parallel queries. Use showValuation=true (default) to include cross-account totals; valuationCcy='USDT' by default. Set preferParallel=true to force the parallel path (per-account valuation breakdown / non-USD valuation). Prefer over calling account_get_balance + account_get_asset_balance separately.
account_get_balance	Trading account balance
account_get_asset_balance	Funding account balance. Use showValuation=true to include total asset valuation across trading/funding/earn accounts. Use valuationCcy (default "USDT") to set the denomination for the valuation total — e.g. valuationCcy="BTC" returns the total in BTC.
account_get_positions	Open positions
account_get_positions_history	Closed position history
account_get_bills	Account bills (recent)
account_get_bills_archive	Account bills (archive)
account_get_trade_fee	Trading fee tier
account_get_config	Account configuration
account_get_max_size	Max order size
account_get_max_avail_size	Max available size
account_get_max_withdrawal	Max withdrawable
account_set_position_mode	Set position mode
account_transfer	Transfer between accounts

---

Input / Output Examples

"How much USDT do I have?"

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

"Show all my open positions"

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

"What's my trading history and realized PnL?"

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

"Show my recent account activity"

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

"What are my trading fees for SWAP?"

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

"How much BTC can I buy in cross margin?"

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

"Transfer 200 USDT from funding to trading"

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

"Check my account config"

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

Where Can the Money Live?

OKX splits assets across multiple sub-accounts. The --valuation breakdown maps directly:

Account type	details key	Used for	Check with
Trading (unified)	trading	Spot, margin, swap, futures, options	okx account balance or details.trading in --valuation
Funding	funding	Deposits/withdrawals, idle funds	okx account asset-balance or details.funding in --valuation
Earn	earn	Simple earn, staking, savings	details.earn in --valuation
Classic	classic	Classic account (legacy, less common)	details.classic in --valuation

Typical flow when user says "I have X USDT but can't trade":

1. okx account asset-balance --valuation → look at each details.* field
2. If details.funding is large and details.trading is small → the funds are in the funding account
3. Transfer: okx account transfer --ccy USDT --amt <n> --from 6 --to 18
4. Confirm: okx account balance USDT → equity should now reflect the transferred amount

Edge Cases

• No balance shown: balance is filtered to > 0 — if nothing shows, all currencies have zero balance
• Positions command returns empty: no open contracts; spot holdings are not shown here (use account balance)
• bills --archive: required for transactions older than 7 days (default window); may be slower
• set-position-mode: cannot switch to net if you have both long and short positions on the same instrument
• transfer --from/--to codes: 6=funding account, 18=trading account; other values exist for sub-account flows
• max-size vs max-avail-size: max-size is the theoretical maximum; max-avail-size accounts for existing orders and reserved margin
• Demo mode: okx --demo account balance (OAuth) or okx --profile <demo-profile> account balance (API Key) shows simulated balances, not real funds

Global Notes

• All write commands require valid credentials (OAuth session or API key in ~/.okx/config.toml)
• Auth method and trading mode are determined in "Credential & Profile Check"; see that section for parameter rules
• Every command result includes a [mode: live] or [mode: demo] tag for audit reference
• --json returns the raw OKX API v5 response by default. Add --env to wrap the output as {"env": "<live|demo>", "profile": "<name>", "data": <response>}
• Rate limit: 10 requests per 2 seconds for account endpoints
• Positions shown are for the unified trading account; funding account assets are separate
• Account types: 6=Funding Account (deposits/withdrawals), 18=Unified Trading Account (spot + derivatives)