okx-cex-trade

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.

Prerequisites

1. Install okx CLI:

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

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
   

3. 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       # verify configuration status (output is masked)

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

1. 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 (模拟盘)"
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. 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.
4. After the user confirms the file is updated, run okx config show to verify (output is masked)
5. 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 money — irreversible
demo	模拟盘	Simulated — no real funds

okx --profile live  spot place ...    # 实盘 — real funds
okx --profile demo  spot place ...    # 模拟盘 — simulated funds

Rules:

1. --profile is required on every authenticated command — determined in "Credential & Profile Check" Step B
2. Every response after a command must append: [profile: live] or [profile: demo]
3. Do not use the --demo flag for mode switching — use --profile instead

Example

User: "Buy 0.01 BTC"
Agent: "Live (实盘) or Demo (模拟盘)?"
User: "Demo"
Agent runs: okx --profile demo spot place --instId BTC-USDT --side buy --ordType market --sz 0.01
Agent replies: "Order placed: 7890123456 (OK) — simulated, no real funds used. [profile: demo]"

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 Conversion Rules for Derivatives

Applies to all swap, futures, and option orders. --sz always means number of contracts, never a currency amount. Follow this flow before every derivative place order.

Step 1 — Identify contract type from instId

instId pattern	Contract type	Settlement	ctVal unit
*-USDT-SWAP	Linear perpetual swap	USDT	Base currency (BTC/ETH/…)
*-USDT-YYMMDD	Linear delivery futures	USDT	Base currency
*-USD-SWAP	Inverse perpetual swap	Base coin	USD (fixed, e.g. 100 USD)
*-USD-YYMMDD	Inverse delivery futures	Base coin	USD (fixed, e.g. 100 USD)
*-USD-YYMMDD-strike-C/P	Inverse option	Base coin	Base currency (e.g. 0.1 BTC)

Step 2 — Determine user's sz intent

User mentions a quantity:

1. Includes currency unit (USDT / USD / $ / ¥ / 元)
   → User is specifying a quote-currency amount → must convert to contracts (see Step 3)

2. Explicitly says "X contracts" / "X 张" / "X 手"
   → Use directly as sz, no conversion needed

3. Plain number with no unit (for swap/futures/option orders)
   → Ambiguous — ask before proceeding:
     "您输入的 X 是合约张数还是 USDT 金额？"
     (Is X the number of contracts or a USDT amount?)
     Wait for the user's answer before continuing.

Step 3 — Apply the correct conversion formula

Before running any formula, fetch the required data:

# Get ctVal, minSz, lotSz for the instrument
okx market instruments --instType <SWAP|FUTURES|OPTION> --instId <instId> --json

# Get current mark price (for linear contracts and options)
okx market mark-price --instType <SWAP|FUTURES|OPTION> --instId <instId> --json

A. Linear contracts (*-USDT-SWAP / *-USDT-YYMMDD)

ctVal unit: base currency (e.g. ETH)
markPx unit: USDT

Formula:  sz = floor(usdtAmt / (markPx × ctVal))

Example — ETH-USDT-SWAP (ctVal=0.1 ETH, markPx=2000 USDT):
  200 USDT → floor(200 / (2000 × 0.1)) = floor(1.0) = 1 contract  ✓
   50 USDT → floor(50  / (2000 × 0.1)) = floor(0.25) = 0          ✗ insufficient

B. Inverse contracts (*-USD-SWAP / *-USD-YYMMDD)

ctVal unit: USD (fixed face value, e.g. 100 USD per contract)
markPx is NOT needed for sz calculation

Formula:  sz = floor(usdtAmt / ctVal)   (1 USDT ≈ 1 USD)

Example — BTC-USD-SWAP (ctVal=100 USD):
  500 USDT → floor(500 / 100) = 5 contracts  ✓

⚠ Settlement warning (always show):
  "This is an inverse contract. Margin and P&L are settled in BTC, not USDT.
   Your USDT must be converted to BTC to meet margin requirements."

C. Inverse options (*-USD-YYMMDD-strike-C/P)

markPx unit: base currency (e.g. BTC per contract)
ctVal unit: base currency (e.g. 0.1 BTC)
Need BTC spot price to convert USDT → contracts

Required data:
  okx option greeks --uly <BTC-USD> --expTime <YYMMDD> --json  → markPx (BTC)
  okx market ticker BTC-USDT --json                            → last price (btcPx)

Formula (buyer cost):
  sz = floor(usdtAmt / (markPx_BTC × btcPx × ctVal))

Example — BTC-USD-250328-95000-C (markPx=0.005 BTC, btcPx=95000, ctVal=0.1 BTC):
  200 USDT → floor(200 / (0.005 × 95000 × 0.1))
           = floor(200 / 47.5) = floor(4.21) = 4 contracts
  Total premium ≈ 4 × 0.005 × 0.1 = 0.002 BTC ≈ 190 USDT

