Okx Cex Trade

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: ``bash npm install -g @okx_ai/okx-trade-cli ``
2. Configure credentials: ``bash okx config init # select site -> follow browser OAuth flow ``
3. Test with demo mode (simulated trading, no real funds): ``bash 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