hodlmm-pulse

HODLMM Pulse

Bitflow HODLMM（DLMM）集中流动性池的费用速度和交易量动能追踪器。

功能

通过追踪费用相对于 7 天滚动基线的生成速度，回答**“现在是部署流动性的好时机吗？”**。如果某个池的费用收入达到每日平均值的 3 倍，就说明交易量正处于活跃飙升期——这是入场、赚取费用并在交易量恢复正常前退出的最佳窗口。

两种运行模式：

1. 单次扫描（scan）——通过一次 API 调用即时对所有池进行动能排名。适合快速筛选。
2. 时间序列（track + report）——定时运行 track（例如每 5 分钟一次），构建本地快照历史记录。收集的数据越多，趋势方向（加速／稳定／降温）就越准确。report 会呈现完整情况。

Agent 为何需要它

hodlmm-advisor 会告诉你在哪里部署（哪个池的风险调整后收益最佳）。hodlmm-pulse 会告诉你何时部署——在缓慢变化的 APR 均值中体现之前，检测费用飙升和交易量加速。二者结合可形成完整的 LP 入场决策流程：

1. hodlmm-pulse scan → 找出动能活跃的池
2. hodlmm-pulse track --pool-id <id> → 通过多次轮询确认趋势方向
3. hodlmm-advisor entry-plan --pool-id <id> → 获取精确的 bin 范围和策略
4. 仅当 pulse 信号为 spike／elevated，且 advisor 返回 "Deploy now" 时执行

安全说明

• 只读——不会提交交易或转移资金
• 无需钱包——任何 Agent 均可安全调用，无需身份验证
• 仅限主网——Bitflow HODLMM API 仅支持主网
• 状态文件写入 ~/.hodlmm-pulse-state.json（仅限本地磁盘，不会向网络写入）
• 滚动窗口：每个池保留最近 288 个快照（按 5 分钟轮询间隔约为 24 小时）

命令

doctor

检查所有数据源和状态文件是否就绪。

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

scan

通过一次调用获取所有池，计算动能分数，并按费用速度排名。无需先前的追踪历史记录，适合快速筛选。

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（可选）— 将输出限制为一个池

动能模型

费用速度

主要信号。当天费用与 7 天日均费用的比值：

feeVelocity = feesUsd1d / (feesUsd7d / 7)

1.0 = 平均水平。3.0 = 费用收入达到日均值的 3 倍。

交易量速度

次要信号。对交易量应用相同比值：

volumeVelocity = volumeUsd1d / (volumeUsd7d / 7)

APR 飙升比率

第三信号。当天已实现 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 小时窗口数据——会近乎实时更新，但不具备分钟级粒度
• 趋势方向至少需要 2 个快照；单次 scan 即可触发可操作的 spike 信号
• 状态文件保存在本地机器上——跟踪历史不会在不同机器间保留
• 默认过滤低 TVL 池（< $500）；其费用指标噪声较大

来源

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