crypto-scam-detector
# 🔍 Crypto Scam Detector v2.0
**Database-first cryptocurrency scam detection for OpenClaw**
Analyzes crypto addresses for phishing, honeypots, rug pulls, and ponzi schemes using a local database with background sync from Etherscan. **Zero external API calls during user checks** = instant results!
## ✨ What's New in v2.0
### 🚀 Major Architecture Upgrade
- ✅ **Database-first design** - All checks query local SQLite database
- ✅ **Instant results** - No API latency during checks (<5ms)
- ✅ **No rate limits** - User queries never hit Etherscan API
- ✅ **Background sync worker** - Separate process pulls from Etherscan
- ✅ **Transaction message analysis** - Decodes and analyzes hex data
- ✅ **Auto-queue system** - Unknown addresses automatically queued for sync
- ✅ **Deep scanning** - Detects suspicious keywords in transaction data
### 🔍 Enhanced Detection
Now catches scams the old version missed:
- ✅ "Lazarus Vanguard" hacking group references
- ✅ "Orbit Bridge Hacker" mentions
- ✅ Private key phishing attempts
- ✅ Exploit recruitment messages
- ✅ And much more...
## 📦 What's Included
```
crypto-scam-detector/
├── SKILL.md # This file
├── DATABASE_ARCHITECTURE.md # Technical documentation
├── database.py # SQLite database layer
├── crypto_check_db.py # Database-only checker (instant)
├── sync_worker.py # Background Etherscan sync worker
├── secure_key_manager.py # Encrypted API key storage
├── install.sh # Auto-installer
├── setup.sh # API key setup wizard
├── check_address.sh # Convenience script (sync if needed)
├── requirements.txt # Python dependencies
└── venv/ # Virtual environment (created on install)
```
## 🚀 Quick Start
### 1. Install
```bash
cd ~/.openclaw/workspace/skills/crypto-scam-detector
bash install.sh
```
### 2. Configure Etherscan API Key (Optional but Recommended)
**Option A: Interactive Setup** (Encrypted storage)
```bash
./setup.sh
# Follow the wizard to encrypt your API key
```
**Option B: Environment Variable**
```bash
export ETHERSCAN_API_KEY="your_key_here"
```
Get free API key: https://etherscan.io/myapikey
### 3. Check an Address
```bash
# Check address (instant, database-only)
python3 crypto_check_db.py 0x1234567890abcdef1234567890abcdef12345678
```
### 4. Run Background Sync Worker
**Manual mode:**
```bash
python3 sync_worker.py
# Runs continuously, processes queue
```
**Batch mode:**
```bash
python3 sync_worker.py --max-jobs 20
# Process 20 addresses then exit
```
**Cron schedule (recommended):**
```bash
# Add to crontab
*/10 * * * * cd ~/.openclaw/workspace/skills/crypto-scam-detector && source venv/bin/activate && ETHERSCAN_API_KEY="key" python3 sync_worker.py --max-jobs 30
```
## 💡 How It Works
### Architecture Flow
```
User checks address
↓
┌──────────────────┐
│ crypto_check_db │ ← Queries local database ONLY
└────────┬─────────┘ (No external API calls)
│
↓
┌──────────────────────┐
│ Local SQLite DB │
│ ~/.config/crypto- │
│ scam-detector/ │
│ │
│ • Addresses │
│ • Transactions │
│ • Risk scores │
│ • Scam indicators │
│ • Sync queue │
└────────▲─────────────┘
│
│ Background sync
│
┌────────┴─────────────┐
│ sync_worker.py │ ← Pulls from Etherscan
│ │ (Uses your API key)
│ • Reads queue │
│ • Calls Etherscan │
│ • Decodes TX data │
│ • Analyzes messages │
│ • Stores in DB │
└──────────────────────┘
```
### User Flow
1. **Check address:** `python3 crypto_check_db.py 0x...`
2. **If in database:** Instant results with full analysis
3. **If NOT in database:**
- Returns "unknown" status
- **Automatically adds to sync queue**
- Shows: "⏳ Check again in a few minutes"
4. **Background worker syncs it** (next cron run or manual trigger)
5. **Check again:** Full analysis now available
## 🔍 Detection Capabilities
### Scam Types Detected
| Type | Detection Method |
|------|------------------|
| **Phishing** | Keyword analysis: "private key", "seed phrase", "verify wallet" |
| **Honeypot** | Contract code analysis (unverified contracts) |
| **Rug Pull** | Transaction pattern analysis |
| **Exploit Groups** | Keywords: "Lazarus", "hack", "exploit", "breach" |
| **Social Engineering** | Keywords: "urgent", "claim reward", "airdrop winner" |
### Risk Scoring
**Algorithm factors:**
- Suspicious transaction count (+25 per TX, max +50)
- Account age (new addresses: +10)
- Balance patterns (large balance + suspicious TX: +20)
- Contract verification (unverified: +30)
**Risk Levels:**
- **0-19**: ✅ Low Risk
- **20-49**: ℹ️ Medium Risk
- **50-79**: ⚠️ High Risk
- **80-100**: 🚨 Critical Risk
## 📋 Commands Reference
### Check Address
```bash
# Human-readable output
python3 crypto_check_db.py 0x...
# JSON output
python3 crypto_check_db.py 0x... --json
```
### Sync Worker
```bash
# Add address to queue
python3 sync_worker.py --add-address 0x...
# Run worker (continuous)
python3 sync_worker.py
# Process N addresses then stop
python3 sync_worker.py --max-jobs 20
# Custom delay between addresses
python3 sync_worker.py --delay 2.0
# Show database stats
python3 sync_worker.py --stats
```
### Convenience Script
```bash
# Check and auto-sync if needed
./check_address.sh 0x...
# Automatically syncs if not in DB, then shows results
```
## 🎯 Example Output
### Critical Risk Address
```
🚨 Analysis for 0x098b716b8aaf21512996dc57eb0615e2383e2f96
Risk Score: 100/100 - CRITICAL RISK
Last Updated: 2026-02-20 07:14:32
🚨 KNOWN SCAM DETECTED!
⚙️ Smart Contract
⚠️ NOT VERIFIED on Etherscan
Transactions: 38
Balance: 101.802430 ETH
🚨 5 Scam Indicator(s) Detected:
• Suspicious keyword detected: 'lazarus' (confidence: 80%)
• Suspicious keyword detected: 'hack' (confidence: 80%)
• Suspicious keyword detected: 'exploit' (confidence: 80%)
• Suspicious keyword detected: 'private key' (confidence: 80%)
⚠️ 5 Suspicious Transaction(s):
• 0x74f7fbfe5a0bd3...
Reason: Suspicious keyword detected: 'lazarus'
Message: "Greetings Lazarus Vanguard..."
📋 Recommendations:
🚫 DO NOT send funds to this address
⚠️ This address has been flagged as high risk
📞 Report the source that gave you this address
```
### Unknown Address (Not Yet Synced)
```
⏳ Analysis for 0xnew_address_not_in_db
Risk Score: 0/100 - UNKNOWN
Last Updated: N/A
⏳ Address not yet in database
Address not in database. Added to sync queue.
📋 Recommendations:
⏳ This address will be analyzed soon
🔍 Check again in a few minutes
⚠️ Exercise caution until analysis completes
```
## ⚙️ Configuration
### Database Location
Default: `~/.config/crypto-scam-detector/crypto_data.db`
### Etherscan API Rate Limits
- **Free tier:** 5 calls/second, 100,000 calls/day
- **Each address:** 4 API calls (balance, TX count, TX list, code)
- **Default delay:** 1.5 seconds between addresses (safe for free tier)
### Recommended Cron Schedule
```bash
# Every 10 minutes, process 30 addresses
*/10 * * * * cd ~/.openclaw/workspace/skills/crypto-scam-detector && source venv/bin/activate && ETHERSCAN_API_KEY="key" python3 sync_worker.py --max-jobs 30 --delay 2.0
# Handles ~4,320 addresses per day
```
## 🛡️ Security
- ✅ **Encrypted API key storage** - AES-256 with PBKDF2
- ✅ **No third-party sharing** - API key only sent to Etherscan
- ✅ **Local processing** - All analysis happens on your machine
- ✅ **No telemetry** - Zero data collection
- ✅ **Open source** - Fully auditable code
## 📊 Database Schema
### Tables
- **addresses** - Address info, risk scores, balances, metadata
- **transactions** - Suspicious transactions with decoded messages
- **scam_indicators** - Individual red flags per address
- **sync_queue** - Addresses waiting to be synced
See `DATABASE_ARCHITECTURE.md` for full technical details.
## 🔄 Sync Frequency
**Default behavior:**
- First check → address queued for sync
- Worker processes queue (manual or cron)
- Subsequent checks → instant from database
**Recommended:** Run worker via cron every 5-10 minutes
## 💻 OpenClaw Integration
### Via Chat
```
"Check if 0x1234... is a scam"
"Is this address safe: 0xabc..."
"Verify 0xdef... before I send ETH"
```
### Automatic Detection
When you check an address, OpenClaw:
1. Runs `crypto_check_db.py`
2. If not in DB → queues for sync
3. Returns current status
4. Suggests checking again after sync
## 🐛 Troubleshooting
### "Address not in database"
**Solution:** Wait for background worker to sync it, or manually trigger:
```bash
python3 sync_worker.py --add-address 0x...
python3 sync_worker.py --max-jobs 1
```
### "Etherscan API key not configured"
**Solution:** Set API key via environment or setup wizard:
```bash
./setup.sh # or
export ETHERSCAN_API_KEY="your_key"
```
### Rate limit errors
**Solution:** Increase delay between addresses:
```bash
python3 sync_worker.py --delay 3.0
```
## 📈 Performance
- ✅ **Check latency:** <5ms (database query)
- ✅ **Sync time:** ~2 seconds per address (4 API calls)
- ✅ **Database size:** ~1KB per address
- ✅ **Capacity:** Handles millions of addresses
## 🆚 Comparison: v1 vs v2
| Feature | v1.1.3 (Old) | v2.0.0 (New) |
|---------|--------------|--------------|
| **Check speed** | 2-5 seconds (API calls) | <5ms (database) |
| **Rate limits** | Yes (every check) | No (checks only query DB) |
| **TX message analysis** | ❌ Not analyzed | ✅ Fully analyzed |
| **False negatives** | High (missed scams) | Low (deep analysis) |
| **Architecture** | Direct API calls | Database + background worker |
| **API key usage** | Every check | Only background worker |
## 📜 License
MIT License - Free and open source
## 🤝 Support
- **GitHub:** https://github.com/trustclaw/crypto-scam-detector
- **Issues:** Report bugs or request features
- **ClawHub:** https://clawhub.com/crypto-scam-detector
- **Hackathon:** NeoClaw Hackathon 2026
## 🏆 Credits
**Developed by Trust Claw Team** for NeoClaw Hackathon 2026
**Built with:**
- SQLite - Local database
- Etherscan API - Blockchain data
- ChainAbuse API - Community scam reports
- Python asyncio - Async operations
---
**🔐 Stay safe in crypto! Always verify addresses before sending funds.**
标签
skill
ai
