/okx-cex-trade

name: okx-cex-trade
description: "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 prevention', 'stpMode', 'auto-cancel on close', 'trailing stop', 'pending order', 'chase order', 'iceberg', 'TWAP', 'split order', 'large order', 'set leverage', 'check my orders', 'fill history', 'buy a call', 'sell a put', 'option chain', 'implied volatility', 'IV', 'Greeks', 'delta', 'gamma', 'event contract', 'buy Yes', 'buy No', 'buy Up', 'buy Down', 'prediction market', or any request to place, cancel, or amend spot, swap, futures, options, or event contract orders on OKX CEX. Covers conditional (TP/SL/trailing) algo orders. Requires API credentials. Do NOT use for market data (okx-cex-market), account balance (okx-cex-portfolio), or bots (okx-cex-bot)."
license: MIT
metadata:
  author: okx
  version: "1.4.1"
  homepage: "https://www.okx.com"
  agent:
    requires:
      bins: ["okx"]
    install:
      - id: npm
        kind: node
        package: "@okx_ai/okx-trade-cli@1.4.1"
        bins: ["okx"]
        label: "Install okx CLI (npm)"

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:

   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](../_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.

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):**

| 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