🇺🇸English

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.

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:

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

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

# Buy $10 worth of SOL (spot, USDT amount)
okx spot place --instId SOL-USDT --side buy --ordType market --sz 10 --tgtCcy quote_ccy

# 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 | | 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 | | READ | List open or historical swap orders 23 | | READ | Single swap order details 24 | | READ | Swap trade fill history 25 | | READ | Current leverage settings 26 | | 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 | | READ | List delivery futures orders 37 | | READ | Open delivery futures positions 38 | | READ | Delivery futures fill history 39 | | READ | Single delivery futures order details 40 | | READ | Current futures leverage settings 41 | | 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 | | READ | Option trade fill history

Cross-Skill Workflows

Spot market buy

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

1. okx-cex-portfolio okx account balance USDT               → confirm available funds ≥ $500
        ↓ user approves
2. okx-cex-trade     okx spot place --instId ETH-USDT --side buy --ordType market --sz 500 --tgtCcy quote_ccy
3. 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 \
                       --ordType market --sz 5 --tdMode cross --posSide long \
                       --tpTriggerPx 105000 --tpOrdPx -1 \
                       --slTriggerPx 88000 --slOrdPx -1
4. okx-cex-trade     okx swap positions                     → confirm position opened

Note: TP/SL is attached directly to the order via --tpTriggerPx/--slTriggerPx — no separate swap algo place step needed. Use swap algo place only when adding TP/SL to an existing position.

Adjust leverage then place order

User: "Set BTC perp to 5x leverage then go long 10 contracts"

1. okx-cex-trade     okx swap get-leverage --instId BTC-USDT-SWAP --mgnMode cross → check current lever
        ↓ user approves change
2. okx-cex-trade     okx swap leverage --instId BTC-USDT-SWAP --lever 5 --mgnMode cross
3. okx-cex-trade     okx swap place --instId BTC-USDT-SWAP --side buy \
                       --ordType market --sz 10 --tdMode cross --posSide long
4. okx-cex-trade     okx swap positions                     → confirm position + leverage

Place trailing stop on open position

User: "Set a 3% trailing stop on my open position"

Spot example (no margin mode needed):

1. okx-cex-portfolio okx account balance BTC               → confirm spot BTC holdings
2. okx-cex-market    okx market ticker BTC-USDT            → current price reference
        ↓ user approves
3. okx-cex-trade     okx spot algo trail --instId BTC-USDT --side sell \
                       --sz <spot_sz> --callbackRatio 0.03
4. okx-cex-trade     okx spot algo orders --instId BTC-USDT → confirm trail order placed

Swap/Perpetual example:

1. okx-cex-trade     okx swap positions                     → confirm size of open long
2. okx-cex-market    okx market ticker BTC-USDT-SWAP        → current price reference
        ↓ user approves
3. okx-cex-trade     okx swap algo trail --instId BTC-USDT-SWAP --side sell \
                       --sz <pos_size> --tdMode cross --posSide long --callbackRatio 0.03
4. okx-cex-trade     okx swap algo orders --instId BTC-USDT-SWAP → confirm trail order placed

Futures/Delivery example:

1. okx-cex-trade     okx futures positions                  → confirm size of open long
2. okx-cex-market    okx market ticker BTC-USDT-<YYMMDD>      → current price reference
        ↓ user approves
3. okx-cex-trade     okx futures algo trail --instId BTC-USDT-<YYMMDD> --side sell \
                       --sz <pos_size> --tdMode cross --posSide long --callbackRatio 0.03
4. okx-cex-trade     okx futures algo orders --instId BTC-USDT-<YYMMDD> → confirm trail order placed

Trade a stock token (TSLA / NVDA / AAPL)

User: "I want to long TSLA with 500 USDT"

