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.
Use metadata.version from this file's frontmatter as the reference for Step 2.

Prerequisites

CODEBLOCK0

Check credentials, then set up if missing:

CODEBLOCK1

Security: NEVER accept API credentials in chat. Guide users to okx config init or edit ~/.okx/config.toml directly.

Credential & Profile Check

Run before every authenticated command.

Step A — Verify credentials

CODEBLOCK2

If no configuration → stop, guide user to okx config init, wait for completion.

Step B — Determine profile (required)

INLINECODE5	Mode	Funds
INLINECODE6	实盘	Real money
INLINECODE7

模拟盘 | Simulated, safe for testing |

Resolution:

1. 1. User intent is clear ("real"/"实盘"/"live" → live; "test"/"模拟"/"demo" → demo) → use it, inform user
2. No explicit declaration → check conversation context for previous profile → use it if found
3. Nothing found → ask: "Live (实盘) or Demo (模拟盘)?" — wait before proceeding

After every command: append [profile: live] or INLINECODE11

Handling 401 Errors

Stop immediately. Guide user to update ~/.okx/config.toml with their editor. Verify with okx config show before retrying.

Skill Routing

Need	Skill
Market data, prices, depth	INLINECODE14
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
INLINECODE18	WRITE	Create a grid bot (spot or contract)
INLINECODE19

WRITE | Stop a grid bot | | 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
INLINECODE23	WRITE	Create a DCA (Martingale) bot (spot or contract)
INLINECODE24

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, 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 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). It is NOT a normal ordId. Never fabricate — always obtain from a prior command.
• algoOrdType for grid must match the bot's actual type. Always use the value from bot grid orders — do not infer from user description alone. Mismatch causes error 50016.
• When operating on existing bots, always list first to get correct IDs, unless the user provides them explicitly.
• TP/SL constraints: tpTriggerPx/tpRatio and slTriggerPx/slRatio are mutually exclusive pairs.

CLI Command Reference

Grid Bot — Create

CODEBLOCK3

Param	Required	Default	Description
INLINECODE39	Yes	-	Instrument (e.g., BTC-USDT for spot, BTC-USDT-SWAP for USDT-M contract, BTC-USD-SWAP for coin-M contract)
INLINECODE43

Yes | - | grid (spot grid) or contract_grid (contract grid, including coin-margined) |
| --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 — required for contract grid |
| --lever | Cond. | - | Leverage (e.g., 5) — contract grid only |
| --sz | Cond. | - | Investment margin in USDT (USDT-M) or coin (coin-M) — contract grid only |
| --basePos / --no-basePos | No | true | Open a base position at creation — contract grid only (ignored for neutral). Use --no-basePos to disable |
| --tpTriggerPx | No | - | Take-profit trigger price (mutually exclusive with --tpRatio) |
| --slTriggerPx | No | - | Stop-loss trigger price (mutually exclusive with --slRatio) |
| --tpRatio | No | - | Take-profit ratio — contract grid only (mutually exclusive with --tpTriggerPx) |
| --slRatio | No | - | Stop-loss ratio — contract grid only (mutually exclusive with --slTriggerPx) |
| --algoClOrdId | No | - | Client-defined algo order ID (1-32 alphanumeric). Unique per user, enables idempotent creation |

---

Grid Bot — Stop

CODEBLOCK4

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

INLINECODE81	Behavior
INLINECODE82	Stop + sell/close all positions at market (default)
INLINECODE83

Stop + keep current assets as-is | | 3 | Stop + close at limit prices | | 5 | Stop + partial close | | 6 | Stop without selling (smart arbitrage) |

---

Grid Bot — List Orders

CODEBLOCK5

Param	Required	Default	Description
INLINECODE87	Yes	-	INLINECODE88 (spot), contract_grid (contract), or moon_grid (moon)
INLINECODE91

No | - | Filter by instrument |
| --algoId | No | - | Filter by algo order ID. NOT a normal trade order ID |
| --history | No | false | Show completed/stopped bots instead of active |

---

Grid Bot — Details

CODEBLOCK6

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

---

Grid Bot — Sub-Orders

CODEBLOCK7

Flag	Effect
(default)	Filled sub-orders (executed grid trades)
INLINECODE95

Pending grid orders currently on the book |

---

DCA Bot — Create (Spot & Contract)

CODEBLOCK8

Param	Required	Default	Description
INLINECODE96	Yes	-	INLINECODE97 (Spot DCA) or contract_dca (Contract DCA)
INLINECODE99

