/okx-cex-bot

name: okx-cex-bot
description: Manage Grid bots (spot/contract/coin-margined) and DCA Martingale bots (Spot DCA 现货马丁 / Contract DCA 合约马丁) on OKX. Covers create, stop, amend, monitor P&L, TP/SL, margin/investment adjustment, and AI-recommended parameters. Requires API credentials. Not for regular orders (okx-cex-trade), market data (okx-cex-market), or account info (okx-cex-portfolio).
license: MIT
metadata:
  author: okx
  version: "1.4.1"
  homepage: "https://www.okx.com"
  agent:
    emoji: "🤖"
    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 Bot Trading

Grid and DCA (Spot & Contract Martingale) bot management on OKX. All bots are **native OKX server-side** — they run on OKX and do not require a local process.

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

npm install -g @okx_ai/okx-trade-cli
okx config init   # select site -> follow browser OAuth flow

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

Credential & Profile Check

**Run before every 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, load `okx-cex-auth` skill and follow login steps, wait for completion.

Step B — Confirm trading mode

Resolution: 1. User intent is clear ("real"/"实盘"/"live" → live; "test"/"模拟"/"demo" → demo) → use it, inform user 2. No explicit declaration → check conversation context for previous choice → reuse if found 3. Nothing found → ask: "Live (实盘) or Demo (模拟盘)?" — wait 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.
• **OAuth users**: omit flags for live; add `--demo` for simulated trading.

**After every command**: append `[mode: live]` or `[mode: demo]`

Handling 401 Errors

**Authentication error** (error contains "401", "Session expired", or "Run `okx auth login` first"): 1. Stop immediately 2. Load `okx-cex-auth` skill and follow re-authentication steps 3. Retry original command

Skill Routing

| Need | Skill | |---|---| | Market data, prices, depth | `okx-cex-market` | | Account balance, positions, fees | `okx-cex-portfolio` | | Regular spot/swap/futures orders | `okx-cex-trade` | | **Grid / DCA bots** | **`okx-cex-bot` (this skill)** |

Command Index

Grid Bot

| Command | Type | Description | |---|---|---| | `okx bot grid create` | WRITE | Create a grid bot (spot or contract) | | `okx bot grid amend` | WRITE | Amend price range, grid count, or TP/SL of a running grid bot | | `okx bot grid stop` | WRITE | Stop a grid bot | | `okx bot grid positions` | READ | Query open contract-grid positions (liquidation price, margin ratio, unrealized PnL) | | `okx bot grid liquidate-price` | READ | Estimate liquidation price for a contract-grid bot | | `okx bot grid close-position` | WRITE | Close remaining position after bot stopped with stopType=2 | | `okx bot grid orders` | READ | List active or history grid bots | | `okx bot grid details` | READ | Grid bot details + PnL | | `okx bot grid sub-orders` | READ | Individual grid fills or pending orders |

DCA Bot (Spot & Contract)

| Command | Type | Description | |---|---|---| | `okx bot dca create` | WRITE | Create a DCA (Martingale) bot (spot or contract) | | `okx bot dca stop` | WRITE | Stop a DCA bot (spot or contract) | | `okx bot dca orders` | READ | List active or history DCA bots (default: contract_dca) | | `okx bot dca details` | READ | DCA bot details + PnL | | `okx bot dca sub-orders` | READ | DCA cycles and orders within a cycle |

Operation Flow

Step 1 — Identify bot type and action

Parse user request → determine module (Grid / DCA) and action (create / stop / list / details).

Step 2 — Execute

**READ commands** (orders, details, sub-orders): run immediately after profile confirmation.

**WRITE commands** (create, amend, stop): confirm key parameters with user once before executing.

Step 3 — Verify after writes

• After create → run the corresponding `orders` command to confirm active
• After amend → run `bot grid details` to confirm updated config
• After stop → run `orders --history` to confirm stopped

Key Rules

• **Never auto-transfer funds.** If balance is insufficient for bot creation, report the shortfall (current available vs required) and ask the user how to proceed: (1) transfer funds manually, (2) reduce size, or (3) cancel.
• **`algoId`** is the bot's algo order ID (from create or list output).