1. okx-cex-market   okx market stock-tokens              → confirm TSLA-USDT-SWAP is available
2. okx-cex-market   okx market ticker TSLA-USDT-SWAP     → current price (e.g., markPx=310 USDT)
3. okx-cex-market   okx market instruments --instType SWAP --instId TSLA-USDT-SWAP --json
                    → ctVal=1, minSz=1, lotSz=1
   Agent computes:  sz = floor(500 / (310 × 1)) = 1 contract (~310 USDT)
   Agent shows conversion summary and asks to confirm

        ↓ user confirms

4. okx-cex-portfolio okx account balance USDT            → confirm margin available
5. okx-cex-trade    okx swap get-leverage --instId TSLA-USDT-SWAP --mgnMode cross
                    → check current leverage; must be ≤ 5x
   (if not set or > 5x) okx swap leverage --instId TSLA-USDT-SWAP --lever 5 --mgnMode cross
6. okx-cex-trade    okx swap place --instId TSLA-USDT-SWAP --side buy --ordType market \
                      --sz 1 --tdMode cross --posSide long
7. okx-cex-trade    okx swap positions TSLA-USDT-SWAP    → confirm position opened

⚠ Stock token constraints : max leverage 5x (exchange rejects > 5x). --posSide is required. Trading follows stock market hours — confirm live ticker before placing.

---

Open linear swap by USDT amount

User: "用 200 USDT 做多 ETH 永续 (cross margin)"

1. okx-cex-market  okx market instruments --instType SWAP --instId ETH-USDT-SWAP --json
                   → ctVal=0.1 ETH, minSz=1, lotSz=1

2. okx-cex-market  okx market mark-price --instType SWAP --instId ETH-USDT-SWAP --json
                   → markPx=2000 USDT

3. Agent computes:  sz = floor(200 / (2000 × 0.1)) = 1 contract (~200 USDT)
   Agent informs user of conversion summary and asks to confirm

        ↓ user confirms

4. okx-cex-trade   okx swap place --instId ETH-USDT-SWAP --side buy --ordType market \
                     --sz 1 --tdMode cross --profile <live|demo>

5. okx-cex-trade   okx swap positions ETH-USDT-SWAP    → confirm position opened

Open inverse swap by USDT amount

User: "用 500 USDT 开一个 BTC 币本位永续多单"

1. okx-cex-market  okx market instruments --instType SWAP --instId BTC-USD-SWAP --json
                   → ctVal=100 USD, minSz=1

2. Agent computes:  sz = floor(500 / 100) = 5 contracts
   Agent warns:    "BTC-USD-SWAP 是币本位合约，保证金和盈亏以 BTC 结算，非 USDT。
                    请确认账户有足够 BTC 作为保证金。"
   Agent shows conversion summary and asks to confirm

        ↓ user confirms

3. okx-cex-trade   okx swap place --instId BTC-USD-SWAP --side buy --ordType market \
                     --sz 5 --tdMode cross --profile <live|demo>

4. okx-cex-trade   okx swap positions BTC-USD-SWAP    → confirm position opened

Cancel all open spot orders

User: "Cancel all my open BTC spot orders"

1. okx-cex-trade     okx spot orders                        → list open orders
2. okx-cex-trade     (for each ordId) okx spot cancel --instId BTC-USDT --ordId <id>
3. okx-cex-trade     okx spot orders                        → confirm all cancelled

Buy a BTC call option

User: "Buy 2 BTC call options at strike 95000 expiring end of March"

1. okx-cex-trade     okx option instruments --uly BTC-USD --expTime 250328
                     → find exact instId (e.g. BTC-USD-250328-95000-C)
2. okx-cex-trade     okx option greeks --uly BTC-USD --expTime 250328
                     → check IV, delta, and markPx to assess fair value
3. okx-cex-portfolio okx account balance                    → confirm enough USDT/BTC for premium
        ↓ user approves
4. okx-cex-trade     okx option place --instId BTC-USD-250328-95000-C \
                       --side buy --ordType limit --tdMode cash --sz 2 --px 0.005
