strategy-grid-trade

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ETH/USDC Grid Trading Bot

ETH/USDC 网格交易机器人

欢迎使用 ETH/USDC 网格交易策略！

我们在 Base 链上自动执行 ETH/USDC 网格交易——震荡行情中低买高卖，每次价格穿越网格线自动成交。策略基于 EMA 动态居中，自适应波动率调整网格步长，内置仓位限制、冷却期、熔断保护，极低 gas 成本。

投资案例：

小李用 5,000 USDC + 1 ETH（约 $8,000 总资产）启动网格机器人。ETH 在 $2,800~$3,200 区间震荡。机器人设置 6 档网格，步长约 1.5%，每次交易约 $500。一周内触发 12 次买卖，累计捕获网格价差约 $180，折合年化约 24%。同期 ETH 横盘无涨跌，手动持有收益为零。

EMA-centered dynamic grid trading on Base (chain 8453) via OKX DEX aggregator. Available as standalone

strategy-grid

binary.

欢迎使用 ETH/USDC 网格交易策略！

我们在Base链上自动执行ETH/USDC网格交易——在震荡行情中低买高卖，每当价格穿越网格线时自动成交。策略基于EMA动态确定网格中心，可自适应波动率调整网格步长，内置仓位限制、冷却期、熔断保护机制，Gas成本极低。

投资案例：

小李用5000 USDC + 1 ETH（约8000美元总资产）启动网格机器人。ETH在2800~3200美元区间震荡。机器人设置6档网格，步长约1.5%，每次交易约500美元。一周内触发12次买卖，累计捕获网格价差约180美元，折合年化收益率约24%。同期ETH横盘无涨跌，手动持有收益为零。

EMA-centered dynamic grid trading on Base (chain 8453) via OKX DEX aggregator. Available as standalone

strategy-grid

binary.

Pre-flight Checks

前置检查

Run immediately when this skill is triggered — before any response or command. Always follow these steps in order. Do not echo routine command output to the user; only provide a brief status update when installing, updating, or handling a failure.

触发本技能后立即执行以下步骤——在回复或执行任何命令之前，必须按顺序完成这些步骤。无需向用户回显常规命令输出；仅在安装、更新或处理失败时提供简短状态更新。

Step 1: Check onchainos

步骤1：检查onchainos

bash

which onchainos

Found → run
```
onchainos --version
```
to confirm, then proceed to Step 2.
Not found → install automatically:
bash
```
curl -sSL https://raw.githubusercontent.com/okx/onchainos-skills/main/install.sh | sh
```
- If install succeeds → verify with
```
onchainos --version
```
  , then proceed to Step 2.
- If install fails → notify the user to install manually:
```
自动安装失败，请手动安装 onchainos：
https://github.com/okx/onchainos-skills
```
  Stop here until user confirms onchainos is available.

bash

which onchainos

已找到 → 运行
```
onchainos --version
```
确认版本，然后进入步骤2。

未找到 → 自动安装：

bash

curl -sSL https://raw.githubusercontent.com/okx/onchainos-skills/main/install.sh | sh

若安装成功 → 用
```
onchainos --version
```
验证，然后进入步骤2。
若安装失败 → 通知用户手动安装：
```
自动安装失败，请手动安装onchainos：
https://github.com/okx/onchainos-skills
```
在此暂停，直到用户确认onchainos已可用。

Step 2: Check skills-store

步骤2：检查skills-store

bash

which skills-store

Not found → install:

bash

curl -sSL https://raw.githubusercontent.com/purong-huang-1121/skills-store/main/install.sh | sh

Check for updates: Read

~/.cargo/bin/.skills-store/last_check_grid

and compare with current timestamp:

bash

cached_ts=$(cat ~/.cargo/bin/.skills-store/last_check_grid 2>/dev/null || true)
now=$(date +%s)

If
```
cached_ts
```
is non-empty and
```
(now - cached_ts) < 43200
```
(12 hours), skip the update.
Otherwise, run the installer to check for updates.

bash

which skills-store

未找到 → 安装：

bash

curl -sSL https://raw.githubusercontent.com/purong-huang-1121/skills-store/main/install.sh | sh

检查更新：读取

~/.cargo/bin/.skills-store/last_check_grid

