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
- Install
okx CLI:
npm install -g @okx_ai/okx-trade-cli
- Configure credentials:
okx config init
Or set environment variables:
export OKX_API_KEY=your_key
export OKX_SECRET_KEY=your_secret
export OKX_PASSPHRASE=your_passphrase
- Test with demo mode:
okx --profile demo account balance
Credential & Profile Check
Run this check before any authenticated command.
Step A โ Verify credentials
okx config show
- If the command returns an error or shows no configuration: stop all operations, guide the user to run
okx config init, and wait for setup to complete before retrying.
- If credentials are configured: proceed to Step B.
Step B โ Confirm profile (required)
--profile is required for all authenticated commands. Never add a profile implicitly.
| Value |
Mode |
Funds |
live |
ๅฎ็ |
Real funds |
demo |
ๆจกๆ็ |
Simulated funds |
Resolution rules:
- Current message intent is clear (e.g. "real" / "ๅฎ็" / "live" โ
live; "test" / "ๆจกๆ" / "demo" โ demo) โ use it and inform the user: "Using --profile live (ๅฎ็)" or "Using --profile demo (ๆจกๆ็)"
- Current message has no explicit declaration โ check conversation context for a previous profile:
- Found โ use it, inform user:
"Continuing with --profile live (ๅฎ็) from earlier"
- Not found โ ask:
"Live (ๅฎ็) or Demo (ๆจกๆ็)?" โ wait for answer before proceeding
Handling 401 Authentication Errors
If any command returns a 401 / authentication error:
- Stop immediately โ do not retry the same command
- Inform the user: "Authentication failed (401). Your API credentials may be invalid or expired."
- Guide the user to update credentials by editing the file directly with their local editor:
~/.okx/config.toml
Update the fields api_key, secret_key, passphrase under the relevant profile.
Do NOT paste the new credentials into chat.
- After the user confirms the file is updated, run
okx config show to verify (output is masked)
- Only then retry the original operation
Demo vs Live Mode
Profile is the single control for ๅฎ็/ๆจกๆ็ switching โ exactly two options:
--profile |
Mode |
Funds |
live |
ๅฎ็ |
Real funds |
demo |
ๆจกๆ็ |
Simulated funds |
okx --profile live account balance
okx --profile demo account balance
Rules:
- Read commands (balance, positions, bills, etc.): always state which profile was used
- Write commands (
transfer, set-position-mode): profile must be confirmed before execution (see "Credential & Profile Check" Step B); transfer especially โ wrong profile means wrong account
- Every response after a command must append:
[profile: live] or [profile: demo]
- Do not use the
--demo flag โ use --profile instead
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
okx account balance
okx account balance USDT
okx account asset-balance
okx account positions
okx account positions-history
okx account bills
okx account fees --instType SPOT
okx account transfer --ccy USDT --amt 100 --from 18 --to 6
Command Index
Read Commands
| # |
Command |
Type |
Description |
| 1 |
okx account balance [ccy] |
READ |
Trading account equity, available, frozen |
| 2 |
okx account asset-balance [ccy] [--valuation] |
READ |
Funding account balance; --valuation adds earn/trading/funding valuation summary |
| 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 0 โ Credential & Profile Check
Before any authenticated command:
Determine profile (required):
- Options:
live (ๅฎ็) or demo (ๆจกๆ็) โ exactly these two values
- Current message intent clear (e.g. "real"/"ๅฎ็"/"live" โ live; "test"/"ๆจกๆ"/"demo" โ demo) โ use it, inform user:
"Using --profile live (ๅฎ็)"
- Current message has no explicit declaration โ check conversation context for previous profile:
- Found โ use it, inform user:
"Continuing with --profile live (ๅฎ็) from earlier"
- Not found โ ask:
"Live (ๅฎ็) or Demo (ๆจกๆ็)?" โ wait for answer
If no credentials configured: guide user to run okx config init, stop all trading actions
After every command result: append [profile: live] or [profile: demo] to the response
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 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=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
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] [--json]
| Param |
Required |
Default |
Description |
ccy |
No |
- |
Filter to a single currency |
--valuation |
No |
false |
Also show total asset valuation across all account types (trading/funding/earn) |
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).
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