hodlmm-pulse

HODLMM Pulse

Bitflow HODLMM（DLMM）集中流動性プールの手数料の勢いと取引量のモメンタムを追跡します。

機能

7日間の移動ベースラインと比べて、手数料が「どれほど速く」発生しているかを追跡し、**「今は流動性を投入するのに適したタイミングか？」**という問いに答えます。日次平均の3倍の手数料を得ているプールは、取引量が活発に急増している状態です。手数料を獲得して、取引量が平常に戻る前に退出する絶好のタイミングです。

利用モードは2つあります。

1. 単発（scan）— 1回の API 呼び出しで全プールのモメンタムを即座にランキングします。すばやい初期調査に便利です。
2. 時系列（track + report）— track を cron（例：5分ごと）で実行し、ローカルにスナップショット履歴を蓄積します。データを多く収集するほど、トレンドの方向（加速／安定／減速）の精度が高まります。report で全体像を確認できます。

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

hodlmm-advisor は「どこに」投入するか（リスク調整後利回りが最も高いプール）を示します。hodlmm-pulse は「いつ」投入するかを示し、変化の遅い APR 平均に反映される前に、手数料の急増や取引量の加速を検出します。この2つを組み合わせることで、LP の投入判断を完結できます。

1. hodlmm-pulse scan → モメンタムが活発なプールを特定
2. hodlmm-pulse track --pool-id <id> → 複数回のポーリングでトレンドの方向を確認
3. hodlmm-advisor entry-plan --pool-id <id> → 正確なビン範囲と戦略を取得
4. pulse シグナルが spike／elevated で、advisor が "Deploy now" を返した場合にのみ実行

安全性に関する注意

• 読み取り専用 — トランザクションの送信や資金の移動は行いません
• ウォレット不要 — 認証なしで、どのエージェントからでも安全に呼び出せます
• メインネット専用 — Bitflow HODLMM API はメインネット専用です
• 状態ファイルは ~/.hodlmm-pulse-state.json に書き込まれます（ローカルディスクのみ。ネットワークへの書き込みはありません）
• 移動ウィンドウ：プールごとに直近288件のスナップショット（5分間隔でポーリングした場合、約24時間分）

コマンド

doctor

すべてのデータソースと状態ファイルの準備状況を確認します。

bun run hodlmm-pulse/hodlmm-pulse.ts doctor

scan

1回の呼び出しで全プールを取得し、モメンタムスコアを計算して、手数料の勢い順にランキングします。過去の追跡履歴が不要なため、すばやい初期調査に使えます。

bun run hodlmm-pulse/hodlmm-pulse.ts scan
bun run hodlmm-pulse/hodlmm-pulse.ts scan --min-tvl 10000

オプション：

• --min-tvl <usd> — この TVL を下回るプールを除外します（デフォルト：500）

track

単一プールのタイムスタンプ付きスナップショットをローカルの状態に追加し、現在のシグナルとトレンドの方向を出力します。呼び出しを重ねるごとにトレンドの精度が高まります。

bun run hodlmm-pulse/hodlmm-pulse.ts track --pool-id dlmm_1

オプション：

• --pool-id（必須）— プール識別子（例：dlmm_1、dlmm_3）

推奨：関心のある各プールについて、5分ごとに cron で実行してください。

report

保存済みのスナップショットを読み込み、プールごとにトレンドの概要を出力します。概要には、現在のシグナル、追跡期間全体のトレンド、観測されたモメンタムのピークが含まれます。シグナルが活発なプールを上位に表示します。

bun run hodlmm-pulse/hodlmm-pulse.ts report
bun run hodlmm-pulse/hodlmm-pulse.ts report --pool-id dlmm_1

オプション：

• --pool-id（任意）— 出力を1つのプールに限定します

モメンタムモデル

手数料の勢い

主要なシグナルです。本日の手数料と、7日間の日次平均との比率です。

feeVelocity = feesUsd1d / (feesUsd7d / 7)

1.0 = 平均的な日。3.0 = 日次平均の3倍の手数料を獲得。

取引量の勢い

副次的なシグナルです。取引量に同じ比率を適用します。

volumeVelocity = volumeUsd1d / (volumeUsd7d / 7)

APR 急増率

第3のシグナルです。本日の実現 APR が長期平均をどれだけ上回っているかを示します。

aprSpike = apr24h / apr

モメンタムスコア（加重複合）

momentumScore = feeVelocity × 0.6 × 50 + volumeVelocity × 0.3 × 50 + aprSpike × 0.1 × 50

50 = 平均的な日。数値が高いほど、通常より活発です。

シグナルのしきい値

シグナル	条件	意味
🔥 spike	feeVelocity ≥ 3×	例外的に活発 — 絶好の投入タイミング
📈 elevated	feeVelocity ≥ 1.5×	平均以上 — 注意深く監視
〰️ normal	0.5× ≤ feeVelocity < 1.5×	ベースラインの範囲内 — 特別な対応は不要
📉 cooling	feeVelocity < 0.5×	ベースライン未満 — 投入タイミングではありません
⬜ flat	手数料と取引量がほぼゼロ	非アクティブなプール — スキップ

トレンドの方向（時系列のみ）

トレンド	意味
⬆️ accelerating	直近のスナップショットで手数料の増加ペースが上昇しています
↔️ stable	手数料の増加ペースは横ばいで、活動が継続しています
⬇️ cooling	手数料の増加ペースが低下しており、期間の終了が近づいています
🆕 new	履歴が不足しています（スナップショットが2件未満）
— flat	プールは休止中です

出力仕様

すべての出力は stdout への JSON です。

成功：

{ "status": "success", "network": "mainnet", "timestamp": "...", ... }

エラー：

{ "error": "descriptive message" }

データソース

ソース	データ	エンドポイント
Bitflow App API（プール一覧）	すべてのプール：feesUsd1d、feesUsd7d、volumeUsd1d、volumeUsd7d、apr、apr24h、tvlUsd	bff.bitflowapis.finance/api/app/v1/pools
Bitflow App API（プール詳細）	単一プールの詳細（track で使用）	bff.bitflowapis.finance/api/app/v1/pools/{id}
Bitflow Quotes API	プール一覧の整合性チェック	bff.bitflowapis.finance/api/quotes/v1/pools
ローカル状態ファイル	トレンド計算用のスナップショット履歴	~/.hodlmm-pulse-state.json

既知の制約

• feesUsd1d と volumeUsd1d は Bitflow の API による過去24時間のローリングウィンドウです。ほぼリアルタイムで更新されますが、1分単位の粒度ではありません
• トレンドの方向を判定するには、少なくとも2件のスナップショットが必要です。spike シグナルは単一の scan でも有効です
• 状態ファイルはマシン内に保存されます。追跡履歴はマシン間で引き継がれません
• TVL が低いプール（500ドル未満）はデフォルトで除外されます。これらの手数料指標は変動が大きいためです

起源

AIBTC x Bitflow Skills Pay the Bills コンペティションの優勝作品です。 オリジナルの作者：@ghislo749 コンペティションの PR：https://github.com/BitflowFinance/bff-skills/pull/94