并与当前时间戳对比：

bash

cached_ts=$(cat ~/.cargo/bin/.skills-store/last_check_grid 2>/dev/null || true)
now=$(date +%s)

若
```
cached_ts
```
非空且
```
(now - cached_ts) < 43200
```
（12小时），则跳过更新。
否则，运行安装程序检查更新。

Step 3: Check strategy-grid

步骤3：检查strategy-grid

bash

which strategy-grid

Found → proceed.

Not found → install:

bash

curl -sSL https://raw.githubusercontent.com/purong-huang-1121/skills-store/main/install_strategy.sh | sh -s -- strategy-grid

If install succeeds → verify with
```
strategy-grid --version
```
, then proceed.

If install fails → notify the user:

自动安装失败，请手动安装 strategy-grid：
curl -sSL https://raw.githubusercontent.com/purong-huang-1121/skills-store/main/install_strategy.sh | sh -s -- strategy-grid

Stop here until user confirms installation.

bash

which strategy-grid

已找到 → 继续。

未找到 → 安装：

bash

curl -sSL https://raw.githubusercontent.com/purong-huang-1121/skills-store/main/install_strategy.sh | sh -s -- strategy-grid

若安装成功 → 用
```
strategy-grid --version
```
验证，然后继续。

若安装失败 → 通知用户：

自动安装失败，请手动安装strategy-grid：
curl -sSL https://raw.githubusercontent.com/purong-huang-1121/skills-store/main/install_strategy.sh | sh -s -- strategy-grid

在此暂停，直到用户确认安装完成。

Authentication

身份验证

Requires two sets of credentials:

OKX API (for price quotes and swap execution):

bash

OKX_API_KEY=...
OKX_SECRET_KEY=...
OKX_PASSPHRASE=...

EVM Wallet (for on-chain signing):

bash

EVM_PRIVATE_KEY=0x...   # Base wallet with ETH + USDC

Optional:

bash

BASE_RPC_URL=...        # Custom Base RPC (default: public endpoint)
TELEGRAM_BOT_TOKEN=...  # Telegram notifications on trade/error
TELEGRAM_CHAT_ID=...    # Telegram chat ID for alerts

需要两组凭证：

OKX API（用于报价和交易执行）：

bash

OKX_API_KEY=...
OKX_SECRET_KEY=...
OKX_PASSPHRASE=...

EVM钱包（用于链上签名）：

bash

EVM_PRIVATE_KEY=0x...   # 持有ETH和USDC的Base钱包

可选配置：

bash

BASE_RPC_URL=...        # 自定义Base RPC节点（默认使用公共节点）
TELEGRAM_BOT_TOKEN=...  # 交易/错误通知的Telegram机器人令牌
TELEGRAM_CHAT_ID=...    # 接收警报的Telegram聊天ID

Before Starting the Bot

启动机器人前的准备

IMPORTANT: Before running

strategy-grid start

, you MUST:

Run
```
strategy-grid config
```
to show the user their current parameters
Present the parameters in a readable table and ask if they want to adjust any

If the user wants to change a parameter, use

strategy-grid set --key <name> --value <value>

Parameters are saved to
```
grid_config.json
```
in the same directory as the
```
strategy-grid
```
executable and persist across restarts — no need to set them every time

Example flow:

bash

undefined

重要提示： 在运行

strategy-grid start

之前，您必须：

运行
```
strategy-grid config
```
向用户展示当前参数
以易读的表格形式呈现参数，并询问用户是否需要调整
若用户需要修改参数，使用
```
strategy-grid set --key <名称> --value <值>
```
进行设置
参数将保存到
```
strategy-grid
```
可执行文件所在目录的
```
grid_config.json
```
中，重启后依然有效——无需每次启动都重新设置

示例流程：

bash

undefined

Show current config

查看当前配置

strategy-grid config

User wants to change tick interval

用户希望修改tick间隔

strategy-grid set --key tick_interval_secs --value 120

User wants wider position limits

用户希望放宽仓位限制

strategy-grid set --key position_max_pct --value 70 strategy-grid set --key position_min_pct --value 30

Now start

现在启动机器人

strategy-grid start

undefined

strategy-grid start

undefined

Quickstart

快速入门

bash

