Aave Liquidation Monitor

Quick Start

Configure your wallet and thresholds once, then the skill runs automatically every 6 hours (configurable).

Step 1: Initialize Your Config

Run /aave-config init to set up:

• Your Ethereum wallet address (read-only; no private keys required)
• Health factor thresholds (default: critical 1.05, warning 1.2, stable >1.5)
• Check interval in hours (default: 6)
• Notification verbosity (verbose = daily summaries even if stable; quiet = only alerts)
• Preferred notification channel (Telegram default, or specify Discord/Slack)

/aave-config init
→ Wallet: 0x1234...5678
→ Thresholds: 1.05 (critical), 1.2 (warning)
→ Interval: 6 hours
→ Verbosity: quiet (alerts only)
→ Channel: telegram

Step 2: Test the Monitor

Run /aave-monitor check to fetch your position immediately and see the alert format:

/aave-monitor check
→ Fetching position for 0x1234...5678 on Ethereum...
→ Health Factor: 2.31 (Stable ✓)
→ Total Collateral: $50,342.12
→ Total Debt: $21,804.00
→ Borrowed Assets: USDC (15,000), WETH (0.5), USDT (6,804)
→ Supplied Assets: WETH (10), USDC (20,000), DAI (30,000)

Step 3: Enable Proactive Monitoring

Run /aave-monitor enable to start automatic checks every 6 hours. The skill registers a cron job that silently runs in the background and alerts you only when health factor drops below threshold.

For manual override:

/aave-monitor enable --interval 4   # Check every 4 hours
/aave-monitor disable               # Stop monitoring
/aave-monitor status                # See current config + last check result

Configuration Reference

See references/config-guide.md for detailed config options, chain support, and threshold guidance.

See references/aave-api.md for Aave V3 GraphQL schema and query patterns.

Security & Credentials: See SECURITY.md for how credentials are handled and threat model.

For auditors: See SECURITY.md for code review checklist and architecture details.

How It Works

• Query Phase: Calls Aave V3 GraphQL API with your wallet address
• Analysis Phase: Extracts health factor, collateral, debt, borrowed/supplied assets
• Alert Logic:
• If HF < 1.05 → CRITICAL (red alert, send immediately)
• If HF < 1.2 → WARNING (yellow alert, send immediately)
• If HF > 1.5 → STABLE (no alert, unless verbose mode enables daily summary)
• Notification Phase: Posts alert to your configured channel with clear summary
• Retry Logic: If API fails, retries up to 3 times with exponential backoff

Error Handling

• Invalid wallet address → Logs error, skips check, retries next interval
• API timeout → Retries up to 3x with exponential backoff (2s, 4s, 8s)
• Malformed response → Alerts you to API changes, logs full response for debugging
• Network errors → Silently retries; alerts only if all retries fail

Security & Credentials

NO private keys are requested or stored — this is read-only monitoring only.

How messaging credentials work

The skill uses OpenClaw's built-in message routing — it does NOT store Telegram, Discord, or Slack tokens.

• You configure your messaging channel in OpenClaw (outside this skill)
• The skill calls OpenClaw's messaging API with just the alert text
• OpenClaw routes the message using your configured channels

/aave-config set channel telegram
→ OpenClaw sends alerts via your pre-configured Telegram channel

You must have a messaging channel already set up in OpenClaw. See OpenClaw docs for setting up Telegram/Discord/Slack integrations.

Data handling

• Wallet address: Stored in OpenClaw's encrypted config (never sent to external services except Aave's public API)
• API responses: Parsed for health factor only; sensitive position data is NOT logged
• Credentials: Managed by OpenClaw, never stored in skill files

What the skill accesses

✅ Aave GraphQL API (public) — reads your position data ✅ OpenClaw message routing — sends formatted alerts to your configured channel ✅ Cron scheduler — runs background checks on your interval

❌ Does NOT:

• Request private keys
• Store API tokens
• Execute transactions
• Modify your positions

Examples

Alert Examples

Critical Alert (HF < 1.05):

🚨 AAVE LIQUIDATION RISK – CRITICAL
Health Factor: 1.02 (Liquidation threshold: 1.0)
⏰ Action required immediately!

📊 Position Summary:
Total Collateral: $50,000
Total Debt: $48,000
Debt Ratio: 96%

Borrowed (at risk):
- USDC: 40,000
- WETH: 8 ETH (~$31k)

Suggested Actions:
1. Repay debt (especially WETH)
2. Supply more collateral
3. Enable eMode if available (higher LTV on correlated assets)

Last checked: 2026-02-11 08:15 UTC

Warning Alert (HF < 1.2):

⚠️ AAVE WARNING
Health Factor: 1.15 (Approaching 1.2 threshold)

Position approaching liquidation. Consider:
- Repaying $2,000 USDC or
- Adding $5,000 collateral (WETH or stETH)

Stable Position (HF > 1.5, verbose mode only):

✅ AAVE POSITION HEALTHY
Health Factor: 2.31
Total Collateral: $50,342.12
Total Debt: $21,804.00

All clear. Check again tomorrow.

Command Examples

# One-time position check
/aave-monitor check

# Start automatic monitoring
/aave-monitor enable

# Change thresholds (e.g., earlier warning at HF 1.3)
/aave-config set thresholds 1.05 1.3

# Check monitoring status
/aave-monitor status

# View last 5 check results with alerts
/aave-monitor history 5

# Disable monitoring temporarily
/aave-monitor disable

Chains Supported

Primary: Ethereum mainnet

Also works (with same config address where applicable):

• Polygon
• Arbitrum
• Optimism
• Base
• Avalanche
• Gnosis

Customization

Change check interval:

/aave-config set interval 4  # Check every 4 hours

Change alert thresholds:

/aave-config set thresholds 1.1 1.25  # Critical at 1.1, warning at 1.25

Enable verbose mode (daily summaries even if stable):

/aave-config set verbosity verbose

Switch notification channel:

/aave-config set channel discord

Implementation Details

See scripts/monitor.js for the core monitoring logic (GraphQL queries, health factor calculation, alert formatting).

See scripts/cron-runner.js for cron job integration with OpenClaw's cron scheduler.

Troubleshooting

"Invalid wallet address" → Check format: must be 0x... format. Try /aave-config view to see current config.

"Health factor not returned by API" → Wallet may not have Aave position. Try /aave-monitor check for immediate response.

"API endpoint unreachable" → Aave API may be down. Skill retries automatically. Check https://status.aave.com.

"No notifications sent" → Check that your notification channel is active. Run /aave-monitor check to test delivery.

Notes

• Health factor = Total Collateral / Total Debt (net of liquidation threshold ratios)
• Liquidation occurs when HF ≤ 1.0
• Variable debt accrues interest; stable debt is fixed-rate
• eMode allows higher LTV for correlated assets (e.g., stablecoins, ETH-LSTs)
• Supplied assets are collateral; they earn interest but can be seized if you're liquidated

Last Updated: 2026-02-11 | Status: Ready for configuration