OKX CEX Portfolio & Account CLI

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

Prerequisites

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

Configure credentials:

bash

okx config init

Or set environment variables:

bash

export OKX_API_KEY=your_key
export OKX_SECRET_KEY=your_secret
export OKX_PASSPHRASE=your_passphrase

Test with demo mode:
bash
```
okx --demo account balance
```

Demo vs Live Mode

Always clarify before any write command whether the user wants demo or live execution.

Check which mode is active:

bash

okx config show       # shows current profile and whether demo is set as default

Run a single command in demo mode by prepending

--demo

bash

okx --demo account balance          # simulated account balance
okx --demo account transfer ...     # simulated transfer (no real funds moved)

Rules for this skill:

Read commands (balance, positions, bills, etc.): run immediately in both modes — always state which mode you used
Write commands (
```
transfer
```
,
```
set-position-mode
```
): before executing, explicitly confirm with the user: "Execute on live account or demo (simulated)?"
When executing in demo mode, prefix your response summary with [DEMO]
When executing on live account, prefix with [LIVE]

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

bash

# 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
okx account positions

# 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 (18) to trading (6)
okx account transfer --ccy USDT --amt 100 --from 18 --to 6

Command Index

Read Commands


okx account balance [ccy]
okx account asset-balance [ccy]
okx account positions
okx account positions-history
okx account bills
okx account fees --instType <type>
okx account config
okx account max-size --instId <id> --tdMode <mode>
okx account max-avail-size --instId <id> --tdMode <mode>
okx account max-withdrawal [ccy]

#	Command	Type	Description
1	`okx account balance [ccy]`	READ	Trading account equity, available, frozen
2	`okx account asset-balance [ccy]`	READ	Funding account balance
3	`okx account positions`	READ	Open contract/swap positions
4	`okx account positions-history`	READ	Closed positions + realized PnL
5	`okx account bills`	READ	Account ledger (deposits, withdrawals, trades)
6	`okx account fees --instType <type>`	READ	My trading fee tier (maker/taker)
7	`okx account config`	READ	Account level, position mode, UID
8	`okx account max-size --instId <id> --tdMode <mode>`	READ	Max buy/sell size at current price
9	`okx account max-avail-size --instId <id> --tdMode <mode>`	READ	Available size for next order
10	`okx account max-withdrawal [ccy]`	READ	Max withdrawable per currency

Write Commands

#	Command	Type	Description
11	`okx account set-position-mode <mode>`	WRITE	Switch net/hedge position mode
12	`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 USDT               → check available equity
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 USDT               → confirm available funds ≥ 1000
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

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 18 --to 6
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 1: Identify account action

Check balance →

okx account balance

(trading) or

okx account asset-balance

(funding)

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

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 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
```
=trading,
```
18
```
=funding); 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

Account Balance — Trading Account

bash

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

bash

okx account asset-balance [ccy] [--json]

Param	Required	Default	Description
`ccy`	No	-	Filter to a single currency

Returns:

ccy

bal

availBal

frozenBal

. Only shows currencies with balance > 0.

Positions — Open Positions

bash

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

bash

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

Returns:

instId

direction

openAvgPx

closeAvgPx

realizedPnl

uTime

Bills — Account Ledger

bash

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

bash

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

bash

okx account config [--json]

Returns:

uid

acctLv

(account level),

posMode

(net/long_short_mode),

autoLoan

greeksType

level

levelTmp

Max Size — Maximum Order Size

bash

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

bash

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

Returns:

instId

availBuy

availSell

— the immediately available size for the next order.

Max Withdrawal

bash

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

Returns table:

ccy

maxWd

maxWdEx

(with borrowing). Shows all currencies if no filter.

Set Position Mode

bash

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

bash

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` =trading, `18` =funding
`--to`	Yes	-	Destination account type: `6` =trading, `18` =funding
`--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`	Trading account balance
`account_get_asset_balance`	Funding account balance
`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?"

bash

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

"Show all my open positions"

bash

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

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

bash

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

"Show my recent account activity"

bash

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

"What are my trading fees for SWAP?"

bash

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

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

bash

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"

bash

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

"Check my account config"

bash

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

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
```
=trading account,
```
18
```
=funding 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
```
shows simulated balances, not real funds

Global Notes

All write commands require valid credentials in
```
~/.okx/config.toml
```
or env vars
```
--profile <name>
```
switches between multiple account configurations
```
--json
```
returns raw OKX API v5 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
```
=Unified Trading Account (spot + derivatives),
```
18
```
=Funding Account (deposits/withdrawals)

okx-cex-portfolio

NPX Install

Tags

SKILL.md Content

OKX CEX Portfolio & Account CLI

Prerequisites

Demo vs Live Mode

Skill Routing

Quickstart

Command Index

Read Commands

Write Commands

Cross-Skill Workflows

Pre-trade balance check

Pre-bot balance check

Review open positions and P&L

Transfer and trade

Check max position size before entering

Operation Flow

Step 1: Identify account action

Step 2: Run read commands immediately — confirm writes

Step 3: Verify after writes

CLI Command Reference

Account Balance — Trading Account

Asset Balance — Funding Account

Positions — Open Positions

Positions History — Closed Positions

Bills — Account Ledger

Fees — Trading Fee Tier

Config — Account Configuration

Max Size — Maximum Order Size

Max Available Size

Max Withdrawal

Set Position Mode

Transfer Funds

MCP Tool Reference

Input / Output Examples

Edge Cases

Global Notes