undefined

bash

undefined

Check market conditions

检查市场状况

strategy-grid analyze

View current state and PnL

查看当前状态和盈亏

strategy-grid status

Run a single tick (fetch price, detect crossing, trade if needed)

执行单次tick（获取价格、检测穿越、必要时执行交易）

strategy-grid tick

Start continuous bot (tick every 60 seconds)

启动持续运行的机器人（每60秒执行一次tick）

strategy-grid start

Stop running bot

停止运行中的机器人

strategy-grid stop

undefined

strategy-grid stop

undefined

Command Index

命令索引


strategy-grid tick
strategy-grid start
strategy-grid stop
strategy-grid status
strategy-grid report
strategy-grid history
strategy-grid reset --force
strategy-grid retry
strategy-grid analyze
strategy-grid deposit
strategy-grid config
strategy-grid set

#	Command	Auth	Description
1	`strategy-grid tick`	Yes	Execute one grid cycle
2	`strategy-grid start`	Yes	Start foreground bot loop (60s ticks)
3	`strategy-grid stop`	No	Stop running bot via PID file
4	`strategy-grid status`	No	Show grid state, balances, PnL
5	`strategy-grid report`	No	Detailed PnL and performance stats
6	`strategy-grid history`	No	Show trade history
7	`strategy-grid reset --force`	No	Clear all grid state
8	`strategy-grid retry`	Yes	Re-execute last failed trade
9	`strategy-grid analyze`	Yes	Market analysis (EMA, volatility, trend)
10	`strategy-grid deposit`	No	Record manual deposit/withdrawal
11	`strategy-grid config`	No	Show current bot configuration
12	`strategy-grid set`	No	Set a config parameter


strategy-grid tick
strategy-grid start
strategy-grid stop
strategy-grid status
strategy-grid report
strategy-grid history
strategy-grid reset --force
strategy-grid retry
strategy-grid analyze
strategy-grid deposit
strategy-grid config
strategy-grid set

序号	命令	需要身份验证	描述
1	`strategy-grid tick`	是	执行一轮网格循环
2	`strategy-grid start`	是	启动前台机器人循环（每60秒执行一次tick）
3	`strategy-grid stop`	否	通过PID文件停止运行中的机器人
4	`strategy-grid status`	否	显示网格状态、资产余额、盈亏情况
5	`strategy-grid report`	否	生成详细的盈亏和性能统计报告
6	`strategy-grid history`	否	显示交易历史
7	`strategy-grid reset --force`	否	清除所有网格状态
8	`strategy-grid retry`	是	重新执行最后一笔失败的交易
9	`strategy-grid analyze`	是	市场分析（EMA、波动率、趋势）
10	`strategy-grid deposit`	否	记录手动存款/取款操作
11	`strategy-grid config`	否	显示当前机器人配置
12	`strategy-grid set`	否	设置配置参数

Core Algorithm

核心算法

1. Fetch ETH price (OKX DEX quote API)
2. Read on-chain balances (ETH + USDC on Base)
3. Check circuit breaker (consecutive errors)
4. Recalibrate grid if needed (price breakout / vol shift / age)
5. Map price → grid level
6. If level changed:
   a. Direction: BUY if level dropped, SELL if rose
   b. Risk checks (cooldown, position limits, repeat guard, consecutive limit)
   c. Calculate trade size (% of portfolio, capped)
   d. Execute swap via OKX DEX aggregator
   e. Update level ONLY on success
7. Save state and report

1. 获取ETH价格（OKX DEX报价API）
2. 读取链上资产余额（Base链上的ETH和USDC）
3. 检查熔断机制（连续错误次数）
4. 必要时重新校准网格（价格突破/波动率变化/网格过期）
5. 将当前价格映射到网格档位
6. 若档位发生变化：
   a. 交易方向：档位下降则买入，档位上升则卖出
   b. 风险检查（冷却期、仓位限制、重复交易防护、连续交易限制）
   c. 计算交易规模（占投资组合的比例，有上限）
   d. 通过OKX DEX聚合器执行兑换
   e. 仅在交易成功时更新当前档位
7. 保存状态并生成报告

Tunable Parameters

可调整参数

Parameters are persisted at

grid_config.json

in the same directory as the

