aibtcdev/hodlmm-range-keeper

HODLMM Range Keeper

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.

Why agents need it

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.

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.

Commands

doctor

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

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.

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.

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.

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.

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.

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:

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

Recenter ready:

{ "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:

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

Error:

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

install-packs

No external packs required. Returns success immediately.

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.