hermetica-yield-rotator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hermetica Yield Rotator

Hermetica收益轮换工具

Cross-protocol yield rotator that monitors Hermetica USDh staking APY against Bitflow HODLMM dlmm_1 APR and executes capital rotation to the higher-yielding protocol on Stacks mainnet.

适用于Stacks主网的跨协议收益轮换工具，可监控Hermetica USDh质押APY与Bitflow HODLMM dlmm_1 APR，并将资金轮换至收益更高的协议。

What it does

功能说明

Queries five Hermetica mainnet contracts (staking-v1, staking-state-v1, staking-silo-v1-1, usdh-token-v1, susdh-token-v1) for the live exchange rate, staking state, cooldown window, and user position. Fetches Bitflow HODLMM dlmm_1 APR and active bin from Bitflow App and Quotes APIs. Tracks the USDh/sUSDh exchange rate in a local state file to estimate APY from ratio changes over time.

In assess mode (default), surfaces a HOLD / STAKE / ROTATE_TO_HODLMM / ROTATE_TO_STAKING recommendation. In write mode (with --confirm), outputs MCP tool commands to execute the recommended action.

Rotation logic: rotates when yield differential exceeds 2% threshold. HODLMM preferred → initiates Hermetica unstake (7-day cooldown), then swaps USDh → USDCx (dlmm_1 accepts USDCx, not USDh) and deploys to HODLMM. Staking preferred → removes HODLMM bins, stakes in Hermetica. Idle USDh → swaps to USDCx then deploys to best-yielding protocol immediately.

30-minute rotation cooldown prevents thrashing. All write actions require

--confirm

查询Hermetica主网的5个合约（staking-v1、staking-state-v1、staking-silo-v1-1、usdh-token-v1、susdh-token-v1）以获取实时汇率、质押状态、冷却窗口及用户持仓情况。通过Bitflow App和Quotes API获取Bitflow HODLMM dlmm_1的APR和活跃仓位。在本地状态文件中跟踪USDh/sUSDh汇率，通过一段时间内的比率变化估算APY。

在评估模式（默认）下，给出HOLD / STAKE / ROTATE_TO_HODLMM / ROTATE_TO_STAKING的建议。在写入模式（带--confirm参数）下，输出MCP工具命令以执行推荐操作。

轮换逻辑： 当收益差值超过2%阈值时触发轮换。若HODLMM收益更高→发起Hermetica unstake（7天冷却期），随后将USDh兑换为USDCx（dlmm_1仅接受USDCx，不支持USDh）并投入HODLMM。若质押收益更高→移除HODLMM仓位，将资金存入Hermetica进行质押。闲置USDh→直接兑换为USDCx，再投入收益最高的协议。

30分钟轮换冷却期 避免频繁操作。所有写入操作均需

--confirm

参数。

Why agents need it

智能体为何需要该工具

USDh staking yield and HODLMM LP fees move independently. Without active rotation, agents leave yield on the table when market conditions shift. This skill closes that gap: a single

--action=rotate --confirm

re-allocates capital to the optimal protocol based on live data.

USDh质押收益与HODLMM流动性挖矿手续费各自独立波动。若不主动轮换，当市场条件变化时，智能体会错失收益。本工具填补了这一空白：只需执行

--action=rotate --confirm

命令，即可根据实时数据将资金重新分配至最优协议。

Safety notes

安全说明

500 USDh autonomous spend cap — hardcoded in code. Without explicit
```
--amount
```
, stake/unstake/rotate operations are capped at 500 USDh regardless of wallet balance. Pass
```
--amount
```
to operate on larger positions.
Doctor-first preflight enforced in code: write actions verify Hermetica contract and staking state are reachable before executing. Aborts with
```
PREFLIGHT_FAILED
```
if sources are down.
All write actions require explicit
```
--confirm
```
flag — no accidental execution
2% minimum differential threshold prevents unnecessary rotation on noise
30-minute cooldown between rotations tracked in local state file
Balance checked before stake/initiate-unstake — rejects if insufficient
Rotation blocked if APY data unavailable (< 1h of exchange rate history)
Rotation cooldown checked before execution
```
initiate-unstake
```
always reports 7-day cooldown so agent can plan
```
complete-unstake
```

