aibtcdev/hodlmm-pulse

HODLMM Pulse

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

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:

1. Single-shot (scan) — instant momentum ranking across all pools from a single API call. Useful for quick triage.
2. 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.

Why agents need it

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:

1. hodlmm-pulse scan → identify pools with active momentum
2. hodlmm-pulse track --pool-id <id> → confirm trend direction over multiple polls
3. hodlmm-advisor entry-plan --pool-id <id> → get exact bin range + strategy
4. Execute only when both pulse signal is spike/elevated and advisor returns "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)

Commands

doctor

Checks all data sources and state file readiness.

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.

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)

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.

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.

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.

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

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.

Volume velocity

Secondary signal. Same ratio applied to volume:

volumeVelocity = volumeUsd1d / (volumeUsd7d / 7)

APR spike ratio

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

aprSpike = apr24h / apr

Momentum score (composite, weighted)

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

50 = average day. Higher = more active than usual.

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 |

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 |

Output contract

All outputs are JSON to stdout.

Success:

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

Error:

{ "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 |

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

Origin

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