OKX CEX Bot Trading CLI

Grid and DCA (Contract Martingale) trading bot management on OKX exchange. All grid and DCA bots in this skill are native OKX platform bots — they run server-side on OKX and do not require a locally running process. Requires API credentials.

Prerequisites

Install okx CLI:
```
npm install -g @okx_ai/okx-trade-cli
```

Configure credentials — check first, then set up if missing:

okx config show   # shows configured profiles; api_key shows last 4 chars if set

If credentials are already configured → proceed to step 3.

If not configured:

okx config init          # interactive wizard — demo mode (opens browser → OKX demo API page)
okx config init          # run again for live mode (creates a second profile)

Creates okx-demo (demo) and/or okx-prod (live) profiles. Each run safely merges into the existing config file without overwriting other profiles.

Or set environment variables:

export OKX_API_KEY=your_key
export OKX_SECRET_KEY=your_secret
export OKX_PASSPHRASE=your_passphrase

Security: NEVER accept API credentials directly in chat. If the user pastes credentials, warn them and ask them to run okx config init or edit ~/.okx/config.toml manually with their local editor instead. Credentials must never appear in conversation history.

Switch between profiles:

okx config set default_profile okx-demo   # switch to demo
okx config set default_profile okx-prod   # switch to live
okx --profile okx-prod bot grid orders --algoOrdType grid  # one-off override

Test with demo mode (simulated trading, no real funds):

okx --profile demo bot grid orders --algoOrdType grid

Credential & Profile Check

Run this check before any authenticated command.

Step A — Verify credentials

okx config show       # verify configuration status (output is masked)

If the command returns an error or shows no configuration: stop all operations, guide the user to run okx config init, and wait for setup to complete before retrying.
If credentials are configured: proceed to Step B.

Step B — Confirm profile (required)

--profile is required for all authenticated commands. Never add a profile implicitly.

Value	Mode	Funds
`live`	实盘	Real funds — bot operates with real money
`demo`	模拟盘	Simulated — safe for testing bot configurations

Resolution rules:

Current message intent is clear (e.g. "real" / "实盘" / "live" → live; "test" / "模拟" / "demo" → demo) → use it and inform the user: "Using --profile live (实盘)" or "Using --profile demo (模拟盘)"
Current message has no explicit declaration → check conversation context for a previous profile:
- Found → use it, inform user: "Continuing with --profile live (实盘) from earlier"
- Not found → ask: "Live (实盘) or Demo (模拟盘)?" — wait for answer before proceeding

Handling 401 Authentication Errors

If any command returns a 401 / authentication error:

Stop immediately — do not retry the same command
Inform the user: "Authentication failed (401). Your API credentials may be invalid or expired."
Guide the user to update credentials by editing the file directly with their local editor:
```
~/.okx/config.toml
```
Update the fields api_key, secret_key, passphrase under the relevant profile. Do NOT paste the new credentials into chat.
After the user confirms the file is updated, run okx config show to verify (output is masked)
Only then retry the original operation

Demo vs Live Mode

Profile is the single control for 实盘/模拟盘 switching — exactly two options:

`--profile`	Mode	Funds
`live`	实盘	Real funds — bot operates with real money
`demo`	模拟盘	Simulated — no real funds

okx --profile live  bot grid create ...    # 实盘 — real funds
okx --profile demo  bot grid create ...    # 模拟盘 — simulated funds

Rules:

--profile is required on every authenticated command — determined in "Credential & Profile Check" Step B
Every response after a command must append: [profile: live] or [profile: demo]
Do not use the --demo flag for mode switching — use --profile instead
For bot create/stop operations (write commands), profile must be explicitly confirmed before execution

Example

User: "Start a BTC grid bot"
Agent: "Live (实盘) or Demo (模拟盘)?"
User: "Demo"
Agent runs: okx --profile demo bot grid create --instId BTC-USDT --algoOrdType grid ...
Agent replies: "Grid bot created: 12345678 (OK) — simulated, no real funds used. [profile: demo]"

Skill Routing

For market data (prices, charts, depth, funding rates) → use okx-cex-market
For account balance, P&L, positions history, fees, transfers → use okx-cex-portfolio
For regular spot/swap/futures/algo orders → use okx-cex-trade
For grid and DCA trading strategies (native OKX platform bots) → use okx-cex-bot (this skill)

Quickstart