5. okx-cex-trade     okx option orders                      → confirm order is live

Check option portfolio Greeks

User: "What's my total delta exposure from options?"

1. okx-cex-trade     okx option positions                   → live positions with per-contract Greeks
2. okx-cex-market    okx market ticker BTC-USD              → current spot price for context

Operation Flow

Step 0 — Credential & Profile Check

Before any authenticated command:

Determine profile (required):

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

1. Current message intent clear (e.g. "real"/"实盘"/"live" → live; "test"/"模拟"/"demo" → demo) → use it, inform user: "Using --profile live (实盘)"
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 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 (instId format: BTC-USDT-<YYMMDD>):

• Place/cancel/amend order → okx futures place/cancel/amend
• Close position → okx futures close
• Leverage → okx futures leverage / okx futures get-leverage
• TP/SL conditional → okx futures algo place/amend/cancel
• Trailing stop → okx futures algo trail
• Query → okx futures orders/positions/fills/get/get-leverage/algo orders

Options (instId format: BTC-USD-250328-95000-C or ...-P):

• Step 1 (required): find valid instId → okx option instruments --uly BTC-USD
• Step 2 (recommended): check IV and Greeks → okx option greeks --uly BTC-USD
• Place/cancel/amend order → okx option place/cancel/amend
• Batch cancel → okx option batch-cancel --orders '[...]'
• Query → okx option orders/get/positions/fills
• tdMode : cash for buyers (full premium upfront, no liquidation risk); cross or isolated for sellers (margin required)

Step 2: Confirm profile (determined in Step 0), then confirm write parameters

Read commands (orders, positions, fills, get, get-leverage, algo orders): run immediately; note the profile used.

• --history flag: defaults to active/open; use --history only if user explicitly asks for history
• --ordType for algo: conditional = single TP or SL; oco = both TP and SL together
• --tdMode for swap/futures: cross or isolated; spot always uses cash (set automatically)
• --posSide for hedge mode: long or ; omit in net mode

Write commands (place, cancel, amend, close, leverage, algo): two confirmations required:

1. Profile — determined in Step 0; use --profile live (实盘) or --profile demo (模拟盘)
2. Confirm parameters — confirm the key order details once before executing:
   • Spot place: confirm --instId, --side, --ordType, --sz; price (--px) required for limit orders; optionally attach TP/SL with --tpTriggerPx/--slTriggerPx
   • Swap/Futures/Option place: before confirming, apply "Sz Conversion Rules for Derivatives" — if the user's input was a USDT amount, resolve it to contracts first, show the conversion summary, and use the computed in the confirmation; confirm , , , ; confirm if in hedge mode; optionally attach TP/SL with /

Step 3: Verify after writes

• After spot place: run okx spot orders to confirm order is live or okx spot fills if market order
• After swap place: run okx swap orders or okx swap positions to confirm
• After swap close: run okx swap positions to confirm position size is 0
• After futures place: run okx futures orders or okx futures positions to confirm

CLI Command Reference

Order Type Reference

---

Spot — Place Order

okx spot place --instId <id> --side <buy|sell> --ordType <type> --sz <n> \
  [--tgtCcy <base_ccy|quote_ccy>] [--px <price>] \
  [--tpTriggerPx <p>] [--tpOrdPx <p|-1>] \
  [--slTriggerPx <p>] [--slOrdPx <p|-1>] \
  [--json]

---

Spot — Cancel Order

okx spot cancel --instId <id> --ordId <id> [--json]

---

Spot — Amend Order

okx spot amend --instId <id> [--ordId <id>] [--clOrdId <id>] \
  [--newSz <n>] [--newPx <p>] [--json]

Must provide at least one of --newSz or --newPx.

---

Spot — Place Algo (TP/SL / Trail)