500 USDh自主支出上限——代码中硬编码。 若未指定
```
--amount
```
参数，质押/unstake/轮换操作的上限为500 USDh，不受钱包余额影响。可通过传入
```
--amount
```
参数处理更大仓位。
代码强制执行预检机制： 写入操作执行前会验证Hermetica合约和质押状态是否可访问。若数据源不可用，将以
```
PREFLIGHT_FAILED
```
终止操作。
所有写入操作均需显式添加
```
--confirm
```
标志——避免误执行
2%最小差值阈值避免因微小波动触发不必要的轮换
本地状态文件跟踪轮换操作的30分钟冷却期
质押/发起unstake前检查余额——余额不足时拒绝执行
若APY数据不可用（汇率历史不足1小时），将阻止轮换操作
执行前检查轮换冷却期
```
initiate-unstake
```
操作始终会告知7天冷却期，以便智能体规划
```
complete-unstake
```
操作

Output Contract

输出规范

All outputs are strict JSON to stdout:

json

{
  "status": "success | error",
  "action": "HOLD | STAKE | ROTATE_TO_HODLMM | ROTATE_TO_STAKING | INITIATE_UNSTAKE | COMPLETE_UNSTAKE | CHECK | Blocked: <reason>",
  "data": {
    "mcp_commands": "[McpCommand[] | null] — present on write actions",
    "staking_enabled": "boolean",
    "exchange_rate": "number",
    "accumulated_yield_pct": "number",
    "estimated_apy_pct": "number | null",
    "cooldown_days": "number",
    "hodlmm_apr_pct": "number | null",
    "hodlmm_active_bin": "number | null",
    "yield_comparison": "string | null",
    "user_usdh": "number | null",
    "user_susdh": "number | null",
    "rotation_cooldown_ok": "boolean",
    "rotate_threshold_pct": "number"
  },
  "error": "null | { code, message, next }"
}

所有输出均为标准JSON格式，输出至标准输出：

json

{
  "status": "success | error",
  "action": "HOLD | STAKE | ROTATE_TO_HODLMM | ROTATE_TO_STAKING | INITIATE_UNSTAKE | COMPLETE_UNSTAKE | CHECK | Blocked: <reason>",
  "data": {
    "mcp_commands": "[McpCommand[] | null] — 写入操作时会返回",
    "staking_enabled": "boolean",
    "exchange_rate": "number",
    "accumulated_yield_pct": "number",
    "estimated_apy_pct": "number | null",
    "cooldown_days": "number",
    "hodlmm_apr_pct": "number | null",
    "hodlmm_active_bin": "number | null",
    "yield_comparison": "string | null",
    "user_usdh": "number | null",
    "user_susdh": "number | null",
    "rotation_cooldown_ok": "boolean",
    "rotate_threshold_pct": "number"
  },
  "error": "null | { code, message, next }"
}

Prerequisites

前置条件

This skill requires the AIBTC MCP server for all on-chain interactions:

bash

npx @aibtc/mcp-server@latest --install

本工具需要AIBTC MCP服务器以实现所有链上交互：

bash

npx @aibtc/mcp-server@latest --install

Commands

命令

doctor

bash

bun run hermetica-yield-rotator/hermetica-yield-rotator.ts doctor

bash

bun run hermetica-yield-rotator/hermetica-yield-rotator.ts doctor

install-packs

bash

bun run hermetica-yield-rotator/hermetica-yield-rotator.ts install-packs --pack all

bash

bun run hermetica-yield-rotator/hermetica-yield-rotator.ts install-packs --pack all