# Create a spot grid bot on BTC ($90k–$100k, 10 grids, invest 1000 USDT)
okx bot grid create --instId BTC-USDT --algoOrdType grid \
  --minPx 90000 --maxPx 100000 --gridNum 10 --quoteSz 1000

# Create a contract grid bot on BTC perp (neutral, 5x leverage, 100 USDT margin)
# basePos defaults to true for long/short (opens base position); neutral ignores it
okx bot grid create --instId BTC-USDT-SWAP --algoOrdType contract_grid \
  --minPx 90000 --maxPx 100000 --gridNum 10 \
  --direction neutral --lever 5 --sz 100

# List all active grid bots
okx bot grid orders --algoOrdType grid

# Get grid bot details and P&L
okx bot grid details --algoOrdType grid --algoId <algoId>

# Stop a grid bot (keep assets as-is)
okx bot grid stop --algoId <algoId> --algoOrdType grid --instId BTC-USDT --stopType 2

# Create a contract DCA bot on BTC perp (long, 3x leverage, 3% TP)
okx bot dca create --instId BTC-USDT-SWAP --lever 3 --direction long \
  --initOrdAmt 100 --safetyOrdAmt 50 --maxSafetyOrds 3 \
  --pxSteps 0.03 --pxStepsMult 1 --volMult 1 --tpPct 0.03

# List all active contract DCA bots
okx bot dca orders

# Get DCA bot details
okx bot dca details --algoId <algoId>

# Stop a DCA bot
okx bot dca stop --algoId <algoId>

Command Index

Grid Bot

#	Command	Type	Description
1	`okx bot grid create`	WRITE	Create a grid bot
2	`okx bot grid stop`	WRITE	Stop a grid bot
3	`okx bot grid orders`	READ	List active or history grid bots
4	`okx bot grid details`	READ	Single grid bot details + PnL
5	`okx bot grid sub-orders`	READ	Individual grid fills or live orders

DCA Bot (Contract Only)

#	Command	Type	Description
6	`okx bot dca create`	WRITE	Create a Contract DCA bot
7	`okx bot dca stop`	WRITE	Stop a Contract DCA bot
8	`okx bot dca orders`	READ	List active or history Contract DCA bots
9	`okx bot dca details`	READ	Single Contract DCA bot details + PnL
10	`okx bot dca sub-orders`	READ	Contract DCA cycles and orders within a cycle

Cross-Skill Workflows

Spot Grid Bot

User: "Start a BTC grid bot between $90k and $100k with 10 grids, invest 1000 USDT"

1. okx-cex-market    okx market ticker BTC-USDT                     → confirm price is in range
2. okx-cex-portfolio okx account balance USDT                       → confirm available funds
        ↓ user approves
3. okx-cex-bot       okx bot grid create --instId BTC-USDT --algoOrdType grid \
                       --minPx 90000 --maxPx 100000 --gridNum 10 --quoteSz 1000
4. okx-cex-bot       okx bot grid orders --algoOrdType grid          → confirm bot is active
5. okx-cex-bot       okx bot grid details --algoOrdType grid --algoId <id> → monitor PnL

Contract Grid Bot (Long / Short / Neutral)

User: "Create a long grid bot on BTC perp from $90k to $100k, 10x leverage"

1. okx-cex-market    okx market ticker BTC-USDT-SWAP                → confirm current price
2. okx-cex-portfolio okx account balance USDT                       → confirm margin
        ↓ user approves
3. okx-cex-bot       okx bot grid create --instId BTC-USDT-SWAP --algoOrdType contract_grid \
                       --minPx 90000 --maxPx 100000 --gridNum 10 \
                       --direction long --lever 10 --sz 100
                       # basePos defaults to true (opens base position for long/short)
                       # For short: --direction short; for neutral: --direction neutral
4. okx-cex-bot       okx bot grid orders --algoOrdType contract_grid → confirm active

Contract DCA Bot (Long / Short)

User: "Start a long DCA bot on BTC perp, 3x leverage, $200 initial, 3% TP"

1. okx-cex-market    okx market ticker BTC-USDT-SWAP               → confirm current price
2. okx-cex-portfolio okx account balance USDT                       → confirm margin
        ↓ user approves
3. okx-cex-bot       okx bot dca create --instId BTC-USDT-SWAP \
                       --lever 3 --direction long \
                       --initOrdAmt 200 --safetyOrdAmt 100 --maxSafetyOrds 3 \
                       --pxSteps 0.03 --pxStepsMult 1 --volMult 1 --tpPct 0.03
                       # For short: --direction short
