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

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

# 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

#	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

#	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

#	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

#	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 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
• 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 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 short; 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
   • 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 or 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

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

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)

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

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 — List Orders

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

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

---

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> \
  [--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

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]

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

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

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

Returns table: instId, mgnMode, posSide, lever.

---

Swap — Place Algo (TP/SL)

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

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

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> \
  [--posSide <long|short>] [--px <price>] [--reduceOnly] [--json]

--instId format: BTC-USDT-250328 (delivery date suffix).

---

Futures — Cancel Order

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

---

Futures — List Orders

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

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]

---

Option — Get Instruments (Option Chain)

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

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]

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

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]

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

---

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

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"

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)

"Set take profit at $105k and stop loss at $88k on 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

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

"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 -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> 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 --sz is base currency; swap/futures --sz is number of contracts