Hermetica Yield Rotator

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.

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

Output Contract

All outputs are strict JSON to stdout:

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

Prerequisites

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

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

Commands

doctor

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

install-packs

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

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

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

run — stake

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

run — initiate-unstake

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

run — complete-unstake

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

run — rotate (auto-rotate to best yield)

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

Live terminal output

doctor

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

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

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

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

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

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

• 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.

Data sources

Origin

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