Use 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', 'limit take profit', 'immediate TP', 'set stop loss', 'self-trade preventi

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 ](../ shared/preflight.md). Use metadata.version from this file's frontmatter as the reference for Step 2. Prerequisites 1. Install okx CLI: 2. Configure credentials: 3. Test with demo mode (simulated trading, no real funds): 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](../ shared/preflight.md) 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. 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): Auth method Live (实盘) Demo (模拟盘) API Key profile <live profile profile <demo profile OAuth (no flag needed, live is default) demo 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 Mode Funds API Key param OAuth param 实盘 (live) Real money — irreversible profile <live profile (default, no flag) 模拟盘 (demo) Simulated — no real funds profile <demo profile demo 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: tgtCcy sz meaning Conversion formula Example: "500U" at 10x lever base ccy (default) contract count no conversion 500 contracts quote ccy USDT notional value floor(sz / (ctVal lastPx)) 500 USDT notional margin USDT margin cost floor(sz lever / (ctVal lastPx)) 500 USDT margin = 5000 USDT notional 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 Command Index Spot Orders (12 commands) Command Type Description 1 okx spot place WRITE Place spot order (market/limit/post only/fok/ioc) 2 okx spot cancel WRITE Cancel spot order 3 okx spot amend WRITE Amend spot order price or size 4 okx spot algo place WRITE Place spot TP/SL algo order 5 okx spot algo amend WRITE Amend spot TP/SL levels 6 okx spot algo cancel WRITE Cancel spot algo order 7 okx spot algo trail WRITE Place spot trailing stop order 8 okx spot orders READ List open or historical spot orders 9 okx spot get READ Single spot order details 10 okx spot fills READ Spot trade fill history 11 okx spot algo orders READ List spot TP/SL algo orders 12 okx spot leverage WRITE Set leverage for spot margin (borrowing). Pair level ( instId ) or currency level cross ( ccy , required for borrow enabled / multi ccy / portfolio margin) For full command syntax, parameter tables, and edge cases, read {baseDir}/references/spot commands.md . Swap / Perpetual Orders (15 commands) Command Type Description 13 okx swap place WRITE Place perpetual swap order 14 okx swap cancel WRITE Cancel swap order 15 okx swap amend WRITE Amend swap order price or size 16 okx swap close WRITE Close entire position at market 17 okx swap leverage WRITE Set leverage for an instrument 18 okx swap algo place WRITE Place swap TP/SL algo order 19 okx swap algo trail WRITE Place swap trailing stop order 20 okx swap algo amend WRITE Amend swap algo order 21 okx swap algo cancel WRITE Cancel swap algo order 22 okx swap positions READ Open perpetual swap positions 23 okx swap orders READ List open or historical swap orders 24 okx swap get READ Single swap order details 25 okx swap fills READ Swap trade fill history 26 okx swap get leverage READ Current leverage settings 27 okx swap algo orders READ List swap algo orders For full command syntax, parameter tables, and edge cases, read {baseDir}/references/swap commands.md . Futures / Delivery Orders (15 commands) Command Type Description 28 okx futures place WRITE Place delivery futures order 29 okx futures cancel WRITE Cancel delivery futures order 30 okx futures amend WRITE Amend delivery futures order price or size 31 okx futures close WRITE Close entire futures position at market 32 okx futures leverage WRITE Set leverage for a futures instrument 33 okx futures algo place WRITE Place futures TP/SL algo order 34 okx futures algo trail WRITE Place futures trailing stop order 35 okx futures algo amend WRITE Amend futures algo order 36 okx futures algo cancel WRITE Cancel futures algo order 37 okx futures orders READ List delivery futures orders 38 okx futures positions READ Open delivery futures positions 39 okx futures fills READ Delivery futures fill history 40 okx futures get READ Single delivery futures order details 41 okx futures get leverage READ Current futures leverage settings 42 okx futures algo orders READ List futures algo orders For full command syntax, parameter tables, and edge cases, read {baseDir}/references/futures commands.md . Options Orders (10 commands) Command Type Description 43 okx option instruments READ Option chain: list available contracts for an underlying 44 okx option greeks READ Implied volatility + Greeks (delta/gamma/theta/vega) by underlying 45 okx option place WRITE Place option order (call or put, buyer or seller) 46 okx option cancel WRITE Cancel unfilled option order 47 okx option amend WRITE Amend option order price or size 48 okx option batch cancel WRITE Batch cancel up to 20 option orders 49 okx option orders READ List option orders (live / history / archive) 50 okx option get READ Single option order details 51 okx op

okx-cex-trade