strategy-grid

executable. View with

strategy-grid config

, modify with

strategy-grid set --key <key> --value <value>

. Changes take effect on next tick (no rebuild needed). If no config file exists, defaults below are used.

The Key column shows the exact key name to use with

strategy-grid set

参数将持久化保存到

strategy-grid

可执行文件所在目录的

grid_config.json

中。使用

strategy-grid config

查看参数，使用

strategy-grid set --key <键名> --value <值>

修改参数。修改后的参数将在下一轮tick生效（若机器人已运行，修改

tick_interval_secs

后需重启机器人）。若不存在配置文件，则使用以下默认值。

Key列显示使用

strategy-grid set

时需指定的准确键名。

Grid Structure

网格结构

Key	Default	Description
`grid_levels`	`6`	Number of grid levels
`ema_period`	`20`	EMA lookback periods for grid center calculation
`volatility_multiplier`	`2.5`	Grid width = multiplier × stddev
`grid_recalibrate_hours`	`12.0`	Max hours before forced recalibration
`tick_interval_secs`	`60`	Seconds between each tick cycle (restart bot to apply)

键名	默认值	描述
`grid_levels`	`6`	网格档位数量
`ema_period`	`20`	计算网格中心的EMA回溯周期
`volatility_multiplier`	`2.5`	网格宽度 = 乘数 × 标准差
`grid_recalibrate_hours`	`12.0`	强制重新校准网格的最长间隔（小时）
`tick_interval_secs`	`60`	每轮tick循环的间隔秒数（修改后需重启机器人）

Adaptive Step Sizing

自适应步长调整

Step scales linearly with real-time volatility:

step = (volatility_multiplier × stddev) / (grid_levels / 2)
step = clamp(step, price × step_min_pct, price × step_max_pct)
step = max(step, step_floor)

Key	Default	Description
`step_min_pct`	`0.008`	Step floor (0.8% of price)
`step_max_pct`	`0.060`	Step cap (6% of price)
`step_floor`	`5.0`	Absolute minimum step in USD

步长会根据实时波动率线性调整：

step = (volatility_multiplier × stddev) / (grid_levels / 2)
step = clamp(step, price × step_min_pct, price × step_max_pct)
step = max(step, step_floor)

键名	默认值	描述
`step_min_pct`	`0.008`	步长下限（价格的0.8%）
`step_max_pct`	`0.060`	步长上限（价格的6%）
`step_floor`	`5.0`	步长的绝对最小值（美元）

Trade Sizing

交易规模

Key	Default	Description
`max_trade_pct`	`0.12`	Max 12% of portfolio per trade
`min_trade_usd`	`5.0`	Minimum trade size in USD
`slippage_pct`	`1`	Slippage tolerance % for DEX swap. Increase to 2-3 if trades revert
`gas_reserve_eth`	`0.003`	ETH reserved for gas, not available for SELL

键名	默认值	描述
`max_trade_pct`	`0.12`	单笔交易最大占投资组合的比例（12%）
`min_trade_usd`	`5.0`	单笔交易的最小规模（美元）
`slippage_pct`	`1`	DEX兑换的滑点容忍度（百分比）。若交易频繁失败，可提高至2-3
`gas_reserve_eth`	`0.003`	预留用于Gas的ETH，不可用于卖出交易

Risk Controls

风险控制

Key	Default	Description
`min_trade_interval`	`1800`	30min cooldown between same-direction trades
`max_same_dir_trades`	`3`	Max consecutive same-direction trades
`position_max_pct`	`65.0`	Block BUY when ETH% exceeds this
`position_min_pct`	`35.0`	Block SELL when ETH% drops below this
`max_consecutive_errors`	`5`	Circuit breaker threshold
`cooldown_after_errors`	`3600`	Seconds cooldown after circuit breaker trips

键名	默认值	描述
`min_trade_interval`	`1800`	同方向交易的冷却时间（30分钟）
`max_same_dir_trades`	`3`	连续同方向交易的最大次数
`position_max_pct`	`65.0`	当ETH占比超过此值时，禁止买入
`position_min_pct`	`35.0`	当ETH占比低于此值时，禁止卖出
`max_consecutive_errors`	`5`	熔断机制触发阈值
`cooldown_after_errors`	`3600`	熔断触发后的冷却时间（秒）

