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

Install
```
okx
```
CLI:
bash
```
npm install -g @okx_ai/okx-trade-cli
```

Configure credentials:

bash

okx config init

Or set environment variables:

bash

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):
bash
```
okx --demo spot orders
```

Demo vs Live Mode

CRITICAL: Always confirm demo vs live before any write command (place, cancel, amend, close, leverage, algo).

How to check current mode

bash

okx config show       # shows current profile settings

How to switch mode per command

Prepend

--demo

to run in simulated trading mode (no real funds affected):

bash

okx --demo spot place --instId BTC-USDT --side buy --ordType market --sz 0.01
okx --demo swap close --instId BTC-USDT-SWAP --mgnMode cross

Omit

--demo

to execute on the live account (real funds).

Rules for this skill

Before every write command, explicitly ask or confirm: "Execute on live account or demo (simulated)?" — do not assume.
Read commands (orders, positions, fills, get, algo orders): run immediately; note which mode was used.
When executing demo, prefix the response summary with [DEMO]
and state no real funds were affected.
When executing live, prefix the response summary with [LIVE]
and flag that real funds are involved.
If the user says "try it" / "test it" / "simulate" / "paper trade" → use
```
--demo
```
.
If the user says "real" / "actual" / "go live" / "execute" → confirm once more before running without
```
--demo
```
.

Example

User: "Buy 0.01 BTC"
Agent: "Execute on live account (real funds) or demo (simulated)?"
User: "Demo"
Agent runs: okx --demo spot place --instId BTC-USDT --side buy --ordType market --sz 0.01
Agent replies: "[DEMO] Order placed: 7890123456 (OK) — simulated, no real funds used."

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
```

Quickstart

bash

# 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

# 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

# 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

# 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


okx spot place
okx spot cancel
okx spot amend
okx spot algo place
okx spot algo amend
okx spot algo cancel
okx spot orders
okx spot get
okx spot fills
okx spot algo 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 orders`	READ	List open or historical spot orders
8	`okx spot get`	READ	Single spot order details
9	`okx spot fills`	READ	Spot trade fill history
10	`okx spot algo orders`	READ	List spot TP/SL algo orders

Swap / Perpetual Orders


okx swap place
okx swap cancel
okx swap amend
okx swap close
okx swap leverage
okx swap algo place
okx swap algo trail
okx swap algo amend
okx swap algo cancel
okx swap positions
okx swap orders
okx swap get
okx swap fills
okx swap get-leverage
okx swap algo orders

#	Command	Type	Description
11	`okx swap place`	WRITE	Place perpetual swap order
12	`okx swap cancel`	WRITE	Cancel swap order
13	`okx swap amend`	WRITE	Amend swap order price or size
14	`okx swap close`	WRITE	Close entire position at market
15	`okx swap leverage`	WRITE	Set leverage for an instrument
16	`okx swap algo place`	WRITE	Place swap TP/SL algo order
17	`okx swap algo trail`	WRITE	Place swap trailing stop order
18	`okx swap algo amend`	WRITE	Amend swap algo order
19	`okx swap algo cancel`	WRITE	Cancel swap algo order
20	`okx swap positions`	READ	Open perpetual swap positions
21	`okx swap orders`	READ	List open or historical swap orders
22	`okx swap get`	READ	Single swap order details
23	`okx swap fills`	READ	Swap trade fill history
24	`okx swap get-leverage`	READ	Current leverage settings
25	`okx swap algo orders`	READ	List swap algo orders

Futures / Delivery Orders


okx futures place
okx futures cancel
okx futures orders
okx futures positions
okx futures fills
okx futures get

#	Command	Type	Description
26	`okx futures place`	WRITE	Place delivery futures order
27	`okx futures cancel`	WRITE	Cancel delivery futures order
28	`okx futures orders`	READ	List delivery futures orders
29	`okx futures positions`	READ	Open delivery futures positions
30	`okx futures fills`	READ	Delivery futures fill history
31	`okx futures get`	READ	Single delivery futures order details

Options Orders


okx option instruments
okx option greeks
okx option place
okx option cancel
okx option amend
okx option batch-cancel
okx option orders
okx option get
okx option positions
okx option fills