okx spot algo place --instId <id> --side <buy|sell> \
  --ordType <oco|conditional|move_order_stop> --sz <n> \
  [--tpTriggerPx <p>] [--tpOrdPx <p|-1>] \
  [--slTriggerPx <p>] [--slOrdPx <p|-1>] \
  [--callbackRatio <r>] [--callbackSpread <s>] [--activePx <p>] \
  [--json]

For oco: provide both TP and SL params. For conditional: provide only TP or only SL. For move_order_stop: provide --callbackRatio or --callbackSpread (one required).

---

Spot — Amend Algo

okx spot algo amend --instId <id> --algoId <id> \
  [--newSz <n>] [--newTpTriggerPx <p>] [--newTpOrdPx <p>] \
  [--newSlTriggerPx <p>] [--newSlOrdPx <p>] [--json]

---

Spot — Cancel Algo

okx spot algo cancel --instId <id> --algoId <id> [--json]

---

Spot — Place Trailing Stop

okx spot algo trail --instId <id> --side <buy|sell> --sz <n> \
  [--callbackRatio <ratio>] [--callbackSpread <spread>] \
  [--activePx <price>] \
  [--json]

Spot trailing stop does not require --tdMode or --posSide (spot has no margin mode or position side concept).

---

Spot — List Orders

okx spot orders [--instId <id>] [--history] [--json]

---

Spot — Get Order

okx spot get --instId <id> [--ordId <id>] [--clOrdId <id>] [--json]

Returns: ordId, instId, side, ordType, px, sz, fillSz, avgPx, state, cTime.

---

Spot — Fills

okx spot fills [--instId <id>] [--ordId <id>] [--json]

Returns: instId, side, fillPx, fillSz, fee, ts.

---

Spot — Algo Orders

okx spot algo orders [--instId <id>] [--history] [--ordType <type>] [--json]

Returns: algoId, instId, type, side, sz, tpTrigger, slTrigger, state.

---

Swap — Place Order

okx swap place --instId <id> --side <buy|sell> --ordType <type> --sz <n> \
  --tdMode <cross|isolated> \
  [--tgtCcy <base_ccy|quote_ccy>] \
  [--posSide <long|short>] [--px <price>] \
  [--tpTriggerPx <p>] [--tpOrdPx <p|-1>] \
  [--slTriggerPx <p>] [--slOrdPx <p|-1>] \
  [--json]

---

Swap — Cancel Order

okx swap cancel --instId <id> --ordId <id> [--json]

---

Swap — Amend Order

okx swap amend --instId <id> [--ordId <id>] [--clOrdId <id>] \
  [--newSz <n>] [--newPx <p>] [--json]

---

Swap — Close Position

okx swap close --instId <id> --mgnMode <cross|isolated> \
  [--posSide <long|short>] [--autoCxl] [--json]

Closes the entire position at market price.

---

Swap — Set Leverage

okx swap leverage --instId <id> --lever <n> --mgnMode <cross|isolated> \
  [--posSide <long|short>] [--json]

⚠ Stock tokens (e.g., TSLA-USDT-SWAP): maximum leverage is 5x. The exchange will reject --lever values above 5 for stock token instruments.

---

Swap — Get Leverage

okx swap get-leverage --instId <id> --mgnMode <cross|isolated> [--json]

Returns table: instId, mgnMode, posSide, lever.

---

Swap — Place Algo (TP/SL / Trail)

okx swap algo place --instId <id> --side <buy|sell> \
  --ordType <oco|conditional|move_order_stop> --sz <n> \
  --tdMode <cross|isolated> \
  [--posSide <long|short>] [--reduceOnly] \
  [--tpTriggerPx <p>] [--tpOrdPx <p|-1>] \
  [--slTriggerPx <p>] [--slOrdPx <p|-1>] \
  [--callbackRatio <r>] [--callbackSpread <s>] [--activePx <p>] \
  [--json]

For move_order_stop: provide --callbackRatio or --callbackSpread (one required).

---

Swap — Place Trailing Stop