⚠ Always show both BTC and USDT premium cost to the buyer.
⚠ Seller margin is also in BTC — remind user of liquidation risk.

Step 4 — Validate and confirm before placing

After computing sz:

1. sz == 0 or sz < minSz
   → Reject. Inform user:
     "Amount too small: minimum order is {minSz} contract(s),
      equivalent to ~{minSz × markPx × ctVal} USDT."

2. sz not a multiple of lotSz
   → Round down to the nearest valid multiple:
     sz = floor(sz / lotSz) × lotSz

3. sz ≥ minSz
   → Show conversion summary and wait for user confirmation before placing:

     Conversion summary:
       Input:    {usdtAmt} USDT
       markPx:   {markPx}  |  ctVal: {ctVal}
       Raw:      {usdtAmt} / ({markPx} × {ctVal}) = {rawResult}
       Rounded:  {sz} contracts  (~{sz × markPx × ctVal} USDT actual value)
     Confirm order with sz={sz}?

Quickstart

# Market buy 0.01 BTC (spot)
okx spot place --instId BTC-USDT --side buy --ordType market --sz 0.01

# Limit sell 0.01 BTC at $100,000 (spot)
okx spot place --instId BTC-USDT --side sell --ordType limit --sz 0.01 --px 100000

# Long 1 contract BTC perp (cross margin)
okx swap place --instId BTC-USDT-SWAP --side buy --ordType market --sz 1 \
  --tdMode cross --posSide long

# Long 1 contract with attached TP/SL (one step)
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

# Close BTC perp long position entirely at market
okx swap close --instId BTC-USDT-SWAP --mgnMode cross --posSide long

# Set 10x leverage on BTC perp (cross)
okx swap leverage --instId BTC-USDT-SWAP --lever 10 --mgnMode cross

# --- Stock Token (TSLA, NVDA, etc.) ---
# Step 1: set leverage ≤ 5x (stock tokens max leverage is 5x)
okx swap leverage --instId TSLA-USDT-SWAP --lever 5 --mgnMode cross

# Step 2: open long on TSLA (--posSide required for stock tokens)
okx swap place --instId TSLA-USDT-SWAP --side buy --ordType market --sz 1 \
  --tdMode cross --posSide long

# Open short on NVDA
okx swap leverage --instId NVDA-USDT-SWAP --lever 3 --mgnMode cross
okx swap place --instId NVDA-USDT-SWAP --side sell --ordType market --sz 1 \
  --tdMode cross --posSide short

# Close TSLA long entirely at market
okx swap close --instId TSLA-USDT-SWAP --mgnMode cross --posSide long

# Set TP/SL on a spot BTC position (sell when price hits $105k, SL at $88k)
okx spot algo place --instId BTC-USDT --side sell --ordType oco --sz 0.01 \
  --tpTriggerPx 105000 --tpOrdPx -1 \
  --slTriggerPx 88000 --slOrdPx -1

# Place trailing stop on BTC perp long (callback 2%)
okx swap algo trail --instId BTC-USDT-SWAP --side sell --sz 1 \
  --tdMode cross --posSide long --callbackRatio 0.02

# Place trailing stop on spot BTC position (callback 2%)
okx spot algo trail --instId BTC-USDT --side sell --sz 0.01 --callbackRatio 0.02

# View open spot orders
okx spot orders

# View open swap positions
okx swap positions

# Cancel a spot order
okx spot cancel --instId BTC-USDT --ordId <ordId>

Command Index

Spot Orders

#	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

Swap / Perpetual Orders

#	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

Futures / Delivery Orders

#	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

Options Orders

#	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

Cross-Skill Workflows

Spot market buy

User: "Buy $500 worth of ETH at market"

1. okx-cex-market    okx market ticker ETH-USDT             → get current price to estimate sz
2. okx-cex-portfolio okx account balance USDT               → confirm available funds ≥ $500
        ↓ user approves
3. okx-cex-trade     okx spot place --instId ETH-USDT --side buy --ordType market --sz <sz>
4. okx-cex-trade     okx spot fills --instId ETH-USDT        → confirm fill price and size

Open long BTC perp with TP/SL

User: "Long 5 contracts BTC perp at market, TP at $105k, SL at $88k"

1. okx-cex-portfolio okx account balance USDT               → confirm margin available
2. okx-cex-portfolio okx account max-size --instId BTC-USDT-SWAP --tdMode cross → confirm size ok
        ↓ user approves
3. okx-cex-trade     okx swap place --instId BTC-USDT-SWAP --side buy \
                     

...