4. okx-cex-bot       okx bot dca orders                             → confirm active
5. okx-cex-bot       okx bot dca details --algoId <id>              → monitor PnL

Monitor and Stop All Bots

User: "Show all my active bots and stop the ones losing money"

1. okx-cex-bot       okx bot grid orders --algoOrdType grid         → list spot grid bots
2. okx-cex-bot       okx bot grid orders --algoOrdType contract_grid → list contract grid bots
3. okx-cex-bot       okx bot dca orders                             → list DCA bots
4. okx-cex-bot       okx bot grid details --algoOrdType grid --algoId <id>  → check PnL
5. okx-cex-bot       okx bot grid stop --algoId <id> --algoOrdType grid --instId BTC-USDT --stopType 2

Operation Flow

Step 0 — Credential & Profile Check

Before any authenticated command:

Determine profile (required):

Options: live (实盘) or demo (模拟盘) — exactly these two values

Current message intent clear (e.g. "real"/"实盘"/"live" → live; "test"/"模拟"/"demo" → demo) → use it, inform user: "Using --profile live (实盘)"
Current message has no explicit declaration → check conversation context for previous profile:
- Found → use it, inform user: "Continuing with --profile live (实盘) from earlier"
- Not found → ask: "Live (实盘) or Demo (模拟盘)?" — wait for answer

If no credentials configured: guide user to run okx config init, stop all trading actions

After every command result: append [profile: live] or [profile: demo] to the response

Critical: `algoId` and `algoOrdType` Rules

algoId is the bot's algo order ID (returned by bot grid create / bot dca create or listed by bot grid orders / bot dca orders). It is NOT a normal trade order ID (ordId). Never fabricate or guess an algoId — always obtain it from a prior create or list command.
algoOrdType for grid commands must match the bot's actual type. Always use the algoOrdType value from the bot grid orders response — do not infer from user description alone. Passing a mismatched type (e.g., contract_grid for a spot grid bot) causes error 50016.
When operating on an existing bot (details, sub-orders, stop), always retrieve the bot list first to get the correct algoId and algoOrdType pair, unless the user provides them explicitly.

Step 1: Identify Bot Type and Action

Grid bot create → okx bot grid create
Grid bot stop → okx bot grid stop
Grid bot status/P&L → okx bot grid orders + okx bot grid details
Grid individual fills → okx bot grid sub-orders
DCA bot create → okx bot dca create (requires --lever and --direction)
DCA bot stop → okx bot dca stop (only --algoId needed)
DCA bot status/P&L → okx bot dca orders + okx bot dca details
DCA individual cycles/orders → okx bot dca sub-orders

Step 2: Run Read Commands Immediately — Confirm Profile (Step 0) then Writes

Read commands (orders, details, sub-orders): run immediately.

--algoOrdType for grid → infer from context (grid for spot, contract_grid for perp)
--history → use default (active); only query history if explicitly requested

Write commands (create, stop): confirm once before executing.

Grid create: confirm --minPx, --maxPx, --gridNum; verify --minPx < current price < --maxPx; confirm investment size
- Spot grid: --quoteSz (USDT) or --baseSz (base currency)
- Contract grid: --direction (long/short/neutral), --lever, --sz (investment margin in USDT); --basePos defaults to true (open base position for long/short)
DCA create: confirm --instId, --lever, --direction, --initOrdAmt, --safetyOrdAmt, --maxSafetyOrds, --pxSteps, --pxStepsMult, --volMult, --tpPct; optional: --slPct, --slMode, --allowReinvest, --triggerStrategy, --triggerPx
Grid stop: confirm --stopType (default omitted → keep assets; 1=sell all to quote)
DCA stop: only --algoId needed
Demo dry-run: suggest okx --profile demo bot grid create ... when user is unsure

⚠ Insufficient balance — NEVER auto-transfer funds. If the trading account balance is insufficient to create a bot, do NOT automatically initiate a fund transfer (account_transfer). Instead, inform the user of the shortfall (current available vs. required amount) and ask how they want to proceed. Suggested options to present:

Transfer funds from funding account to trading account (specify amount)
Reduce the investment size to fit available balance
Cancel the bot creation

Step 3: Verify After Writes