Common Parameter Adjustments

常见参数调整

Slippage (trades reverting on-chain):

bash

strategy-grid set --key slippage_pct --value 2

Wider position limits (allow more one-sided exposure):

bash

strategy-grid set --key position_max_pct --value 75
strategy-grid set --key position_min_pct --value 25

Faster/slower tick interval:

bash

strategy-grid set --key tick_interval_secs --value 120   # 2 minutes

Note: Restart the bot after changing

tick_interval_secs

Larger trade sizes:

bash

strategy-grid set --key max_trade_pct --value 0.20       # 20% per trade
strategy-grid set --key min_trade_usd --value 10         # $10 minimum

滑点调整（链上交易频繁失败）：

bash

strategy-grid set --key slippage_pct --value 2

放宽仓位限制（允许更大的单边敞口）：

bash

strategy-grid set --key position_max_pct --value 75
strategy-grid set --key position_min_pct --value 25

调整tick间隔（更快/更慢）：

bash

strategy-grid set --key tick_interval_secs --value 120   # 2分钟

注意：修改

tick_interval_secs

后需重启机器人。

增大交易规模：

bash

strategy-grid set --key max_trade_pct --value 0.20       # 单笔交易最大占比20%
strategy-grid set --key min_trade_usd --value 10         # 最小交易规模10美元

CLI Command Reference

CLI命令参考

strategy-grid tick

Execute one grid cycle: fetch price, detect grid crossing, execute trade if needed.

Output actions:

```
grid_calibrated
```
— Grid was recalibrated (first tick or recalibration trigger)
```
no_crossing
```
— Price stayed within same grid level
```
trade_executed
```
— Swap executed successfully
```
trade_failed
```
— Swap attempted but failed (retriable)
```
blocked
```
— Risk check prevented trade (cooldown, position limit, etc.)
```
skipped
```
— Trade amount below minimum

执行一轮网格循环：获取价格、检测网格穿越、必要时执行交易。

输出动作：

```
grid_calibrated
```
— 网格已重新校准（首次tick或触发校准条件）
```
no_crossing
```
— 价格未穿越网格档位
```
trade_executed
```
— 兑换交易成功执行
```
trade_failed
```
— 尝试兑换但失败（可重试）
```
blocked
```
— 风险检查阻止了交易（冷却期、仓位限制等）
```
skipped
```
— 交易金额低于最小值

strategy-grid start

Start the bot in foreground, executing

tick

every 60 seconds. Creates a PID file at

~/.skills-store/grid_bot.pid

. Use Ctrl+C or

grid stop

to terminate.

在前台启动机器人，每60秒执行一次

tick

。会在

~/.skills-store/grid_bot.pid

创建PID文件。可使用Ctrl+C或

grid stop

终止机器人。

strategy-grid stop

Stop a running bot by sending SIGTERM to the process in the PID file.

通过向PID文件中的进程发送SIGTERM信号来停止运行中的机器人。

strategy-grid status

Show current grid state, balances, PnL overview, and whether the bot is running.

显示当前网格状态、资产余额、盈亏概览以及机器人是否在运行。

strategy-grid report

Detailed performance report: success rate, buy/sell counts, total volume, grid profit, deposits, and portfolio PnL.

生成详细的性能报告：交易成功率、买卖次数、总交易量、网格收益、存款记录和投资组合盈亏。

strategy-grid history [--limit N]

Show trade history (default: last 50 trades). Each trade includes direction, price, amount, tx hash, and grid levels.

显示交易历史（默认显示最近50笔交易）。每笔交易包含方向、价格、金额、交易哈希和网格档位信息。

strategy-grid reset --force

Delete all grid state. Requires

--force

flag for safety.

删除所有网格状态。为确保安全，必须添加

--force

参数。

strategy-grid retry

Re-execute the last failed trade. Validates that price hasn't moved >5% since failure.

重新执行最后一笔失败的交易。会验证自失败以来价格波动是否未超过5%。

strategy-grid analyze

Market analysis showing current price, EMA-20, volatility, trend direction, and grid utilization.

生成市场分析报告，包含当前价格、EMA-20、波动率、趋势方向和网格利用率。