#	Command	Type	Description
32	`okx option instruments`	READ	Option chain: list available contracts for an underlying
33	`okx option greeks`	READ	Implied volatility + Greeks (delta/gamma/theta/vega) by underlying
34	`okx option place`	WRITE	Place option order (call or put, buyer or seller)
35	`okx option cancel`	WRITE	Cancel unfilled option order
36	`okx option amend`	WRITE	Amend option order price or size
37	`okx option batch-cancel`	WRITE	Batch cancel up to 20 option orders
38	`okx option orders`	READ	List option orders (live / history / archive)
39	`okx option get`	READ	Single option order details
40	`okx option positions`	READ	Open option positions with live Greeks
41	`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 \
                       --ordType market --sz 5 --tdMode cross --posSide long
4. okx-cex-trade     okx swap algo place --instId BTC-USDT-SWAP --side sell \
                       --ordType oco --sz 5 --tdMode cross --posSide long \
                       --tpTriggerPx 105000 --tpOrdPx -1 \
                       --slTriggerPx 88000 --slOrdPx -1
5. okx-cex-trade     okx swap positions                     → confirm position opened

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 BTC perp long"

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

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 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
```
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-250328

Place/cancel order →
```
okx futures place/cancel
```
Query →
```
okx futures orders/positions/fills/get
```

