DefiLlama Watchdog

# DeFiLlama Protocol Watchdog (DeFi Guardian) [](https://github.com/Neros0/defillama-watchdog/actions) [](LICENSE) [](https://www.python.org/downloads/) [](https://skills.sh) [](https://defillama.com) [](https://github.com/Neros0/defillama-watchdog/stargazers) Proactively monitor DeFi protocols and get alerted when TVL drops beyond your threshold. No dashboards to refresh—your agent (OpenClaw, Claude Code, Cursor, etc.) runs the check on a schedule and pushes alerts to you over Telegram, WhatsApp, or your preferred channel. **Use case:** "Alert me if any of my watched protocols lose more than 10% TVL in one check." The watchdog runs in the background and only speaks when your money might be at risk. **Out of the box:** The repo ships with a default `config.json` (watch list: Aave V3, Uniswap V3, Lido; 10% threshold). Install with OpenClaw below; optionally add `assets/portfolio.json` for hacks/unlocks matching and `.env` with `DEFILLAMA_PRO_API_KEY` for Pro features (inflows, unlocks). ### Install with OpenClaw (recommended) ```bash npx skills add Neros0/defillama-watchdog ``` Then configure your watch list and Telegram—see [Preparing for OpenClaw](#preparing-for-openclaw-before-you-install) and [openclaw/README.md](openclaw/README.md). We recommend using this skill with OpenClaw so you get scheduled checks, risk chaining, and alerts to Telegram/WhatsApp without extra setup. ### How this fits with [DefiLlama's tools](https://defillama.com/tools) DefiLlama's tools (Sheets, LlamaSwap, Borrow Aggregators, Yields, etc.) are **pull**: you open the site and look. This skill is **push**: an agent runs on your machine, watches the same data on a schedule, and alerts you (e.g. Telegram/WhatsApp) only when something crosses your threshold. It doesn't replace their tools—it's the **notification and automation layer** that uses DefiLlama as the data source. The more tools they add, the more valuable an agent that monitors and summarizes them becomes. **[LlamaAI](https://defillama.com/ai)** (DefiLlama's paid conversational AI) is great for research: "Show me top protocols with growing TVL," deep reports, charts. It's **pull** and **reactive**. This skill is **free**, **local**, and **proactive**: it doesn't wait for you to ask—it runs on a heartbeat and notifies you when your watched protocols cross your risk threshold. LlamaAI helps you find alpha; this skill helps you **guard what you already have**. ### Why DefiLlama instead of "just listening to the chain?" People sometimes ask: why not index the blockchain directly for real-time TVL? The trade-off is **operational simplicity and cost** vs **raw latency**. - **Complexity (multichain).** To "listen" to Aave you need custom indexing per chain: Ethereum, Arbitrum, Base, Polygon, Avalanche, etc.—different block times, RPC quirks, event ABIs. DefiLlama is a **standardized layer**: one API, one JSON shape, all chains. You trade a few minutes of delay for orders of magnitude less engineering. - **Data quality.** Raw chain data is noisy: flash loans look like deposits; LP tokens and underlying assets can double-count. DefiLlama's adapters are battle-tested and open-source; they define what actually counts as TVL. You inherit that logic instead of reimplementing it. - **Cost.** Reliable, low-latency chain listening usually means paid RPC (Alchemy, QuickNode, etc.), often $50–500/month. This skill **costs nothing**: it hits a public API every few minutes and runs on a laptop or a $5 VPS. | | Direct on-chain indexing | This watchdog (DefiLlama API) | | ----------- | ------------------------ | --------------------------------- | | Setup | Days/weeks per protocol | Minutes (add a slug to config) | | Cost | Paid RPC typical | Free | | Scalability | More chains = more infra | Add slugs, same infra | | Latency | Near real-time | ~5–15 min after DefiLlama updates | This project is not a high-frequency bot; it's a **proactive insurance policy**. If TVL drops 20% over 10 minutes, you still have time to react. The goal is to turn "check dashboards and hacks manually" into "get one notification when it matters." ## What’s in this repo | Path | Purpose | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SKILL.md` | Skill definition for agents: when to use, how to run, how to interpret output | | `config.json` | Watch list, threshold, `chains`, `capital_flow`, `bridge`, `metrics_guard`, `true_growth`, `unlocks_monitor`, `revenue_guard`, `pro` | | `.env.example` | Template for env vars (copy to `.env` and add `DEFILLAMA_PRO_API_KEY`); `.env` is gitignored | | `requirements.txt` | Dependencies (stdlib-only by default; optional pandas/requests noted) | | `scripts/setup.sh` | Environment setup: creates `assets/`, checks Python, optional venv | | `scripts/init_skill.py` | First-run: ensures `assets/`, prompts for portfolio or scans for `portfolio.json`, dry-run DefiLlama API | | `scripts/watchdog.py` | TVL watchdog: compares protocol TVL to last run, prints ALERT or HEARTBEAT_OK; supports `--json` | | `scripts/capital_flow.py` | Capital flow: rotation radar + stablecoin sentiment; supports `--json` | | `scripts/bridge_monitor.py` | Bridge surge: 24h volume vs 7-day average per chain; BRIDGE_SURGE when spike; supports `--json` | | `scripts/metrics_guard.py` | Yield & Risk: portfolio vs DefiLlama Recent Hacks; EMERGENCY if match; supports `--json` | | `scripts/true_growth.py` | Smart Money: BULLISH_DIVERGENCE when TVL down but USD inflows positive; may need Pro key; supports `--json` | | `scripts/unlocks_monitor.py` | Dump Watch: DUMP_RISK when portfolio protocol has unlock >1% supply in 72h; may need Pro key; supports `--json` | | `scripts/revenue_guard.py` | Sustainability: VALUE when fees