Yes | - | Instrument (e.g., BTC-USDT for spot, BTC-USDT-SWAP for contract) |
| --lever | Cond. | - | Leverage multiplier (e.g., 3). Required for contract_dca |
| --direction | Yes | - | long or short. spot_dca must be long |
| --initOrdAmt | Yes | - | Initial order amount (quote currency) |
| --maxSafetyOrds | Yes | - | Max safety orders, integer [0, 100] (e.g., 3; 0 = no DCA) |
| --safetyOrdAmt | Cond. | - | Safety order amount (quote currency). Required when maxSafetyOrds > 0 |
| --pxSteps | Cond. | - | Initial price deviation [0.001, 0.5], e.g., 0.03 = 3%. Required when maxSafetyOrds > 0 |
| --pxStepsMult | Cond. | 1 | Price step multiplier (e.g., 1.2). Required when maxSafetyOrds > 0 |
| --volMult | Cond. | 1 | Safety order size multiplier (e.g., 1.5). Required when maxSafetyOrds > 0 |
| --tpPct | Yes | - | Take-profit ratio: long [0.001, 10], short [0.001, 0.9999] (e.g., 0.03 = 3%) |
| --slPct | No | - | Stop-loss ratio, must exceed MPD (e.g., 0.05 = 5%). Must be used with --slMode |
| --slMode | No | market | Stop-loss type: limit or market. Must be used with --slPct |
| --allowReinvest | No | true | Reinvest profit into the next DCA cycle |
| --triggerStrategy | No | instant | contractdca: instant, price, rsi; spotdca: instant, rsi |
| --triggerPx | No | - | Trigger price — required when triggerStrategy=price (contract_dca only) |
| --triggerCond | No | - | cross_up or cross_down — required when triggerStrategy=rsi, optional when triggerStrategy=price |
| --thold | No | - | RSI threshold (e.g. 30) — required when triggerStrategy=rsi |
| --timeframe | No | - | RSI timeframe (e.g. 15m) — required when triggerStrategy=rsi |
| --timePeriod | No | 14 | RSI period — optional when triggerStrategy=rsi |
| --algoClOrdId | No | - | Client-defined strategy order ID (1-32 alphanumeric) |
| --reserveFunds | No | true | true or false — whether to reserve funds |
| --tradeQuoteCcy | No | - | Trade quote currency |

Conditional required logic:

• - Always required: --algoOrdType, --instId, --direction, --initOrdAmt, --maxSafetyOrds, INLINECODE173
• When algoOrdType=contract_dca: also required INLINECODE175
• When maxSafetyOrds > 0: also required --safetyOrdAmt, --pxSteps, --pxStepsMult, INLINECODE180
• INLINECODE181 and --slMode must be both set or both omitted

---

DCA Bot — Stop

CODEBLOCK9

Param	Required	Default	Description
INLINECODE183	Yes	-	INLINECODE184 or INLINECODE185
INLINECODE186

Yes | - | DCA bot algo order ID (from create or list output). NOT a normal trade order ID |
| --stopType | Cond. | 1 (contract_dca) | Required for spot_dca: 1=sell all tokens, 2=keep tokens. contract_dca always uses 1 (close position) |

---

DCA Bot — List Orders

CODEBLOCK10

Param	Required	Default	Description
INLINECODE194	No	INLINECODE195	Filter by strategy type
INLINECODE196

No | - | Filter by DCA bot algo order ID |
| --instId | No | - | Filter by instrument |
| --history | No | false | Show completed/stopped bots instead of active |

---

DCA Bot — Details

CODEBLOCK11

Returns: avgPx, upl, liqPx, sz, tpPx, slPx, initPx, fundingFee, fee, fillSafetyOrds, algoClOrdId, baseSz, quoteSz, tradeQuoteCcy.

---

DCA Bot — Sub-Orders

CODEBLOCK12

Flag / Param	Effect
(default)	List all cycles
INLINECODE213

Show orders within a specific cycle |

Quickstart

CODEBLOCK13

Cross-Skill Workflows

Spot Grid Bot

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

CODEBLOCK14

Contract DCA Bot

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

CODEBLOCK15

Spot DCA Bot

User: "帮我在现货上 DCA BTC，首单 100 USDT，5% 止盈"