Options (instId format:

BTC-USD-250328-95000-C

...-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 demo vs live, then confirm write parameters

Read commands (orders, positions, fills, get, get-leverage, algo orders): run immediately; note the mode 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
```
short
```
; omit in net mode

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

Demo or live? — Ask the user before the first write in any session. If unclear, default to asking.
- Demo → prepend
```
--demo
```
  to every write command; label result
```
[DEMO]
```
- Live → execute without
```
--demo
```
  ; label result
```
[LIVE]
```
Confirm parameters — confirm the key order details once before executing:
- Spot place: confirm
```
--instId
```
  ,
```
--side
```
  ,
```
--ordType
```
  ,
```
--sz
```
  ; price (
```
--px
```
  ) required for limit orders
- Swap place: confirm
```
--instId
```
  ,
```
--side
```
  ,
```
--sz
```
  ,
```
--tdMode
```
  ; confirm
```
--posSide
```
  if in hedge mode
- Swap close: confirm
```
--instId
```
  ,
```
--mgnMode
```
  ,
```
--posSide
```
  ; closes the entire position at market
- Swap leverage: confirm new leverage and impact on existing positions; cannot exceed exchange max
- Algo place (TP/SL): confirm trigger prices; use
```
--tpOrdPx -1
```
  for market execution at trigger
- Algo trail: confirm
```
--callbackRatio
```
  (e.g.,
```
0.02
```
  = 2%) or
```
--callbackSpread
```
  (fixed price spread)

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

okx swap positions

to confirm

After
```
swap close
```
: run
```
okx swap positions
```
to confirm position size is 0
After algo place: run
```
okx spot algo orders
```
or
```
okx swap algo orders
```
to confirm algo is active
After cancel: run
```
okx spot orders
```
/
```
okx swap orders
```
to confirm order is gone

CLI Command Reference

Order Type Reference

`--ordType`	Description	Requires `--px`
`market`	Fill immediately at best price	No
`limit`	Fill at specified price or better	Yes
`post_only`	Limit order; cancelled if it would be a taker	Yes
`fok`	Fill entire order immediately or cancel	Yes
`ioc`	Fill what's available immediately, cancel rest	Yes
`conditional`	Algo: single TP or SL trigger	No (set trigger px)
`oco`	Algo: TP + SL together (one cancels other)	No (set both trigger px)
`move_order_stop`	Trailing stop (swap only)	No (set callback)

Spot — Place Order

bash

okx spot place --instId <id> --side <buy|sell> --ordType <type> --sz <n> \
  [--px <price>] [--json]

Param	Required	Default	Description
`--instId`	Yes	-	Spot instrument (e.g., `BTC-USDT` )
`--side`	Yes	-	`buy` or `sell`
`--ordType`	Yes	-	`market` , `limit` , `post_only` , `fok` , `ioc`
`--sz`	Yes	-	Order size in base currency (e.g., BTC amount)
`--px`	Cond.	-	Price — required for `limit` , `post_only` , `fok` , `ioc`

Spot — Cancel Order

bash

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

Spot — Amend Order

bash

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

Must provide at least one of

--newSz

--newPx

Spot — Place Algo (TP/SL)

bash

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

Param	Required	Default	Description
`--tpTriggerPx`	Cond.	-	Take-profit trigger price
`--tpOrdPx`	Cond.	-	TP order price; use `-1` for market execution
`--slTriggerPx`	Cond.	-	Stop-loss trigger price
`--slOrdPx`	Cond.	-	SL order price; use `-1` for market execution

For

oco

: provide both TP and SL params. For

conditional

: provide only TP or only SL.

Spot — Amend Algo

bash

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

Spot — Cancel Algo

bash

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

Spot — List Orders

bash

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

Flag	Effect
(default)	Open/pending orders
`--history`	Historical (filled, cancelled) orders

Spot — Get Order

bash

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

Returns:

ordId

instId

side

ordType

px

sz

fillSz

avgPx

state

cTime

Spot — Fills

bash

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

Returns:

instId

side

fillPx

fillSz

fee

ts

Spot — Algo Orders

bash

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

Returns:

algoId

instId

, type,

side

sz

tpTrigger

slTrigger

state

Swap — Place Order

bash

okx swap place --instId <id> --side <buy|sell> --ordType <type> --sz <n> \
  --tdMode <cross|isolated> \
  [--posSide <long|short>] [--px <price>] [--json]

Param	Required	Default	Description
`--instId`	Yes	-	Swap instrument (e.g., `BTC-USDT-SWAP` )
`--side`	Yes	-	`buy` or `sell`
`--ordType`	Yes	-	`market` , `limit` , `post_only` , `fok` , `ioc`
`--sz`	Yes	-	Number of contracts
`--tdMode`	Yes	-	`cross` or `isolated`
`--posSide`	Cond.	-	`long` or `short` — required in hedge mode
`--px`	Cond.	-	Price — required for limit orders

Swap — Cancel Order

bash

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

Swap — Amend Order

bash

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

Swap — Close Position

bash

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

Param	Required	Default	Description
`--instId`	Yes	-	Swap instrument
`--mgnMode`	Yes	-	`cross` or `isolated`
`--posSide`	Cond.	-	`long` or `short` — required in hedge mode
`--autoCxl`	No	false	Auto-cancel pending orders before closing

Closes the entire position at market price.

Swap — Set Leverage

bash

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

Param	Required	Default	Description
`--instId`	Yes	-	Swap instrument
`--lever`	Yes	-	Leverage multiplier (e.g., `10` )
`--mgnMode`	Yes	-	`cross` or `isolated`
`--posSide`	Cond.	-	`long` or `short` — required for isolated mode in hedge mode

Swap — Get Leverage

bash

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

Returns table:

instId

mgnMode

posSide

lever

Swap — Place Algo (TP/SL)

bash

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

--reduceOnly

: close-only; will not open a new position if one doesn't exist.

Swap — Place Trailing Stop

bash

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]

Param	Required	Default	Description
`--callbackRatio`	Cond.	-	Trailing callback as a ratio (e.g., `0.02` = 2%); use this or `--callbackSpread`
`--callbackSpread`	Cond.	-	Trailing callback as fixed price distance
`--activePx`	No	-	Price at which trailing stop becomes active

Swap — Amend Algo

bash

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

Swap — Cancel Algo

bash

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

Swap — List Orders

bash

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

Swap — Get Order

bash

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

Returns:

ordId

instId

side

posSide

ordType

px

sz

fillSz

avgPx

state

cTime

Swap — Positions

bash

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

Returns:

instId

side

size

avgPx

upl

uplRatio

lever

. Only non-zero positions.

Swap — Fills

bash

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

--archive

: access older fills beyond the default window.

Swap — Algo Orders

bash

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

Futures — Place Order

bash

