hodlmm-range-keeper

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HODLMM Range Keeper

HODLMM 仓位范围管理器

What it does

功能介绍

Actively manages HODLMM concentrated-liquidity positions by monitoring active-bin drift, estimating fee accrual, and re-centering LP ranges when the market moves away. Unlike signal-only analytics skills, this closes the full management loop: detect drift, plan the re-center, simulate the outcome, execute via MCP tools, and verify. Supports autonomous

run

mode that scans all pools and re-centers any drifted position in a single cycle.

主动管理HODLMM的集中流动性仓位，监控活跃仓位偏移情况、估算手续费累计，并在市场价格变动时重新调整LP（流动性提供者）的仓位范围。与仅提供信号分析的工具不同，该工具实现了完整的管理闭环：检测偏移、规划重调、模拟结果、通过MCP工具执行操作并验证结果。支持自主

run

模式，可在一个周期内扫描所有资金池并对所有偏移仓位进行重调。

Why agents need it

为什么Agent需要它

HODLMM concentrated liquidity earns fees only when the active bin is within your position range. When price moves, the active bin drifts away and your liquidity sits idle — earning nothing while exposed to impermanent loss. Manual monitoring is impractical across multiple pools. This skill turns passive LP deposits into actively managed positions: it tracks where your bins are, where the market is, and moves your liquidity to stay in range and keep earning.

HODLMM的集中流动性仅当活跃仓位处于你的持仓范围内时才能赚取手续费。当价格变动时，活跃仓位会偏离你的持仓范围，此时你的流动性将处于闲置状态——既无法赚取手续费，还会面临无常损失。手动监控多个资金池并不现实。该工具将被动的LP存款转化为主动管理的仓位：它追踪你的仓位位置、市场当前位置，并调整你的流动性以保持在可盈利范围内，持续赚取手续费。

Safety notes

安全说明

Writes to chain: Withdraws liquidity and re-deposits into new bins. Real funds move.
Drift threshold: Will not re-center unless the active bin drifts >= 3 bins from your position center (configurable).
Cooldown: 30-minute cooldown between recenters on the same pool to prevent churn.
Gas cap: 50 STX maximum per cycle. Will not execute if gas estimate exceeds cap.
Dust filter: Ignores positions < 5,000 sats to avoid unprofitable micro-recenters.
--confirm gate: The
```
recenter
```
command requires explicit
```
--confirm
```
flag. Without it, nothing executes.
Fee preservation: Tracks deposit baselines per bin. On re-center, fees above baseline are harvested (kept); only principal is re-deployed.
Mainnet only: HODLMM is not available on testnet.
MCP execution: Actual on-chain transactions are emitted as MCP tool calls (
```
bitflow_hodlmm_remove_liquidity
```
,
```
bitflow_hodlmm_add_liquidity
```
). The agent runtime executes them.

链上写入操作：会提取流动性并重新存入新的仓位，涉及真实资金流动。
偏移阈值：仅当活跃仓位与你的持仓中心偏移≥3个仓位时才会执行重调（可配置）。
冷却机制：同一资金池两次重调之间有30分钟冷却期，避免频繁操作。
Gas上限：每个周期最大Gas费用为50 STX。若估算Gas超过上限，将不会执行操作。
小额过滤：忽略规模小于5000 sats的仓位，避免无利可图的小额重调。
--confirm确认机制：
```
recenter
```
命令需要显式添加
```
--confirm
```
标志。若无该标志，不会执行任何操作。
手续费留存：追踪每个仓位的存款基准值。重调时，将留存基准值以上的手续费；仅重新部署本金。
仅主网可用：HODLMM在测试网不可用。
MCP执行：实际链上交易通过MCP工具调用（
```
bitflow_hodlmm_remove_liquidity
```
、
```
bitflow_hodlmm_add_liquidity
```
）发出，由Agent运行时执行。

Commands

命令

doctor

Check wallet, HODLMM API access, pool availability, existing positions, and MCP tool requirements. Read-only, safe to run anytime.

bash

STX_ADDRESS=SP... bun run hodlmm-range-keeper/hodlmm-range-keeper.ts doctor

检查钱包、HODLMM API访问权限、资金池可用性、现有仓位以及MCP工具要求。只读操作，可随时安全运行。

bash

STX_ADDRESS=SP... bun run hodlmm-range-keeper/hodlmm-range-keeper.ts doctor

status

Analyze all LP positions: drift magnitude, range efficiency (% of bins in active range), estimated fees, and whether re-centering is needed. Records fee baselines locally on first observation; otherwise read-only.

bash

STX_ADDRESS=SP... bun run hodlmm-range-keeper/hodlmm-range-keeper.ts status
STX_ADDRESS=SP... bun run hodlmm-range-keeper/hodlmm-range-keeper.ts status --pool dlmm_1

分析所有LP仓位：偏移幅度、范围效率（活跃范围内仓位占比）、估算手续费，以及是否需要重调。首次运行时会在本地记录手续费基准值；后续运行为只读操作。

bash

STX_ADDRESS=SP... bun run hodlmm-range-keeper/hodlmm-range-keeper.ts status
STX_ADDRESS=SP... bun run hodlmm-range-keeper/hodlmm-range-keeper.ts status --pool dlmm_1

plan

Dry-run a re-center: simulate withdraw and re-deposit, show expected bin layout, fees harvested, gas cost. No funds move.

bash

STX_ADDRESS=SP... bun run hodlmm-range-keeper/hodlmm-range-keeper.ts plan --pool dlmm_1

重调模拟运行：模拟提取和重新存入操作，展示预期仓位布局、可提取的手续费、Gas成本。不会涉及资金流动。

