usdcx-yield-optimizer

name	usdcx-yield-optimizer
description	Autonomous USDCx yield deployer for Bitflow — scans 7 HODLMM pools and XYK venues, reads on-chain positions via call-read-only, risk-tags volatile pairs via sBTC reserve health check, applies a Yield-to-Gas profit gate, and outputs executable call_contract MCP command specs to deploy USDCx to the highest-yielding pool. Suggests Hermetica sUSDh as a route when swap yields beat direct venues. The first skill that treats USDCx as a primary yield asset.
metadata	{"author":"cliqueengagements","author-agent":"Micro Basilisk (Agent 77) — SP219TWC8G12CSX5AB093127NC82KYQWEH8ADD1AY | bc1qzh2z92dlvccxq5w756qppzz8fymhgrt2dv8cf5","user-invocable":"true","arguments":"doctor | install-packs | position [--wallet <address>] | run [--amount <usdcx>] [--risk <low|medium|high>] [--from <current_venue>] [--confirm]","entry":"usdcx-yield-optimizer/usdcx-yield-optimizer.ts","requires":"","tags":"defi, mainnet-only"}

USDCx Yield Optimizer

The first autonomous yield deployer for Bitflow's native stablecoin.

Scans every live USDCx venue on Bitflow, risk-tags each one, applies a Yield-to-Gas profit gate, and outputs executable MCP commands to deploy USDCx to the highest-yielding HODLMM pool. From analysis to action in one command.

Write-ready. Generates deployment specs for HODLMM liquidity router with --confirm. Spec-only until MCP adds trait_reference support (see Write Capability Status). Mainnet only.

---

What it does

Five-step pipeline: Position -> Scan -> Risk-tag -> Gate -> Act

Step 0 — Position (on-chain read): When position is called, reads the wallet's HODLMM bin placements, balances, and active bin distance directly from on-chain pool contracts via call-read-only. No signing required. Covers 3 unique pool contracts (sBTC/USDCx, STX/USDCx, aeUSDC/USDCx).

Step 1 — Scan every USDCx venue in parallel:

• 7 Bitflow HODLMM concentrated liquidity pools (sBTC/USDCx, STX/USDCx, aeUSDC/USDCx, USDh/USDCx)
• Bitflow XYK passive LP pools (aeUSDC pairs)
• Hermetica sUSDh vault (as a suggested route via sBTC swap)

Step 2 — Risk-tag each venue:

• Stablecoin HODLMM pairs (aeUSDC/USDCx, USDh/USDCx): low risk — no impermanent loss, no volatile exposure
• STX/USDCx pools: medium risk — impermanent loss from STX volatility
• sBTC/USDCx pools: medium if sBTC reserve GREEN, high if YELLOW/RED
• Hermetica route: medium risk — requires sBTC exposure + protocol risk

The sBTC reserve signal is derived from live price deviation (sBTC/BTC) — no external oracle dependency.

Step 3 — Gate (Yield-to-Gas profit gate): When --from is specified (agent is already in a venue), applies the YTG rule: 7d extra yield > gas cost x 3. Prevents churn — never migrate for marginal APY gains that gas costs would eat.

Step 4 — Act (MCP command generation): When --confirm is passed with --amount, generates executable call_contract MCP command specs targeting the recommended pool's active bin. Without --confirm, runs in dry-run mode — analysis only, no executable output. Deployment capped at 5,000 USDCx per operation (enforced in code).

---

Why agents need it

One question: "I'm holding USDCx — where should it be earning yield right now, and is it safe?"

USDCx is Bitflow's native stablecoin, live across 7 HODLMM pools and XYK venues, plus swap routes to Hermetica. Before this skill, an agent had to manually check each pool, estimate risk, compare APRs, and figure out the contract parameters — across 7+ venues with different fee structures. Now it's one command.

Five problems, one skill:

1. Where is my USDCx now? → position reads on-chain — which pool, which bins, in-range or not
2. What are all my options? → run scans 7 HODLMM pools + XYK + Hermetica in one call
3. Which option is safest? → Risk-tags each venue (stablecoin=low, STX=medium, sBTC=depends on reserve health)
4. Is moving worth it? → Profit gate: "will 7 days of extra yield cover 3x the gas to migrate?"
5. How do I execute? → Generates the exact contract call spec for the winning pool

Especially valuable for autonomous agents managing stablecoin reserves, where capital efficiency matters but safety matters more.

---

Safety notes

• Write-ready. Generates complete call_contract deployment specs with --confirm. Currently spec-only due to MCP trait_reference limitation (see "Write Capability Status" section). Dry-run by default.
• --confirm required — without this flag, the skill only analyzes and recommends. No deployment specs generated without explicit opt-in.
• Deployment cap: 5,000 USDCx per operation — enforced in code (MAX_DEPLOY_USDCX = 5000), not just documented.
• Mainnet only. All endpoints target Stacks and Bitcoin mainnet.
• Profit gate enforced in code — not just documented:
  • PROFIT_GATE_MULTIPLIER = 3 — 7d gain must exceed 3x gas cost
  • MIN_APY_IMPROVEMENT_PCT = 1.0 — never recommend for <1% APY gain
  • MIN_TVL_USD = 50,000 — skip pools below this TVL
  • MAX_SANE_APR = 500 — reject implausible APR values (API spoofing protection)
  • SBTC_DEV_GREEN_PCT = 0.5 — sBTC price deviation threshold for GREEN signal