run — assess (read-only, no --confirm needed)

run — 评估模式（只读，无需--confirm）

bash

bun run hermetica-yield-rotator/hermetica-yield-rotator.ts run --wallet SP1234...

bash

bun run hermetica-yield-rotator/hermetica-yield-rotator.ts run --wallet SP1234...

run — stake

run — 质押

bash

bun run hermetica-yield-rotator/hermetica-yield-rotator.ts run \
  --wallet SP1234... --action=stake --amount=500 --confirm

bash

bun run hermetica-yield-rotator/hermetica-yield-rotator.ts run \
  --wallet SP1234... --action=stake --amount=500 --confirm

run — initiate-unstake

run — 发起unstake

bash

bun run hermetica-yield-rotator/hermetica-yield-rotator.ts run \
  --wallet SP1234... --action=initiate-unstake --amount=500 --confirm

bash

bun run hermetica-yield-rotator/hermetica-yield-rotator.ts run \
  --wallet SP1234... --action=initiate-unstake --amount=500 --confirm

run — complete-unstake

run — 完成unstake

bash

bun run hermetica-yield-rotator/hermetica-yield-rotator.ts run \
  --wallet SP1234... --action=complete-unstake --confirm

bash

bun run hermetica-yield-rotator/hermetica-yield-rotator.ts run \
  --wallet SP1234... --action=complete-unstake --confirm

run — rotate (auto-rotate to best yield)

run — 轮换（自动切换至最优收益协议）

bash

bun run hermetica-yield-rotator/hermetica-yield-rotator.ts run \
  --wallet SP1234... --action=rotate --confirm

bash

bun run hermetica-yield-rotator/hermetica-yield-rotator.ts run \
  --wallet SP1234... --action=rotate --confirm

Live terminal output

终端实时输出示例

doctor

json

{
  "status": "ok",
  "checks": [
    { "name": "Hermetica staking-v1",                      "ok": true, "detail": "exchange rate: 1.00000000 USDh/sUSDh" },
    { "name": "Hermetica staking-state-v1",                "ok": true, "detail": "staking enabled: true, cooldown: 7.0 days" },
    { "name": "Hermetica token contracts (USDh + sUSDh)",  "ok": true, "detail": "USDh supply: $9,049,413.13, sUSDh: 1,836,203.38" },
    { "name": "Bitflow HODLMM App API (dlmm_1)",           "ok": true, "detail": "APR: 17.72%, TVL: $77,143" },
    { "name": "Bitflow HODLMM Bins API (dlmm_1)",          "ok": true, "detail": "active bin: 504" }
  ],
  "message": "All data sources reachable. Ready to run."
}

json

{
  "status": "ok",
  "checks": [
    { "name": "Hermetica staking-v1",                      "ok": true, "detail": "exchange rate: 1.00000000 USDh/sUSDh" },
    { "name": "Hermetica staking-state-v1",                "ok": true, "detail": "staking enabled: true, cooldown: 7.0 days" },
    { "name": "Hermetica token contracts (USDh + sUSDh)",  "ok": true, "detail": "USDh supply: $9,049,413.13, sUSDh: 1,836,203.38" },
    { "name": "Bitflow HODLMM App API (dlmm_1)",           "ok": true, "detail": "APR: 17.72%, TVL: $77,143" },
    { "name": "Bitflow HODLMM Bins API (dlmm_1)",          "ok": true, "detail": "active bin: 504" }
  ],
  "message": "All data sources reachable. Ready to run."
}

install-packs

json

{
  "status": "ok",
  "message": "No packs required. hermetica-yield-rotator uses Hermetica contracts and Hiro/Bitflow public APIs only.",
  "data": { "requires": [] }
}

json

{
  "status": "ok",
  "message": "No packs required. hermetica-yield-rotator uses Hermetica contracts and Hiro/Bitflow public APIs only.",
  "data": { "requires": [] }
}