After grid create: run okx bot grid orders to confirm bot is active; then okx bot grid details to monitor PnL
After DCA create: run okx bot dca orders to confirm bot is active; then okx bot dca details for details
After stop: run okx bot grid orders --history / okx bot dca orders --history to confirm bot is stopped

CLI Command Reference

Grid Bot — Create

okx bot grid create --instId <id> --algoOrdType <type> \
  --maxPx <px> --minPx <px> --gridNum <n> \
  [--runType <1|2>] \
  [--quoteSz <n>] [--baseSz <n>] \
  [--direction <long|short|neutral>] [--lever <n>] [--sz <n>] \
  [--basePos] [--no-basePos] \
  [--json]

Param	Required	Default	Description
`--instId`	Yes	-	Instrument (e.g., `BTC-USDT` for spot grid, `BTC-USDT-SWAP` for contract grid)
`--algoOrdType`	Yes	-	`grid` (spot grid) or `contract_grid` (contract grid)
`--maxPx`	Yes	-	Upper price boundary
`--minPx`	Yes	-	Lower price boundary
`--gridNum`	Yes	-	Grid levels (2–100)
`--runType`	No	`1`	`1`=arithmetic spacing, `2`=geometric spacing
`--quoteSz`	Cond.	-	USDT investment — spot grid only (provide `quoteSz` or `baseSz`)
`--baseSz`	Cond.	-	Base currency investment — spot grid only
`--direction`	Cond.	-	`long`, `short`, or `neutral` — contract grid only
`--lever`	Cond.	-	Leverage (e.g., `5`) — contract grid only
`--sz`	Cond.	-	Investment margin in USDT — contract grid only
`--basePos` / `--no-basePos`	No	`true`	Open a base position at creation — contract grid only (ignored for neutral direction). Default is `true` (opens base position). Use `--no-basePos` to disable.

Grid Bot — Stop

okx bot grid stop --algoId <id> --algoOrdType <type> --instId <id> \
  [--stopType <1|2|3|5|6>] [--json]

--algoId and --algoOrdType must come from bot grid orders output. The algoOrdType must match the bot's actual type — do not guess.

`--stopType`	Behavior
`1`	Stop + sell/close all positions at market
`2`	Stop + keep current assets as-is (default)
`3`	Stop + close at limit prices
`5`	Stop + partial close
`6`	Stop without selling (smart arbitrage)

Grid Bot — List Orders

okx bot grid orders --algoOrdType <type> [--instId <id>] [--algoId <id>] [--history] [--json]

Param	Required	Default	Description
`--algoOrdType`	Yes	-	`grid` (spot), `contract_grid` (contract), or `moon_grid` (moon)
`--instId`	No	-	Filter by instrument
`--algoId`	No	-	Filter by algo order ID (returned by create or previous list). NOT a normal trade order ID.
`--history`	No	false	Show completed/stopped bots instead of active

Grid Bot — Details

okx bot grid details --algoOrdType <type> --algoId <id> [--json]

--algoId and --algoOrdType must come from bot grid orders output. The algoOrdType must match the bot's actual type.

Returns: bot config, current PnL (pnlRatio), grid range, number of grids, state, position info.

Grid Bot — Sub-Orders

okx bot grid sub-orders --algoOrdType <type> --algoId <id> [--live] [--json]

--algoId and --algoOrdType must come from bot grid orders output.

Flag	Effect
(default)	Filled sub-orders (executed grid trades)
`--live`	Pending grid orders currently on the book

DCA Bot — Create (Contract Only)

okx bot dca create --instId <id> --lever <n> --direction <long|short> \
  --initOrdAmt <n> --safetyOrdAmt <n> --maxSafetyOrds <n> \
  --pxSteps <ratio> --pxStepsMult <mult> --volMult <mult> --tpPct <ratio> \
  [--slPct <ratio>] [--slMode <limit|market>] [--allowReinvest <true|false>] \
  [--triggerStrategy <instant|price|rsi>] [--triggerPx <price>] [--json]

