Hermetica Yield Rotator

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.

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

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

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

bitflow_hodlmm_add_liquidity

bitflow_hodlmm_remove_liquidity

Data sources

SPN5AK…HSG.staking-v1::get-usdh-per-susdh

::get-staking-enabled

::get-cooldown-window

::get-current-ts

::get-total-supply

api.mainnet.hiro.so/extended/v1/address/{addr}/balances

bff.bitflowapis.finance/api/app/v1/pools

/users/{addr}/positions/{pool}/bins

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