Back to Details

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

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

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

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
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.
FieldTypeDescription
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

数据来源

SourceDataEndpoint
Bitflow HODLMM APIPool list, active bin
bff.bitflowapis.finance/api/quotes/v1/pools
Bitflow Bins APIPer-bin prices (raw, for slippage)
bff.bitflowapis.finance/api/quotes/v1/bins/{poolId}
Bitflow App Pools APITVL, 24h volume, APR, token prices, decimals
bff.bitflowapis.finance/api/app/v1/pools
Bitflow Position APIUser's position bins
bff.bitflowapis.finance/api/app/v1/users/{addr}/positions/{pool}/bins
Hiro Stacks APISTX 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 APITVL、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 APISTX手续费预估
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