hodlmm-bin-guardian

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HODLMM Bin Guardian

HODLMM仓位守护者

Monitors Bitflow HODLMM (DLMM) bins to keep LP positions in the active earning range.

监控Bitflow HODLMM（DLMM）仓位，确保LP持仓处于可产生收益的活跃区间。

What it does

功能介绍

Fetches live Bitflow HODLMM pool state, the user's actual LP position bins (via wallet address), and compares the user's bin range against the active bin to determine if the position is earning fees. Volume, TVL, APR, and token prices are sourced directly from Bitflow's HODLMM app API — no external oracles. Slippage is measured as the deviation between the HODLMM active-bin price and Bitflow's own reported token price. Also checks estimated gas cost and cooldown before recommending REBALANCE.

获取Bitflow HODLMM资金池的实时状态、用户实际LP持仓仓位（通过钱包地址），并将用户的仓位区间与活跃仓位进行对比，判断持仓是否在产生手续费。交易量、总锁仓价值（TVL）、年化收益率（APR）和代币价格均直接来自Bitflow的HODLMM应用API——无需外部预言机。滑点的计算方式为HODLMM活跃仓位价格与Bitflow自身报告的代币价格之间的偏差。在建议调仓（REBALANCE）前，还会检查预估Gas成本和冷却时间。

Why agents need it

Agent为何需要它

HODLMM positions stop earning fees the moment the market price moves outside the deposited bin range. This skill gives an autonomous agent a reliable, safe-to-run check that surfaces out-of-range positions and flags them for human-approved rebalancing — without ever spending funds autonomously.

当市场价格移出存入的仓位区间时，HODLMM持仓将停止产生手续费。该技能为自主Agent提供可靠、安全的检查机制，可识别出区间外的持仓并标记为需人工批准的调仓项——且绝不会自主动用资金。

Safety notes

安全说明

Read-only. No transactions are submitted.
Mainnet-only. Bitflow HODLMM API does not support testnet.
Refuses to recommend rebalance if 24h pool volume < $10,000 USD.
Refuses to recommend rebalance if slippage > 0.5% (HODLMM bin price vs Bitflow app price).
Any actual rebalance (add/withdraw liquidity) requires explicit human approval before execution.
All price data sourced from Bitflow APIs only — no external oracles.

只读模式：不会提交任何交易。
仅主网可用：Bitflow HODLMM API不支持测试网。
若资金池24小时交易量 < 10,000美元，将拒绝建议调仓。
若滑点 > 0.5%（HODLMM仓位价格与Bitflow应用价格对比），将拒绝建议调仓。
任何实际调仓操作（添加/提取流动性）在执行前均需人工明确批准。
所有价格数据仅来自Bitflow API——无外部预言机。

Commands

命令

doctor

Checks all data sources: Bitflow HODLMM API, Bitflow Bins API, Bitflow App Pools API, and Hiro Stacks API.

bash

bun run hodlmm-bin-guardian/hodlmm-bin-guardian.ts doctor

检查所有数据源：Bitflow HODLMM API、Bitflow Bins API、Bitflow App Pools API和Hiro Stacks API。

bash

bun run hodlmm-bin-guardian/hodlmm-bin-guardian.ts doctor

install-packs

No additional packs required — uses Bitflow and Hiro public HTTP APIs directly.

bash

bun run hodlmm-bin-guardian/hodlmm-bin-guardian.ts install-packs

无需额外依赖包——直接使用Bitflow和Hiro的公开HTTP API。

bash

bun run hodlmm-bin-guardian/hodlmm-bin-guardian.ts install-packs

run

Checks the LP position in the default sBTC HODLMM pool (dlmm_1) and outputs a recommendation. Pass

--wallet

to enable the real in-range check against actual position bins.

bash

undefined

检查默认sBTC HODLMM资金池（dlmm_1）中的LP持仓并输出建议。传入

--wallet

参数可针对实际持仓仓位进行真实的区间检查。

bash

