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. ```bash bun run hodlmm-flow/hodlmm-flow.ts doctor ``` ### install-packs No-op subcommand for registry compatibility. This skill has no additional packs to install. ```bash bun run hodlmm-flow/hodlmm-flow.ts install-packs ``` ### flow --pool-id Analyze swap flow for a single pool. Default: last 100 swaps. ```bash 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. ```bash 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). ```bash 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):** ```json { "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:** ```json { "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