aibtcdev/hodlmm-risk

HODLMM Risk Skill

What it does

Monitors HODLMM (DLMM) pool volatility and LP risk on Bitflow. Computes bin spread, reserve imbalance, and concentration metrics to classify market regime and emit position-sizing signals.

Why agents need it

Agents managing HODLMM liquidity need a risk gate before adding, holding, or withdrawing. This skill provides that gate — a numeric volatility score and regime label that downstream agents can use to decide whether to act.

Safety notes

• Read-only — never writes to chain or moves funds.
• Mainnet only — Bitflow HODLMM APIs are mainnet-only.
• No wallet or funds required.
• Pools with all-zero reserves return an error rather than misleading metrics.

Commands

assess-pool

Assess volatility and risk metrics for a HODLMM pool.

bun run hodlmm-risk/hodlmm-risk.ts assess-pool --pool-id <pool_id>

Options:

• --pool-id (required) — HODLMM pool identifier (e.g. dlmm_3)

Output:

{
  "network": "mainnet",
  "poolId": "dlmm_3",
  "activeBinId": 447,
  "totalBins": 69,
  "binSpread": 0.021,
  "reserveImbalanceRatio": 0.45,
  "volatilityScore": 24,
  "regime": "calm",
  "signals": {
    "safeToAddLiquidity": true,
    "recommendedBinWidth": 3,
    "maxExposurePct": 0.25
  },
  "timestamp": "2026-03-24T20:00:00.000Z"
}

assess-position

Assess risk for a specific wallet's HODLMM position in a pool.

bun run hodlmm-risk/hodlmm-risk.ts assess-position --pool-id <pool_id> --address <stx_address>

Options:

• --pool-id (required) — HODLMM pool identifier
• --address (required) — Stacks address to check

Output:

{
  "network": "mainnet",
  "poolId": "dlmm_3",
  "address": "SP2...",
  "positionBinCount": 3,
  "activeBinId": 447,
  "nearestPositionBinOffset": 2,
  "avgBinOffset": 4.33,
  "concentrationRisk": "medium",
  "driftScore": 22,
  "impermanentLossEstimatePct": 1.76,
  "recommendation": "rebalance",
  "timestamp": "2026-03-24T20:00:00.000Z"
}

regime-snapshot

Get a single-point volatility regime snapshot for a pool.

bun run hodlmm-risk/hodlmm-risk.ts regime-snapshot --pool-id <pool_id>

Options:

• --pool-id (required) — HODLMM pool identifier

Output:

{
  "network": "mainnet",
  "poolId": "dlmm_3",
  "volatilityScore": 24,
  "regime": "calm",
  "activeBinId": 447,
  "binSpread": 0.021,
  "reserveImbalanceRatio": 0.45,
  "note": "Single-point snapshot. For trend analysis, store snapshots externally over time.",
  "timestamp": "2026-03-24T20:00:00.000Z"
}

Output contract

All outputs are flat JSON to stdout (no wrapper envelope).

On error:

{ "error": "descriptive error message" }

Known constraints

• Mainnet only — Bitflow HODLMM APIs do not exist on testnet.
• No wallet required — all operations are read-only.
• Volatility score ranges 0-100: 0-30 = calm, 31-60 = elevated, 61-100 = crisis.
• Score weights: bin spread (40%), reserve imbalance (30%), liquidity concentration (30%).
• driftScore is derived from avgBinOffset: Math.min(avgOffset * 5, 100). Each bin of drift adds +5 score points, capped at 100 (i.e. 20+ bins from active = score 100 = withdraw).
• impermanentLossEstimatePct is a linear approximation: driftScore * 0.08 (max 8% at driftScore=100). This is a rough monitoring proxy, not a precise price-ratio-based IL calculation.
• concentrationRisk thresholds: 1 bin = "high", 2-3 bins = "medium", 4+ bins = "low".
• signals derivation: calm → recommendedBinWidth: 3, maxExposurePct: 0.25; elevated → recommendedBinWidth: 7, maxExposurePct: 0.10; crisis → recommendedBinWidth: 15, maxExposurePct: 0.0.
• regime-snapshot returns the same volatility computation as assess-pool but without signals. Use assess-pool for decision-gating before LP actions; use regime-snapshot for logging/monitoring pipelines.
• regime-snapshot returns a single point-in-time reading. For trend analysis, store snapshots externally over time.
• Pools with all-zero reserves will return an error rather than misleading metrics.
• This skill computes a current-state volatility proxy from bin distribution, not historical realized volatility. No time-series or migration tracking is performed.

Origin

Winner of AIBTC x Bitflow Skills Pay the Bills competition Day 2. Original author: @locallaunchsc-cloud Competition PR: https://github.com/BitflowFinance/bff-skills/pull/23