strategy-grid deposit --amount N [--note "..."]

Record a manual deposit (positive) or withdrawal (negative) for accurate PnL tracking.

记录手动存款（正数）或取款（负数），以确保盈亏计算准确。

strategy-grid config

Show all current bot parameters and their values. Indicates whether a custom config file exists.

显示当前机器人的所有参数及其值。会提示是否存在自定义配置文件。

strategy-grid set --key NAME --value VALUE

Set a single parameter. Saved to

grid_config.json

in the executable's directory. Takes effect on next tick (restart bot if already running to apply tick_interval changes).

Available keys:

grid_levels

tick_interval_secs

max_trade_pct

min_trade_usd

slippage_pct

ema_period

volatility_multiplier

step_min_pct

step_max_pct

step_floor

grid_recalibrate_hours

min_trade_interval

max_same_dir_trades

position_max_pct

position_min_pct

gas_reserve_eth

max_consecutive_errors

cooldown_after_errors

设置单个参数。参数将保存到可执行文件所在目录的

grid_config.json

中。修改后的参数将在下一轮tick生效（若机器人已运行，修改

tick_interval_secs

后需重启）。

可用键名：

grid_levels

tick_interval_secs

max_trade_pct

min_trade_usd

slippage_pct

ema_period

volatility_multiplier

step_min_pct

step_max_pct

step_floor

grid_recalibrate_hours

min_trade_interval

max_same_dir_trades

position_max_pct

position_min_pct

gas_reserve_eth

max_consecutive_errors

cooldown_after_errors

。

Level Update Rule (Critical)

档位更新规则（关键）

Outcome	Update level?	Rationale
Trade succeeded	Yes	Grid crossing consumed
Trade failed	No	Retry on next tick
Trade skipped (cooldown/limit)	No	Don't lose the crossing

结果	是否更新档位？	原因
交易成功	是	网格穿越已被消耗
交易失败	否	在下一轮tick重试
交易被跳过（冷却期/限制）	否	不丢失网格穿越的机会

PnL Tracking

盈亏追踪

total_pnl    = current_portfolio_value - initial_value - deposits
grid_profit += estimated spread capture on SELL trades

total_pnl    = 当前投资组合价值 - 初始价值 - 存款总额
grid_profit += 卖出交易中捕获的预估价差

State Persistence

状态持久化

State is stored at

~/.skills-store/grid_state.json

with atomic writes (write to .tmp, rename). Includes: grid parameters, price history (last 288 = 24h at 5min), trade history (last 50), balance snapshots, cumulative stats, and error tracking. PID file at

~/.skills-store/grid_bot.pid

状态存储在

~/.skills-store/grid_state.json

中，采用原子写入方式（先写入.tmp文件，再重命名）。包含：网格参数、价格历史（最近288条=5分钟间隔的24小时数据）、交易历史（最近50笔）、资产余额快照、累计统计数据和错误追踪信息。PID文件存储在

~/.skills-store/grid_bot.pid

。

Cross-Skill Workflows

跨技能工作流

Need	Skill
USDC yield optimization (Aave/Compound/Morpho)	`strategy-auto-rebalance`
Aave V3 supply/withdraw/markets	`dapp-aave`
Morpho vault operations	`dapp-morpho` (CLI: `skills-store morpho` )
Hyperliquid perpetual trading	`dapp-hyperliquid`
Prediction markets	`dapp-polymarket` / `dapp-kalshi`

需求	对应技能
USDC收益优化（Aave/Compound/Morpho）	`strategy-auto-rebalance`
Aave V3存/取/市场查询	`dapp-aave`
Morpho金库操作	`dapp-morpho` （CLI命令： `skills-store morpho` ）
Hyperliquid永续合约交易	`dapp-hyperliquid`
预测市场	`dapp-polymarket` / `dapp-kalshi`

Edge Cases

边缘场景处理

Scenario	Behavior
First tick (no grid)	Calibrates grid from current price + history, sets initial level
Price exits grid range	Triggers recalibration (breakout detected)
Volatility shifts >30%	Triggers recalibration
Grid age > 12 hours	Triggers recalibration
5 consecutive errors	Circuit breaker trips, 1-hour cooldown
Trade amount < $5	Skipped (below minimum)
ETH balance < 0.003	Gas reserve protected, SELL blocked
No EVM_PRIVATE_KEY	Error on tick/start/retry commands
Bot already running	`start` rejects with existing PID warning
No running bot	`stop` returns error
Reset without --force	Returns error, requires confirmation

