Blockchain Fraud Detector

<div align="center">

An AI-powered blockchain fraud detection system that analyzes Ethereum wallet addresses using machine learning, multi-agent AI, and real-time transaction monitoring.

Features · How It Works · Tech Stack · Setup · Pages

</div>

---

What is this?

This tool analyzes Ethereum wallet addresses and determines whether they are safe, suspicious, or fraudulent using a combination of:

• A trained XGBoost ML model on historical transaction data
• Etherscan API for live on-chain transaction data
• ChainAbuse API for known fraud reports
• Groq / Gemini LLM for AI-powered analysis and explanation
• CrewAI multi-agent system for automated investigation

Enter any Ethereum address and get an instant risk assessment with a color-coded verdict.

---

Risk Levels

| Color | Level | Meaning | |---|---|---| | 🟢 Green | Safe | No suspicious patterns detected | | 🟡 Yellow | Suspicious | Some risk indicators found — proceed with caution | | 🔴 Red | Fraudulent | High confidence fraud — address flagged |

---

Features

🔍 Address Analysis

• Enter any Ethereum wallet address
• Instant risk score with color-coded verdict (green / yellow / red)
• Detailed breakdown of why the address was flagged
• Cross-references ChainAbuse fraud reports database
• AI-generated explanation of the risk factors

📡 Live Monitor

• Automatically fetches new Ethereum transactions every 15 seconds
• Each transaction analyzed in real time
• Flagged addresses highlighted immediately
• No manual input needed — fully automated

📜 History

• Every manual search is saved automatically
• Browse past analyses with their verdicts
• Search and filter previous results

🤖 AI Agent (experimental)

• Multi-agent investigation using CrewAI
• Agents collaborate to investigate suspicious addresses
• LangChain + Groq/Gemini powered reasoning

🧠 AI Training (experimental)

• Interface for retraining the ML model
• Upload new labeled transaction data
• Batch feature extraction pipeline

---

How It Works

User enters Ethereum address
        ↓
Fetch transaction history from Etherscan + Alchemy
        ↓
Extract features (tx count, avg value, unique senders, etc.)
        ↓
XGBoost ML model → risk score
        ↓
Cross-check ChainAbuse fraud reports
        ↓
LLM (Groq/Gemini) generates human-readable explanation
        ↓
Color-coded verdict returned to user

---

Tech Stack

| Layer | Technology | |---|---| | Backend | Python + FastAPI | | ML Model | XGBoost + scikit-learn | | AI / LLM | Groq (llama3) or Google Gemini | | Agents | CrewAI + LangChain | | Blockchain data | Etherscan API + Alchemy API | | Fraud reports | ChainAbuse API | | Database | SQLite (SQLAlchemy) | | Frontend | HTML + CSS + JavaScript (served by FastAPI) |

---

Project Structure

fraud-detector-v2/
├── main.py                  ← FastAPI app entry point
├── config.py                ← API keys + config
├── database.py              ← SQLite database setup
├── models.py                ← Pydantic data models
├── requirements.txt         ← Python dependencies
├── .env                     ← API keys (never committed)
├── .env.example             ← Template for env setup
│
├── agents/                  ← CrewAI multi-agent system
├── services/
│   ├── analyzer.py          ← Main fraud analysis logic
│   ├── ai_analyzer.py       ← LLM-powered analysis
│   ├── blockchain.py        ← Etherscan + Alchemy calls
│   ├── chainabuse.py        ← ChainAbuse fraud reports
│   ├── monitor.py           ← Live transaction monitor
│   ├── monitor_state.py     ← Monitor state management
│   ├── index.html           ← Main analysis page
│   ├── history.html         ← Search history page
│   ├── live_monitor.html    ← Live monitoring page
│   ├── ai_agent.html        ← AI agent page
│   └── ai_training.html     ← Model training page
│
├── models/
│   ├── fraud_model.pkl      ← Trained XGBoost model
│   └── feature_names.pkl    ← Feature names for model
│
└── training/
    ├── train_model.py       ← Model training script
    ├── prepare_dataset.py   ← Dataset preparation
    ├── auto_trainer.py      ← Automated retraining
    └── training_data.csv    ← Training dataset

---

Setup

Prerequisites

• Python 3.10+
• API keys for Etherscan, Alchemy, Groq or Gemini, ChainAbuse

1. Clone the repo

git clone https://github.com/Azmeer-59189/fraud-detector-v2.git
cd fraud-detector-v2

2. Create a virtual environment

python -m venv venv

# Windows
venv\Scripts\activate

# Mac/Linux
source venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Configure environment

cp .env.example .env

Open .env and fill in your API keys:

ETHERSCAN_API_KEY=your-etherscan-api-key
ALCHEMY_API_KEY=your-alchemy-api-key
GROQ_API_KEY=your-groq-api-key
GEMINI_API_KEY=your-gemini-api-key
CHAINABUSE_API_KEY=your-chainabuse-api-key
AI_PROVIDER=groq

Getting API keys:

• Etherscan → https://etherscan.io/myapikey (free)
• Alchemy → https://dashboard.alchemy.com (free tier)
• Groq → https://console.groq.com/keys (free)
• Gemini → https://aistudio.google.com/app/apikey (free)
• ChainAbuse → https://www.chainabuse.com/settings/api (free)

5. Run the app

python main.py

Open http://localhost:8000

---

Pages

| URL | Page | Description | |---|---|---| | / | Address Analyzer | Enter an Ethereum address and get risk verdict | | /history | Search History | All past manual analyses saved here | | /live | Live Monitor | Auto-fetches and analyzes new transactions every 15s | | /ai-agent | AI Agent | Multi-agent investigation (experimental) | | /ai-training | AI Training | Retrain the ML model (experimental) |

---

Environment Variables

| Variable | Required | Description | |---|---|---| | ETHERSCAN_API_KEY | ✅ | Fetch transaction history | | ALCHEMY_API_KEY | ✅ | Ethereum node access | | GROQ_API_KEY | ✅ (if using Groq) | Free LLM for AI analysis | | GEMINI_API_KEY | ✅ (if using Gemini) | Google Gemini for AI analysis | | CHAINABUSE_API_KEY | ✅ | Known fraud address database | | AI_PROVIDER | ✅ | Set to groq or gemini |

---

Roadmap

• [x] Ethereum address fraud analysis
• [x] Color-coded risk verdict (green/yellow/red)
• [x] ChainAbuse fraud report integration
• [x] Live transaction monitoring (15s refresh)
• [x] Search history with SQLite
• [x] XGBoost ML model
• [x] LLM-powered risk explanation
• [ ] AI agent investigation (in progress)
• [ ] Model retraining UI (in progress)
• [ ] Support for other chains (BSC, Polygon)
• [ ] Browser extension

---

License

MIT License — see LICENSE for details.

---

Author

Syed Azmeer

• GitHub: @Azmeer-59189

---

<div align="center"> Built as a blockchain security research project </div>