Okx Cex Trade

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.