hodlmm-bin-guardian

HODLMM Bin Guardian

Bitflow HODLMM（DLMM）のビンを監視し、LP ポジションが手数料を獲得できるアクティブな範囲内に保たれているか確認します。

概要

Bitflow HODLMM プールの最新状態と、ウォレットアドレスを使ってユーザーの実際の LP ポジションのビンを取得し、ユーザーのビン範囲をアクティブビンと比較して、ポジションが手数料を獲得しているか判定します。取引量、TVL、APR、トークン価格は Bitflow の HODLMM アプリ API から直接取得し、外部オラクルは使用しません。スリッページは、HODLMM のアクティブビン価格と Bitflow が報告するトークン価格との差として測定します。また、REBALANCE を推奨する前に、推定ガス代とクールダウンも確認します。

エージェントに必要な理由

市場価格が預け入れたビンの範囲外に移動すると、HODLMM ポジションはすぐに手数料を獲得できなくなります。このスキルを使うと、自律型エージェントが範囲外のポジションを検出し、人間の承認を得たうえでリバランスするよう通知できます。資金を自律的に使用することはありません。

安全に関する注意事項

• 読み取り専用です。 トランザクションは送信されません。
• メインネット専用です。 Bitflow HODLMM API はテストネットに対応していません。
• 24 時間のプール取引量が 10,000 USD 未満の場合、リバランスを推奨しません。
• スリッページ（HODLMM のビン価格と Bitflow アプリの価格との差）が 0.5% を超える場合、リバランスを推奨しません。
• 実際にリバランス（流動性の追加／引き出し）を行うには、実行前に人間による明示的な承認が必要です。
• 価格データはすべて 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 です。

フィールド	型	説明
status	"success" | "error"	全体の結果
action	string	理由付きの HOLD、REBALANCE、PINNED、または CHECK
data.in_range	boolean | null	ウォレットが指定されていない場合は null
data.active_bin	number	プールの現在のアクティブビン ID
data.at_grid_edge	boolean	アクティブビンがグリッドの端（符号なしの 0 または 1000）にあるかどうか。ビンの読み取り結果からアクティブビンを検証可能な形で確認できた場合にのみ true
data.pinned	boolean	グリッドの端にあり、かつスリッページの判定に失敗している状態（構造的な乖離）。PINNED を参照
data.user_bin_range	{min,max,count,bins} | null	ユーザーの流動性ビン範囲
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 ビン 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	推定ガス代が上限以内かどうか
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 時間の取引高（USD）
data.liquidity_usd	number	プールの TVL（USD）
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	プール一覧、アクティブビン	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 の変更履歴（初日のレビューでの修正）

レンジ内判定 — 以前は偽装、現在は実際に判定

以前： inRange = isFinite(pool.active_bin) && pool.active_bin > 0 — 常に true でした。

現在： GET /api/app/v1/users/{address}/positions/{poolId}/bins への実際の HTTP 呼び出しを行います。user_liquidity > 0 のビンを抽出し、active_bin_id がその集合に含まれているか確認します。

スリッページ — 以前はハードコード、現在はリアルタイムかつ完全に Bitflow のデータを使用

以前： 定数値で、常に判定を通過していました。

現在： (bin_price_raw / 1e8) × 10^(xDec − yDec) と Bitflow アプリ API のトークン価格を比較します。外部オラクルは使用せず、すべて Bitflow のエンドポイントから取得したデータを使用します。

ガス代の推定 — 以前は根拠のない定数、現在はリアルタイムで取得

以前： gas_estimated_stx: 0.006 — ハードコードされていました。

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

クールダウン — 以前は未追跡、現在は永続化

以前： 状態ファイルがなく、クールダウン判定は常に通過していました。

現在： ~/.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）

プールのアクティブビンがグリッドの端（符号なしの 0 または 1000）にあり、かつプールと市場の乖離がスリッページ上限を超えている場合、ガーディアンは、通過不可能なスリッページによる HOLD の代わりに、個別の PINNED アクション（および at_grid_edge / pinned データフィールド）を出力します。PINNED の間は、コントラクトの設計上、プール価格が固定され、乖離は構造的なものです。リバランスや無条件のスワップは行わず、退出／出金経路に進む（最低出金額は引き続き適用されます）か、エスカレーションしてください。Bitflow API に公式の PINNED シグナルはありません。これはコントラクトの動作から導き出されるものです。dlmm_3 でのライブ観測（2026-07-13）：約 36 時間にわたり、構造的な乖離が 1.4～4.8％発生し、スリッページ制限付きの自動化がデッドロックしました。

PINNED 出力例（追加されたフィールドは 2026-07-15 時点のもの。上記の run の 2 つの例は 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 が含まれるようになりました。