| name | okx-cex-trade |
| description | This skill should be used when the user asks to 'buy BTC', 'sell ETH', 'place a limit order', 'place a market order', 'cancel my order', 'amend my order', 'long BTC perp', 'short ETH swap', 'open a position', 'close a position', 'set take profit', 'set stop loss', 'add a trailing stop', 'set leverage', 'check my orders', 'order status', 'fill history', 'trade history', 'buy a call', 'sell a put', 'buy call option', 'sell put option', 'option chain', 'implied volatility', 'IV', 'option Greeks', 'delta', 'gamma', 'theta', 'vega', 'delta hedge', 'option order', 'option position', 'option fills', or any request to place/cancel/amend spot, perpetual swap, delivery futures, or options orders on OKX CEX. Covers spot trading, swap/perpetual contracts, delivery futures, options (calls/puts, Greeks, IV), and conditional (TP/SL/trailing) algo orders. Requires API credentials. Do NOT use for market data (use okx-cex-market), account balance/positions (use okx-cex-portfolio), or grid/DCA bots (use okx-cex-bot). |
| license | MIT |
| metadata | {"author":"okx","version":"1.0.0","homepage":"https://www.okx.com","agent":{"requires":{"bins":"[Truncated]"},"install":["[Truncated]"]}} |
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:
npm install -g @okx_ai/okx-trade-cli
- Configure credentials:
okx config init
Or set environment variables:
export OKX_API_KEY=your_key
export OKX_SECRET_KEY=your_secret
export OKX_PASSPHRASE=your_passphrase
- Test with demo mode (simulated trading, no real funds):
okx --profile demo spot orders
Credential & Profile Check
Run this check before any authenticated command.
Step A — Verify credentials
okx config show # 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:
- Current message intent is clear (e.g. "real" / "实盘" / "live" →
live; "test" / "模拟" / "demo" → demo) → use it and inform the user: "Using --profile live (实盘)" or "Using --profile demo (模拟盘)"
- Current message has no explicit declaration → check conversation context for a previous profile:
- Found → use it, inform user:
"Continuing with --profile live (实盘) from earlier"
- Not found → ask:
"Live (实盘) or Demo (模拟盘)?" — wait for answer before proceeding
Handling 401 Authentication Errors
If any command returns a 401 / authentication error:
- Stop immediately — do not retry the same command
- Inform the user: "Authentication failed (401). Your API credentials may be invalid or expired."
- Guide the user to update credentials by editing the file directly with their local editor:
~/.okx/config.toml
Update the fields api_key, secret_key, passphrase under the relevant profile.
Do NOT paste the new credentials into chat.
- After the user confirms the file is updated, run
okx config show to verify (output is masked)
- Only then retry the original operation
Demo vs Live Mode
Profile is the single control for 实盘/模拟盘 switching — 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:
--profile is required on every authenticated command — determined in "Credential & Profile Check" Step B- Every response after a command must append:
[profile: live] or [profile: demo]
- Do not use the
--demo flag for mode switching — use --profile instead
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
- Current message intent clear (e.g. "real"/"实盘"/"live" → live; "test"/"模拟"/"demo" → demo) → use it, inform user:
"Using --profile live (实盘)"
- 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:
- Profile — determined in Step 0; use
--profile live (实盘) or --profile demo (模拟盘)
- 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 |
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