undefined

Full check with wallet (recommended)

带钱包的完整检查（推荐）

bun run hodlmm-bin-guardian/hodlmm-bin-guardian.ts run --wallet SP1234... bun run hodlmm-bin-guardian/hodlmm-bin-guardian.ts run --wallet SP1234... --pool-id dlmm_1

Pool-only check (no position check — in_range will be null)

仅资金池检查（无持仓检查——in_range将为null）

bun run hodlmm-bin-guardian/hodlmm-bin-guardian.ts run

undefined

bun run hodlmm-bin-guardian/hodlmm-bin-guardian.ts run

undefined

Live terminal output

终端实时输出

doctor (all 4 sources reachable)

doctor（4个数据源均可达）

json

{
  "status": "ok",
  "checks": [
    { "name": "Bitflow HODLMM API",      "ok": true, "detail": "8 pools found, dlmm_1 active bin: 504" },
    { "name": "Bitflow Bins API (dlmm_1)", "ok": true, "detail": "active_bin_id=504, 1001 bins" },
    { "name": "Bitflow App Pools API",   "ok": true, "detail": "dlmm_1 TVL: $77,142.99, vol_24h: $126,045, APR: 17.72%" },
    { "name": "Hiro Stacks API (fees)",  "ok": true, "detail": "2 µSTX/byte" }
  ],
  "message": "All data sources reachable. Ready to run."
}

json

{
  "status": "ok",
  "checks": [
    { "name": "Bitflow HODLMM API",      "ok": true, "detail": "8 pools found, dlmm_1 active bin: 504" },
    { "name": "Bitflow Bins API (dlmm_1)", "ok": true, "detail": "active_bin_id=504, 1001 bins" },
    { "name": "Bitflow App Pools API",   "ok": true, "detail": "dlmm_1 TVL: $77,142.99, vol_24h: $126,045, APR: 17.72%" },
    { "name": "Hiro Stacks API (fees)",  "ok": true, "detail": "2 µSTX/byte" }
  ],
  "message": "All data sources reachable. Ready to run."
}

run --wallet (wallet has no dlmm_1 position, slippage gate active)

run --wallet（钱包在dlmm_1中无持仓，滑点限制生效）

json

{
  "status": "success",
  "action": "HOLD — position out of range but rebalance blocked: price slippage 1.86% > 0.5% cap.",
  "data": {
    "in_range": false,
    "active_bin": 504,
    "user_bin_range": null,
    "can_rebalance": false,
    "refusal_reasons": [ "price slippage 1.86% > 0.5% cap" ],
    "slippage_ok": false,
    "slippage_pct": 1.8595,
    "bin_price_raw": 66459654464,
    "pool_price_usd": 66459.65,
    "market_price_usd": 65246.37,
    "slippage_source": "bitflow-app-price-vs-hodlmm-active-bin",
    "gas_ok": true,
    "gas_estimated_stx": 0.0144,
    "cooldown_ok": true,
    "cooldown_remaining_h": 0,
    "last_rebalance_at": null,
    "volume_ok": true,
    "volume_24h_usd": 126045,
    "liquidity_usd": 77143,
    "apr_24h_pct": 17.72,
    "pool_id": "dlmm_1",
    "pool_name": "sBTC-USDCx-LP",
    "fee_bps": 30,
    "position_note": "No position found for SP219TWC8G12CSX5AB093127NC82KYQWEH8ADD1AY in pool dlmm_1."
  },
  "error": null
}

json

