hodlmm-pulse

What this skill does

# 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.

```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)

### 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.

### 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

## 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:**
```json
{ "status": "success", "network": "mainnet", "timestamp": "...", ... }
```

**Error:**
```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` |

## 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