okx futures place --instId <id> --side <buy|sell> --ordType <type> --sz <n> \
  --tdMode <cross|isolated> \
  [--posSide <long|short>] [--px <price>] [--reduceOnly] [--json]

--instId

format:

BTC-USDT-250328

(delivery date suffix).

Futures — Cancel Order

bash

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

Futures — List Orders

bash

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

`--status`	Effect
`open`	Active/pending orders (default)
`history`	Recent completed/cancelled
`archive`	Older history

Futures — Positions

bash

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

Returns:

instId

side

pos

avgPx

upl

lever

Futures — Fills

bash

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

Futures — Get Order

bash

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

Option — Get Instruments (Option Chain)

bash

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

Param	Required	Description
`--uly`	Yes	Underlying, e.g. `BTC-USD` or `ETH-USD`
`--expTime`	No	Filter by expiry date, e.g. `250328`

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

bash

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

bash

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

Param	Required	Default	Description
`--instId`	Yes	-	e.g. `BTC-USD-250328-95000-C` (call) or `...-P` (put)
`--side`	Yes	-	`buy` or `sell`
`--ordType`	Yes	-	`market` , `limit` , `post_only` , `fok` , `ioc`
`--tdMode`	Yes	-	`cash` = buyer (full premium); `cross` / `isolated` = seller (margin)
`--sz`	Yes	-	Number of contracts
`--px`	Cond.	-	Required for `limit` , `post_only` , `fok` , `ioc`
`--reduceOnly`	No	false	Close-only; do not open a new position

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

bash

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

Option — Amend Order

bash

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

Must provide at least one of

--newSz

--newPx

Option — Batch Cancel

bash

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

--orders

is a JSON array of up to 20 objects, each

{"instId":"...","ordId":"..."}

bash

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

Option — List Orders

bash

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

Flag	Effect
(default)	Live/pending orders
`--history`	Historical (7d)
`--archive`	Older archive (3mo)

Option — Get Order

bash

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

Returns:

ordId

instId

side

ordType

px

sz

fillSz

avgPx

state

cTime

Option — Positions

bash

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

bash

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

Tool	Description
`spot_place_order`	Place spot order
`spot_cancel_order`	Cancel spot order
`spot_amend_order`	Amend spot order
`spot_place_algo_order`	Place spot TP/SL algo
`spot_amend_algo_order`	Amend spot algo
`spot_cancel_algo_order`	Cancel spot algo
`spot_get_orders`	List spot orders
`spot_get_order`	Get single spot order
`spot_get_fills`	Spot fill history
`spot_get_algo_orders`	List spot algo orders
`swap_place_order`	Place swap order
`swap_cancel_order`	Cancel swap order
`swap_amend_order`	Amend swap order
`swap_close_position`	Close swap position
`swap_set_leverage`	Set swap leverage
`swap_place_algo_order`	Place swap TP/SL algo
`swap_place_move_stop_order`	Place swap trailing stop
`swap_amend_algo_order`	Amend swap algo
`swap_cancel_algo_orders`	Cancel swap algo
`swap_get_positions`	Swap positions
`swap_get_orders`	List swap orders
`swap_get_order`	Get single swap order
`swap_get_fills`	Swap fill history
`swap_get_leverage`	Get swap leverage
`swap_get_algo_orders`	List swap algo orders
`futures_place_order`	Place futures order
`futures_cancel_order`	Cancel futures order
`futures_get_orders`	List futures orders
`futures_get_positions`	Futures positions
`futures_get_fills`	Futures fill history
`futures_get_order`	Get single futures order
`option_get_instruments`	Option chain (list available contracts)
`option_get_greeks`	IV and Greeks by underlying
`option_place_order`	Place option order
`option_cancel_order`	Cancel option order
`option_amend_order`	Amend option order
`option_batch_cancel`	Batch cancel up to 20 option orders
`option_get_orders`	List option orders
`option_get_order`	Get single option order
`option_get_positions`	Option positions with live Greeks
`option_get_fills`	Option fill history

Input / Output Examples

"Buy 0.05 BTC at market"

bash

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"

bash

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

"Show my open spot orders"

bash

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

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

bash

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

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

bash

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"

bash

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

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

bash

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

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

bash

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

"Show my open swap positions"