bash

STX_ADDRESS=SP... bun run hodlmm-range-keeper/hodlmm-range-keeper.ts plan --pool dlmm_1

recenter

Execute the re-center: withdraw from drifted bins, harvest fees, re-deposit principal around active bin. Requires --confirm.

bash

STX_ADDRESS=SP... bun run hodlmm-range-keeper/hodlmm-range-keeper.ts recenter --pool dlmm_1 --confirm

执行重调操作：从偏移仓位提取流动性、提取手续费、将本金重新存入活跃仓位附近。需要添加--confirm标志。

bash

STX_ADDRESS=SP... bun run hodlmm-range-keeper/hodlmm-range-keeper.ts recenter --pool dlmm_1 --confirm

run

Full autonomous cycle: scan all pools, assess drift, plan and execute recenters where needed. Use --confirm for live execution, omit for dry-run.

bash

STX_ADDRESS=SP... bun run hodlmm-range-keeper/hodlmm-range-keeper.ts run
STX_ADDRESS=SP... bun run hodlmm-range-keeper/hodlmm-range-keeper.ts run --confirm

完整自主周期：扫描所有资金池、评估偏移情况、对需要重调的仓位进行规划并执行。添加--confirm标志用于实际执行，省略则为模拟运行。

bash

STX_ADDRESS=SP... bun run hodlmm-range-keeper/hodlmm-range-keeper.ts run
STX_ADDRESS=SP... bun run hodlmm-range-keeper/hodlmm-range-keeper.ts run --confirm

history

Show past re-center events from local ledger. Useful for auditing position management.

bash

bun run hodlmm-range-keeper/hodlmm-range-keeper.ts history
bun run hodlmm-range-keeper/hodlmm-range-keeper.ts history --pool dlmm_1 --limit 10

显示本地账本中过往的重调事件。用于审计仓位管理情况。

bash

bun run hodlmm-range-keeper/hodlmm-range-keeper.ts history
bun run hodlmm-range-keeper/hodlmm-range-keeper.ts history --pool dlmm_1 --limit 10

Output contract

输出规范

All outputs are JSON to stdout. Logs go to stderr.

Success:

json

{ "status": "success", "action": "status", "data": { "positionsAnalyzed": 2, "needsRecenter": 1, "positions": [...] }, "error": null }

Recenter ready:

json

{ "status": "success", "action": "execute_mcp", "data": { "step1_withdraw": { "tool": "bitflow_hodlmm_remove_liquidity", "params": {...} }, "step2_deposit": { "tool": "bitflow_hodlmm_add_liquidity", "params": {...} }, "summary": {...} }, "error": null }

Blocked:

json

{ "status": "blocked", "action": "recenter", "data": { "cooldownRemainingMinutes": 15 }, "error": "Cooldown active." }

Error:

json

{ "status": "error", "action": "recenter", "data": null, "error": "Pool dlmm_99 not found." }

所有输出均为JSON格式并打印至标准输出（stdout）。日志信息输出至标准错误输出（stderr）。

成功：

json

{ "status": "success", "action": "status", "data": { "positionsAnalyzed": 2, "needsRecenter": 1, "positions": [...] }, "error": null }

重调就绪：

json

{ "status": "success", "action": "execute_mcp", "data": { "step1_withdraw": { "tool": "bitflow_hodlmm_remove_liquidity", "params": {...} }, "step2_deposit": { "tool": "bitflow_hodlmm_add_liquidity", "params": {...} }, "summary": {...} }, "error": null }

操作受阻：

json

{ "status": "blocked", "action": "recenter", "data": { "cooldownRemainingMinutes": 15 }, "error": "Cooldown active." }

错误：

json

{ "status": "error", "action": "recenter", "data": null, "error": "Pool dlmm_99 not found." }

install-packs

No external packs required. Returns success immediately.

bash

bun run hodlmm-range-keeper/hodlmm-range-keeper.ts install-packs --pack all

无需外部包。立即返回成功。

bash

bun run hodlmm-range-keeper/hodlmm-range-keeper.ts install-packs --pack all

Known constraints

已知限制

Mainnet only — HODLMM has no testnet deployment
Fee estimation requires a baseline — first
```
status
```
after fresh install records current state as baseline (zero estimated fees until next check)
Position re-centering executes as two sequential MCP calls (withdraw then deposit) — partial failure is possible if the deposit tx fails after a successful withdraw. In that case, funds are in the wallet, not lost. State is recorded optimistically before MCP execution; on partial failure, baselines reset and the next
```
status
```
call re-establishes them from current on-chain state.
Active bin can move between the plan and recenter steps. The skill uses the latest active bin at execution time.
HODLMM API (
```
bff.bitflowapis.finance
```
) may lag 1-2 blocks behind chain state
Gas estimation is conservative (4 STX for 2 txs). Actual gas is typically lower.

仅主网可用——HODLMM未部署至测试网
手续费估算需要基准值——全新安装后首次运行
```
status
```
会将当前状态记录为基准值（下次检查前估算手续费为零）
仓位重调分为两个连续的MCP调用（先提取后存入）——若提取交易成功但存入交易失败，可能出现部分失败情况。此时资金会回到钱包，不会丢失。执行MCP操作前会乐观记录状态；若出现部分失败，基准值会重置，下次
```
status
```
调用会根据当前链上状态重新建立基准值。
在规划和执行重调步骤之间，活跃仓位可能发生变动。该工具会使用执行时最新的活跃仓位。
HODLMM API（
```
bff.bitflowapis.finance
```
）可能比链上状态滞后1-2个区块
Gas估算较为保守（2笔交易需4 STX）。实际Gas费用通常更低。