OKX CEX Bot Trading CLI
Grid and DCA (Dollar Cost Averaging / 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 CLI:
bash
npm install -g @okx_ai/okx-trade-cli
- Configure credentials:
Or set environment variables:
bash
export OKX_API_KEY=your_key
export OKX_SECRET_KEY=your_secret
export OKX_PASSPHRASE=your_passphrase
- Test with demo mode (simulated trading, no real funds):
bash
okx --demo bot grid orders --algoOrdType grid
Skill Routing
- For market data (prices, charts, depth, funding rates) → use
- For account balance, P&L, positions history, fees, transfers → use
- For regular spot/swap/futures/algo orders → use
- For grid and DCA trading strategies (native OKX platform bots) → use (this skill)
Quickstart
bash
# 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 contracts)
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 DCA bot on BTC (3% TP, 3 safety orders, each triggers at 5% drop)
okx bot dca create --instId BTC-USDT \
--initOrdAmt 50 --safetyOrdAmt 30 --maxSafetyOrds 3 \
--pxSteps 0.05 --pxStepsMult 1 --volMult 1 \
--tpPct 0.03 --triggerType 1
# List all active spot DCA bots
okx bot dca orders
# Get DCA bot details
okx bot dca details --algoId <algoId>
# Stop a DCA bot (sell base and get quote)
okx bot dca stop --algoId <algoId> --instId BTC-USDT --stopType 1
Command Index
Grid Bot
| # | Command | Type | Description |
|---|
| 1 | | WRITE | Create a grid bot |
| 2 | | WRITE | Stop a grid bot |
| 3 | | READ | List active or history grid bots |
| 4 | | READ | Single grid bot details + PnL |
| 5 | | READ | Individual grid fills or live orders |
DCA Bot
| # | Command | Type | Description |
|---|
| 6 | | WRITE | Create a DCA bot (spot or contract) |
| 7 | | WRITE | Stop a DCA bot (spot or contract) |
| 8 | | READ | List active or history DCA bots |
| 9 | | READ | Single DCA bot details + PnL |
| 10 | | READ | Individual DCA fills, live orders, or cycles |
Use
(default) or
to switch between spot and contract DCA.
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
# For short: --direction short; for neutral: --direction neutral
4. okx-cex-bot okx bot grid orders --algoOrdType contract_grid → confirm active
Spot DCA Bot
User: "Set up a DCA bot on ETH, initial buy $100, 5 safety orders at 3% drops, 2% TP"
1. okx-cex-market okx market ticker ETH-USDT → check current price
2. okx-cex-portfolio okx account balance USDT → confirm funds available
↓ user approves
3. okx-cex-bot okx bot dca create --instId ETH-USDT \
--initOrdAmt 100 --safetyOrdAmt 50 --maxSafetyOrds 5 \
--pxSteps 0.03 --pxStepsMult 1 --volMult 1 \
--tpPct 0.02 --triggerType 1
4. okx-cex-bot okx bot dca orders → confirm bot is active
5. okx-cex-bot okx bot dca details --algoId <id> → monitor PnL
Contract DCA Bot (Long / Short)
User: "Start a short 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 --type contract --instId BTC-USDT-SWAP \
--initOrdAmt 200 --safetyOrdAmt 100 --maxSafetyOrds 3 \
--pxSteps 0.03 --pxStepsMult 1.2 --volMult 1.5 \
--tpPct 0.03 --lever 3 --side sell
# For long: --side buy
4. okx-cex-bot okx bot dca orders --type contract → confirm active
5. okx-cex-bot okx bot dca details --type contract --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 [--type contract] → 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 1: Identify Bot Type and Action
- Grid bot create →
- Grid bot stop →
- Grid bot status/P&L → +
- Grid individual fills →
- DCA bot create → (add for contract DCA)
- DCA bot stop → (add for contract DCA)
- DCA bot status/P&L → +
- DCA individual fills/cycles →
Step 2: Run Read Commands Immediately — Confirm Writes
Read commands (orders, details, sub-orders): run immediately.
- for grid → infer from context ( for spot, for perp)
- for DCA → defaults to ; use for contract DCA
- → use default (active); only query history if explicitly requested
Write commands (create, stop): confirm once before executing.
- Grid create: confirm , , ; verify < current price < ; confirm investment size
- Spot grid: (USDT) or (base currency)
- Contract grid: (//), , (number of contracts)
- DCA create: confirm , , , ,
- Spot DCA: requires (=instant, =RSI); default
- Contract DCA: add , , and (=long, =short)
- Grid stop: confirm (default omitted → keep assets; =sell all to quote)
- DCA stop: confirm (=sell base to quote, default; =keep base)
- Demo dry-run: suggest
okx --demo bot grid create ...
Step 3: Verify After Writes
- After grid create: run to confirm bot is active; then to monitor PnL
- After DCA create: run to confirm bot is active; then for details
- After stop: run
okx bot grid orders --history
okx bot dca orders --history
CLI Command Reference
Grid Bot — Create
bash
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>] \
[--json]
| Param | Required | Default | Description |
|---|
| Yes | - | Instrument (e.g., for spot grid, for contract grid) |
| Yes | - | (spot grid) or (contract grid) |
| Yes | - | Upper price boundary |
| Yes | - | Lower price boundary |
| Yes | - | Grid levels (2–100) |
| No | | =arithmetic spacing, =geometric spacing |
| Cond. | - | USDT investment — spot grid only (provide or ) |
| Cond. | - | Base currency investment — spot grid only |
| Cond. | - | , , or — contract grid only |
| Cond. | - | Leverage (e.g., ) — contract grid only |
| Cond. | - | Number of contracts to invest — contract grid only |
Grid Bot — Stop
bash
okx bot grid stop --algoId <id> --algoOrdType <type> --instId <id> \
[--stopType <1|2|3|5|6>] [--json]
| Behavior |
|---|
| Stop + sell/close all positions at market |
| Stop + keep current assets as-is (default) |
| Stop + close at limit prices |
| Stop + partial close |
| Stop without selling (smart arbitrage) |
Grid Bot — List Orders
bash
okx bot grid orders --algoOrdType <type> [--instId <id>] [--algoId <id>] [--history] [--json]
| Param | Required | Default | Description |
|---|
| Yes | - | or |
| No | - | Filter by instrument |
| No | - | Filter by algo ID |
| No | false | Show completed/stopped bots instead of active |
Grid Bot — Details
bash
okx bot grid details --algoOrdType <type> --algoId <id> [--json]
Returns: bot config, current PnL (
), grid range, number of grids, state, position info.
Grid Bot — Sub-Orders
bash
okx bot grid sub-orders --algoOrdType <type> --algoId <id> [--live] [--json]
| Flag | Effect |
|---|
| (default) | Filled sub-orders (executed grid trades) |
| Pending grid orders currently on the book |
DCA Bot — Create
bash
# Spot DCA (default)
okx bot dca create --instId <id> \
--initOrdAmt <n> --safetyOrdAmt <n> --maxSafetyOrds <n> \
--pxSteps <ratio> --pxStepsMult <mult> --volMult <mult> \
--tpPct <ratio> [--slPct <ratio>] \
--triggerType <1|2> \
[--reserveFunds <true|false>] [--json]
# Contract DCA
okx bot dca create --type contract --instId <id> \
--initOrdAmt <n> --safetyOrdAmt <n> --maxSafetyOrds <n> \
--pxSteps <ratio> --pxStepsMult <mult> --volMult <mult> \
--tpPct <ratio> [--slPct <ratio>] \
--lever <n> --side <buy|sell> \
[--reserveFunds <true|false>] [--json]
| Param | Required | Default | Description |
|---|
| No | | or |
| Yes | - | Instrument (e.g., for spot, for contract) |
| Yes | - | Initial order amount in USDT |
| Yes | - | Safety order amount in USDT |
| Yes | - | Max number of safety orders (e.g., ) |
| Yes | - | Price drop % per safety order (e.g., = 3%) |
| Yes | - | Price step multiplier between safety orders (e.g., ) |
| Yes | - | Safety order size multiplier (e.g., ) |
| Yes | - | Take-profit ratio (e.g., = 3%) |
| No | - | Stop-loss ratio (e.g., = 5%) |
| No | | Pre-reserve full required assets upfront |
| Spot only | - | =instant start, =RSI signal trigger |
| Contract only | - | Leverage multiplier (e.g., ) |
| Contract only | - | =long, =short |
DCA Bot — Stop
bash
okx bot dca stop [--type <spot|contract>] --algoId <id> --instId <id> \
[--stopType <1|2>] [--json]
| Behavior |
|---|
| Sell base currency to quote at market (cash out) — default |
| Keep base currency as-is |
DCA Bot — List Orders
bash
okx bot dca orders [--type <spot|contract>] [--history] [--json]
| Param | Required | Default | Description |
|---|
| No | | or |
| No | false | Show completed/stopped bots instead of active |
DCA Bot — Details
bash
okx bot dca details [--type <spot|contract>] --algoId <id> [--json]
Returns: bot config, current PnL (
), safety orders triggered, state. Contract also returns
,
,
.
DCA Bot — Sub-Orders
bash
okx bot dca sub-orders [--type <spot|contract>] --algoId <id> [--live] [--cycleId <id>] [--json]
| Flag / Param | Effect |
|---|
| (default, spot) | Filled sub-orders (executed DCA buys) |
| Spot: pending orders currently on the book |
| (default, contract) | List all cycles |
| Contract: show orders within a specific cycle |
MCP Tool Reference
CLI and MCP tools share the same underlying tool layer. MCP tools accept
or
directly.
| Tool | Description |
|---|
| Create spot or contract DCA bot |
| Stop spot or contract DCA bot |
| List spot or contract DCA bots |
| Single DCA bot details |
| Sub-orders (spot) or cycles (contract) |
Input / Output Examples
"Start a BTC grid bot from $90k to $100k with 10 grids"
bash
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"
bash
okx bot grid orders --algoOrdType grid
"What's the P&L on my BTC grid bot?"
bash
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"
bash
okx bot grid stop --algoId 12345678 --algoOrdType grid --instId BTC-USDT --stopType 2
"Create a DCA bot on ETH: $100 initial, safety orders at 3% drops, 2% TP"
bash
okx bot dca create --instId ETH-USDT \
--initOrdAmt 100 --safetyOrdAmt 50 --maxSafetyOrds 3 \
--pxSteps 0.03 --pxStepsMult 1 --volMult 1 \
--tpPct 0.02 --triggerType 1
# → DCA bot created: 87654321 (OK)
"Show my active DCA bots"
"How is my ETH DCA bot doing?"
bash
okx bot dca details --algoId 87654321
# → current PnL, avg entry, safety orders triggered, TP target
"Stop my ETH DCA bot and sell everything"
bash
okx bot dca stop --algoId 87654321 --instId ETH-USDT --stopType 1
"Create a contract DCA bot on BTC perp, long, 3x leverage, 2% TP"
bash
okx bot dca create --type contract --instId BTC-USDT-SWAP \
--initOrdAmt 200 --safetyOrdAmt 100 --maxSafetyOrds 3 \
--pxSteps 0.03 --pxStepsMult 1.2 --volMult 1.5 \
--tpPct 0.02 --lever 3 --side buy
Edge Cases
Grid Bot
- Price out of range: must be < current price < ; check with first
- Insufficient balance: check → before creating
- Contract grid direction: (buys more at lower prices), (sells at higher), (both)
- Contract grid --sz: number of contracts, not USDT amount
- Stop type: sells/closes all; keeps assets; for contract grid positions
- Already stopped bot: stop returns error — check
bot grid orders --history
- Demo mode:
okx --demo bot grid create ...
DCA Bot
- Insufficient balance: check → before creating
- pxStepsMult: use for equal price spacing; to widen gaps between successive safety orders
- volMult: use for equal safety order sizes; to increase size per safety order (Martingale)
- triggerType 2 (RSI): requires additional RSI parameters — use (instant) unless specifically requested
- Stop type: sells base to quote (cash out); keeps base currency as-is
- Already stopped bot: stop returns error — check first to confirm state
- Contract DCA: add to any DCA CLI command; create also requires and
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.
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 or env vars
- switches between multiple accounts
- returns raw OKX API v5 response
- Rate limit: 20 requests per 2 seconds per UID for all bot operations
- Grid range: 2–100
- DCA safety orders are triggered sequentially as price drops by increments
- Contract DCA automatically starts with an instant trigger (set by the tool internally)