🔍 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

CODEBLOCK0

🚀 Quick Start

1. Install

CODEBLOCK1

2. Configure Etherscan API Key (Optional but Recommended)

Option A: Interactive Setup (Encrypted storage)
CODEBLOCK2

Option B: Environment Variable
CODEBLOCK3

Get free API key: https://etherscan.io/myapikey

3. Check an Address

CODEBLOCK4

4. Run Background Sync Worker

Manual mode:
CODEBLOCK5

Batch mode:
CODEBLOCK6

Cron schedule (recommended):
CODEBLOCK7

💡 How It Works

Architecture Flow

CODEBLOCK8

User Flow

1. 1. Check address: INLINECODE0
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"

1. 4. Background worker syncs it (next cron run or manual trigger)
2. 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

CODEBLOCK9

Sync Worker

CODEBLOCK10

Convenience Script

CODEBLOCK11

🎯 Example Output

Critical Risk Address

CODEBLOCK12

Unknown Address (Not Yet Synced)

CODEBLOCK13

⚙️ Configuration

Database Location

Default: INLINECODE1

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

CODEBLOCK14

🛡️ 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
• scamindicators - Individual red flags per address
• syncqueue - 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

CODEBLOCK15

Automatic Detection

When you check an address, OpenClaw:

1. 1. Runs INLINECODE3
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: CODEBLOCK16

"Etherscan API key not configured"

Solution: Set API key via environment or setup wizard: CODEBLOCK17

Rate limit errors

Solution: Increase delay between addresses: CODEBLOCK18

📈 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.