🛰️ DeFi Sentinel X

Autonomous AI Agent for X Layer DeFi Protocol Monitoring

An autonomous AI agent that monitors X Layer (OKX's EVM-compatible L2, chainId 196) DeFi protocols in real-time — detecting price manipulation, liquidity drains, and unusual trading activity, then generating severity-classified alerts with on-chain risk scores.

Built for the OKX BuildX AI Season Hackathon ($300K prize pool).

🎯 Problem

DeFi protocols on X Layer are vulnerable to attacks that execute in seconds:

• Price manipulation via sandwich attacks and oracle manipulation

• Liquidity drains from pool imbalances and rug pulls

• Unusual trading from MEV bots and exploit frontrunning

Users have no real-time early warning system. By the time a human notices a pool's reserves dropping, the damage is done. Existing monitoring tools are either centralized alerts (slow) or static dashboards (passive).

Related MCP server: BlueAgent x402 Services

💡 Solution

DeFi Sentinel X is an autonomous AI agent that:

1. Continuously scans X Layer DeFi pools via real on-chain RPC calls

2. Detects anomalies using statistical heuristics (reserve imbalance, liquidity drain, unusual activity)

3. Computes risk scores (0-100 composite score) factoring anomaly severity, confidence, and type diversity

4. Generates alerts with severity classification and recommended actions

5. Checks position health for Aave V3 lending positions (health factor, liquidation distance)

The agent uses an MCP-style tool architecture — each capability is a discrete tool with a JSON Schema input definition, orchestrated by an agent layer that chains: scan_pool → detect_anomaly → calculate_risk_score → generate_alert.

🌟 Unique Angle

Unlike passive monitoring dashboards, DeFi Sentinel X is an active AI agent that:

• Uses real X Layer RPC (live block numbers, gas prices, eth_call against pool contracts)

• Follows the MCP (Model Context Protocol) tool pattern — 7 tools, each with name, description, and JSON Schema input, callable individually or orchestrated by the agent

• Runs fully on free-tier infrastructure (Vercel serverless + SQLite /tmp + public RPCs)

• Provides deterministic, reproducible agent orchestration (no LLM API key needed for the demo — the tool-chaining logic is the AI layer)

• Deploys as a Vercel serverless function — no servers, no cost, scales to zero

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│                 DeFi Sentinel X Agent                │
│          (Autonomous Tool Orchestrator)              │
│                                                      │
│  scan_pool → detect_anomaly → risk_score → alert    │
│                                                      │
│  Additional: get_position_health, get_chain_status  │
│             get_audit_trail                          │
└──────────────┬──────────────────────┬────────────────┘
               │                      │
       ┌───────▼───────┐    ┌────────▼────────┐
       │  X Layer RPC  │    │  SQLite (/tmp)  │
       │  (real data)  │    │  (audit trail)  │
       │               │    │                 │
       │ eth_chainId   │    │ scans table     │
       │ eth_blockNum  │    │ anomalies tbl   │
       │ eth_call      │    │ alerts table    │
       │ eth_getBalance│    │ risk_assess tbl │
       └───────────────┘    └─────────────────┘
               │
       ┌───────▼───────┐
       │   Vercel      │
       │  Serverless   │
       │  (@vercel/py) │
       └───────────────┘

MCP Tool Architecture (7 Tools)

All tools are also exposed via MCP protocol endpoints:

• GET /mcp/tools — MCP tools/list

• POST /mcp/call — MCP tools/call (body: {"name": "...", "arguments": {...}})

🛠️ Tech Stack

✅ What's Real vs ⚠️ Mocked

✅ Real (Live On-Chain)

• X Layer RPC calls — eth_chainId, eth_blockNumber, eth_gasPrice return live data (chainId 196, current block ~67M)

• eth_call against pool contracts — getReserves(), totalSupply() selectors sent to real X Layer contracts

• eth_getBalance — real native balance reads for wallet health checks

• SQLite persistence — scans, anomalies, alerts, and risk assessments stored in /tmp/defi_sentinel_x.db (survives across warm serverless invocations)

• Anomaly detection heuristics — reserve imbalance, liquidity drain, zero liquidity, unusual activity detection run on real pool data

• Composite risk scoring — 0-100 score with severity classification (CRITICAL/HIGH/MODERATE/LOW/MINIMAL)

• Agent orchestration — tool-chaining logic: scan → detect → score → alert (the AI layer)

⚠️ Mocked / Simulated

• Pool reserve values — if eth_call returns zeros (demo pool addresses aren't real Uniswap pairs on X Layer), falls back to deterministic simulation based on pool name + block number (reproducible, varies as blocks advance)

• Aave V3 health factor — derived from address hash (real Aave integration requires Pool.getUserAccountData() which needs a funded position; the eth_getBalance call IS real)

• Baseline reserve ratios — hardcoded (production would use a time-series DB like TimescaleDB)

• "Unusual activity" heuristic — uses block-number parity as a proxy for tx volume (production would use mempool/trace data)

• No LLM API key — the agent orchestration is deterministic (reproducible in serverless without external API dependencies)

🚀 Quick Start

Local Development

cd defi-sentinel-x
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000
# Open http://localhost:8000

API Endpoints

Deploy to Vercel

vercel --prod --yes --token "$VERCEL_TOKEN"

🔗 Links

• Live Demo: https://defi-sentinel-x.vercel.app

• GitHub: https://github.com/0xConsole/defi-sentinel-x

• X Layer: https://www.okx.com/xlayer

• Hackathon: OKX BuildX AI Season ($300K)

📁 Project Structure

defi-sentinel-x/
├── api/
│   └── index.py              # Vercel entry point
├── app/
│   ├── __init__.py
│   ├── main.py               # FastAPI app + routes
│   ├── tools.py              # MCP tool registry + handlers (7 tools)
│   ├── agent.py              # Agent orchestrator (tool-chaining)
│   ├── xlayer_client.py      # X Layer RPC client (real on-chain reads)
│   └── store.py              # SQLite persistence layer
├── static/
│   └── index.html            # Dark-theme dashboard UI
├── vercel.json               # Vercel config
├── requirements.txt          # Python deps
├── SUBMISSION.md             # Hackathon submission fields
└── README.md                 # This file

📜 License

MIT License — see LICENSE

Built by 0xConsole for the OKX BuildX AI Season Hackathon.