aibtcdev 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:
- Detect risk — continuously monitor LTV across all Zest positions
- Classify urgency — score positions as healthy, warning, critical, or emergency
- Compute safe repayments — calculate minimum repayment to restore target LTV
- Execute protection — repay debt automatically with enforced spend caps
- 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_repayMCP 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:
| Control | Default | Enforced |
|---|---|---|
| Max repay per operation | 50,000 sats (0.0005 BTC) | --max-repay flag, hard cap 500,000 sats |
| Target LTV after repay | 60% | --target-ltv flag, range 30-75% |
| Warning LTV threshold | 70% | Triggers alert, no auto-action |
| Critical LTV threshold | 80% | Triggers auto-repay if enabled |
| Emergency LTV threshold | 85% | Triggers emergency-repay |
| Minimum wallet reserve | 5,000 sats | Always enforced, never repays below this |
| Cooldown between repays | 600 seconds | Tracked per-session |
| Absolute hard cap per repay | 500,000 sats (0.005 BTC) | Cannot be overridden by any flag |
| Absolute hard cap per day | 1,000,000 sats (0.01 BTC) | Cannot be overridden by any flag |
Output contract
All commands output structured JSON:
{
"status": "success | error | blocked",
"action": "Human-readable next step",
"data": { },
"error": { "code": "...", "message": "...", "next": "..." } | null
}
Error codes
| Code | Meaning |
|---|---|
no_wallet |
Wallet not unlocked or STACKS_ADDRESS not set |
insufficient_balance |
Not enough tokens to repay (after reserve) |
no_position |
No active Zest borrowing position found |
healthy_ltv |
LTV is below warning threshold — no action needed |
exceeds_hard_cap |
Requested repayment exceeds absolute safety cap |
exceeds_daily_cap |
Daily repayment limit already reached |
cooldown_active |
Must wait before next repayment operation |
api_unreachable |
Zest Protocol API not responding |
repay_failed |
On-chain repayment transaction failed |
On-chain proof
| Evidence | Detail |
|---|---|
| Wallet | SP322ZK4VXT3KGDT9YQANN9R28SCT02MZ97Y24BRW |
| BTC Address | bc1qdfm56pmmq40me84aau2fts3725ghzqlwf6ys7p |
| sBTC Balance | 28,306 sats active on Zest-eligible wallet |
| DLMM NFTs | 387 NFTs across Bitflow pools (cross-protocol DeFi activity) |
| Stableswap LP | 771M tokens in USDH-USDCx pool |
| Agent | Flying Whale — Genesis L2, ERC-8004 #54 on aibtc.com |
| Explorer | View on Hiro |
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