CODEBLOCK16

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
• Contract grid direction: long (buys more at lower prices), short (sells at higher), neutral (both). Direction is required for contract grid
• 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 (USDT-M) or coin (coin-M), not number of contracts
• Coin-margined grids: use inverse instruments (e.g., BTC-USD-SWAP). Margin unit is the base coin (BTC), not USDT
• Stop type: stopType 1 sells/closes all (default); stopType 2 keeps assets; stopType 5/6 for contract grid positions
• TP/SL: tpTriggerPx/tpRatio and slTriggerPx/slRatio are mutually exclusive pairs. Ratio-based TP/SL is contract grid only
• Already stopped bot: stop returns error — check bot grid orders --history first to confirm state
• Insufficient margin (51340): extract required minimum from error, check balance via okx-cex-portfolio, report shortfall to user — do NOT auto-transfer
• Demo mode: okx --profile demo bot grid create ... — safe for testing, no real funds
• algoClOrdId duplicate: if the same algoClOrdId already exists, the API returns error code INLINECODE236

DCA Bot

• - Spot DCA direction: must always be long. If user says "short spot DCA", explain that spot DCA only supports long direction
• Spot DCA stopType: always ask user whether to sell all tokens (1) or keep them (2) when stopping
• Contract DCA lever: required. If missing, the tool returns a validation error
• pxStepsMult: 1.0 = equal spacing; >1.0 = widen gaps between successive safety orders
• volMult: 1.0 = equal sizes; >1.0 = increase per safety order (Martingale scaling)
• triggerStrategy: instant starts immediately; price waits for trigger price (contractdca only); rsi waits for RSI condition (both spotdca and contractdca)
• Already stopped bot: stop returns error — check bot dca orders --history first
• Demo mode: okx --profile demo bot dca create ... — safe testing, no real funds
• INVALIDPRICESTEPSMULTIPLIER error: adjust slPct. Recalculate MPD = Σ(pxSteps × pxStepsMult^i) for i = 0..maxSafetyOrds−1, then set slPct > MPD
• algoClOrdId duplicate: error code INLINECODE251

Communication Guidelines

• - Grid/DCA: use "bot" not "strategy" (e.g., "grid bot", "DCA bot")
• DCA: always say "DCA" or "Martingale" — DCA supports both Spot DCA and Contract DCA
• Chinese: Grid = "网格", Spot DCA = "现货马丁", Contract DCA = "合约马丁"
• Use natural language for parameters — "What price range?" not "Enter minPx and maxPx"
• If the user already provides values, map directly — don't re-ask

Parameter Display Names

INLINECODE252 and {quote}: extract from instId by splitting on -. E.g., BTC-USDT-SWAP → base=BTC, quote=USDT.

Grid Bot — Spot (algoOrdType=grid)

API Field	EN	ZH
INLINECODE258	Trading pair	交易对
INLINECODE259

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	EN	ZH
INLINECODE267	Trading pair	交易对
INLINECODE268

Lower price bound | 网格下限价格 | | maxPx | Upper price bound | 网格上限价格 | | gridNum | Number of grids | 网格数量 | | sz | Investment margin (USDT for USDT-M; {base} for coin-M) | 投入保证金（USDT-M 为 USDT；币本位为 {base}） | | 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 (Spot & Contract)

API Field	EN	ZH
INLINECODE277	Strategy type (spot/contract)	策略类型（现货/合约）
INLINECODE278

Trading pair | 交易对 | | initOrdAmt | Initial order amount ({quote}) | 首单金额（{quote}） | | safetyOrdAmt | Safety order amount ({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 | 利润再投入 | | triggerStrategy | Trigger mode (contractdca: instant/price/rsi; spotdca: instant/rsi) | 触发方式 | | triggerPx | Trigger price | 触发价格 | | algoClOrdId | Client order ID | 客户端策略订单 ID | | stopType | Stop type (sell all / keep tokens) | 停止类型（卖出/保留） | | reserveFunds | Reserve funds | 预留资金 |

slPct stop-loss logic:

• - Long: stop-loss price = initial fill price × (1 − slPct)
• Short: stop-loss price = initial fill price × (1 + slPct)

When triggered and position fully closed, the bot ends.

Global Notes

• - All bots run on OKX servers — stopping the CLI does not affect them
• INLINECODE297 is required for all authenticated commands
• INLINECODE298 returns the raw OKX API v5 response by default. Add --env to wrap the output as INLINECODE300
• Rate limit: 20 requests per 2 seconds per UID
• Grid --gridNum range: 2–100