hodlmm-risk

HODLMM リスクスキル

概要

Bitflow 上の HODLMM（DLMM）プールのボラティリティと LP リスクを監視します。ビンのスプレッド、準備金の不均衡、集中度の指標を計算し、市場レジームを分類してポジションサイズのシグナルを出力します。

エージェントに必要な理由

HODLMM の流動性を管理するエージェントは、追加、保有、または引き出しの前にリスク判定を行う必要があります。このスキルは、その判定に必要な数値のボラティリティスコアとレジームラベルを提供し、後続のエージェントが行動するかどうかを判断できるようにします。

安全上の注意

• 読み取り専用です。チェーンへの書き込みや資金の移動は行いません。
• メインネット専用です。Bitflow HODLMM API はメインネットでのみ利用できます。
• ウォレットや資金は不要です。
• 準備金がすべてゼロのプールでは、誤解を招く指標を返さず、エラーを返します。

コマンド

assess-pool

HODLMM プールのボラティリティとリスク指標を評価します。

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

オプション：

• --pool-id（必須） — HODLMM プール識別子（例：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

特定のウォレットが保有するプール内の HODLMM ポジションのリスクを評価します。

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

オプション：

• --pool-id（必須） — HODLMM プール識別子
• --address（必須） — 確認する Stacks アドレス

出力：

{
  "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（必須） — HODLMM プール識別子

出力：

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

出力仕様

すべての出力は標準出力へのフラットな JSON です（ラッパーエンベロープはありません）。

エラー時：

{ "error": "descriptive error message" }

既知の制約

• メインネット専用です。Bitflow HODLMM API はテストネットには存在しません。
• ウォレットは不要です。すべての操作は読み取り専用です。
• ボラティリティスコアの範囲は 0～100 です。0～30 = 落ち着いた状態、31～60 = 上昇、61～100 = 危機的な状態です。
• スコアの重み付け：ビンのスプレッド（40％）、準備金の不均衡（30％）、流動性の集中度（30％）。
• driftScore は avgBinOffset から算出されます：Math.min(avgOffset * 5, 100)。ドリフトが 1 ビン増えるごとにスコアが 5 ポイント加算され、上限は 100 です（つまり、アクティブビンから 20 ビン以上離れるとスコアは 100 となり、引き出しが推奨されます）。
• impermanentLossEstimatePct は線形近似値です：driftScore * 0.08（driftScore=100 のとき最大 8％）。これは大まかな監視用の代替指標であり、価格比率に基づく正確な IL 計算ではありません。
• concentrationRisk のしきい値：1 ビン = 「高」、2～3 ビン = 「中」、4 ビン以上 = 「低」。
• signals の導出：落ち着いた状態 → recommendedBinWidth: 3, maxExposurePct: 0.25、上昇 → recommendedBinWidth: 7, maxExposurePct: 0.10、危機的な状態 → recommendedBinWidth: 15, maxExposurePct: 0.0。
• regime-snapshot は assess-pool と同じボラティリティ計算を返しますが、シグナルは含みません。LP 操作の前に判断ゲートとして使用する場合は assess-pool を、ログ記録／監視パイプラインには regime-snapshot を使用してください。
• regime-snapshot が返すのは、単一時点の読み取り値です。傾向分析には、スナップショットを外部に保存して経時的に追跡してください。
• 準備金がすべてゼロのプールでは、誤解を招く指標を返さず、エラーを返します。
• このスキルは、過去の実現ボラティリティではなく、ビンの分布から現在の状態のボラティリティ代替指標を計算します。時系列追跡や移行追跡は行いません。

出典

AIBTC x Bitflow Skills Pay the Bills コンペティション Day 2 の優勝作品です。 原作者：@locallaunchsc-cloud コンペティションの PR：https://github.com/BitflowFinance/bff-skills/pull/23