• Graceful degradation: If any source is unavailable, skill continues with available data and reports sources_failed. Status becomes "degraded" but output remains valid for available venues.
• Exit codes: 0 = ok, 1 = degraded, 3 = error

---

Commands

doctor

Verifies all data sources: Bitflow HODLMM App API, Bitflow Ticker, Bitflow Prices, Hiro fees, Hermetica staking, sBTC price signal, HODLMM on-chain pool reads.

bun run usdcx-yield-optimizer/usdcx-yield-optimizer.ts doctor

install-packs

No additional packages required — fully self-contained using native fetch.

bun run usdcx-yield-optimizer/usdcx-yield-optimizer.ts install-packs

position

Reads on-chain HODLMM positions for a wallet across all 3 USDCx pool contracts. Returns bin placements, balances, active bin distance, and in-range status. Uses call-read-only — no signing required.

# Default wallet (Agent 77)
bun run usdcx-yield-optimizer/usdcx-yield-optimizer.ts position

# Specific wallet
bun run usdcx-yield-optimizer/usdcx-yield-optimizer.ts position --wallet SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9

run

Scan all USDCx venues and output ranked recommendations.

# Basic scan — rank all venues, medium risk tolerance
bun run usdcx-yield-optimizer/usdcx-yield-optimizer.ts run

# Conservative — only stablecoin pairs and lending
bun run usdcx-yield-optimizer/usdcx-yield-optimizer.ts run --risk low

# With amount for profit gate calculation
bun run usdcx-yield-optimizer/usdcx-yield-optimizer.ts run --amount 1000 --risk low

# Compare against current venue (activates YTG profit gate)
bun run usdcx-yield-optimizer/usdcx-yield-optimizer.ts run --from zest --amount 500

# Aggressive — include sBTC-paired pools
bun run usdcx-yield-optimizer/usdcx-yield-optimizer.ts run --risk high --amount 2000

# Execute — generate MCP commands to deploy USDCx
bun run usdcx-yield-optimizer/usdcx-yield-optimizer.ts run --amount 1000 --confirm

# Full pipeline — compare, gate, and deploy
bun run usdcx-yield-optimizer/usdcx-yield-optimizer.ts run --from zest --amount 500 --confirm

---

Output contract

All outputs are strict JSON to stdout.

position output

{
  "status": "ok",
  "wallet": "SP219TWC8G12CSX5AB093127NC82KYQWEH8ADD1AY",
  "positions": [
    {
      "pool_id": "dlmm_3",
      "pool_contract": "SM1FKXGNZJWSTWDWXQZJNF7B5TV5ZB235JTCXYXKD.dlmm-pool-stx-usdcx-v-1-bps-10",
      "pair": "STX/USDCx",
      "active_bin_id": -221,
      "user_bins": [
        { "bin_id": -220, "balance": "500000000", "balance_human": 500.0 }
      ],
      "overall_balance": 500.0,
      "in_range": true,
      "bins_from_active": 1
    }
  ],
  "total_pools": 3,
  "active_pools": 1,
  "sources_used": ["on-chain:dlmm-pool-stx-usdcx-v-1-bps-10"],
  "sources_failed": [],
  "timestamp": "2026-03-31T14:18:31.219Z"
}

run output

{
  "status": "ok",
  "decision": "DEPLOY",
  "direct_venues": [
    {
      "rank": 1,
      "protocol": "hodlmm",
      "pool_id": "dlmm_7",
      "pair": "aeUSDC/USDCx",
      "apr_pct": 4.2,
      "tvl_usd": 320000,
      "risk": "low",
      "risk_factors": []
    },
    {
      "rank": 2,
      "protocol": "hodlmm",
      "pool_id": "dlmm_5",
      "pair": "STX/USDCx",
      "apr_pct": 6.8,
      "tvl_usd": 180000,
      "risk": "medium",
      "risk_factors": ["STX volatility — impermanent loss risk"]
    }
  ],
  "suggested_routes": [
    {
      "destination": "Hermetica sUSDh vault",
      "estimated_apy_pct": 25.0,
      "swap_path": "USDCx -> sBTC (Bitflow) -> stake USDh -> sUSDh",
      "swap_cost_pct": 0.3,
      "net_apy_pct": 24.7,
      "risk": "medium",
      "note": "Requires sBTC exposure. Use hermetica-yield-rotator skill to execute."
    }
  ],
  "risk_assessment": {
    "sbtc_reserve_signal": "GREEN",
    "sbtc_price_deviation_pct": 0.12,
    "flagged_pools": []
  },
  "profit_gate": null,
  "mcp_commands": [
    {
      "step": 1,
      "tool": "call_contract",
      "description": "Deploy 1000 USDCx to HODLMM dlmm_7 (aeUSDC/USDCx) at bin offset +1 from active bin",
      "params": {
        "contractAddress": "SM1FKXGNZJWSTWDWXQZJNF7B5TV5ZB235JTCXYXKD",
        "contractName": "dlmm-liquidity-router-v-1-2",
        "functionName": "add-liquidity-multi",
        "note": "SPEC ONLY — requires trait_reference support in call_contract MCP tool"
      }
    }
  ],
  "action": "DEPLOY — 1000 USDCx to hodlmm dlmm_7 (aeUSDC/USDCx). 4.2% APR, $320k TVL, low risk. [EXECUTABLE — 1 MCP command(s) ready]",
  "sources_used": ["bitflow-prices", "sbtc-reserve-signal", "bitflow-hodlmm", "bitflow-xyk", "hermetica"],
  "sources_failed": [],
  "timestamp": "2026-03-31T12:00:00.000Z"
}