okx swap algo trail --instId <id> --side <buy|sell> --sz <n> \
  --tdMode <cross|isolated> \
  [--posSide <long|short>] [--reduceOnly] \
  [--callbackRatio <ratio>] [--callbackSpread <spread>] \
  [--activePx <price>] \
  [--json]

---

Swap — Amend Algo

okx swap algo amend --instId <id> --algoId <id> \
  [--newSz <n>] [--newTpTriggerPx <p>] [--newTpOrdPx <p>] \
  [--newSlTriggerPx <p>] [--newSlOrdPx <p>] [--json]

---

Swap — Cancel Algo

okx swap algo cancel --instId <id> --algoId <id> [--json]

---

Swap — List Orders

okx swap orders [--instId <id>] [--history] [--json]

---

Swap — Get Order

okx swap get --instId <id> [--ordId <id>] [--clOrdId <id>] [--json]

Returns: ordId, instId, side, posSide, ordType, px, sz, fillSz, avgPx, state, cTime.

---

Swap — Positions

okx swap positions [<instId>] [--json]

Returns: instId, side, size, avgPx, upl, uplRatio, lever. Only non-zero positions.

---

Swap — Fills

okx swap fills [--instId <id>] [--ordId <id>] [--archive] [--json]

--archive: access older fills beyond the default window.

---

Swap — Algo Orders

okx swap algo orders [--instId <id>] [--history] [--ordType <type>] [--json]

---

Futures — Place Order

okx futures place --instId <id> --side <buy|sell> --ordType <type> --sz <n> \
  --tdMode <cross|isolated> \
  [--tgtCcy <base_ccy|quote_ccy>] \
  [--posSide <long|short>] [--px <price>] [--reduceOnly] \
  [--tpTriggerPx <p>] [--tpOrdPx <p|-1>] \
  [--slTriggerPx <p>] [--slOrdPx <p|-1>] \
  [--json]

--instId format: BTC-USDT-<YYMMDD> (delivery date suffix).

---

Futures — Cancel Order

okx futures cancel --instId <id> --ordId <id> [--json]

---

Futures — Amend Order

okx futures amend --instId <id> [--ordId <id>] [--clOrdId <id>] \
  [--newSz <n>] [--newPx <p>] [--json]

Must provide at least one of --newSz or --newPx.

---

Futures — Close Position

okx futures close --instId <id> --mgnMode <cross|isolated> \
  [--posSide <long|short>] [--autoCxl] [--json]

Closes the entire position at market price.

---

Futures — Set Leverage

okx futures leverage --instId <id> --lever <n> --mgnMode <cross|isolated> \
  [--posSide <long|short>] [--json]

---

Futures — Get Leverage

okx futures get-leverage --instId <id> --mgnMode <cross|isolated> [--json]

Returns table: instId, mgnMode, posSide, lever.

---

Futures — List Orders

okx futures orders [--instId <id>] [--status <open|history|archive>] [--json]

---

Futures — Positions

okx futures positions [<instId>] [--json]

Returns: instId, side, pos, avgPx, upl, lever.

---

Futures — Fills

okx futures fills [--instId <id>] [--ordId <id>] [--archive] [--json]

---

Futures — Get Order

okx futures get --instId <id> [--ordId <id>] [--json]

---

Futures — Place Algo (TP/SL / Trail)

okx futures algo place --instId <id> --side <buy|sell> \
  --ordType <oco|conditional|move_order_stop> --sz <n> \
  --tdMode <cross|isolated> \
  [--posSide <long|short>] [--reduceOnly] \
  [--tpTriggerPx <p>] [--tpOrdPx <p|-1>] \
  [--slTriggerPx <p>] [--slOrdPx <p|-1>] \
  [--callbackRatio <r>] [--callbackSpread <s>] [--activePx <p>] \
  [--json]

--instId format: BTC-USDT-<YYMMDD> (e.g., BTC-USDT-250328). For move_order_stop: provide --callbackRatio or --callbackSpread (one required).