run --wallet (assess — no position)

run --wallet（评估模式——无持仓）

json

{
  "status": "success",
  "action": "CHECK — staking enabled, protocol healthy. Provide --wallet to check position.",
  "data": {
    "staking_enabled": true,
    "exchange_rate": 1,
    "accumulated_yield_pct": 0,
    "estimated_apy_pct": null,
    "cooldown_days": 7,
    "usdh_total_supply": 9049413.13,
    "susdh_total_supply": 1836203.38,
    "hodlmm_apr_pct": 17.72,
    "hodlmm_tvl_usd": 77142.99,
    "hodlmm_active_bin": 504,
    "yield_comparison": "HODLMM dlmm_1 APR: 17.72% | USDh staking APY: tracking started — check again in ≥1h",
    "user_usdh": 0,
    "user_susdh": 0,
    "user_susdh_value_usdh": 0,
    "hodlmm_position_bins": null,
    "rotation_cooldown_ok": true,
    "rotate_threshold_pct": 2,
    "refusal_reasons": null,
    "silo_epoch_ts": 1774660532
  },
  "error": null
}

json

{
  "status": "success",
  "action": "CHECK — staking enabled, protocol healthy. Provide --wallet to check position.",
  "data": {
    "staking_enabled": true,
    "exchange_rate": 1,
    "accumulated_yield_pct": 0,
    "estimated_apy_pct": null,
    "cooldown_days": 7,
    "usdh_total_supply": 9049413.13,
    "susdh_total_supply": 1836203.38,
    "hodlmm_apr_pct": 17.72,
    "hodlmm_tvl_usd": 77142.99,
    "hodlmm_active_bin": 504,
    "yield_comparison": "HODLMM dlmm_1 APR: 17.72% | USDh staking APY: tracking started — check again in ≥1h",
    "user_usdh": 0,
    "user_susdh": 0,
    "user_susdh_value_usdh": 0,
    "hodlmm_position_bins": null,
    "rotation_cooldown_ok": true,
    "rotate_threshold_pct": 2,
    "refusal_reasons": null,
    "silo_epoch_ts": 1774660532
  },
  "error": null
}

run --action=stake --amount=500 --confirm (balance guard — no USDh)

run --action=stake --amount=500 --confirm（余额校验——无USDh）

json

{
  "status": "error",
  "action": "Blocked: Amount 500.00 USDh exceeds wallet balance 0.00",
  "data": null,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Amount 500.00 USDh exceeds wallet balance 0.00",
    "next": "Reduce --amount or acquire more USDh."
  }
}

json

{
  "status": "error",
  "action": "Blocked: Amount 500.00 USDh exceeds wallet balance 0.00",
  "data": null,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Amount 500.00 USDh exceeds wallet balance 0.00",
    "next": "Reduce --amount or acquire more USDh."
  }
}

run --action=rotate (missing --confirm guard)

run --action=rotate（缺少--confirm校验）

json

{
  "status": "error",
  "action": "Blocked: --confirm required for action 'rotate'",
  "data": null,
  "error": {
    "code": "CONFIRM_REQUIRED",
    "message": "--confirm required for action 'rotate'",
    "next": "Re-run with --confirm to execute."
  }
}

json

{
  "status": "error",
  "action": "Blocked: --confirm required for action 'rotate'",
  "data": null,
  "error": {
    "code": "CONFIRM_REQUIRED",
    "message": "--confirm required for action 'rotate'",
    "next": "Re-run with --confirm to execute."
  }
}

run --action=rotate --confirm (no APY data yet guard)

run --action=rotate --confirm（APY数据不足校验）

json

