CL LP Auto-Rebalancer v1

Cron 驱动的 Uniswap V3 集中流动性自动调仓机器人，运行在 EVM L2 链上，通过 onchainos CLI 执行 DeFi 操作。核心思路：波动率决定范围宽度 — 低波动率时收紧范围提高资本效率，高波动率时放宽范围减少调仓频率和无常损失。

每个 tick：获取价格 → 波动率分析 → 范围计算 → 调仓决策 → 执行调仓 → 报告。

Architecture

Cron (5min) → Python script → onchainos CLI → OKX Web3 API → Chain
                  ↓                ↓
            cl_lp_state.json    Wallet (TEE signing)
                  ↓
            ┌──────────────┐
            │ Price Fetch   │ ← onchainos swap quote / market price
            │ K-line ATR    │ ← onchainos market kline (1H × 24)
            │ MTF Analysis  │ ← price_history (288 bars = 24h)
            └──────┬───────┘
                   ↓
            Range Calculation (vol-adaptive)
                   ↓
            Rebalance Decision
                   ↓
            ┌──────────────┐
            │ Claim Fees    │ ← onchainos defi claim
            │ Remove Liq    │ ← onchainos defi redeem
            │ Swap Ratio    │ ← onchainos swap swap
            │ Add Liq       │ ← onchainos defi deposit
            └──────┬───────┘
                   ↓
            Structured JSON output

OKX Skill Dependencies (via onchainos CLI — 处理认证、链解析、错误重试):

• Price: onchainos market price --address \x3Ctoken> --chain \x3Cchain>
• K-line: onchainos market kline --address \x3Ctoken> --chain \x3Cchain> --bar 1H --limit 24
• Quote: onchainos swap quote --from \x3CA> --to \x3CB> --amount \x3Camt> --chain \x3Cchain>
• Swap: onchainos swap swap --from \x3CA> --to \x3CB> --amount \x3Camt> --chain \x3Cchain> --wallet \x3Caddr> --slippage \x3Cpct>
• Approve: onchainos swap approve --token \x3Caddr> --amount \x3Camt> --chain \x3Cchain>
• Pool Search: onchainos defi search --chain \x3Cchain> --token "\x3Ctoken0>,\x3Ctoken1>" --product-group DEX_POOL
• Pool Detail: onchainos defi detail --investment-id \x3Cid> --chain \x3Cchain>
• Calculate Entry: onchainos defi calculate-entry --investment-id \x3Cid> --chain \x3Cchain> --tick-lower \x3Ctick> --tick-upper \x3Ctick>
• Deposit: onchainos defi deposit --investment-id \x3Cid> --chain \x3Cchain> --amount0 \x3Camt> --amount1 \x3Camt> --tick-lower \x3Ctick> --tick-upper \x3Ctick>
• Redeem: onchainos defi redeem --investment-id \x3Cid> --chain \x3Cchain> --token-id \x3Cid> --percent 100
• Claim Fees: onchainos defi claim --investment-id \x3Cid> --chain \x3Cchain> --token-id \x3Cid>
• Positions: onchainos defi positions --chain \x3Cchain>
• Position Detail: onchainos defi position-detail --investment-id \x3Cid> --chain \x3Cchain> --token-id \x3Cid>

Step 0: Pool Selection (First-Time Setup)

When user has no config.json or asks to set up a new pool, trigger this step.

核心原则：AI 应从用户的自然语言中提取意图，自动推断尽可能多的参数，只在信息不足时才追问。

0.1 Intent Recognition

从用户输入中提取：

缺失信息的默认推断：

• 未指定链 → 推荐 Base（L2 gas 低，适合频繁调仓）
• 未指定代币对 → 必须追问（核心参数，无法推断）
• 未指定 fee tier → 根据代币对自动选 TVL 最大的池子
• 未指定风险偏好 → 从代币对自动分类

0.2 Pool Type Classification

根据代币对自动分类，不需要问用户：

主流币白名单：ETH, WETH, WBTC, USDC, USDT, DAI, FRAX, ARB, OP, MATIC, BNB, AVAX, SOL

0.3 Meme Coin Risk Gate

仅当检测到 meme/低市值代币时触发。MUST display warning before proceeding:

⚠️ Meme 币 LP 额外风险：
1. 极端无常损失 — 价格可能单方向暴涨/暴跌 90%+
2. 流动性枯竭 — 池子 TVL 可能骤降，头寸无法退出
3. 合约风险 — 代币可能有 honeypot/税收/暂停转账等恶意机制
4. 调仓失败 — 低流动性导致 swap 滑点过大

Must get explicit user confirmation before proceeding.

0.4 Search, Rank & Auto-Select