Param	Required	Default	Description
`--instId`	Yes	-	Instrument (e.g., `BTC-USDT-SWAP`)
`--lever`	Yes	-	Leverage multiplier (e.g., `3`)
`--direction`	Yes	-	`long` or `short`
`--initOrdAmt`	Yes	-	Initial order margin (quote currency)
`--maxSafetyOrds`	Yes	-	Max number of safety orders (e.g., `3`; `0` = no DCA)
`--safetyOrdAmt`	Yes	-	Safety order margin (quote currency)
`--pxSteps`	Yes	-	Initial price deviation percentage (e.g., `0.03` = 3%)
`--pxStepsMult`	Yes	-	Price step multiplier between safety orders (e.g., `1.2`)
`--volMult`	Yes	-	Safety order size multiplier (e.g., `1.5`)
`--tpPct`	Yes	-	Take-profit ratio (e.g., `0.03` = 3%)
`--slPct`	No	-	Stop-loss ratio (e.g., `0.05` = 5%)
`--slMode`	No	`market`	Stop-loss price type: `limit` (limit price) or `market` (market price)
`--allowReinvest`	No	`true`	Reinvest profit into the next DCA cycle
`--triggerStrategy`	No	`instant`	How the bot starts: `instant`, `price` (wait for trigger price), or `rsi` (RSI signal)
`--triggerPx`	No	-	Trigger price — required when `triggerStrategy=price`

DCA Bot — Stop

okx bot dca stop --algoId <id> [--json]

Param	Required	Description
`--algoId`	Yes	DCA bot algo order ID (from `bot dca orders` or `bot dca create` output). NOT a normal trade order ID.

DCA Bot — List Orders

okx bot dca orders [--algoId <id>] [--instId <id>] [--history] [--json]

Param	Required	Default	Description
`--algoId`	No	-	Filter by DCA bot algo order ID (from create or previous list). NOT a normal trade order ID.
`--instId`	No	-	Filter by instrument, e.g. `BTC-USDT-SWAP`
`--history`	No	false	Show completed/stopped bots instead of active

DCA Bot — Details

okx bot dca details --algoId <id> [--json]

--algoId must come from bot dca orders or bot dca create output. NOT a normal trade order ID.

Returns: position details including avgPx, upl, liqPx, sz, tpPx, slPx, initPx, fundingFee, fee, fillSafetyOrds.

DCA Bot — Sub-Orders

okx bot dca sub-orders --algoId <id> [--cycleId <id>] [--json]

--algoId must come from bot dca orders or bot dca create output.

Flag / Param	Effect
(default)	List all cycles
`--cycleId <id>`	Show orders within a specific cycle

MCP Tool Reference

CLI and MCP tools share the same underlying tool layer. All DCA tools operate on contract DCA only.

Tool	Description
`dca_create_order`	Create a Contract DCA bot
`dca_stop_order`	Stop a Contract DCA bot
`dca_get_orders`	List Contract DCA bots
`dca_get_order_details`	Single Contract DCA bot details
`dca_get_sub_orders`	Contract DCA cycles and orders within a cycle

Input / Output Examples

"Start a BTC grid bot from $90k to $100k with 10 grids"

okx bot grid create --instId BTC-USDT --algoOrdType grid \
  --minPx 90000 --maxPx 100000 --gridNum 10 --quoteSz 1000
# → Grid bot created: 12345678 (OK)

"Show all my active grid bots"

okx bot grid orders --algoOrdType grid

"What's the P&L on my BTC grid bot?"

okx bot grid details --algoOrdType grid --algoId 12345678
# → pnlRatio, pnl, investAmt, totalAnnRate, runType, gridNum, maxPx, minPx

"Stop my BTC grid bot and keep the assets"

okx bot grid stop --algoId 12345678 --algoOrdType grid --instId BTC-USDT --stopType 2

"Create a DCA bot on BTC perp, long, 3x leverage, 3% TP"

okx bot dca create --instId BTC-USDT-SWAP --lever 3 --direction long \
  --initOrdAmt 200 --safetyOrdAmt 100 --maxSafetyOrds 3 \
  --pxSteps 0.03 --pxStepsMult 1 --volMult 1 --tpPct 0.03
# → DCA bot created: 87654321 (OK)

"Create a DCA bot with safety orders and stop-loss"

okx bot dca create --instId BTC-USDT-SWAP --lever 3 --direction long \
  --initOrdAmt 200 --safetyOrdAmt 100 --maxSafetyOrds 3 \
  --pxSteps 0.03 --pxStepsMult 1.2 --volMult 1.5 \
  --tpPct 0.03 --slPct 0.15 --slMode market

"Show my active DCA bots"

okx bot dca orders

"How is my BTC DCA bot doing?"

okx bot dca details --algoId 87654321
# → avgPx, upl, liqPx, sz, tpPx, slPx, fillSafetyOrds