---

Futures — Place Trailing Stop

okx futures algo trail --instId <id> --side <buy|sell> --sz <n> \
  --tdMode <cross|isolated> \
  [--posSide <long|short>] [--reduceOnly] \
  [--callbackRatio <ratio>] [--callbackSpread <spread>] \
  [--activePx <price>] \
  [--json]

---

Futures — Amend Algo

okx futures algo amend --instId <id> --algoId <id> \
  [--newSz <n>] [--newTpTriggerPx <p>] [--newTpOrdPx <p>] \
  [--newSlTriggerPx <p>] [--newSlOrdPx <p>] [--json]

---

Futures — Cancel Algo

okx futures algo cancel --instId <id> --algoId <id> [--json]

---

Futures — Algo Orders

okx futures algo orders [--instId <id>] [--history] [--ordType <type>] [--json]

---

Option — Get Instruments (Option Chain)

okx option instruments --uly <underlying> [--expTime <YYMMDD>] [--json]

Returns: instId, uly, expTime, stk (strike), optType (C/P), state.

Run this before placing any option order to get the exact instId.

---

Option — Get Greeks

okx option greeks --uly <underlying> [--expTime <YYMMDD>] [--json]

Returns IV (markVol) and BS Greeks (deltaBS, gammaBS, thetaBS, vegaBS) plus markPx for each contract.

---

Option — Place Order

okx option place --instId <id> --side <buy|sell> --ordType <type> \
  --tdMode <cash|cross|isolated> --sz <n> \
  [--px <price>] [--reduceOnly] [--clOrdId <id>] [--json]

tdMode rules:

• Buyer (side=buy): always use cash — pay full premium, no margin call risk
• Seller (side=sell): use cross or isolated — margin required, liquidation risk

---

Option — Cancel Order

okx option cancel --instId <id> [--ordId <id>] [--clOrdId <id>] [--json]

---

Option — Amend Order

okx option amend --instId <id> [--ordId <id>] [--clOrdId <id>] \
  [--newSz <n>] [--newPx <p>] [--json]

Must provide at least one of --newSz or --newPx.

---

Option — Batch Cancel

okx option batch-cancel --orders '<JSON>' [--json]

--orders is a JSON array of up to 20 objects, each {"instId":"...","ordId":"..."}:

okx option batch-cancel --orders '[{"instId":"BTC-USD-250328-95000-C","ordId":"123"},{"instId":"BTC-USD-250328-90000-P","ordId":"456"}]'

---

Option — List Orders

okx option orders [--instId <id>] [--uly <underlying>] [--history] [--archive] [--json]

---

Option — Get Order

okx option get --instId <id> [--ordId <id>] [--clOrdId <id>] [--json]

Returns: ordId, instId, side, ordType, px, sz, fillSz, avgPx, state, cTime.

---

Option — Positions

okx option positions [--instId <id>] [--uly <underlying>] [--json]

Returns: instId, posSide, pos, avgPx, upl, deltaPA, gammaPA, thetaPA, vegaPA. Only non-zero positions shown.

---

Option — Fills

okx option fills [--instId <id>] [--ordId <id>] [--archive] [--json]

--archive: access fills beyond the default 3-day window (up to 3 months).

---

MCP Tool Reference

---

Input / Output Examples

"Buy 0.05 BTC at market"

okx spot place --instId BTC-USDT --side buy --ordType market --sz 0.05
# → Order placed: 7890123456 (OK)

"Set a limit sell for 0.1 ETH at $3500"

okx spot place --instId ETH-USDT --side sell --ordType limit --sz 0.1 --px 3500
# → Order placed: 7890123457 (OK)

"Show my open spot orders"

okx spot orders
# → table: ordId, instId, side, type, price, size, filled, state

"Long 10 contracts BTC perp at market (cross margin)"

okx swap place --instId BTC-USDT-SWAP --side buy --ordType market --sz 10 \
  --tdMode cross --posSide long
