OKX CEX Trading CLI

Spot, perpetual swap, delivery futures, options, and event contract order management on OKX exchange. Place, cancel, amend, and monitor orders; query option chains and Greeks; trade binary outcome event contracts (Yes/No, Up/Down); set take-profit/stop-loss and trailing stops; manage leverage and positions. Requires API credentials.

CLI vs MCP tool names — Subcommands use spaces (okx swap algo place, okx bot grid create), not hyphens. Do NOT convert an MCP tool identifier (swap_place_algo_order) into a hyphen-joined CLI command (okx swap place-algo) — that will be rejected with "Unknown command". Per-module mapping tables live in references/<module>-commands.md.

Preflight

Before running any command, follow ../_shared/preflight.md. Use metadata.version from this file's frontmatter as the reference for Step 2.

Prerequisites

1. Install okx CLI:

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

2. Configure credentials:

   okx config init   # select site -> follow browser OAuth flow
   

3. Test with demo mode (simulated trading, no real funds):

   okx --demo spot orders
   

Security: NEVER accept credentials in chat. Guide users to okx config init for setup.

Credential & Profile Check

Run this check before any authenticated command. The auth method is detected during preflight Step 2 and remembered for the session.

Step A — Verify credentials

Run both commands — the apiKey field from okx auth status --json is the auth-binary's internal state and is always false regardless of whether ~/.okx/config.toml has an API-key profile. okx config show --json is the only authoritative source for API-key presence.

okx config show --json      # reveals API-key profiles (TOML config)
okx auth status --json      # reveals OAuth session state (auth-binary state)

Apply in this order — first match wins:

• config show --json has any profile with a non-empty api_key field → API Key mode. Proceed to Step B.
• No API-key profile AND auth status --json returns "status":"logged_in" → OAuth mode. Proceed to Step B.
• No API-key profile AND "status":"pending" — login is in progress, wait for it to complete.
• No API-key profile AND "status":"not_logged_in" — stop all operations, load okx-cex-auth skill and follow login steps, wait for completion.

Step B — Confirm trading mode

Resolution rules:

1. Current message intent is clear (e.g. "real" / "实盘" / "live" → live; "test" / "模拟" / "demo" → demo) → use it and inform the user
2. Current message has no explicit declaration → check conversation context for a previous choice:
   • Found → reuse it, inform user
   • Not found → ask: "Live (实盘) or Demo (模拟盘)?" — wait for answer before proceeding

How to apply the mode depends on auth method (detected in Step A):

• API Key users: run okx config show --json to discover available profile names and their demo settings. Use --profile <name> to select the correct one.
• OAuth users: omit flags for live trading; add --demo for simulated trading. Do not use --profile to switch modes.

Handling Authentication Errors

Authentication error (error contains "401", "Session expired", or "Run okx auth login first"):

1. Stop immediately — do not retry the same command
2. Inform the user: "Authentication failed. Your session may have expired."
3. Load okx-cex-auth skill and follow the re-authentication steps
4. After successful re-authentication, retry the original command

Demo vs Live Mode

Rules:

