# BaseSentinel — AI DeFi Risk Monitor for Base L2

> Unlike generic DeFi monitors, BaseSentinel uses MCP tool protocol for AI
> agent-native integration and focuses exclusively on Base L2 ecosystem
> protocols with real-time on-chain risk scoring.

**Live demo:** https://base-sentinel-agent.vercel.app
**Repo:** https://github.com/0xConsole/base-sentinel-agent

Built for the **Orion Agents Builder Hackathon** — an AI agent for the Base
ecosystem that monitors DeFi protocol risk in real time.

---

## What it does

BaseSentinel continuously evaluates the health of Base-native protocols
(Aerodrome, Moonwell, Seamless, Baseline, Aave V3) using statistical
anomaly detection. Every monitoring capability is exposed as an **MCP
(Model Context Protocol) tool**, so an AI agent can integrate and call them
natively — the agent gets a risk report, detects anomalies, and raises
alerts without a human in the loop.

### Statistical anomaly detection

| Detector | Threshold | What it catches |
|----------|-----------|-----------------|
| Z-score | > 3σ | TVL / volume far from rolling mean |
| Velocity | > 15% | Single-step rate-of-change spike |
| Liquidity drain | > 3σ on returns | Coordinated withdrawal pattern |
| TVL risk score | 0-100 composite | Weighted liquidity + volume + reserve risk |

### MCP Tool Registry

| Tool | Description |
|------|-------------|
| `check_pool_health` | TVL, volume, reserve, 0-100 risk score, status |
| `detect_anomalies` | z-score, velocity, liquidity drain across protocols |
| `generate_risk_report` | Per-protocol + ecosystem-wide risk report |
| `monitor_base_protocol` | Block-level monitoring with health deltas |
| `alert_on_threshold` | Threshold-driven alert generation |

## API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | GET | Dark-themed dashboard |
| `/api/health` | GET | Service + Base RPC status |
| `/api/agent/status` | GET | Agent config + MCP tool inventory |
| `/api/demo` | GET/POST | Full monitoring cycle (the demo flow) |
| `/api/tools/check_pool_health` | GET | MCP tool: check pool health |
| `/api/tools/detect_anomalies` | GET | MCP tool: detect anomalies |
| `/api/tools/generate_risk_report` | GET | MCP tool: risk report |
| `/api/tools/monitor_base_protocol` | GET | MCP tool: monitor protocol |
| `/api/tools/alert_on_threshold` | GET | MCP tool: alert evaluation |
| `/api/mcp/tools` | GET | MCP tools/list (JSON Schema) |
| `/api/mcp/call` | POST | MCP tools/call (`{name, arguments}`) |

## Quick start (local)

```bash
git clone https://github.com/0xConsole/base-sentinel-agent.git
cd base-sentinel-agent
pip install -r requirements.txt
uvicorn app.main:app --reload
# open http://localhost:8000
```

## Demo flow

Click **"Run Monitoring Cycle"** on the dashboard, or call the endpoint:

```bash
curl https://base-sentinel-agent.vercel.app/api/demo | jq .summary
```

This runs the full autonomous pipeline:
`monitor_base_protocol → detect_anomalies → generate_risk_report → alert_on_threshold`
and returns the ecosystem risk score, anomaly count, and active alerts.

### Call an MCP tool (agent-native)

```bash
# List tools (MCP tools/list)
curl https://base-sentinel-agent.vercel.app/api/mcp/tools | jq .

# Call a tool (MCP tools/call)
curl -X POST https://base-sentinel-agent.vercel.app/api/mcp/call \
  -H 'Content-Type: application/json' \
  -d '{"name":"detect_anomalies","arguments":{"protocol_name":"all"}}' | jq .
```

## Architecture

```
┌─────────────────────────────────────────────────┐
│  Dashboard (static/index.html — dark theme)      │
│  Real-time fetch · 30s auto-refresh · risk gauge │
└────────────────────┬────────────────────────────┘
                     │ fetch /api/*
┌────────────────────▼────────────────────────────┐
│  FastAPI app (app/main.py)                        │
│  Routes: /, /api/health, /api/demo, /api/agent/*  │
│         /api/tools/*, /api/mcp/*                  │
└────────────────────┬────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────┐
│  Agent (app/agent.py) — MCP Tool Registry         │
│  • check_pool_health   • monitor_base_protocol    │
│  • detect_anomalies    • alert_on_threshold       │
│  • generate_risk_report                           │
│  Statistical: z-score >3σ, velocity >15%, drain   │
└────────────────────┬────────────────────────────┘
                     │ eth_blockNumber RPC
┌────────────────────▼────────────────────────────┐
│  Base L2 RPC (mainnet.base.org → sepolia → mock) │
│  Protocols: Aerodrome, Moonwell, Seamless,       │
│             Baseline, Aave V3                     │
└──────────────────────────────────────────────────┘
```

## Tech stack

- **Backend:** FastAPI + Pydantic (Python)
- **Chain data:** Base L2 public RPC (free), deterministic mock fallback
- **Frontend:** Single-file dark dashboard (vanilla HTML/CSS/JS)
- **Deploy:** Vercel serverless free tier (`@vercel/python` + `@vercel/static`)
- **MCP:** JSON Schema tool definitions, `/api/mcp/tools` + `/api/mcp/call`

## What's real vs mocked

| Component | Status |
|-----------|--------|
| FastAPI backend + 5 MCP tools | **Real** — fully implemented |
| Statistical anomaly detection | **Real** — z-score, velocity, drain |
| Base L2 RPC integration | **Real** — probes mainnet.base.org; falls back to mock telemetry if RPC unreachable |
| Protocol TVL series | Mock when RPC offline (deterministic, preserves statistical signal shape) — real contract addresses used as identity anchors |
| Dashboard + risk gauge | **Real** — live fetch + auto-refresh |
| Vercel deploy | **Real** — base-sentinel-agent.vercel.app |

## Orion Agents Builder Hackathon

- **Hackathon:** orionagents.org/hackathon
- **Track:** AI agent on Base ecosystem
- **Prize:** $5K, 7 winners, Sep 2 deadline
- **Repo:** github.com/0xConsole/base-sentinel-agent
- **Live:** base-sentinel-agent.vercel.app

## License

MIT