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. 1. Install okx CLI:

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

1. 2. 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
   

1. 3. Test with demo mode:

CODEBLOCK3

Credential & Profile Check

Run this check before any authenticated command.

Step A — Verify credentials

CODEBLOCK4

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

INLINECODE4 is required for all authenticated commands. Never add a profile implicitly.

Value	Mode	Funds
INLINECODE5	实盘	Real funds
INLINECODE6

模拟盘 | Simulated funds |

Resolution rules:

1. 1. Current message intent is clear (e.g. "real" / "实盘" / "live" → live; "test" / "模拟" / "demo" → demo) → use it and inform the user: "Using --profile live (实盘)" or INLINECODE10
2. 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:

1. 1. Stop immediately — do not retry the same command
2. Inform the user: "Authentication failed (401). Your API credentials may be invalid or expired."
3. 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.

1. 4. After the user confirms the file is updated, run okx config show to verify (output is masked)
2. Only then retry the original operation

Demo vs Live Mode

Profile is the single control for 实盘/模拟盘 switching — exactly two options:

INLINECODE17	Mode	Funds
INLINECODE18	实盘	Real funds
INLINECODE19

模拟盘 | Simulated funds |

CODEBLOCK6

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 INLINECODE23
• Do not use the --demo flag — use --profile instead

Skill Routing

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

Quickstart

CODEBLOCK7

Command Index

Read Commands

#	Command	Type	Description
1	INLINECODE30	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	INLINECODE41	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?"

CODEBLOCK8

Pre-bot balance check

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

CODEBLOCK9

Review open positions and P&L

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

CODEBLOCK10

Transfer and trade

User: "Move 500 USDT from my funding account to trade BTC"

CODEBLOCK11

Check max position size before entering

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

CODEBLOCK12

Operation Flow

Step 0 — Credential & Profile Check

Before any authenticated command:

Determine profile (required):

• - Options: live (实盘) or demo (模拟盘) — exactly these two values

1. 1. Current message intent clear (e.g. "real"/"实盘"/"live" → live; "test"/"模拟"/"demo" → demo) → use it, inform user: INLINECODE45
2. 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 → INLINECODE53
• View closed positions + PnL → INLINECODE54
• View transaction history → INLINECODE55
• Check fee tier → INLINECODE56
• Check account settings → INLINECODE57
• Calculate order size → okx account max-size or INLINECODE59
• Check withdrawal limit → INLINECODE60
• Transfer funds → INLINECODE61
• Change position mode → INLINECODE62

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, INLINECODE66
• INLINECODE67 for fees/positions: SPOT, SWAP, FUTURES, INLINECODE71
• INLINECODE72 for bills: access older records beyond the default window
• INLINECODE73 for max-size: cash (spot), cross, or INLINECODE76

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
• INLINECODE80: 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

Account Balance — Trading Account

CODEBLOCK13

Param	Required	Default	Description
INLINECODE93	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

CODEBLOCK14

Param	Required	Default	Description
INLINECODE99	No	-	Filter to a single currency
INLINECODE100

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

CODEBLOCK15

Param	Required	Default	Description
INLINECODE107	No	-	Filter: SWAP, FUTURES, INLINECODE110
INLINECODE111

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

CODEBLOCK16

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

---

Bills — Account Ledger

CODEBLOCK17

Param	Required	Default	Description
INLINECODE125	No	false	Access older records (archive endpoint)
INLINECODE126

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

CODEBLOCK18

Param	Required	Default	Description
INLINECODE136	Yes	-	INLINECODE137, SWAP, FUTURES, INLINECODE140
INLINECODE141

No | - | Specific instrument (optional) |

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

---

Config — Account Configuration

CODEBLOCK19

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

---

Max Size — Maximum Order Size

CODEBLOCK20

Param	Required	Default	Description
INLINECODE155	Yes	-	Instrument ID
INLINECODE156

Yes | - | cash (spot), cross, or isolated |
| --px | No | - | Reference price (uses mark price if omitted) |

Returns: instId, maxBuy, maxSell.

---

Max Available Size

CODEBLOCK21

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

---

Max Withdrawal

CODEBLOCK22

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

---

Set Position Mode

CODEBLOCK23

Value	Behavior
INLINECODE170	One-directional (default) — long and short net out
INLINECODE171

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

CODEBLOCK24

Param	Required	Default	Description
INLINECODE173	Yes	-	Currency to transfer (e.g., USDT)
INLINECODE175

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
INLINECODE191	Trading account balance
INLINECODE192

Funding account balance. Use showValuation=true to include total asset valuation across trading/funding/earn accounts. |
| 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?"
CODEBLOCK25

"Show all my open positions"
CODEBLOCK26

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

"Show my recent account activity"
CODEBLOCK28

"What are my trading fees for SWAP?"
CODEBLOCK29

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

"Transfer 200 USDT from funding to trading"
CODEBLOCK31

"Check my account config"
CODEBLOCK32

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 --profile demo account balance shows simulated balances, not real funds

Global Notes

• - All write commands require valid credentials in ~/.okx/config.toml or env vars
• INLINECODE213 is required for all authenticated commands; see "Credential & Profile Check" section
• Every command result includes a [profile: <name>] tag for audit reference
• INLINECODE215 returns the raw OKX API v5 response by default. Add --env to wrap the output as INLINECODE217
• 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)