onchainos defi search --chain \x3Cchain> --token "\x3Ctoken0>,\x3Ctoken1>" --product-group DEX_POOL

自动选择逻辑（用户无需手动选）：

1. 按 TVL 降序排列
2. 如果用户指定了 fee tier → 直接匹配
3. 如果未指定 → 选 TVL 最大的池子（通常是最佳流动性）
4. 展示选择结果供用户确认：池名、fee tier、TVL、预估池 APY（rate 字段）

Fee tier 参考（仅在用户问及或多池需选择时展示）：

• 0.01%: 稳定币对 · 0.05%: 高相关性对 · 0.3%: 主流对（推荐）· 1%: 高波动对

0.5 Generate config.json

自动 fetch detail (onchainos defi detail) 并生成 config，无需用户手动填写。

字段映射：

• investment_id ← search investmentId
• chain_id ← search chainIndex
• platform_id ← detail analysisPlatformId（注意不是 platformId）
• fee_tier ← search feeRate
• tick_spacing ← 根据 fee tier 推导：0.01%→1, 0.05%→10, 0.3%→60, 1%→200
• token0/token1 ← detail underlyingToken。如果 token 是 native ETH（0xeee...），LP 合约用 WETH，需映射（Base: 0x4200000000000000000000000000000000000006）
• native_token ← 始终 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee（用于 swap 和余额查询）
• 其余参数 ← 根据 pool type 自动填入下表默认值

{
  "investment_id": "\x3Cauto>",
  "pool_chain": "\x3Cauto>",
  "chain_id": "\x3Cauto>",
  "platform_id": "\x3Cauto>",
  "native_token": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
  "fee_tier": "\x3Cauto>",
  "tick_spacing": "\x3Cauto>",
  "token0": { "symbol": "\x3Cauto>", "address": "\x3Cauto>", "decimals": "\x3Cauto>" },
  "token1": { "symbol": "\x3Cauto>", "address": "\x3Cauto>", "decimals": "\x3Cauto>" },
  "range_mult": { "low": 1.0, "medium": 1.2, "high": 1.5, "extreme": 2.0 },
  "min_range_pct": 2,
  "max_range_pct": 5,
  "asym_factor": 0.3,
  "min_position_age_seconds": 3600,
  "max_rebalances_24h": 6,
  "gas_to_fee_ratio": 0.5,
  "max_il_tolerance_pct": 5.0,
  "edge_proximity_threshold": 0.15,
  "stop_loss_pct": 0.15,
  "trailing_stop_pct": 0.1,
  "slippage_pct": 1,
  "gas_reserve_eth": 0.02,
  "min_trade_usd": 5.0,
  "quiet_interval_seconds": 1800,
  "max_consecutive_errors": 5,
  "cooldown_after_errors_seconds": 3600
}

Pool-type-specific defaults（自动应用，无需用户选择）：

0.6 Gate

• config.json written with valid investment_id, token0, token1
• .env configured (copy from .env.example, fill in API credentials + WALLET_ADDR)
• onchainos wallet balance returns valid balances for the target chain
• If meme pool: user has explicitly confirmed risk warning

Pipeline: Runtime Steps

CRITICAL RULE: Steps MUST execute in order. Do NOT skip steps or proceed past a gate that has not been satisfied.

Step 1: Data Acquisition

Actions:

1. Fetch current price via onchainos market price or onchainos swap quote
2. Fetch current position detail via onchainos defi position-detail (if position exists)
3. Update price_history (append, cap at 288 = 24h @ 5min)
4. Fetch on-chain balances via onchainos wallet balance

Gate (ALL must pass):

• Price is non-null and > 0
• Circuit breaker not active (consecutive_errors \x3C 5)
• Stop not triggered (stop_triggered == null)

Step 2: Volatility & Trend Analysis

Actions:

1. Fetch K-line data (1H candles, 24 bars) → compute ATR-based volatility (hourly cache)
2. Classify volatility: low (\x3C1.5%), medium (1.5-3%), high (3-5%), extreme (>5%)
3. Compute multi-timeframe trend analysis (复用 grid-trading MTF):
   • Short EMA (25min), Medium EMA (1h), Long EMA (4h)
   • EMA alignment → trend direction (bullish/bearish/neutral) + strength (0-1)
   • 8h structure detection (uptrend/downtrend/ranging)
4. Compute 1h and 4h momentum

Output: atr_pct float, vol_class string, mtf dict

Gate:

• atr_pct is non-null and > 0
• vol_class is one of: low, medium, high, extreme
• mtf dict has trend and strength fields (graceful fallback to neutral)

Step 3: Range Calculation

Actions:

1. Compute range width based on volatility class:
   • Low (\x3C1.5%): 2 × ATR each side → tight range, max capital efficiency
   • Medium (1.5-3%): 3 × ATR each side → balanced
   • High (3-5%): 5 × ATR each side → wide range, fewer rebalances
   • Extreme (>5%): 8 × ATR each side → safety first
2. Apply trend asymmetry (if trend strength > 0.3):
   • Bullish: upper side wider, lower side tighter (跟随上涨空间)
   • Bearish: lower side wider, upper side tighter (防御下跌空间)
3. Convert price range to tick range (aligned to pool's tick_spacing)
4. Compute capital efficiency estimate: price / (upper - lower)

Output: tick_lower, tick_upper, range_width_pct, capital_efficiency

Gate:

• tick_lower \x3C current_tick \x3C tick_upper
• Range width >= minimum (2 × tick_spacing)
• tick values aligned to pool's tick_spacing

Step 4: Rebalance Decision

Actions:

1. If no existing position → always deploy (first run)
2. Check rebalance triggers:
   • Out of range: price \x3C lower or price > upper → MUST rebalance
3. Anti-churn checks:
   • Position age >= MIN_POSITION_AGE (2h)
   • Rebalance count \x3C MAX_REBALANCES_24H (6/day)
   • Gas cost \x3C GAS_TO_FEE_RATIO × expected fees (50%)
   • New range differs >5% from current range
4. Check stop conditions: stop-loss, trailing stop, IL tolerance

Gate:

• Rebalance trigger identified, OR no rebalance needed (skip to Step 5)
• All anti-churn checks passed (if rebalancing)
• No stop condition triggered

Step 5: Execution & Notification

Actions (if rebalancing):

1. Claim accumulated fees: onchainos defi claim
2. Remove liquidity: onchainos defi redeem --percent 100
3. Calculate target token ratio for new range: onchainos defi calculate-entry
4. Swap to correct ratio: onchainos swap swap (if needed)
5. Deposit at new range: onchainos defi deposit
6. On failure at any sub-step: emergency fallback deploy at 3× normal width
7. Record rebalance in state, update position info

Actions (always): 8. Calculate performance metrics (PnL, fees claimed, IL, time-in-range) 9. Build structured notification output (see Notification Tiers below)

Output: tiered notification JSON (via ---JSON--- block)

Tool Wrapper: onchainos CLI Reference

Prerequisites

which onchainos  # must be installed
# Auth via environment variables
OKX_API_KEY=...
OKX_SECRET_KEY=...
OKX_PASSPHRASE=...

Core DeFi Operations

Market & Swap Operations

Error Handling Protocol

Every function returns (result, failure_info). Failure info is structured:

failure_info = {
    "reason": str,      # machine-readable: "claim_failed", "redeem_failed", "deposit_failed", etc.
    "detail": str,      # human-readable context
    "retriable": bool,  # safe to auto-retry?
    "hint": str         # "transient_api_error", "retry_with_fresh_quote", "insufficient_balance"
}

Auto-retry policy: 1 retry for retriable=True with 3s delay.

Rebalance failure fallback: if deposit fails after remove, emergency deploy at 3× normal width.

Tunable Parameters

Range Configuration

Rebalance Triggers

Anti-Churn Controls

Multi-Timeframe Analysis

Risk Controls

Execution

Risk Control Flow

[1] stop_triggered → refuse all operations, emit alert JSON
[2] circuit_breaker (consecutive_errors >= 5) → 1h cooldown, refuse
[3] data validation (price/balance/position null) → refuse
[4] stop-loss / trailing-stop / IL tolerance → set stop_triggered, alert
[5] rebalance frequency (>6/day) → skip rebalance
[6] position age (\x3C2h) → skip rebalance
[7] gas cost check (>50% of expected fees) → skip rebalance
[8] minimum range change (\x3C5%) → skip rebalance
[9] execute rebalance → success / failure with emergency fallback

Operational Interface

Sub-Commands

status 触发词（用户说以下任意内容时应调用 status）：

• 查询收益、收益怎么样、赚了多少、PnL、盈亏
• 查询仓位、头寸状态、LP 状况、仓位情况
• 年化多少、APY、费用收入、手续费
• 无常损失、IL
• 总资产、Portfolio、余额
• LP 里有多少 ETH / USDC

COMMANDS = {
    "tick": tick, "status": status, "report": report,
    "history": history_cmd, "reset": reset, "close": close,
    "analyze": analyze
}
if __name__ == "__main__":
    cmd = sys.argv[1] if len(sys.argv) > 1 else "tick"
    COMMANDS.get(cmd, tick)()

Notification Tiers

脚本内部封装完整的消息格式化和可视化逻辑，通过 ---JSON--- 块输出结构化数据（含 notification 渲染块），由调度器路由到通信渠道。

status/analyze 命令为用户主动查询，直接输出到终端，不推送。status 优先从 _cached_snapshot（每 5min tick 时写入）读取已计算好的数据，无需任何 API 调用即可返回完整状态（Portfolio 跨平台总览 + 头寸 + PnL + IL + APY + LP 代币拆分）。缓存过期（>360s）时自动 fallback 到实时查询。

脚本负责：消息标题、字段组织、范围位置可视化、颜色级别、footer 上下文。调度器只需透传 notification 块到通信平台。

State Schema

{
  "version": 1,
  "pool": {
    "investment_id": "uniswap-v3-base-eth-usdc-3000",
    "chain": "base",
    "chain_id": 8453,
    "token0": "0x4200000000000000000000000000000000000006",
    "token1": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "fee_tier": 3000,
    "tick_spacing": 60
  },
  "position": {
    "token_id": null,
    "tick_lower": null,
    "tick_upper": null,
    "price_lower": null,
    "price_upper": null,
    "created_at": null,
    "created_atr_pct": null,
    "created_vol_class": null
  },
  "price_history": [],
  "vol_history": [],
  "rebalance_history": [
    {
      "time": "ISO timestamp",
      "trigger": "out_of_range",
      "old_range": [-198120, -197400],
      "new_range": [-198300, -197100],
      "fees_claimed_usd": 1.25
    }
  ],
  "stats": {
    "total_rebalances": 0,
    "total_fees_claimed_usd": 0,
    "unclaimed_fee_usd": 0,
    "time_in_range_pct": 100,
    "initial_portfolio_usd": null,
    "total_deposits_usd": 0,
    "portfolio_peak_usd": null,
    "started_at": null,
    "last_check": null
  },
  "errors": {
    "consecutive": 0,
    "cooldown_until": null
  },
  "stop_triggered": null,
  "kline_cache": null,
  "mtf_cache": null,
  "last_quiet_report": null
}

Key fields:

• pool: target pool configuration (chain, tokens, fee tier, tick spacing)
• position.token_id: NFT position ID (null if no active position)
• position.created_atr_pct: ATR at position creation (for vol shift detection)
• rebalance_history: full audit trail of all rebalances with costs
• stats.time_in_range_pct: key performance metric — % of ticks where price was in range
• stats.initial_portfolio_usd + total_deposits_usd: PnL 计算的成本基准
• stats.total_fees_claimed_usd + unclaimed_fee_usd: LP 手续费总收入，用于推导 IL
• stop_triggered: string describing trigger condition, or null

Core Algorithm

1. Fetch current price
2. Fetch position detail (if exists)
3. Update price_history (cap at 288 = 24h)
4. Fetch K-line data (1H × 24) → compute ATR volatility (hourly cache)
5. Classify volatility → vol_class (low/medium/high/extreme)
6. Multi-timeframe analysis → trend/strength/momentum/structure
7. Compute optimal range:
   a. Base width = VOL_MULTIPLIER[vol_class] × ATR each side
   b. Apply trend asymmetry (upper/lower sides)
   c. Convert to ticks, align to tick_spacing
8. Check rebalance triggers:
   a. Out of range → must rebalance
9. Anti-churn gates (position age, frequency, gas cost, range change)
10. If rebalancing:
    a. Claim fees → remove liquidity → swap to ratio → deposit at new range
    b. On failure: emergency fallback at 3× width
11. Check stop conditions (stop-loss, trailing stop, IL tolerance)
12. Calculate performance metrics
13. Report status (structured JSON)

Deployment

OpenClaw Cron (recommended)

# Register tick (every 5 minutes)
zeroclaw cron add '*/5 * * * *' \
  'cd ~/.openclaw/skills/cl-lp-rebalancer/references && set -a && . ../.env && set +a && python3 cl_lp.py tick'

# Register daily report (08:00 CST = 00:00 UTC)
zeroclaw cron add '0 0 * * *' \
  'cd ~/.openclaw/skills/cl-lp-rebalancer/references && set -a && . ../.env && set +a && python3 cl_lp.py report'

Manual

# Single tick
python3 cl_lp.py tick

# Dry run (fetch real data, simulate operations)
DRY_RUN=true python3 cl_lp.py tick

# Status check
python3 cl_lp.py status

# Close position and exit
python3 cl_lp.py close

Failure & Rollback

IF rebalance sub-step fails:
  1. Log failure reason to cl_lp.log
  2. Increment errors.consecutive
  3. If errors.consecutive >= 5: trigger circuit breaker (1h cooldown)
  4. If failure after remove liquidity: emergency deploy at 3× normal width
     (priority: get funds back into a position, even if suboptimal)
  5. Report failure via JSON output
  6. On next tick: retry from last successful sub-step if possible

Anti-Patterns