bash

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

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

bash

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

"Show me the BTC option chain expiring March 28"

bash

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?"

bash

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"

bash

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"

bash

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
```
-1
```
means market execution at trigger
Fills vs orders:
```
fills
```
shows executed trades;
```
orders --history
```
shows all orders including cancelled

Swap / Perpetual

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 entire position; to partial close, use
```
swap place
```
with a reduce-only algo
Leverage: max leverage varies by instrument and account level; exchange rejects if exceeded
Trailing stop: use either
```
--callbackRatio
```
(relative, e.g.,
```
0.02
```
) or
```
--callbackSpread
```
(absolute price), not both
Algo on close side: always set
```
--side
```
opposite to position (e.g., long position → sell algo)

Futures / Delivery

instId format: delivery futures use date suffix:
```
BTC-USDT-250328
```
for March 28, 2025 expiry
Expiry: futures expire on the delivery date — all positions auto-settle; do not hold through expiry unless intended
No swap-specific features: futures don't have trailing stops or
```
swap close
```
— use
```
futures cancel
```
+
```
futures place
```
for adjustments

Options

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)
sz unit: number of contracts (1 BTC option contract = 0.1 BTC on OKX);
```
--px
```
is quoted in BTC (e.g.
```
0.005
```
= 0.005 BTC premium per contract)
Expiry: options expire at 08:00 UTC on the expiry date; in-the-money options are auto-exercised; do not hold through expiry unless intended
No TP/SL algo on options: the
```
swap algo
```
/
```
spot algo
```
commands do not apply to option positions; manage risk by cancelling/amending option orders directly
Greeks in positions:
```
okx option positions
```
returns live portfolio Greeks (
```
deltaPA
```
,
```
gammaPA
```
, etc.) from the account's position-level calculation, while
```
okx option greeks
```
returns BS model Greeks per contract

Global Notes

All write commands require valid credentials in
```
~/.okx/config.toml
```
or env vars
```
--profile <name>
```
switches between multiple account configurations
```
--json
```
returns raw OKX API v5 response
```
--demo
```
flag enables simulated trading with paper funds
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
```
--sz
```
is base currency; swap/futures
```
--sz
```
is number of contracts

okx-cex-trade

NPX Install

Tags

SKILL.md Content

OKX CEX Trading CLI

Prerequisites

Demo vs Live Mode

How to check current mode

How to switch mode per command

Rules for this skill

Example

Skill Routing

Quickstart

Command Index

Spot Orders

Swap / Perpetual Orders

Futures / Delivery Orders

Options Orders

Cross-Skill Workflows

Spot market buy

Open long BTC perp with TP/SL

Adjust leverage then place order

Place trailing stop on open position

Cancel all open spot orders

Buy a BTC call option

Check option portfolio Greeks

Operation Flow

Step 1: Identify instrument type and action

Step 2: Confirm demo vs live, then confirm write parameters

Step 3: Verify after writes

CLI Command Reference

Order Type Reference

Spot — Place Order

Spot — Cancel Order

Spot — Amend Order

Spot — Place Algo (TP/SL)

Spot — Amend Algo

Spot — Cancel Algo

Spot — List Orders

Spot — Get Order

Spot — Fills

Spot — Algo Orders

Swap — Place Order

Swap — Cancel Order

Swap — Amend Order

Swap — Close Position

Swap — Set Leverage

Swap — Get Leverage

Swap — Place Algo (TP/SL)

Swap — Place Trailing Stop

Swap — Amend Algo

Swap — Cancel Algo

Swap — List Orders

Swap — Get Order

Swap — Positions

Swap — Fills

Swap — Algo Orders

Futures — Place Order

Futures — Cancel Order

Futures — List Orders

Futures — Positions

Futures — Fills

Futures — Get Order

Option — Get Instruments (Option Chain)

Option — Get Greeks

Option — Place Order

Option — Cancel Order

Option — Amend Order

Option — Batch Cancel

Option — List Orders

Option — Get Order

Option — Positions

Option — Fills

MCP Tool Reference

Input / Output Examples

Edge Cases

Spot

Swap / Perpetual

Futures / Delivery

Options