HODLMM Risk Skill

What it does

Why agents need it

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

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

• --pool-id

  (required) — HODLMM pool identifier (e.g.

  dlmm_3

  )

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

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

• --pool-id

  (required) — HODLMM pool identifier

• --address

  (required) — Stacks address to check

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

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

• --pool-id

  (required) — HODLMM pool identifier

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

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