# → Order placed: 7890123458 (OK)

"Long 10 contracts BTC perp with TP at $105k and SL at $88k"

okx swap place --instId BTC-USDT-SWAP --side buy --ordType market --sz 10 \
  --tdMode cross --posSide long \
  --tpTriggerPx 105000 --tpOrdPx -1 --slTriggerPx 88000 --slOrdPx -1
# → Order placed: 7890123459 (OK) — TP/SL attached via attachAlgoOrds

"Set take profit at $105k and stop loss at $88k on an existing BTC perp long"

okx swap algo place --instId BTC-USDT-SWAP --side sell --ordType oco --sz 10 \
  --tdMode cross --posSide long \
  --tpTriggerPx 105000 --tpOrdPx -1 \
  --slTriggerPx 88000 --slOrdPx -1
# → Algo order placed: ALGO456789 (OK)

"Close my ETH perp position"

okx swap close --instId ETH-USDT-SWAP --mgnMode cross --posSide long
# → Position closed: ETH-USDT-SWAP long

"Set BTC perp leverage to 5x (cross)"

okx swap leverage --instId BTC-USDT-SWAP --lever 5 --mgnMode cross
# → Leverage set: 5x BTC-USDT-SWAP

"Long 1 contract TSLA stock token at market (cross margin)"

okx swap place --instId TSLA-USDT-SWAP --side buy --ordType market --sz 1 \
  --tdMode cross --posSide long
# → Order placed: 7890123461 (OK) [profile: live]

"Open short on NVDA, 2 contracts"

okx swap place --instId NVDA-USDT-SWAP --side sell --ordType market --sz 2 \
  --tdMode cross --posSide short
# → Order placed: 7890123462 (OK) [profile: live]

"Place a 2% trailing stop on my BTC perp long"

okx swap algo trail --instId BTC-USDT-SWAP --side sell --sz 10 \
  --tdMode cross --posSide long --callbackRatio 0.02
# → Trailing stop placed: TRAIL123 (OK)

"Place a 3% trailing stop on my spot BTC"

okx spot algo trail --instId BTC-USDT --side sell --sz 0.01 --callbackRatio 0.03
# → Trailing stop placed: TRAIL456 (OK)

"Place a 2% trailing stop on my BTC futures long"

okx futures algo trail --instId BTC-USDT-<YYMMDD> --side sell --sz 5 \
  --tdMode cross --posSide long --callbackRatio 0.02
# → Trailing stop placed: TRAIL789 (OK)

"Close my BTC futures long position"

okx futures close --instId BTC-USDT-260328 --mgnMode cross --posSide long
# → Position closed: BTC-USDT-260328 long

"Set BTC futures leverage to 10x (cross)"

okx futures leverage --instId BTC-USDT-260328 --lever 10 --mgnMode cross
# → Leverage set: 10x BTC-USDT-260328

"Place a TP at $105k and SL at $88k on my ETH futures long"

okx futures algo place --instId ETH-USDT-260328 --side sell --ordType oco --sz 5 \
  --tdMode cross --posSide long \
  --tpTriggerPx 105000 --tpOrdPx -1 \
  --slTriggerPx 88000 --slOrdPx -1
# → Algo order placed: ALGO789012 (OK)

"Show my open swap positions"

okx swap positions
# → table: instId, side, size, avgPx, upl, uplRatio, lever

"What are my recent fill trades for BTC spot?"

okx spot fills --instId BTC-USDT
# → table: instId, side, fillPx, fillSz, fee, ts

"Show me the BTC option chain expiring March 28"

okx option instruments --uly BTC-USD --expTime 250328
# → table: instId, expTime, stk, optType (C/P), state

"What's the IV and delta for BTC options expiring March 28?"

okx option greeks --uly BTC-USD --expTime 250328
# → table: instId, delta, gamma, theta, vega, iv (markVol), markPx

