hodlmm-bin-guardian

HODLMM Bin Guardian

监控 Bitflow HODLMM（DLMM）区间，确保 LP 仓位处于可赚取收益的活跃范围内。

功能

获取实时 Bitflow HODLMM 池状态、用户实际 LP 仓位所在区间（通过钱包地址），并将用户的区间与活跃区间进行比较，以判断仓位是否正在赚取手续费。交易量、TVL、APR 和代币价格均直接取自 Bitflow 的 HODLMM 应用 API，不使用外部预言机。滑点通过比较 HODLMM 活跃区间价格与 Bitflow 报告的代币价格来衡量。还会检查预估 Gas 费用和冷却时间，然后再建议执行 REBALANCE。

Agent 为何需要它

市场价格一旦超出已存入的区间，HODLMM 仓位就会立即停止赚取手续费。此技能可让自主 Agent 安全、可靠地检查仓位，并找出超出范围的仓位，提示需经人工批准后再平衡；绝不会自主花费资金。

安全说明

• 只读。 不会提交任何交易。
• 仅限主网。 Bitflow HODLMM API 不支持测试网。
• 若池的 24 小时交易量低于 $10,000 USD，则拒绝建议再平衡。
• 若滑点超过 0.5%（HODLMM 区间价格与 Bitflow 应用价格之差），则拒绝建议再平衡。
• 任何实际再平衡操作（添加／提取流动性）都必须在执行前获得明确的人工批准。
• 所有价格数据均仅取自 Bitflow API，不使用外部预言机。

命令

doctor

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

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

install-packs

无需安装其他包，直接使用 Bitflow 和 Hiro 的公开 HTTP API。

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

run

检查默认的 sBTC HODLMM 池（dlmm_1）中的 LP 仓位，并输出建议。 传入 --wallet 可启用针对实际仓位区间的真实范围检查。

# 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)
bun run hodlmm-bin-guardian/hodlmm-bin-guardian.ts run

实时终端输出

doctor（所有 4 个数据源均可访问）

{
  "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（钱包没有 dlmm_1 仓位，滑点门槛生效）

{
  "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（活跃仓位处于范围内，所有门槛均通过）

{
  "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，并写入 stdout。

字段	类型	描述
status	"success" | "error"	总体结果
action	string	HOLD、REBALANCE、PINNED 或附带原因的 CHECK
data.in_range	boolean | null	未提供钱包时为 null
data.active_bin	number	池当前活跃 bin ID
data.at_grid_edge	boolean	活跃 bin 是否位于网格边缘（无符号 0 或 1000）；仅当读取到的 bins 可验证地包含活跃 bin 时才为 true
data.pinned	boolean	位于网格边缘且滑点门槛未通过——结构性偏离；参见 PINNED
data.user_bin_range	{min,max,count,bins} | null	用户的流动性 bin 范围
data.can_rebalance	boolean	是否通过所有安全门槛
data.refusal_reasons	string[] | null	阻止 REBALANCE 的原因
data.slippage_ok	boolean	价格偏差是否在上限范围内
data.slippage_pct	number	|hodlmm_price − bitflow_price| / bitflow_price × 100
data.bin_price_raw	number	Bitflow bins API 返回的原始活跃 bin 价格
data.pool_price_usd	number | null	HODLMM 推导的美元价格：(bin_price_raw / 1e8) × 10^(xDec − yDec)
data.market_price_usd	number | null	Bitflow 应用报告的代币美元价格
data.slippage_source	string	价格来源标识符
data.gas_ok	boolean	预估 Gas 是否在限额内
data.gas_estimated_stx	number	2 笔交易再平衡的预估 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 小时美元交易量
data.liquidity_usd	number	池的 TVL（美元）
data.apr_24h_pct	number	Bitflow 应用 API 提供的 24 小时手续费 APR
data.pool_id	string	池标识符
data.pool_name	string	人类可读的池名称
data.fee_bps	number	池手续费（基点）
data.position_note	string?	需要说明持仓状态时提供

数据来源

来源	数据	端点
Bitflow HODLMM API	池列表、活跃 bin	bff.bitflowapis.finance/api/quotes/v1/pools
Bitflow Bins API	每个 bin 的价格（原始值，用于计算滑点）	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	用户的持仓 bins	bff.bitflowapis.finance/api/app/v1/users/{addr}/positions/{pool}/bins
Hiro Stacks API	STX 手续费预估	api.mainnet.hiro.so/v2/fees/transfer

v2 更新日志（修复首日评审发现的问题）

区间内检查——之前是假的，现在是真实检查

之前： inRange = isFinite(pool.active_bin) && pool.active_bin > 0——始终为 true。

之后： 通过 HTTP 实际调用 GET /api/app/v1/users/{address}/positions/{poolId}/bins。筛选 user_liquidity > 0 的 bins，并检查 active_bin_id 是否包含在该集合中。

滑点——之前是硬编码值，现在实时获取且完全基于 Bitflow

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

之后： 将 (bin_price_raw / 1e8) × 10^(xDec − yDec) 与 Bitflow app API 的代币价格进行比较。不使用外部预言机——所有数据均来自 Bitflow 端点。

Gas 预估——之前是随意设定的常量，现在实时获取

之前： gas_estimated_stx: 0.006——硬编码。

之后： Hiro /v2/fees/transfer × 500 bytes × 2 txns × 3× 合约乘数 × 1.2 安全缓冲系数。

冷却期——之前没有跟踪，现在可持久保存

之前： 没有状态文件，冷却期始终通过。

之后： 读取并写入 ~/.hodlmm-guardian-state.json。每次运行都会返回 cooldown_remaining_h。

Frontmatter — 已移除过时依赖

之前： requires: [bitflow] — 引用了一个不存在的依赖。

之后： requires: "" — 完全自包含，所有数据均来自公共 HTTP API。

来源

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

PINNED 检测（2026-07-15 现场审计 F-5）

当池的活动 bin 位于网格边缘（无符号 0 或 1000），且池价与市场价的偏差超过滑点上限时，guardian 会发出独立的 PINNED 操作（并附带 at_grid_edge / pinned 数据字段），而不是无法通过的滑点 HOLD。处于 pinned 状态时，合约设计会冻结池价，偏差属于结构性偏差 — 不要重新平衡或盲目兑换；应转入退出／提取路径（最低提取金额仍可执行），或升级处理。Bitflow API 没有官方的 pinned 信号；这是根据合约行为推导得出的。2026-07-13 在 dlmm_3 上观察到此情况：约 36 小时内存在 1.4–4.8% 的结构性偏差，导致受滑点限制的自动化流程陷入僵局。

PINNED 输出示例（2026-07-15 添加字段；上方两个 run 示例早于 at_grid_edge / pinned）

{
  "status": "success",
  "action": "PINNED — pool is at the grid edge (active bin 0) with structural pool-vs-market divergence 2.74%. The slippage gate cannot clear while pinned. Do NOT rebalance or blind-swap; route to the exit/withdraw path (withdraw minimums remain enforceable while pinned) or escalate to a human.",
  "data": {
    "in_range": false,
    "active_bin": 0,
    "at_grid_edge": true,
    "pinned": true,
    "can_rebalance": false,
    "refusal_reasons": ["price slippage 2.74% > 0.5% cap"],
    "slippage_ok": false,
    "slippage_pct": 2.74
  }
}

正常（非 pinned）的 run 输出现在也会包含 "at_grid_edge": false, "pinned": false。