hodlmm-pulse

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HODLMM Pulse

Fee velocity and volume momentum tracker for Bitflow HODLMM (DLMM) concentrated liquidity pools.

Bitflow HODLMM（DLMM）集中流动性池的费用流速与交易量动量追踪工具。

What it does

功能说明

Answers the question "is now a good time to deploy liquidity?" by tracking how fast fees are being generated relative to the 7-day rolling baseline. A pool earning 3× its daily average in fees is in an active volume spike — the prime window to enter, capture fees, and exit before volume normalises.

Two modes of operation:

Single-shot (
```
scan
```
) — instant momentum ranking across all pools from a single API call. Useful for quick triage.
Time-series (
```
track
```
+
```
report
```
) — run
```
track
```
on a cron (e.g. every 5 min) to build a local snapshot history. The more data collected, the more accurate the trend direction (accelerating / stable / cooling).
```
report
```
surfaces the full picture.

通过追踪当前费用生成速度相对于7天滚动基准值的情况，回答“现在是否是部署流动性的好时机？”这一问题。若某池当日费用收益达到日均水平的3倍，则说明该池正处于交易量活跃峰值——这是入场捕获费用、在交易量回归常态前退出的黄金窗口。

支持两种运行模式：

单次扫描（
```
scan
```
）——通过一次API调用即可获取所有池的即时动量排名，适用于快速筛选。
时间序列追踪（
```
track
```
+
```
report
```
）——通过定时任务（例如每5分钟）运行
```
track
```
来构建本地快照历史。收集的数据越多，趋势方向（加速/稳定/降温）的判断就越准确。
```
report
```
可呈现完整的趋势图景。

Why agents need it

为何Agent需要它

hodlmm-advisor

tells you where to deploy (which pool has the best risk-adjusted yield).

hodlmm-pulse

tells you when — detecting fee spikes and volume acceleration before they appear in slow-moving APR averages. Together they form a complete LP entry decision loop:

```
hodlmm-pulse scan
```
→ identify pools with active momentum
```
hodlmm-pulse track --pool-id <id>
```
→ confirm trend direction over multiple polls

hodlmm-advisor entry-plan --pool-id <id>

→ get exact bin range + strategy

Execute only when both pulse signal is
```
spike
```
/
```
elevated
```
and advisor returns
```
"Deploy now"
```

hodlmm-advisor

告诉你在哪里部署流动性（哪个池拥有最佳风险调整收益率），而

hodlmm-pulse

告诉你何时部署——在缓慢更新的APR平均值显示之前，提前检测费用峰值和交易量加速情况。二者共同构成完整的流动性提供者（LP）入场决策流程：

```
hodlmm-pulse scan
```
→ 识别具有活跃动量的池
```
hodlmm-pulse track --pool-id <id>
```
→ 通过多次轮询确认趋势方向

hodlmm-advisor entry-plan --pool-id <id>

→ 获取精确的区间范围与策略

仅当
```
pulse
```
信号为
```
spike
```
/
```
elevated
```
且advisor返回
```
"Deploy now"
```
时执行部署

Safety notes

安全说明

Read-only — never submits transactions or moves funds
No wallet required — safe to call from any agent without authentication
Mainnet-only — Bitflow HODLMM API is mainnet-only
State file written to
```
~/.hodlmm-pulse-state.json
```
(local disk only, no network writes)
Rolling window: last 288 snapshots per pool (~24h at 5-min polling intervals)

只读模式——绝不会提交交易或转移资金
无需钱包——无需认证即可在任意Agent中安全调用
仅主网可用——Bitflow HODLMM API仅支持主网
状态文件写入
```
~/.hodlmm-pulse-state.json
```
（仅本地磁盘存储，无网络写入）
滚动窗口：每个池最多保留288个快照（按5分钟轮询间隔计算约为24小时）

Commands

命令

doctor

Checks all data sources and state file readiness.

bash

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

检查所有数据源和状态文件的就绪情况。

bash

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

scan

Fetches all pools in one call, computes momentum scores, ranks by fee velocity. Use for quick triage without needing prior tracking history.

bash

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

Options:

```
--min-tvl <usd>
```
— exclude pools below this TVL (default: 500)

一次性获取所有池的数据，计算动量得分并按费用流速排名。无需预先追踪历史即可快速筛选。

bash

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

Appends a timestamped snapshot for a single pool to local state, then outputs the current signal and trend direction. Trend accuracy improves with each successive call.

bash

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

Options:

```
--pool-id
```
(required) — pool identifier (e.g.
```
dlmm_1
```
,
```
dlmm_3
```
)

Recommended: run via cron every 5 minutes for each pool of interest.

将单个池的带时间戳快照追加到本地状态，然后输出当前信号和趋势方向。每次调用都会提升趋势判断的准确性。

bash

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

选项：

```
--pool-id
```
（必填）——池标识符（例如：
```
dlmm_1
```
、
```
dlmm_3
```
）

推荐：为每个关注的池设置每5分钟运行一次的定时任务。

report

Reads all stored snapshots and outputs a trend summary per pool: current signal, trend over the full tracking window, peak momentum seen. Prioritises pools with active signals at the top.