{
  "status": "success",
  "action": "HOLD — position out of range but rebalance blocked: price slippage 1.86% > 0.5% cap.",
  "data": {
    "in_range": false,
    "active_bin": 504,
    "user_bin_range": null,
    "can_rebalance": false,
    "refusal_reasons": [ "price slippage 1.86% > 0.5% cap" ],
    "slippage_ok": false,
    "slippage_pct": 1.8595,
    "bin_price_raw": 66459654464,
    "pool_price_usd": 66459.65,
    "market_price_usd": 65246.37,
    "slippage_source": "bitflow-app-price-vs-hodlmm-active-bin",
    "gas_ok": true,
    "gas_estimated_stx": 0.0144,
    "cooldown_ok": true,
    "cooldown_remaining_h": 0,
    "last_rebalance_at": null,
    "volume_ok": true,
    "volume_24h_usd": 126045,
    "liquidity_usd": 77143,
    "apr_24h_pct": 17.72,
    "pool_id": "dlmm_1",
    "pool_name": "sBTC-USDCx-LP",
    "fee_bps": 30,
    "position_note": "No position found for SP219TWC8G12CSX5AB093127NC82KYQWEH8ADD1AY in pool dlmm_1."
  },
  "error": null
}

run --wallet (active position in range, all gates pass)

run --wallet（活跃持仓在区间内，所有限制条件均通过）

json

{
  "status": "success",
  "action": "HOLD — position in range at active bin 504. APR (24h): 17.72%.",
  "data": {
    "in_range": true,
    "active_bin": 504,
    "user_bin_range": { "min": 500, "max": 508, "count": 3, "bins": [500, 504, 508] },
    "can_rebalance": true,
    "refusal_reasons": null,
    "slippage_ok": true,
    "slippage_pct": 0.04,
    "bin_price_raw": 66459654464,
    "pool_price_usd": 66459.65,
    "market_price_usd": 66433.0,
    "slippage_source": "bitflow-app-price-vs-hodlmm-active-bin",
    "gas_ok": true,
    "gas_estimated_stx": 0.0144,
    "cooldown_ok": true,
    "cooldown_remaining_h": 0,
    "last_rebalance_at": null,
    "volume_ok": true,
    "volume_24h_usd": 126045,
    "liquidity_usd": 77143,
    "apr_24h_pct": 17.72,
    "pool_id": "dlmm_1",
    "pool_name": "sBTC-USDCx-LP",
    "fee_bps": 30
  },
  "error": null
}

json

{
  "status": "success",
  "action": "HOLD — position in range at active bin 504. APR (24h): 17.72%.",
  "data": {
    "in_range": true,
    "active_bin": 504,
    "user_bin_range": { "min": 500, "max": 508, "count": 3, "bins": [500, 504, 508] },
    "can_rebalance": true,
    "refusal_reasons": null,
    "slippage_ok": true,
    "slippage_pct": 0.04,
    "bin_price_raw": 66459654464,
    "pool_price_usd": 66459.65,
    "market_price_usd": 66433.0,
    "slippage_source": "bitflow-app-price-vs-hodlmm-active-bin",
    "gas_ok": true,
    "gas_estimated_stx": 0.0144,
    "cooldown_ok": true,
    "cooldown_remaining_h": 0,
    "last_rebalance_at": null,
    "volume_ok": true,
    "volume_24h_usd": 126045,
    "liquidity_usd": 77143,
    "apr_24h_pct": 17.72,
    "pool_id": "dlmm_1",
    "pool_name": "sBTC-USDCx-LP",
    "fee_bps": 30
  },
  "error": null
}

Output contract

输出规范

All outputs are strict JSON to stdout.

