aibtcdev/hodlmm-flow

HODLMM Flow

Swap flow intelligence for Bitflow HODLMM concentrated liquidity pools.

What it does

Every other HODLMM tool looks at pool state — TVL, bin distribution, positions. This one looks at swap flow: what's actually trading, in what direction, by whom, and what it means for LPs.

Fetches on-chain swap transactions from Hiro API, parses DLMM core contract events to extract per-bin-hop volumes, and computes six market microstructure metrics: direction bias, flow toxicity, bin velocity, whale concentration, liquidation pressure, and bot/organic classification. Produces an LP safety verdict with a predicted range lifespan.

Why agents need it

Concentrated liquidity LPs face adverse selection — informed traders extract value from stale positions. Without flow analysis, an agent choosing range parameters is flying blind. This skill gives agents the data to:

• Detect toxic flow — consecutive same-direction swaps signal informed trading that picks off LPs
• Predict range lifespan — bin velocity tells you how long a ±N-bin position will stay in range
• Identify who's trading — bot vs organic vs liquidator classification reveals market structure
• Assess directional risk — strong bias means one side of your position is getting drained
• Spot liquidation cascades — Zest liquidation flow through HODLMM pools signals collateral stress

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 is mainnet-only
• Uses Hiro transactions + events APIs. A Hiro API key (--hiro-api-key) is recommended for analyzing more than 100 swaps to avoid rate limits

Commands

doctor

Checks connectivity to Hiro API (transactions, events) and Bitflow APIs (quotes, app). Verifies the full data pipeline is accessible.

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

install-packs

No-op subcommand for registry compatibility. This skill has no additional packs to install.

bun run hodlmm-flow/hodlmm-flow.ts install-packs

flow --pool-id

Analyze swap flow for a single pool. Default: last 100 swaps.

bun run hodlmm-flow/hodlmm-flow.ts flow --pool-id dlmm_3

flow --pool-id --window

Time-windowed analysis. Analyzes swaps within the specified duration.

bun run hodlmm-flow/hodlmm-flow.ts flow --pool-id dlmm_3 --window 24h

flow --all

Protocol-wide flow summary across all 8 HODLMM pools (dlmm_1 through dlmm_8).

bun run hodlmm-flow/hodlmm-flow.ts flow --all

Options:

• --pool-id <id> — Pool to analyze (dlmm_1 through dlmm_8)
• --window <duration> — Time window (e.g. 24h, 7d, 30m)
• --swaps <count> — Number of swaps to analyze (default: 100)
• --all — Analyze all 8 HODLMM pools
• --hiro-api-key <key> — Hiro API key for elevated rate limits

Output contract

All outputs are JSON to stdout.

Success (single pool):

{
  "status": "success",
  "network": "mainnet",
  "timestamp": "2026-04-09T20:00:00.000Z",
  "poolId": "dlmm_3",
  "pair": "STX/USDCx",
  "swapsAnalyzed": 100,
  "timeSpanHours": 4.2,
  "metrics": {
    "directionBias": -0.31,
    "directionBiasLabel": "Moderate sell-X pressure",
    "flowToxicity": 0.62,
    "flowToxicityLabel": "Elevated — directional momentum present",
    "binVelocity": 12.5,
    "binVelocityLabel": "Moderate — normal volatility",
    "whaleConcentration": 0.45,
    "whaleConcentrationLabel": "Concentrated — few actors drive most volume",
    "liquidationPressure": 0.02,
    "liquidationPressureLabel": "Low — 1 liquidation(s), minimal impact",
    "botFlowRatio": 0.72,
    "botFlowRatioLabel": "Bot-heavy — majority of flow is automated"
  },
  "verdict": {
    "lpSafety": "caution",
    "score": 52,
    "reasoning": "Strong directional pressure (selling X). Concentrated flow — few actors dominating volume.",
    "recommendation": "Monitor flow direction. Consider asymmetric range if bias persists.",
    "rangeLifespanHours": 0.8
  },
  "topActors": [
    { "address": "SP2V3J7G...", "swapCount": 45, "volumeShare": 82.1, "label": "bot" }
  ]
}

Error:

{ "error": "descriptive message" }

Metrics reference

| Metric | Range | What it measures | |---|---|---| | Direction bias | [-1, +1] | Net buying vs selling pressure. -1 = all selling X, +1 = all buying X | | Flow toxicity | [0, 1] | Consecutive same-direction ratio. >0.6 = informed flow adversely selecting LPs | | Bin velocity | bins/hour | Active bin change rate. Predicts how fast positions go out of range | | Whale concentration | [0, 1] | Herfindahl index on swap volume. >0.25 = concentrated, >0.5 = monopolistic | | Liquidation pressure | [0, 1] | Volume fraction from Zest liquidate-with-swap transactions | | Bot flow ratio | [0, 1] | Volume fraction from automated addresses (>10 swaps/hour or >30% of flow) |

Data source

Swap data is sourced from Hiro API (/extended/v1/address/{pool}/transactions + /extended/v1/tx/events). Each swap transaction's DLMM core contract logs are parsed to extract per-bin-hop amounts (dx, dy), active bin IDs, callers, and swap direction.

Bitflow does not currently expose swap history via their own API. This skill recommends they add a /trades or /swaps endpoint — they already have the data server-side. This would eliminate Hiro dependency and enable real-time flow monitoring.

Known constraints

• Free-tier Hiro supports ~100 swaps per run (~100-150 API calls). Use --hiro-api-key for larger analyses
• Only ~25-30% of transactions hitting pool contracts are swaps — the rest are add/withdraw liquidity. The skill pages through until it collects enough swap txs
• Multi-hop swap transactions (crossing multiple bins) produce multiple events per tx — all are aggregated correctly
• swap-simple-multi function calls don't indicate direction in the function name — direction is resolved from contract events
• Stale data: Hiro API indexes with a slight delay (~1-2 blocks). Very recent swaps may not appear immediately

Origin

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