1. Trading mode is required on every authenticated command — determined in "Credential & Profile Check" Step B
2. Every response after a command must append: [mode: live] or [mode: 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 browsing/discovering event contracts (what's available, how many, list active) → use okx-cex-trade with okx event browse / okx event series
• For trading event contracts (place/cancel/amend prediction market orders) → use okx-cex-trade with okx event place / okx event cancel / okx event amend
• For grid and DCA trading bots → use okx-cex-bot

Important: When user asks about "contracts" in the context of event contracts or prediction markets, route to this skill — NOT to okx-cex-portfolio. Portfolio does not handle event contracts — it covers account balance, positions, P&L, and transfers only.

Sz Handling for Derivatives

⚠ CRITICAL: Always verify contract face value before placing orders

Before placing any SWAP/FUTURES/OPTION order, call market_get_instruments to get ctVal (contract face value). Do NOT assume contract sizes — they vary by instrument (e.g. ETH-USDT-SWAP = 0.1 ETH/contract, BTC-USDT-SWAP = 0.01 BTC/contract).

Use ctVal to:

• Calculate the correct number of contracts from user's intended position size
• Verify margin requirements before submitting the order
• Show the user the actual position value: sz × ctVal × price

SWAP and FUTURES orders

Three tgtCcy modes for USDT-denominated sizing:

When user specifies a USDT amount (e.g. "200U", "500 USDT", "$1000"): → AMBIGUOUS — this could mean notional value OR margin cost. You MUST ask the user to clarify before proceeding:

• notional value: sz = position value in USDT (e.g. 500 USDT buys 500 USDT worth of contracts directly)
• margin cost: actual position = sz × leverage (e.g. 500 USDT margin at 10× = 5000 USDT notional position) Wait for the user's answer before continuing.
• If notional value → use --tgtCcy quote_ccy
• If margin cost → use --tgtCcy margin

When user specifies contracts (e.g. "2 张", "5 contracts"): → First verify ctVal via market_get_instruments, then use --sz with the contract count. Confirm with user: "X contracts = X × ctVal underlying, total value ≈ $Y".

When user gives a plain number with no unit (for swap/futures): → AMBIGUOUS — You MUST ask the user to clarify before proceeding:

• contract count: X contracts (each worth ctVal of underlying)
• USDT notional value: position value in USDT
• USDT margin cost: margin amount (actual position = X × leverage) Wait for the user's answer before continuing.

⚠ Inverse contracts (*-USD-SWAP, *-USD-YYMMDD): tgtCcy=quote_ccy and tgtCcy=margin also work (note: quote_ccy = USD, not USDT, for inverse instruments). Always warn: "This is an inverse contract. Margin and P&L are settled in BTC, not USDT."

Option orders

When the user specifies a USDT amount for options, use --tgtCcy quote_ccy (notional) or --tgtCcy margin (margin cost) and pass the amount as --sz. The system automatically converts to contracts. Note: option contracts typically have large face values (e.g. ctVal=1 BTC ≈ $84,000), so the minimum USDT amount for 1 contract is high. For option sellers (cross/isolated tdMode), margin mode accounts for leverage automatically.

Quickstart

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

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

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

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

# Long 1000 USDT notional value of BTC perp (auto-convert to contracts)
okx swap place --instId BTC-USDT-SWAP --side buy --ordType market --sz 1000 \
  --tgtCcy quote_ccy --tdMode cross --posSide long

# Long with 500 USDT margin at current leverage (e.g. 10x → 5000 USDT notional)
okx swap place --instId BTC-USDT-SWAP --side buy --ordType market --sz 500 \
  --tgtCcy margin --tdMode cross --posSide long

# Long 1 contract with attached TP/SL (one step)
okx swap place --instId BTC-USDT-SWAP --side buy --ordType market --sz 1 \
  --tdMode cross --posSide long \
  --tpTriggerPx 105000 --tpOrdPx=-1 --slTriggerPx 88000 --slOrdPx=-1

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

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

# Set TP/SL on a spot BTC position
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>

# --- Event Contract ---
# List event series
okx event series

# Browse live markets in a series
okx event markets BTC-ABOVE-DAILY --state live

# Place event contract order
okx event place --instId BTC-ABOVE-DAILY-260224-1600-70000 --side buy --outcome YES --sz 10

Command Index

Spot Orders (12 commands)

For full command syntax, parameter tables, and edge cases, read {baseDir}/references/spot-commands.md.

Swap / Perpetual Orders (15 commands)

For full command syntax, parameter tables, and edge cases, read {baseDir}/references/swap-commands.md.

Futures / Delivery Orders (15 commands)

For full command syntax, parameter tables, and edge cases, read {baseDir}/references/futures-commands.md.

Options Orders (10 commands)

For full command syntax, USDT-to-contracts conversion formula, tdMode rules, and edge cases, read {baseDir}/references/options-commands.md.

Event Contract Orders (9 commands)

For full command syntax, parameter tables, and edge cases, read {baseDir}/references/event-commands.md.

Operation Flow

Step 0 — Credential & Profile Check

Before any authenticated command: see Credential & Profile Check. Determine auth method and trading mode before executing.

After every command result: append [mode: live] or [mode: demo].

Step 1 — Identify instrument type and action

Spot (instId format: BTC-USDT):

• Place/cancel/amend order → okx spot place/cancel/amend
• TP/SL conditional → okx spot algo place/amend/cancel
• Trailing stop → okx spot algo trail
• Query → okx spot orders/get/fills/algo orders

Swap/Perpetual (instId format: BTC-USDT-SWAP):

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

Futures/Delivery (instId format: BTC-USDT-<YYMMDD>):

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

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

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

Event Contracts:

Instrument ID (instId, API field) format: {UNDERLYING}-{TYPE}-{YYMMDD}-{HHMM}-{STRIKE} for "Price Above Target" / "One Touch" contracts (e.g. BTC-ABOVE-DAILY-260224-1600-70000), or {UNDERLYING}-{TYPE}-{YYMMDD}-{START}-{END} for "Price Direction (Up/Down)" contracts (e.g. BTC-UPDOWN-15MIN-260224-1600-1615). Always obtain the instrument ID from okx event markets <seriesId> — never guess or use placeholders.

Series ID (seriesId, API field): human-readable (e.g. BTC-ABOVE-DAILY, BTC-UPDOWN-15MIN) or internal random string (e.g. FMQRZ). Both are valid for subsequent commands. Obtain from okx event series.

Event contract trading flow:

1. Discover → okx event browse (preferred, returns series + live markets in one call) or okx event series — present results grouped by type; highlight named series; always show the Series ID
2. Browse live markets → okx event markets <seriesId> --state live — obtains the instrument ID for each tradeable contract; if a live Price is shown, it is the event contract price (0.01–0.99), not the underlying asset price — reflects the market-implied probability when actively trading
3. Check event details → okx event events <seriesId>
4. Confirm + Place → okx event place <instId> <side> <outcome> <sz> — only after user explicitly confirms
5. Track → okx event orders --status open / okx account positions --instType EVENTS
6. Exit or settle → sell via okx event place <instId> sell <outcome> <sz>, or wait for --state expired

Edge cases:

• Settled results: okx event markets <seriesId> --state expired — no separate ended tool

Event Contract sz Rules:

• Market order (ordType=market): --sz is quote currency amount.
• Limit order (ordType=limit / post_only): --sz is number of contracts (integer). Each contract settles at 1 unit of quote currency; cost per contract = px (event contract price, 0.01–0.99). E.g. 10 contracts at px=0.5 costs 5.
• px semantics: px is the event contract price (0.01–0.99), NOT the underlying asset price. When actively trading, it reflects the market-implied probability. Example: px=0.6 means the market is pricing the event at roughly 60%.
• Outcome display: expired/result views show translated values. For price_up_down, treat YES/NO as UP/DOWN.

For event contract workflows and step-by-step examples, read {baseDir}/references/event-workflows.md.

For cross-skill workflows and step-by-step examples, read {baseDir}/references/workflows.md.

Step 2 — Confirm profile, then confirm write parameters

Read commands (orders, positions, fills, get, get-leverage, algo orders): run immediately.

• --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): confirm the key order details once before executing:

• Spot place: confirm --instId, --side, --ordType, --sz (and --tgtCcy quote_ccy if quote-currency amount)
• Swap/Futures place: confirm --instId, --side, --sz, --tdMode, and explicitly confirm order mode when user specifies a USDT amount: --tgtCcy quote_ccy (notional value, sz = position value) or --tgtCcy margin (margin cost, actual position = sz * leverage). Always state which mode is being used.
• Option place: confirm --instId, --side, --sz, --tdMode (and --tgtCcy quote_ccy or --tgtCcy margin if USDT amount — system auto-converts); do NOT attach TP/SL
• Event Contract place: confirm --instId, --side, --outcome, --sz, --ordType; for market orders sz is quote currency amount, for limit orders sz is number of contracts + --px required
• Swap/Futures close: confirm --instId, --mgnMode, --posSide
• Leverage: confirm new leverage and impact on existing positions. Pre-checks to avoid common 400s: (a) --lever must be a positive number within the instrument's max (see okx market instruments → lever); (b) for --mgnMode isolated in hedge pos mode, --posSide is required — each side (long, short) must be set separately, setting one does NOT auto-apply to the other; (c) portfolio-margin accounts cannot adjust cross leverage for SWAP/FUTURES — OKX will reject; if unsure, run okx account config and check acctLv first. If set-leverage fails (error mentions "cancel orders or stop bots"): troubleshoot in priority order — (1) query pending algo orders first (swap/futures algo-orders --status pending), as this is the most common blocker; (2) only if no algo orders, check active bots (bot grid-orders). Do NOT automatically cancel orders or stop bots — present findings and let the user decide
• Algo place (TP/SL): confirm trigger prices; use --tpOrdPx=-1 for market execution
• Algo trail: confirm --callbackRatio (e.g., 0.02 = 2%) or --callbackSpread

For full parameter details per command, read the relevant reference file.

Error-suggested remediation safeguard

When an OKX API error message suggests a fix that involves write operations (cancel orders, close positions, stop bots/strategies, transfer funds, etc.), you MUST NOT automatically execute those actions. Instead:

1. Report the error and its suggestion to the user verbatim
2. Diagnose — run read-only queries to identify what is blocking (e.g., algo-orders --status pending, positions, bot grid-orders --status active)
3. Present findings — show the user what was found and which specific items would need to be cancelled/closed/stopped
4. Wait for explicit confirmation before executing any remediation

This applies to all error codes whose messages suggest destructive actions, including but not limited to:

• Set-leverage blocked by pending algo orders or active bots
• Account setting changes requiring order/position/strategy cleanup (e.g., error codes 59000, 59002, 59007)
• Margin mode switches requiring position closure
• Any error containing phrases like "cancel", "close", "stop", "transfer … before"

Rationale: Error messages list all possible blockers generically — the actual blocker is often just one item (e.g., a single TP/SL order). Blindly following the error text can cause unnecessary position closures or bot shutdowns that the user did not intend.

Step 3 — Verify after writes

• After spot place: run okx spot orders to confirm order is live or okx spot fills if market order
• After swap place: run okx swap orders or okx swap positions to confirm
• After swap close: run okx swap positions to confirm position size is 0
• After futures place: run okx futures orders or okx futures positions to confirm
• After futures close: run okx futures positions to confirm position size is 0
• After spot algo place/trail: run okx spot algo orders to confirm algo is active
• After swap algo place/trail: run okx swap algo orders to confirm algo is active
• After futures algo place/trail: run okx futures algo orders to confirm algo is active
• After cancel: run okx spot orders / okx swap orders / okx futures orders / okx event orders to confirm order is gone
• After event place: run okx event orders --status open to confirm order is pending
• After event cancel: run okx event orders to confirm order is gone

Global Notes

• All write commands require valid credentials (OAuth session or API key in ~/.okx/config.toml)
• Auth method and trading mode are determined in "Credential & Profile Check"; see that section for parameter rules
• --json returns the raw OKX API v5 response by default. Add --env to wrap the output as {"env": "<live|demo>", "profile": "<name>", "data": <response>} — useful when you need to know the active environment and credential profile
• 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
• Network errors: If commands fail with a connection error, prompt user to check VPN: curl -I https://www.okx.com
• Capability discovery: Run okx list-tools --json to get a machine-readable JSON listing of all CLI commands, tool names, and parameters — useful for programmatic enumeration without parsing --help text

For MCP tool reference, output conventions, and order amount safety rules, read {baseDir}/references/templates.md.