hodlmm-risk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HODLMM Risk Skill

HODLMM风险监控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.

监控Bitflow上HODLMM（DLMM）资金池的波动率和LP风险。计算仓位价差、储备失衡和集中度指标，以分类市场状态并发出仓位调整信号。

Why agents need it

Agent为何需要该工具

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.

管理HODLMM流动性的Agent在添加、持有或提取流动性前需要风险管控机制。本Skill提供了这样的管控机制——一个数值化的波动率评分和状态标签，下游Agent可据此决定是否执行操作。

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.

仅支持只读操作——绝不会写入链上数据或转移资金。
仅支持主网——Bitflow HODLMM API仅在主网可用。
无需钱包或资金。
储备全为零的资金池会返回错误，而非误导性指标。

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:

json

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

评估HODLMM资金池的波动率和风险指标。

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

选项：

```
--pool-id
```
（必填）——HODLMM资金池标识符（例如
```
dlmm_3
```
）

输出：

json

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

json

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

评估特定钱包在HODLMM资金池中持仓的风险。

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

选项：

```
--pool-id
```
（必填）——HODLMM资金池标识符
```
--address
```
（必填）——需要检查的Stacks地址

输出：

json

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

json

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

获取资金池的单点波动率状态快照。

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

选项：

```
--pool-id
```
（必填）——HODLMM资金池标识符

输出：

json

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

json

{ "error": "descriptive error message" }

所有输出均为扁平JSON格式，输出至标准输出（无包装信封）。

错误时输出：

json

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

仅支持主网——Bitflow HODLMM API在测试网不存在。
无需钱包——所有操作均为只读。
波动率评分范围0-100：0-30=平稳，31-60=升高，61-100=危机。
评分权重：仓位价差（40%）、储备失衡（30%）、流动性集中度（30%）。
```
driftScore
```
由
```
avgBinOffset
```
推导而来：
```
Math.min(avgOffset * 5, 100)
```
。每偏移一个仓位加5分，最高100分（即偏离活跃仓位20个以上时评分为100，建议提取流动性）。
```
impermanentLossEstimatePct
```
为线性近似值：
```
driftScore * 0.08
```
（driftScore=100时最高为8%）。这是一个粗略的监控指标，并非基于价格比率的精确无常损失计算。
```
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
```
返回单点时间的读数。如需趋势分析，请在外部存储历史快照。
储备全为零的资金池会返回错误，而非误导性指标。
本Skill基于仓位分布计算当前状态的波动率指标，而非历史实际波动率。不执行时间序列或迁移跟踪。

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

AIBTC x Bitflow Skills Pay the Bills竞赛第二天的获胜作品。原作者：@locallaunchsc-cloud 竞赛PR：https://github.com/BitflowFinance/bff-skills/pull/23