Learn-skills.dev zest-auto-repay

What it does

Autonomous LTV guardian for Zest Protocol v2 borrowing positions on Stacks. Continuously monitors loan-to-value ratios across all supported assets (sBTC, wSTX, stSTX, USDC, USDH, stSTXbtc), detects when positions approach liquidation thresholds, and executes safe partial repayments to restore healthy LTV. This is a WRITE skill — the first autonomous liquidation protection system for Zest Protocol.

Why agents need it

Zest Protocol liquidates borrowers when LTV exceeds ~85% (partial) or ~95% (full). Liquidation penalties destroy collateral value. Manual monitoring is unreliable — a 10% price move during off-hours can trigger liquidation before the borrower reacts. This skill gives agents the ability to:

1. Detect risk — continuously monitor LTV across all Zest positions
2. Classify urgency — score positions as healthy, warning, critical, or emergency
3. Compute safe repayments — calculate minimum repayment to restore target LTV
4. Execute protection — repay debt automatically with enforced spend caps
5. Preserve reserves — never repay below minimum wallet reserve threshold

Without this, leveraged Zest positions are exposed to unmonitored liquidation risk 24/7.

Zest Protocol integration

Direct integration with Zest Protocol v2 on Stacks mainnet:

• Reads position data from

  SP1A27KFY4XERQCCRCARCYD1CC5N7M6688BSYADJ7.v0-4-market

• Monitors all 6 supported assets: sBTC, wSTX, stSTX, USDC, USDH, stSTXbtc
• Executes repayments via

  zest_repay

  MCP tool
• Fetches live interest rates from on-chain vault contracts
• Supports both self-repay and on-behalf-of repayment

Commands

doctor

Check environment readiness: wallet, balances, Zest API connectivity, active positions, current LTV.

bun run zest-auto-repay/zest-auto-repay.ts doctor

run --action=status

Full position analysis with LTV scoring, liquidation distance, and risk classification.

bun run zest-auto-repay/zest-auto-repay.ts run --action=status

run --action=monitor

Continuous monitoring mode. Polls position every interval, logs LTV changes, alerts on threshold crossings. Read-only — does not execute repayments.

bun run zest-auto-repay/zest-auto-repay.ts run --action=monitor --interval=300

run --action=repay

Compute and execute a safe repayment to restore target LTV. Enforces all safety limits.

bun run zest-auto-repay/zest-auto-repay.ts run --action=repay --asset=sBTC --target-ltv=60 --max-repay=50000

run --action=emergency-repay

Immediate maximum repayment when LTV is critical (>85%). Skips drift checks, uses higher spend cap, prioritizes speed.

bun run zest-auto-repay/zest-auto-repay.ts run --action=emergency-repay --asset=sBTC

Safety notes

All limits are implemented and enforced in the TypeScript file, not just documented:

--max-repay

--target-ltv

Output contract

All commands output structured JSON:

{
  "status": "success | error | blocked",
  "action": "Human-readable next step",
  "data": { },
  "error": { "code": "...", "message": "...", "next": "..." } | null
}

Error codes

no_wallet

insufficient_balance

no_position

healthy_ltv

exceeds_hard_cap

exceeds_daily_cap

cooldown_active

api_unreachable

repay_failed

On-chain proof

SP322ZK4VXT3KGDT9YQANN9R28SCT02MZ97Y24BRW

bc1qdfm56pmmq40me84aau2fts3725ghzqlwf6ys7p

Architecture

Agent invokes skill
  -> doctor: pre-flight checks (wallet, gas, API, position, LTV)
  -> status: fetch all Zest positions -> LTV scoring -> risk classification
  -> monitor: continuous polling -> LTV tracking -> alert on threshold crossing
  -> repay: pre-flight -> LTV check -> compute safe amount -> enforce caps -> emit repay tx
  -> emergency-repay: minimal checks -> max safe repayment -> immediate execution

The skill does NOT broadcast transactions directly. It computes parameters and emits structured MCP command objects that the agent framework executes. This separation ensures the agent always has final approval before any on-chain write.

Known constraints

• Zest Protocol v2 mainnet only — no testnet support
• Repayment amount is denominated in the borrowed asset's smallest unit
• zToken shares appreciate over time — withdrawal amounts may differ from supply amounts
• Interest accrues continuously — LTV can increase between checks
• Liquidation can occur between monitoring intervals during extreme volatility
• Requires STX for transaction fees (separate from repayment amount)
• On-behalf-of repayment requires the borrower's address