bash

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

Options:

```
--pool-id
```
(optional) — limit output to one pool

读取所有存储的快照，输出每个池的趋势摘要：当前信号、整个追踪窗口内的趋势、观测到的峰值动量。将具有活跃信号的池排在最前面。

bash

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

选项：

```
--pool-id
```
（可选）——将输出限制为单个池

Momentum model

动量模型

Fee velocity

费用流速

Primary signal. Ratio of today's fees to the 7-day daily average:

feeVelocity = feesUsd1d / (feesUsd7d / 7)

1.0

= average day.

3.0

= earning 3× the daily average.

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

feeVelocity = feesUsd1d / (feesUsd7d / 7)

1.0

= 平均水平。

3.0

= 收益达到日均水平的3倍。

Volume velocity

交易量流速

Secondary signal. Same ratio applied to volume:

volumeVelocity = volumeUsd1d / (volumeUsd7d / 7)

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

volumeVelocity = volumeUsd1d / (volumeUsd7d / 7)

APR spike ratio

APR峰值比率

Tertiary signal. How much today's realized APR exceeds the long-run average:

aprSpike = apr24h / apr

三级信号。当日实际APR超出长期平均水平的倍数：

aprSpike = apr24h / apr

Momentum score (composite, weighted)

动量得分（加权综合值）

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

= average day. Higher = more active than usual.

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

= 平均水平。数值越高，活跃度越高于常态。

Signal thresholds

信号阈值

Signal	Condition	Meaning
`🔥 spike`	feeVelocity ≥ 3×	Exceptional activity — prime entry window
`📈 elevated`	feeVelocity ≥ 1.5×	Above average — monitor closely
`〰️ normal`	0.5× ≤ feeVelocity < 1.5×	Within baseline — no special action
`📉 cooling`	feeVelocity < 0.5×	Below baseline — not an entry window
`⬜ flat`	Fees + volume near zero	Inactive pool — skip

信号	条件	含义
`🔥 spike`	feeVelocity ≥ 3×	异常活跃——黄金入场窗口
`📈 elevated`	feeVelocity ≥ 1.5×	高于平均水平——密切监控
`〰️ normal`	0.5× ≤ feeVelocity < 1.5×	在基准范围内——无需特殊操作
`📉 cooling`	feeVelocity < 0.5×	低于基准水平——非入场窗口
`⬜ flat`	费用+交易量接近零	池处于非活跃状态——跳过

Trend direction (time-series only)

趋势方向（仅时间序列模式）

Trend	Meaning
`⬆️ accelerating`	Fee velocity rising across recent snapshots
`↔️ stable`	Fee velocity flat — activity sustained
`⬇️ cooling`	Fee velocity declining — window closing
`🆕 new`	Insufficient history (< 2 snapshots)
`— flat`	Pool is inactive

趋势	含义
`⬆️ accelerating`	近期快照显示费用流速持续上升
`↔️ stable`	费用流速平稳——活跃度持续
`⬇️ cooling`	费用流速下降——窗口正在关闭
`🆕 new`	历史数据不足（<2个快照）
`— flat`	池处于非活跃状态

Output contract

输出规范

All outputs are JSON to stdout.

Success:

json

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

Error:

json

{ "error": "descriptive message" }

所有输出均为JSON格式并打印到标准输出。

成功输出：

json

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

错误输出：

json

{ "error": "descriptive message" }

Data sources

数据源

Source	Data	Endpoint
Bitflow App API (pools list)	All pools: feesUsd1d, feesUsd7d, volumeUsd1d, volumeUsd7d, apr, apr24h, tvlUsd	`bff.bitflowapis.finance/api/app/v1/pools`
Bitflow App API (pool detail)	Single pool detail (used by `track` )	`bff.bitflowapis.finance/api/app/v1/pools/{id}`
Bitflow Quotes API	Pool list sanity check	`bff.bitflowapis.finance/api/quotes/v1/pools`
Local state file	Snapshot history for trend computation	`~/.hodlmm-pulse-state.json`

来源	数据	端点
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`

Known constraints

已知限制

```
feesUsd1d
```
and
```
volumeUsd1d
```
are 24h rolling windows from Bitflow's API — they update in near-real-time but are not per-minute granularity
Trend direction requires at least 2 snapshots;
```
spike
```
signal is actionable from a single
```
scan
```
State file is local to the machine — tracking history does not persist across machines
Low-TVL pools (< $500) are filtered by default; their fee metrics are noisy

```
feesUsd1d
```
和
```
volumeUsd1d
```
是Bitflow API提供的24小时滚动窗口数据——近乎实时更新，但不支持分钟级粒度
趋势方向判断至少需要2个快照；
```
spike
```
信号可通过单次
```
scan
```
直接使用
状态文件存储在本地机器上——追踪历史无法跨机器同步
默认过滤低TVL池（<$500）——这类池的费用指标噪音较大

Origin

起源

Winner of AIBTC x Bitflow Skills Pay the Bills competition. Original author: @ghislo749 Competition PR: https://github.com/BitflowFinance/bff-skills/pull/94

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