"Stop my BTC DCA bot"

okx bot dca stop --algoId 87654321

Edge Cases

Grid Bot

Price out of range: --minPx must be < current price < --maxPx; check with okx-cex-market first
Insufficient balance: check okx-cex-portfolio → account balance before creating. If insufficient, do NOT auto-transfer — report the shortfall and ask the user for instructions (see Step 2)
Contract grid direction: long (buys more at lower prices), short (sells at higher), neutral (both)
Contract grid basePos: defaults to true — long/short grids automatically open a base position at creation. Neutral direction ignores this. Pass --no-basePos to disable.
Contract grid --sz: investment margin in USDT (not number of contracts)
Stop type: stopType 1 sells/closes all; stopType 2 keeps assets; stopType 5/6 for contract grid positions
Already stopped bot: stop returns error — check bot grid orders --history first to confirm state
Demo mode: okx --profile demo bot grid create ... — safe for testing, no real funds

DCA Bot

Contract only: DCA bots only support futures/swap instruments (e.g., BTC-USDT-SWAP). Spot DCA is not available.
Insufficient balance: check okx-cex-portfolio → account balance before creating. If insufficient, do NOT auto-transfer — report the shortfall and ask the user for instructions (see Step 2)
pxStepsMult: use 1.0 for equal price spacing; >1.0 to widen gaps between successive safety orders
volMult: use 1.0 for equal safety order sizes; >1.0 to increase size per safety order (Martingale)
triggerStrategy: instant (default) starts immediately; price waits for a trigger price; rsi uses RSI signals
Stop: only --algoId is needed — no instId or stopType required
Already stopped bot: stop returns error — check bot dca orders --history first to confirm state
DCA create requires: --instId, --lever, --direction (long/short), --initOrdAmt, --safetyOrdAmt, --maxSafetyOrds, --pxSteps, --pxStepsMult, --volMult, --tpPct

Communication Guidelines

Use "bot" not "strategy" when referring to grid or DCA in user-facing responses (e.g., "grid bot", "DCA bot" — not "grid strategy" or "DCA strategy").
Always refer to DCA bots as "DCA" — do not translate to "定投" or "recurring buy". The underlying mechanism is Martingale (马丁格尔), not simple dollar cost averaging. Use "DCA" in all user-facing responses regardless of language.
Grid bot can be referred to as "网格" in Chinese contexts.

Parameter Display Names

When communicating with users, use the display name instead of the raw API field name. The API field is for internal mapping only.

Currency placeholders: {base} and {quote} refer to the actual currencies from the trading pair. Extract them by splitting instId on -: for BTC-USDT-SWAP → base=BTC, quote=USDT (ignore the SWAP suffix); for ETH-USDT-SWAP → base=ETH, quote=USDT.

Grid Bot — Spot (`algoOrdType=grid`)

API Field	Display Name (EN)	Display Name (ZH)
`instId`	Trading pair	交易对
`minPx`	Lower price bound	网格下限价格
`maxPx`	Upper price bound	网格上限价格
`gridNum`	Number of grids	网格数量
`quoteSz`	Investment amount ({quote})	投入金额（{quote}）
`baseSz`	Investment amount ({base})	投入金额（{base}）
`runType`	Spacing mode (1=arithmetic, 2=geometric)	网格间距模式（1=等差, 2=等比）
`stopType`	Stop behavior	停止方式

Grid Bot — Contract (`algoOrdType=contract_grid`)

API Field	Display Name (EN)	Display Name (ZH)
`instId`	Trading pair	交易对
`minPx`	Lower price bound	网格下限价格
`maxPx`	Upper price bound	网格上限价格
`gridNum`	Number of grids	网格数量
`sz`	Investment margin ({quote})	投入保证金（{quote}）
`direction`	Direction (long / short / neutral)	方向（做多 / 做空 / 中性）
`lever`	Leverage	杠杆倍数
`runType`	Spacing mode (1=arithmetic, 2=geometric)	网格间距模式（1=等差, 2=等比）
`basePos`	Open base position	是否开底仓
`stopType`	Stop behavior	停止方式

DCA Bot (Contract)