Field	Type	Description
`status`	`"success" \| "error"`	Overall result
`action`	`string`	`HOLD` , `REBALANCE` , or `CHECK` with reason
`data.in_range`	`boolean \| null`	`null` if no wallet provided
`data.active_bin`	`number`	Pool's current active bin ID
`data.user_bin_range`	`{min,max,count,bins} \| null`	User's liquidity bin range
`data.can_rebalance`	`boolean`	Whether all safety gates pass
`data.refusal_reasons`	`string[] \| null`	Why REBALANCE is blocked
`data.slippage_ok`	`boolean`	Whether price deviation is within cap
`data.slippage_pct`	`number`	`\|hodlmm_price − bitflow_price\| / bitflow_price × 100`
`data.bin_price_raw`	`number`	Raw active bin price from Bitflow bins API
`data.pool_price_usd`	`number \| null`	HODLMM derived USD price: `(bin_price_raw / 1e8) × 10^(xDec − yDec)`
`data.market_price_usd`	`number \| null`	Bitflow app reported token price in USD
`data.slippage_source`	`string`	Price source identifier
`data.gas_ok`	`boolean`	Whether estimated gas is within limit
`data.gas_estimated_stx`	`number`	Estimated STX for 2-txn rebalance
`data.cooldown_ok`	`boolean`	Whether cooldown has elapsed
`data.cooldown_remaining_h`	`number`	Hours until next rebalance allowed
`data.last_rebalance_at`	`string \| null`	ISO timestamp of last recorded rebalance
`data.volume_ok`	`boolean`	Whether 24h volume meets minimum
`data.volume_24h_usd`	`number`	24h pool volume in USD
`data.liquidity_usd`	`number`	Pool TVL in USD
`data.apr_24h_pct`	`number`	24h fee APR from Bitflow app API
`data.pool_id`	`string`	Pool identifier
`data.pool_name`	`string`	Human-readable pool name
`data.fee_bps`	`number`	Pool fee in basis points
`data.position_note`	`string?`	Present when position state needs explanation

所有输出均为标准JSON格式，输出至标准输出（stdout）。

字段	类型	描述
`status`	`"success" \| "error"`	整体结果状态
`action`	`string`	`HOLD` 、 `REBALANCE` 或 `CHECK` 及对应原因
`data.in_range`	`boolean \| null`	未提供钱包时为 `null`
`data.active_bin`	`number`	资金池当前活跃仓位ID
`data.user_bin_range`	`{min,max,count,bins} \| null`	用户的流动性仓位区间
`data.can_rebalance`	`boolean`	是否通过所有安全限制条件
`data.refusal_reasons`	`string[] \| null`	拒绝调仓的原因
`data.slippage_ok`	`boolean`	价格偏差是否在限制范围内
`data.slippage_pct`	`number`	`\|hodlmm_price − bitflow_price\| / bitflow_price × 100`
`data.bin_price_raw`	`number`	来自Bitflow bins API的原始活跃仓位价格
`data.pool_price_usd`	`number \| null`	HODLMM推导的USD价格： `(bin_price_raw / 1e8) × 10^(xDec − yDec)`
`data.market_price_usd`	`number \| null`	Bitflow应用报告的代币USD价格
`data.slippage_source`	`string`	价格来源标识
`data.gas_ok`	`boolean`	预估Gas是否在限制范围内
`data.gas_estimated_stx`	`number`	两次调仓交易的预估STX消耗
`data.cooldown_ok`	`boolean`	冷却时间是否已结束
`data.cooldown_remaining_h`	`number`	距离下次允许调仓的剩余小时数
`data.last_rebalance_at`	`string \| null`	上次记录调仓的ISO时间戳
`data.volume_ok`	`boolean`	24小时交易量是否满足最低要求
`data.volume_24h_usd`	`number`	资金池24小时USD交易量
`data.liquidity_usd`	`number`	资金池TVL（USD）
`data.apr_24h_pct`	`number`	来自Bitflow应用API的24小时手续费年化收益率
`data.pool_id`	`string`	资金池标识
`data.pool_name`	`string`	易读的资金池名称
`data.fee_bps`	`number`	资金池手续费（基点）
`data.position_note`	`string?`	当持仓状态需要说明时显示

Data sources

数据来源

Source	Data	Endpoint
Bitflow HODLMM API	Pool list, active bin	`bff.bitflowapis.finance/api/quotes/v1/pools`
Bitflow Bins API	Per-bin prices (raw, for slippage)	`bff.bitflowapis.finance/api/quotes/v1/bins/{poolId}`
Bitflow App Pools API	TVL, 24h volume, APR, token prices, decimals	`bff.bitflowapis.finance/api/app/v1/pools`
Bitflow Position API	User's position bins	`bff.bitflowapis.finance/api/app/v1/users/{addr}/positions/{pool}/bins`
Hiro Stacks API	STX fee estimate	`api.mainnet.hiro.so/v2/fees/transfer`