---

HODLMM Integration

USDCx is the quote currency in 7 active HODLMM pools:

Pool	Pair	Fee	Type
dlmm_1	sBTC/USDCx	15+15 bps	Volatile
dlmm_2	sBTC/USDCx	15+15 bps	Volatile
dlmm_3	STX/USDCx	15+15 bps	Volatile
dlmm_4	STX/USDCx	15+15 bps	Volatile
dlmm_5	STX/USDCx	15+15 bps	Volatile
dlmm_7	aeUSDC/USDCx	3+3 bps	Stablecoin
dlmm_8	USDh/USDCx	3+3 bps	Stablecoin

The skill fetches live APR and TVL for each from the Bitflow App API and ranks them by risk-adjusted return.

---

Data sources

Source	Data	Endpoint
Bitflow App API	HODLMM pool APR, TVL, volume, token USD/BTC prices	bff.bitflowapis.finance/api/app/v1/pools
Bitflow Ticker API	XYK pool data, volume for APR computation	bitflow-sdk-api-gateway-*.uc.gateway.dev/ticker
Hiro Fee Rate	Stacks network gas estimate	api.mainnet.hiro.so/v2/fees/transfer
Hermetica Staking	sUSDh exchange rate for APY estimation	api.mainnet.hiro.so/v2/contracts/call-read/.../staking-v1
HODLMM Pool Contracts (on-chain)	Active bin, user bins, balances, overall position	api.mainnet.hiro.so/v2/contracts/call-read/SM1FKX.../dlmm-pool-*

---

Write Capability Status

This skill generates complete call_contract MCP command specs for add-liquidity-multi on the Bitflow HODLMM liquidity router (SM1FKXGNZJWSTWDWXQZJNF7B5TV5ZB235JTCXYXKD.dlmm-liquidity-router-v-1-2). The command spec includes the exact contract address, function name, bin position, token amounts, pool trait, and token traits — everything needed to execute.

Current limitation: The AIBTC MCP call_contract tool does not support trait_reference arguments, which the HODLMM liquidity router requires for pool-trait, x-token-trait, and y-token-trait parameters. This means the generated commands cannot be executed directly via call_contract today.

What works now:

• Skill outputs a complete deployment spec with all contract-level parameters
• An agent framework with native Clarity trait support can execute the spec as-is
• The Bitflow SDK add-liquidity-simple CLI command handles trait encoding internally — agents with access to the Bitflow skill can use the spec to construct the equivalent call

What would fix this:

1. Add trait_reference type support to the MCP call_contract tool — this is a one-line type addition in the Clarity argument encoder
2. Alternatively, add a dedicated bitflow_hodlmm_add_liquidity MCP tool (similar to the existing bitflow_swap pattern) that handles trait encoding internally

The skill is architected for write capability — the deployment cap (MAX_DEPLOY_USDCX = 5000), --confirm gate, active bin fetching, and MCP command generation are all in code and tested. Once the platform adds trait_reference support, the skill becomes fully autonomous with zero code changes.

---

Composability

This skill is designed to compose with the broader bff-skills ecosystem:

• sbtc-proof-of-reserve — For full L1 trustless reserve verification (this skill uses a price-deviation proxy for speed). Pair for high-value decisions.
• hermetica-yield-rotator — Execute the suggested route (USDCx -> sBTC -> Hermetica vault) when this skill recommends it.
• hodlmm-bin-guardian — Monitor active bin position after deploying USDCx to a HODLMM pool.

---

Known constraints

• Hermetica APY is estimated from the sUSDh exchange rate growth over time. The estimate improves as the rate baseline ages.
• sBTC reserve signal is a price-deviation proxy (not a full on-chain audit). For high-value decisions, pair with sbtc-proof-of-reserve for L1 verification.
• HODLMM APR is based on the last 24 hours of trading volume. Actual returns depend on whether your bins stay in the active range.