defillama-watchdog

name	defillama-watchdog
description	DeFi protocol monitoring with alerts for TVL drops, capital rotation, hacks, bridge surges, unlocks, and revenue. Runs checks on demand or scheduled.
version	1.0.0
author	defillama-watchdog
license	MIT
tags	["defi","defillama","tvl","alerts","monitoring"]
requires	["network"]
allowed-tools	["Bash(python3 scripts/watchdog.py)","Bash(python3 scripts/capital_flow.py)","Bash(python3 scripts/bridge_monitor.py)","Bash(python3 scripts/metrics_guard.py)","Bash(python3 scripts/true_growth.py)","Bash(python3 scripts/unlocks_monitor.py)","Bash(python3 scripts/revenue_guard.py)","Bash(python3 scripts/full_briefing.py)"]

DeFiLlama Protocol Watchdog

Monitor DeFi protocols for TVL drops, capital rotation, security risks, and market opportunities.

When to Use

• User wants to monitor or track specific protocols (e.g., "watch Aave", "alert me if Uniswap drops")
• User asks for a security audit, risk check, or full briefing
• User wants rotation alerts or sentiment updates (capital flow analysis)
• User wants to check if protocols were hacked (portfolio safety)

Don't use for one-off queries like "what is Aave's TVL?" — answer those directly.

Available Commands

All commands run from the skill root. Add --json for structured output.

Command	Purpose	Output Signals
python3 scripts/watchdog.py	Check TVL drops	ALERT: or HEARTBEAT_OK
python3 scripts/capital_flow.py	Capital rotation & sentiment	ROTATION:, SENTIMENT:, or HEARTBEAT_OK
python3 scripts/bridge_monitor.py	Bridge volume surges	BRIDGE_SURGE: or HEARTBEAT_OK
python3 scripts/metrics_guard.py	Portfolio vs Recent Hacks	EMERGENCY: or HEARTBEAT_OK
python3 scripts/true_growth.py	Smart money (TVL down, inflows up)	BULLISH_DIVERGENCE: or HEARTBEAT_OK
python3 scripts/unlocks_monitor.py	Token unlock risks	DUMP_RISK: or HEARTBEAT_OK
python3 scripts/revenue_guard.py	Revenue/fee growth	VALUE: or HEARTBEAT_OK
python3 scripts/full_briefing.py	Run all checks	All signals combined

How to Respond

When User Requests a Check

1. Run the appropriate script(s)
2. Parse the output signals:
   • HEARTBEAT_OK = All clear
   • ALERT: = TVL dropped beyond threshold
   • EMERGENCY: = Portfolio protocol was hacked
   • ROTATION: = Capital moving between chains
   • SENTIMENT: = Risk-on/risk-off signal
   • BRIDGE_SURGE: = Bridge volume spike (hot chain)
   • BULLISH_DIVERGENCE: = TVL down but inflows up
   • DUMP_RISK: = Large unlock coming
   • VALUE: = Revenue growing faster than price
3. Synthesize results into 2-5 sentences explaining what happened and why it matters

Response Pattern for Alerts

When you detect a risk signal:

1. Lead with the key finding (TVL drop, hack, rotation)
2. Add context from other signals:
   • If ALERT: → run capital_flow.py to check if it's rotation or protocol-specific
   • If portfolio exists → run metrics_guard.py to check hack risk
   • Optionally run other checks for depth (unlocks, inflows, revenue)
3. Give a clear takeaway (what should the user do?)

Example Synthesis

Bad: "ALERT: AAVE V3 TVL dropped by 12.3%. ROTATION: Stablecoin supply on Ethereum shrank 1.5%."

Good: "Aave V3 TVL dropped 12.3% in the last period. This appears linked to broader capital rotation — stablecoin supply on Ethereum is down while Solana is growing. Not protocol-specific risk, but watch for continued outflows."

Common User Requests

"Alert me if [protocol] drops more than X%"

• Ensure config.json has correct watch_list (use DefiLlama slugs) and threshold
• Explain the watchdog runs on schedule and will alert when breached

"Run a security audit" / "Full briefing" / "Risk check"

• Run python3 scripts/full_briefing.py
• Synthesize all output signals into one narrative

"Any capital rotation?" / "Sentiment update?"

• Run python3 scripts/capital_flow.py
• Report ROTATION: and SENTIMENT: signals, or say "no significant moves"

"Were any of my protocols hacked?"

• Run python3 scripts/metrics_guard.py
• Requires assets/portfolio.json (DefiLlama protocol IDs)
• Report EMERGENCY: immediately if found

"Manual check now"

• Run python3 scripts/watchdog.py
• Report results or confirm "all within threshold"

Configuration

File: config.json in skill root

Key settings:

• watch_list: Array of DefiLlama protocol slugs (e.g., ["aave-v3", "uniswap", "lido"])
• threshold: Decimal for alert threshold (e.g., 0.10 = 10% drop)
• risk_level: "high" (5%), "standard" (10%), "low" (15%)
• Feature toggles: capital_flow.enabled, metrics_guard.enabled, bridge.enabled, etc.

Portfolio tracking: Create assets/portfolio.json with DefiLlama protocol IDs for hack/unlock alerts.

Pro features: Some features (inflows, unlocks) need DEFILLAMA_PRO_API_KEY in environment. Most features work without any API key.

Important Notes

• Protocol slugs must match DefiLlama exactly (check defillama.com/protocols)
• Scripts store state in assets/ directory (TVL history, bridge data, etc.)
• All scripts exit 0 and print to stdout — parse the signal lines
• Latency: Alerts arrive after DefiLlama updates (~5-15 min) + next check cycle
• No API key required for: TVL, capital flow, hacks, bridge, revenue
• Pro API key needed for: inflows (true_growth), unlocks (unlocks_monitor)

Output Style

• Keep it concise: 2-5 sentence summaries
• Lead with action: "Aave dropped 12%" not "The system detected..."
• Provide context: Explain if it's rotation, hack risk, or protocol-specific
• Skip if quiet: Don't report HEARTBEAT_OK unless user asked for status
• Handle errors gracefully: If script fails, tell user to run manually