来源	数据内容	接口地址
Bitflow HODLMM API	资金池列表、活跃仓位	`bff.bitflowapis.finance/api/quotes/v1/pools`
Bitflow Bins API	单仓位价格（原始数据，用于滑点计算）	`bff.bitflowapis.finance/api/quotes/v1/bins/{poolId}`
Bitflow App Pools API	TVL、24小时交易量、APR、代币价格、小数位数	`bff.bitflowapis.finance/api/app/v1/pools`
Bitflow Position API	用户持仓仓位	`bff.bitflowapis.finance/api/app/v1/users/{addr}/positions/{pool}/bins`
Hiro Stacks API	STX手续费预估	`api.mainnet.hiro.so/v2/fees/transfer`

v2 changelog (fixes from day-1 review)

v2更新日志（首日评审修复内容）

In-range check — was fake, now real

区间检查——从模拟变为真实

Before:

inRange = isFinite(pool.active_bin) && pool.active_bin > 0

— always

true

After: Real HTTP call to

GET /api/app/v1/users/{address}/positions/{poolId}/bins

. Filters bins where

user_liquidity > 0

, checks if

active_bin_id

is in that set.

之前：

inRange = isFinite(pool.active_bin) && pool.active_bin > 0

——始终为

true

。

之后： 真实调用

GET /api/app/v1/users/{address}/positions/{poolId}/bins

接口。筛选

user_liquidity > 0

的仓位，检查

active_bin_id

是否在该集合中。

Slippage — was hardcoded, now live and fully Bitflow-native

滑点——从硬编码变为实时且完全基于Bitflow原生数据

Before: Constant value, always passed.

After:

(bin_price_raw / 1e8) × 10^(xDec − yDec)

vs Bitflow app API token price. No external oracles — all data from Bitflow endpoints.

之前： 固定值，始终通过检查。

之后： 对比

(bin_price_raw / 1e8) × 10^(xDec − yDec)

与Bitflow应用API的代币价格。无外部预言机——所有数据均来自Bitflow接口。

Gas estimate — was a made-up constant, now live

Gas预估——从虚构常量变为实时数据

Before:

gas_estimated_stx: 0.006

— hardcoded.

After:

Hiro /v2/fees/transfer × 500 bytes × 2 txns × 3× contract multiplier × 1.2 safety buffer

之前：

gas_estimated_stx: 0.006

——硬编码值。

之后：

Hiro /v2/fees/transfer × 500字节 × 2笔交易 × 3倍合约乘数 × 1.2安全缓冲

。

Cooldown — was not tracked, now persistent

冷却时间——从无追踪变为持久化存储

Before: No state file, cooldown always passing.

After: Reads/writes

~/.hodlmm-guardian-state.json

. Returns

cooldown_remaining_h

on each run.

之前： 无状态文件，冷却时间检查始终通过。

之后： 读写

~/.hodlmm-guardian-state.json

文件。每次运行返回

cooldown_remaining_h

。

Frontmatter — stale dependency removed

前置依赖——移除过时依赖

Before:

requires: [bitflow]

— referenced a non-existent dependency.

After:

requires: ""

— fully self-contained, all data from public HTTP APIs.

之前：

requires: [bitflow]

——引用不存在的依赖。

之后：

requires: ""

——完全独立，所有数据均来自公开HTTP API。

Origin

来源

Winner of AIBTC x Bitflow Skills Pay the Bills competition. Original author: @cliqueengagements Competition PR: https://github.com/BitflowFinance/bff-skills/pull/39

AIBTC x Bitflow Skills Pay the Bills竞赛获胜作品。原作者：@cliqueengagements 竞赛PR：https://github.com/BitflowFinance/bff-skills/pull/39