OKX CEX Trading CLI
Spot, perpetual swap, delivery futures, and options order management on OKX exchange. Place, cancel, amend, and monitor orders; query option chains and Greeks; set take-profit/stop-loss and trailing stops; manage leverage and positions. 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 (simulated trading, no real funds):
okx --profile demo spot orders
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:
--profile |
Mode |
Funds |
live |
ๅฎ็ |
Real money โ irreversible |
demo |
ๆจกๆ็ |
Simulated โ no real funds |
Rules:
--profile is required on every authenticated command โ determined in "Credential & Profile Check" Step B
- Every response after a command must append:
[profile: live] or [profile: demo]
- Do not use the
--demo flag for mode switching โ 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
- For regular spot/swap/futures/options/algo orders โ use
okx-cex-trade (this skill)
- For grid and DCA trading bots โ use
okx-cex-bot
Sz Handling for Derivatives
โ CRITICAL: Always verify contract face value before placing orders
Before placing any SWAP/FUTURES/OPTION order, call market_get_instruments to get ctVal (contract face value). Do NOT assume contract sizes โ they vary by instrument (e.g. ETH-USDT-SWAP = 0.1 ETH/contract, BTC-USDT-SWAP = 0.01 BTC/contract).
Use ctVal to:
- Calculate the correct number of contracts from user's intended position size
- Verify margin requirements before submitting the order
- Show the user the actual position value:
sz ร ctVal ร price
SWAP and FUTURES orders
When user specifies a USDT amount (e.g. "200U", "500 USDT", "$1000"):
โ Use --tgtCcy quote_ccy and pass the amount directly as --sz. The API converts to contracts automatically.
When user specifies contracts (e.g. "2 ๅผ ", "5 contracts"):
โ First verify ctVal via market_get_instruments, then use --sz with the contract count. Confirm with user: "X contracts = X ร ctVal underlying, total value โ $Y".
When user gives a plain number with no unit (for swap/futures):
โ Ambiguous โ ask before proceeding: "ๆจ่พๅ
ฅ็ X ๆฏๅ็บฆๅผ ๆฐ่ฟๆฏ USDT ้้ข๏ผ" Wait for the user's answer before continuing.
โ Inverse contracts (*-USD-SWAP, *-USD-YYMMDD): tgtCcy=quote_ccy also works (note: quote_ccy = USD, not USDT, for inverse instruments). Always warn: "This is an inverse contract. Margin and P&L are settled in BTC, not USDT."
Option orders
Options do NOT support tgtCcy. When the user specifies a USDT amount for options, you must convert manually. For the full conversion formula and validation steps, read {baseDir}/references/options-commands.md.
Quickstart
okx spot place --instId BTC-USDT --side buy --ordType market --sz 0.01
okx spot place --instId SOL-USDT --side buy --ordType market --sz 10 --tgtCcy quote_ccy
okx spot place --instId BTC-USDT --side sell --ordType limit --sz 0.01 --px 100000
okx swap place --instId BTC-USDT-SWAP --side buy --ordType market --sz 1 \
--tdMode cross --posSide long
okx swap place --instId BTC-USDT-SWAP --side buy --ordType market --sz 1000 \
--tgtCcy quote_ccy --tdMode cross --posSide long
okx swap place --instId BTC-USDT-SWAP --side buy --ordType market --sz 1 \
--tdMode cross --posSide long \
--tpTriggerPx 105000 --tpOrdPx -1 --slTriggerPx 88000 --slOrdPx -1
okx swap close --instId BTC-USDT-SWAP --mgnMode cross --posSide long
okx swap leverage --instId BTC-USDT-SWAP --lever 10 --mgnMode cross
okx spot algo place --instId BTC-USDT --side sell --ordType oco --sz 0.01 \
--tpTriggerPx 105000 --tpOrdPx -1 \
--slTriggerPx 88000 --slOrdPx -1
okx swap algo trail --instId BTC-USDT-SWAP --side sell --sz 1 \
--tdMode cross --posSide long --callbackRatio 0.02
okx spot orders
okx swap positions
okx spot cancel --instId BTC-USDT --ordId <ordId>
Command Index
Spot Orders (11 commands)
| # |
Command |
Type |
Description |
| 1 |
okx spot place |
WRITE |
Place spot order (market/limit/post_only/fok/ioc) |
| 2 |
okx spot cancel |
WRITE |
Cancel spot order |
| 3 |
okx spot amend |
WRITE |
Amend spot order price or size |
| 4 |
okx spot algo place |
WRITE |
Place spot TP/SL algo order |
| 5 |
okx spot algo amend |
WRITE |
Amend spot TP/SL levels |
| 6 |
okx spot algo cancel |
WRITE |
Cancel spot algo order |
| 7 |
okx spot algo trail |
WRITE |
Place spot trailing stop order |
| 8 |
okx spot orders |
READ |
List open or historical spot orders |
| 9 |
okx spot get |
READ |
Single spot order details |
| 10 |
okx spot fills |
READ |
Spot trade fill history |
| 11 |
okx spot algo orders |
READ |
List spot TP/SL algo orders |
For full command syntax, parameter tables, and edge cases, read {baseDir}/references/spot-commands.md.
Swap / Perpetual Orders (15 commands)
| # |
Command |
Type |
Description |
| 12 |
okx swap place |
WRITE |
Place perpetual swap order |
| 13 |
okx swap cancel |
WRITE |
Cancel swap order |
| 14 |
okx swap amend |
WRITE |
Amend swap order price or size |
| 15 |
okx swap close |
WRITE |
Close entire position at market |
| 16 |
okx swap leverage |
WRITE |
Set leverage for an instrument |
| 17 |
okx swap algo place |
WRITE |
Place swap TP/SL algo order |
| 18 |
okx swap algo trail |
WRITE |
Place swap trailing stop order |
| 19 |
okx swap algo amend |
WRITE |
Amend swap algo order |
| 20 |
okx swap algo cancel |
WRITE |
Cancel swap algo order |
| 21 |
okx swap positions |
READ |
Open perpetual swap positions |
| 22 |
okx swap orders |
READ |
List open or historical swap orders |
| 23 |
okx swap get |
READ |
Single swap order details |
| 24 |
okx swap fills |
READ |
Swap trade fill history |
| 25 |
okx swap get-leverage |
READ |
Current leverage settings |
| 26 |
okx swap algo orders |
READ |
List swap algo orders |
For full command syntax, parameter tables, and edge cases, read {baseDir}/references/swap-commands.md.
Futures / Delivery Orders (15 commands)
| # |
Command |
Type |
Description |
| 27 |
okx futures place |
WRITE |
Place delivery futures order |
| 28 |
okx futures cancel |
WRITE |
Cancel delivery futures order |
| 29 |
okx futures amend |
WRITE |
Amend delivery futures order price or size |
| 30 |
okx futures close |
WRITE |
Close entire futures position at market |
| 31 |
okx futures leverage |
WRITE |
Set leverage for a futures instrument |
| 32 |
okx futures algo place |
WRITE |
Place futures TP/SL algo order |
| 33 |
okx futures algo trail |
WRITE |
Place futures trailing stop order |
| 34 |
okx futures algo amend |
WRITE |
Amend futures algo order |
| 35 |
okx futures algo cancel |
WRITE |
Cancel futures algo order |
| 36 |
okx futures orders |
READ |
List delivery futures orders |
| 37 |
okx futures positions |
READ |
Open delivery futures positions |
| 38 |
okx futures fills |
READ |
Delivery futures fill history |
| 39 |
okx futures get |
READ |
Single delivery futures order details |
| 40 |
okx futures get-leverage |
READ |
Current futures leverage settings |
| 41 |
okx futures algo orders |
READ |
List futures algo orders |
For full command syntax, parameter tables, and edge cases, read {baseDir}/references/futures-commands.md.
Options Orders (10 commands)
| # |
Command |
Type |
Description |
| 42 |
okx option instruments |
READ |
Option chain: list available contracts for an underlying |
| 43 |
okx option greeks |
READ |
Implied volatility + Greeks (delta/gamma/theta/vega) by underlying |
| 44 |
okx option place |
WRITE |
Place option order (call or put, buyer or seller) |
| 45 |
okx option cancel |
WRITE |
Cancel unfilled option order |
| 46 |
okx option amend |
WRITE |
Amend option order price or size |
| 47 |
okx option batch-cancel |
WRITE |
Batch cancel up to 20 option orders |
| 48 |
okx option orders |
READ |
List option orders (live / history / archive) |
| 49 |
okx option get |
READ |
Single option order details |
| 50 |
okx option positions |
READ |
Open option positions with live Greeks |
| 51 |
okx option fills |
READ |
Option trade fill history |
For full command syntax, USDT-to-contracts conversion formula, tdMode rules, and edge cases, read {baseDir}/references/options-commands.md.
Operation Flow
Step 0 โ Credential & Profile Check
Before any authenticated command: see Credential & Profile Check. Determine profile (live or demo) before executing.
After every command result: append [profile: live] or [profile: demo].
Step 1 โ Identify instrument type and action
Spot (instId format: BTC-USDT):
- Place/cancel/amend order โ
okx spot place/cancel/amend
- TP/SL conditional โ
okx spot algo place/amend/cancel
- Trailing stop โ
okx spot algo trail
- Query โ
okx spot orders/get/fills/algo orders
Swap/Perpetual (instId format: BTC-USDT-SWAP):
- Place/cancel/amend order โ
okx swap place/cancel/amend
- Close position โ
okx swap close
- Leverage โ
okx swap leverage / okx swap get-leverage
- TP/SL conditional โ
okx swap algo place/amend/cancel
- Trailing stop โ
okx swap algo trail
- Query โ
okx swap positions/orders/get/fills/get-leverage/algo orders
Futures/Delivery (ins