"Buy 1 BTC call at strike 95000 expiring March 28, limit at 0.005 BTC"

okx option place --instId BTC-USD-250328-95000-C \
  --side buy --ordType limit --tdMode cash --sz 1 --px 0.005
# → Order placed: 7890123460 (OK)

"Show my open option positions"

okx option positions
# → table: instId, posSide, pos, avgPx, upl, delta, gamma, theta, vega

Edge Cases

Spot

• Market order size : --sz is in base currency (e.g., BTC amount), not USDT
• Insufficient balance : check okx-cex-portfolio account balance before placing
• Price not required : market orders don't need --px; limit / post_only / fok / ioc do
• Algo oco : provide both tpTriggerPx and slTriggerPx; price means market execution at trigger

Swap / Perpetual

• sz unit : always number of contracts — never pass a USDT amount directly. If the user gives a USDT amount, apply "Sz Conversion Rules for Derivatives" before placing
• Linear vs inverse : BTC-USDT-SWAP is linear (USDT-margined); BTC-USD-SWAP is inverse (BTC-margined). For inverse, warn the user that margin and P&L are settled in BTC
• posSide : required in hedge mode (long_short_mode); omit in net mode. Check okx account config for posMode
• tdMode : use cross for cross-margin, isolated for isolated margin
• Close position : swap close closes the position; to partial close, use with a reduce-only algo

Futures / Delivery

• sz unit : always number of contracts — apply "Sz Conversion Rules for Derivatives" when user gives a USDT amount
• Linear vs inverse : BTC-USDT-<YYMMDD> is linear; BTC-USD-<YYMMDD> is inverse (USD face value, BTC settlement). For inverse, sz = floor(usdtAmt / ctVal) where ctVal is typically 100 USD
• instId format : delivery futures use date suffix: BTC-USDT-<YYMMDD> (e.g., BTC-USDT-260328 for March 28, 2026 expiry)
• Expiry : futures expire on the delivery date — all positions auto-settle; do not hold through expiry unless intended
• Close position : use futures close to close the entire position at market price — same semantics as swap close; to partial close, use futures place with

Options

• sz unit : always number of contracts — apply "Sz Conversion Rules for Derivatives" when user gives a USDT amount. For inverse options (BTC-USD), premium is quoted in BTC; convert via sz = floor(usdtAmt / (markPx_BTC × btcPx × ctVal))
• instId format : {uly}-{YYMMDD}-{strike}-{C|P} — e.g. BTC-USD-250328-95000-C; always run okx option instruments --uly BTC-USD first to confirm the exact contract exists
• tdMode : buyers always use cash (full premium paid upfront, no liquidation); sellers use cross or isolated (margin required, liquidation risk)
• px unit : quoted in base currency for inverse options (e.g. 0.005 = 0.005 BTC premium per contract); always show equivalent USDT value to the user

Global Notes

• All write commands require valid credentials in ~/.okx/config.toml or env vars
• --profile <name> is required for all authenticated commands; see "Credential & Profile Check" section
• Every command result includes a [profile: <name>] tag for audit reference
• --json returns raw OKX API v5 response
• Rate limit: 60 order operations per 2 seconds per UID
• Batch operations (batch cancel, batch amend) are available via MCP tools directly if needed
• Position mode (net vs long_short_mode) affects whether --posSide is required
• Spot/swap/futures place orders support --tgtCcy: use quote_ccy when user specifies USDT amount, (default) for base currency or contracts. Do NOT manually convert between currencies — let the API handle it via tgtCcy. Option does not support tgtCcy.

Weekly Installs

1.1K

Repository

okx/agent-skills

GitHub Stars

41

First Seen

Mar 8, 2026

Security Audits

Gen Agent Trust HubPassSocketWarnSnykWarn

Installed on

opencode1.1K

codex1.1K

gemini-cli1.1K

amp1.1K

github-copilot1.1K

kimi-cli1.1K