场景	行为
首次tick（无网格）	根据当前价格和历史数据校准网格，设置初始档位
价格超出网格范围	触发重新校准（检测到突破）
波动率变化超过30%	触发重新校准
网格运行时间超过12小时	触发重新校准
连续5次错误	熔断机制触发，进入1小时冷却期
交易金额低于5美元	跳过交易（低于最小值）
ETH余额低于0.003	保护Gas预留额度，禁止卖出交易
未配置EVM_PRIVATE_KEY	tick/start/retry命令执行失败
机器人已在运行	`start` 命令拒绝执行并提示已存在PID
无运行中的机器人	`stop` 命令返回错误
未加--force参数执行reset	返回错误，需确认

Troubleshooting

故障排除

Symptom	Cause	Fix
Trade reverts on-chain ( `trade_failed` )	Slippage too low for the DEX route	`strategy-grid set --key slippage_pct --value 2` (or 3 for volatile periods)
RPC 429 / rate limit errors	Public Base RPC rate limited	Set `BASE_RPC_URL` env var to a private RPC endpoint
Circuit breaker trips (5 errors)	Repeated failures (RPC, slippage, gas)	Check logs, fix root cause, then wait 1h or `strategy-grid reset --force`
Bot not trading (no_crossing)	Price within same grid level	Normal — bot only trades when price crosses a grid boundary
Trade blocked: position limit	ETH% too high/low	Adjust `position_max_pct` / `position_min_pct` or manually rebalance
Trade blocked: cooldown	Same-direction trade too soon (30min default)	Lower `min_trade_interval` if you want faster trading
Trade blocked: repeat guard	Same crossing as last trade	Normal — prevents oscillation. Will clear when price moves to a new level
Gas estimation fails	Insufficient ETH for gas	Ensure wallet has > 0.003 ETH (adjust via `gas_reserve_eth` )

症状	原因	解决方法
链上交易回滚（ `trade_failed` ）	DEX路由的滑点设置过低	`strategy-grid set --key slippage_pct --value 2` （波动剧烈时可设为3）
RPC 429/速率限制错误	公共Base RPC节点达到速率限制	设置 `BASE_RPC_URL` 环境变量为私有RPC节点
熔断机制触发（连续5次错误）	重复失败（RPC、滑点、Gas问题）	检查日志，修复根本原因，等待1小时或执行 `strategy-grid reset --force`
机器人未执行交易（ `no_crossing` ）	价格未穿越网格档位	正常现象——仅当价格穿越网格线时才会触发交易
交易被阻止：仓位限制	ETH占比过高/过低	调整 `position_max_pct` / `position_min_pct` 或手动再平衡
交易被阻止：冷却期	同方向交易间隔过短（默认30分钟）	若需要更频繁交易，降低 `min_trade_interval` 的值
交易被阻止：重复防护	与上一笔交易的网格穿越相同	正常现象——防止震荡。价格进入新档位后会自动解除
Gas估算失败	ETH余额不足支付Gas	确保钱包持有超过0.003 ETH（可通过 `gas_reserve_eth` 调整预留额度）

Anti-Patterns

反模式

Pattern	Problem
Recalibrate every tick	Grid oscillates, no stable levels
Update level on failure/skip	Silently loses grid crossings
No position limits	Trending market → 100% one-sided
Fixed step in volatile market	Too small → over-trades; too large → never triggers
`sell - buy` as PnL	Net cash flow ≠ profit
No cooldown	Rapid swings cause burst of trades eating slippage

模式	问题
每轮tick都重新校准网格	网格震荡，无稳定档位
交易失败/跳过时更新档位	悄悄丢失网格穿越机会
无仓位限制	趋势市场下会导致100%单边敞口
波动市场中使用固定步长	步长过小→过度交易；步长过大→永远不触发交易
用 `卖出金额-买入金额` 计算盈亏	净现金流不等于实际利润
无冷却期设置	价格快速波动导致大量交易，滑点成本过高