API Field	Display Name (EN)	Display Name (ZH)
`instId`	Trading pair	交易对
`initOrdAmt`	Initial margin ({quote})	首单保证金（{quote}）
`safetyOrdAmt`	Safety order margin ({quote})	补仓保证金（{quote}）
`maxSafetyOrds`	Max safety orders	最大补仓次数
`pxSteps`	Price drop per safety order (%)	补仓价格跌幅（%）
`pxStepsMult`	Price step multiplier	补仓跌幅倍数
`volMult`	Safety order size multiplier	补仓金额倍数
`tpPct`	Take-profit ratio (%)	止盈比例（%）
`slPct`	Stop-loss ratio (%)	止损比例（%）
`slMode`	Stop-loss type (limit / market)	止损类型（限价 / 市价）
`lever`	Leverage	杠杆倍数
`direction`	Direction (long / short)	方向（做多 / 做空）
`allowReinvest`	Reinvest profit into next cycle	利润再投入下一轮
`triggerStrategy`	Trigger mode (instant / price / rsi)	触发方式（立即 / 价格 / RSI）
`triggerPx`	Trigger price (for price mode)	触发价格（价格模式时）

slPct stop-loss logic (contract DCA):

Long (direction=long): stop-loss price = initial order fill price × (1 − slPct)

Short (direction=short): stop-loss price = initial order fill price × (1 + slPct)

When the stop-loss price is triggered and the position is fully closed, the bot ends.

Interaction Rules

When collecting parameters from the user, always use natural language — never expose raw API field names.

Ask "What price range for the grid? (lower ~ upper)" — not "Enter minPx and maxPx"
Ask "How many grids?" — not "Enter gridNum"
Spot grid: ask "How much to invest (USDT)?" (use the actual quote currency) — not "Enter quoteSz"
Contract grid: ask "How much margin to invest (USDT)?" (use the actual quote currency) — not "Enter sz"
DCA: ask "How much initial margin (USDT)?" — not "Enter initOrdAmt"
Ask "What leverage?" — not "Enter lever"
Ask "Long or short?" — not "Enter direction"
Ask "Take-profit target (%)?" — not "Enter tpPct"
Ask "How many safety orders at most?" — not "Enter maxSafetyOrds"

If the user already provides values in their initial request, do not re-ask — map them directly to the corresponding API fields.

Global Notes

Grid and DCA bots are native OKX platform bots — they run entirely on OKX servers; stopping the CLI does not affect them
All write commands require valid credentials in ~/.okx/config.toml or env vars
--profile <name> is required for all authenticated commands; see "Credential & Profile Check" section
Every command result includes a [profile: <name>] tag for audit reference
--json returns raw OKX API v5 response
Rate limit: 20 requests per 2 seconds per UID for all bot operations
Grid --gridNum range: 2–100
DCA safety orders are triggered sequentially as price drops by --pxSteps increments
Contract DCA automatically starts with an instant trigger by default (configurable via --triggerStrategy)

okx-cex-bot

OKX CEX Bot Trading CLI

Prerequisites

Credential & Profile Check

Step A — Verify credentials

Step B — Confirm profile (required)

Handling 401 Authentication Errors

Demo vs Live Mode

Example

Skill Routing

Quickstart

Command Index

Grid Bot

DCA Bot (Contract Only)

Cross-Skill Workflows

Spot Grid Bot

Contract Grid Bot (Long / Short / Neutral)

Contract DCA Bot (Long / Short)

Monitor and Stop All Bots

Operation Flow

Step 0 — Credential & Profile Check

Critical: algoId and algoOrdType Rules

Step 1: Identify Bot Type and Action

Step 2: Run Read Commands Immediately — Confirm Profile (Step 0) then Writes

Step 3: Verify After Writes

CLI Command Reference

Grid Bot — Create

Grid Bot — Stop

Grid Bot — List Orders

Grid Bot — Details

Grid Bot — Sub-Orders

DCA Bot — Create (Contract Only)

DCA Bot — Stop

DCA Bot — List Orders

DCA Bot — Details

DCA Bot — Sub-Orders

MCP Tool Reference

Input / Output Examples

Edge Cases

Grid Bot

DCA Bot

Communication Guidelines

Parameter Display Names

Grid Bot — Spot (algoOrdType=grid)

Grid Bot — Contract (algoOrdType=contract_grid)

DCA Bot (Contract)

Interaction Rules

Global Notes

Critical: `algoId` and `algoOrdType` Rules

Grid Bot — Spot (`algoOrdType=grid`)

Grid Bot — Contract (`algoOrdType=contract_grid`)