{
  "status": "error",
  "action": "Blocked: Cannot rotate without both USDh APY and HODLMM APR data. APY requires ≥1h of exchange rate observations.",
  "data": null,
  "error": {
    "code": "INSUFFICIENT_YIELD_DATA",
    "message": "Cannot rotate without both USDh APY and HODLMM APR data. APY requires ≥1h of exchange rate observations.",
    "next": "Run in assess mode for ≥1h, then retry --action=rotate."
  }
}

json

{
  "status": "error",
  "action": "Blocked: Cannot rotate without both USDh APY and HODLMM APR data. APY requires ≥1h of exchange rate observations.",
  "data": null,
  "error": {
    "code": "INSUFFICIENT_YIELD_DATA",
    "message": "Cannot rotate without both USDh APY and HODLMM APR data. APY requires ≥1h of exchange rate observations.",
    "next": "Run in assess mode for ≥1h, then retry --action=rotate."
  }
}

Does this integrate HODLMM?

是否集成HODLMM？

Yes — eligible for the +$1,000 sBTC bonus pool

Integrates HODLMM at the execution level: fetches live dlmm_1 APR and active bin on every run, outputs

bitflow_swap

(USDh → USDCx),

bitflow_hodlmm_add_liquidity

, and

bitflow_hodlmm_remove_liquidity

MCP commands as part of the rotation pipeline. The swap step is required because dlmm_1 accepts USDCx, not USDh.

是 — 有资格参与1000 sBTC奖励池

在执行层面集成HODLMM：每次运行时获取dlmm_1的实时APR和活跃仓位，在轮换流程中输出

bitflow_swap

（USDh → USDCx）、

bitflow_hodlmm_add_liquidity

和

bitflow_hodlmm_remove_liquidity

MCP命令。兑换步骤是必需的，因为dlmm_1仅接受USDCx，不支持USDh。

Data sources

数据源

Source	Data	Endpoint
Hermetica staking-v1	Exchange rate	`SPN5AK…HSG.staking-v1::get-usdh-per-susdh`
Hermetica staking-state-v1	Staking enabled, cooldown	`::get-staking-enabled` , `::get-cooldown-window`
Hermetica staking-silo-v1-1	Epoch timestamp	`::get-current-ts`
Hermetica usdh-token-v1 / susdh-token-v1	Token supplies	`::get-total-supply`
Hiro Address API	User FT balances	`api.mainnet.hiro.so/extended/v1/address/{addr}/balances`
Bitflow HODLMM App API	dlmm_1 APR, TVL, user position bins	`bff.bitflowapis.finance/api/app/v1/pools` , `/users/{addr}/positions/{pool}/bins`
Bitflow HODLMM Quotes API	Active bin ID	`bff.bitflowapis.finance/api/quotes/v1/bins/{pool}`

来源	数据	端点
Hermetica staking-v1	汇率	`SPN5AK…HSG.staking-v1::get-usdh-per-susdh`
Hermetica staking-state-v1	质押启用状态、冷却期	`::get-staking-enabled` , `::get-cooldown-window`
Hermetica staking-silo-v1-1	纪元时间戳	`::get-current-ts`
Hermetica usdh-token-v1 / susdh-token-v1	代币总供应量	`::get-total-supply`
Hiro Address API	用户FT余额	`api.mainnet.hiro.so/extended/v1/address/{addr}/balances`
Bitflow HODLMM App API	dlmm_1的APR、TVL、用户仓位	`bff.bitflowapis.finance/api/app/v1/pools` , `/users/{addr}/positions/{pool}/bins`
Bitflow HODLMM Quotes API	活跃仓位ID	`bff.bitflowapis.finance/api/quotes/v1/bins/{pool}`

Origin

起源

Winner of AIBTC x Bitflow Skills Pay the Bills competition. Original author: @cliqueengagements Competition PR: https://github.com/BitflowFinance/bff-skills/pull/56

AIBTC x Bitflow Skills Pay the Bills竞赛获胜作品。原作者：@cliqueengagements 竞赛PR：https://github.com/BitflowFinance/bff-skills/pull/56