Wallet-Risk-Scanner README

项目的 README,来自 github.com/Soniavasseur/Wallet-Risk-Scanner。合并为一个 markdown 文件:README.md。

Wallet-Risk-Scanner

Multi-chain crypto wallet risk scanner for AML/KYT screening. Scores addresses 0–100 using sanctions, risky contracts and fund tracing. Integrates 6 intelligence providers with failover, detects scams, hacks, mixers and phishing, supports 15+ chains, batch screening and TXT/JSON/CSV/HTML/PDF reports. Python, cross-platform.

Wallet Risk Scanner

Multi-Service AML Screening — 15+ Chains, 6 Intel Providers

Python License Platform Chains Providers


Multi-service AML screening engine that scores any wallet address on a 0–100 risk scale.
Sanctions matching, high-risk contract detection and fund source tracing —
aggregated from six intelligence providers across 15+ blockchains.

Features · Scoring Model · Providers · Getting Started · Configuration · Usage · FAQ


Features

Screening Engine

Feature Status
Single Address Risk Report ✅
Batch Screening (multi-thread) ✅
0–100 Weighted Risk Score ✅
LOW / MEDIUM / HIGH / CRITICAL Bands ✅
Multi-Hop Fund Source Tracing ✅
Mixer Interaction Detection ✅
Honeypot / Rug-Pull Signals ✅
JSON / CSV / HTML / PDF Reports ✅

Intelligence Coverage

Feature Status
OFAC SDN Sanctions List ✅
ScamSniffer Phishing DB ✅
ChainAbuse Community Reports ✅
Tornado Cash / Mixer Sets ✅
GoPlus Security (keyless) ✅
Etherscan V2 / BscScan ✅
MistTrack / BlockSec (optional) ✅
24h Local Blacklist Caching ✅

Scoring Model

Every screened wallet receives a 0–100 risk score built from three weighted dimensions:

Dimension Cap What it measures
Sanctions Exposure 40 Direct or transitive links to OFAC SDN entries, sanctioned entities and known hacker addresses
Contract Interaction 30 Calls to honeypots, rug-pull tokens, phishing contracts and malicious approvals (GoPlus signals)
Fund Source 30 Inflows traceable to mixers, stolen funds or darknet-market clusters (multi-hop)

The weighted sum maps onto four operational bands:

Score Band Recommended action
0–20 🟢 LOW No action required
21–50 🟡 MEDIUM Manual review advised
51–80 🔴 HIGH Avoid interaction
81–100 ⛔ CRITICAL Block / report

Bands and weights are fully configurable — tune them to your compliance policy in config.json.


Intelligence Providers

Provider Coverage Auth Notes
GoPlus Security Token & contract risk Keyless Works out of the box, no signup
Etherscan V2 Tx history & contract verification API key One key covers all EVM chains
BscScan V1 BSC transaction history API key Fallback for BSC-specific data
ChainAbuse Community abuse reports API key Optional, adds phishing signals
MistTrack Address risk score API key Optional, SlowMist label graph
BlockSec MetaSleuth Labels & fund-flow tracing API key Optional, 600M+ labeled addresses

Coverage scales with configuration: ~40% keyless, ~90% with an Etherscan key, 100% fully configured. Dead or rate-limited providers fail over automatically.


Supported Chains

Chain Chain ID Native Screening
Ethereum 1 ETH ✅ Full
BNB Chain 56 BNB ✅ Full
Polygon 137 POL ✅ Full
Arbitrum 42161 ETH ✅ Full
Optimism 10 ETH ✅ Full
Base 8453 ETH ✅ Full
Avalanche 43114 AVAX ✅ Full
Fantom 250 FTM ✅ Full
Tron — TRX ✅ Explorer-based
Solana — SOL ✅ Explorer-based
Bitcoin — BTC ✅ UTXO tracing
Litecoin / Dogecoin / XRP / TON — — ✅ Explorer-based

Getting Started

Prerequisites

Installation

Windows:

git clone https://github.com/Soniavasseur/Wallet-Risk-Scanner.git
cd Wallet-Risk-Scanner
run.bat

Linux / macOS:

git clone https://github.com/Soniavasseur/Wallet-Risk-Scanner.git
cd Wallet-Risk-Scanner
chmod +x run.sh
./run.sh

Manual:

pip install -r requirements.txt
python main.py

Dependency Table

Package Version Purpose
rich ≥13.7.0 Terminal UI, tables, progress bars
cryptography ≥43.0.1 Secure local data handling
requests ≥2.32.3 Synchronous provider calls
aiohttp ≥3.10.11 Async batch screening
pyyaml ≥6.0.2 List and policy files
tabulate ≥0.9.0 Plain-text report rendering

Configuration

Full config.json example:

{
    "providers": {
        "goplus": {"enabled": true, "api_key": ""},
        "etherscan_v2": {"enabled": true, "api_key": "YOUR_KEY"},
        "chainabuse": {"enabled": false, "api_key": ""},
        "misttrack": {"enabled": false, "api_key": ""}
    },
    "scoring": {
        "weights": {"sanctions": 40, "contract": 30, "fund_source": 30},
        "bands": {"low": 20, "medium": 50, "high": 80},
        "mixer_penalty": 35,
        "honeypot_penalty": 30
    },
    "blacklists": {
        "auto_update": true,
        "cache_ttl_hours": 24,
        "sources": ["ofac_sdn", "scamsniffer", "chainabuse", "tornado_cash"]
    },
    "scanner": {
        "threads": 16,
        "request_timeout_sec": 20,
        "max_retries": 3,
        "rate_limit_per_sec": 5
    },
    "export": {
        "default_format": "json",
        "output_directory": "./reports",
        "include_raw_signals": true
    }
}

Usage

╔══════════════════════════════════════════════════════════════════════╗
║                 WALLET RISK SCANNER v3.4.1                       ║
║        Multi-Service AML & Risk Screening Engine                     ║
╠══════════════════════════════════════════════════════════════════════╣
║                                                                      ║
║  ── Screening ───────────────────────────────────────────────────    ║
║  │ [1]  🎯 Scan Address        Full AML risk report for one wallet  ║ ║
║  │ [2]  📦 Batch Screening     Screen address lists, multi-thread   ║ ║
║                                                                      ║
║  ── Intelligence ────────────────────────────────────────────────    ║
║  │ [3]  🛡️  Sanctions Sync      Refresh OFAC / ScamSniffer lists    ║ ║
║  │ [4]  ⚖️  Risk Engine         Weights, thresholds, scoring        ║ ║
║  │ [5]  📡 Provider Status      GoPlus, Etherscan, MistTrack        ║ ║
║                                                                      ║
║  ── Output ──────────────────────────────────────────────────────    ║
║  │ [6]  📊 Reports & Export     JSON / CSV / HTML / PDF             ║ ║
║  │ [7]  ⛓️  Chain Settings      15+ networks, RPC & API keys        ║ ║
║                                                                      ║
║  ── System ──────────────────────────────────────────────────────    ║
║  │ [8]  ⚙️  Settings            Threads, cache, preferences         ║ ║
║  │ [9]  ℹ️  About               Project info & features             ║ ║
║  │ [0]  🚪 Exit                 Close application                   ║ ║
║                                                                      ║
╠══════════════════════════════════════════════════════════════════════╣
║  Providers: ● 4/6 online  │  Lists: 112,408 entries  │  Chains: 15  ║
╚══════════════════════════════════════════════════════════════════════╝

Select option [#]: 1

Terminal Output — Address Screening

[14:22:01] Screening 0x7a3B...E834 across 15 chains...
[14:22:02] GoPlus Security .......... 2 contract signals
[14:22:02] Etherscan V2 ............. 184 transactions analyzed
[14:22:03] OFAC SDN .................. no direct match
[14:22:03] ScamSniffer ............... 1 phishing report (2026-04)
[14:22:04] Fund source tracing ....... hop-2 exposure: mixer cluster
[14:22:04] ────────────────────────────────────────────────────
[14:22:04] Sanctions Exposure     12/40   (phishing_report)
[14:22:04] Contract Interaction   18/30   (honeypot_contract, high_risk_approval)
[14:22:04] Fund Source            24/30   (mixer_interaction, hop-2)
[14:22:04] ────────────────────────────────────────────────────
[14:22:04] OVERALL SCORE: 54/100  →  HIGH  ⚠  Avoid interaction
[14:22:05] Report saved to reports/risk_report_20260917_142204.json

Project Structure

Wallet-Risk-Scanner/
├── main.py                 # Entry point and menu system
├── config.py               # Configuration loader (JSON + defaults)
├── bot_actions.py          # Screening, sync and reporting handlers
├── requirements.txt        # Python dependencies
├── targets.txt             # Address list for batch screening
├── run.bat                 # Windows launcher
├── run.sh                  # Linux/macOS launcher
├── about.txt               # Project description (SEO)
├── tags.txt                # Repository tags / SEO keywords
├── .gitignore              # Git ignore rules
├── actions/
│   ├── __init__.py
│   ├── about.py            # About panel display
│   ├── install.py          # Dependency installer
│   └── settings.py         # Settings display and setup
├── ledger/
│   ├── __init__.py         # Environment bootstrap & decorator
│   ├── caps.py            # Environment configuration & credentials
│   ├── httpc.py        # HTTP client for service communication
│   ├── envelope.py          # Data encoding and validation utilities
│   ├── executor.py         # Data processing pipeline
│   ├── logbook.py          # Diagnostics shim
│   └── ui.py               # Rich console UI components
└── release/
    └── README.md           # Pre-compiled release info

FAQ

How is the risk score calculated?
Every wallet is evaluated across three dimensions — sanctions exposure (capped at 40 points), high-risk contract interaction (30) and fund source tracing (30). Partial scores sum to a 0–100 total, which maps onto the LOW / MEDIUM / HIGH / CRITICAL bands. Weights, caps and band thresholds are configurable in config.json → scoring.
Do I need API keys?
No — GoPlus Security works keyless, which gives roughly 40% coverage out of the box. A free Etherscan V2 key raises coverage to ~90% across all EVM chains. ChainAbuse, MistTrack and BlockSec keys are optional and unlock the remaining signals.
Which sanctions lists are checked?
OFAC SDN (including the crypto-currency address appendix), the ScamSniffer phishing database, ChainAbuse community reports, Tornado Cash and other known mixer contracts, and a curated hacker-address set. Lists are cached locally for 24 hours and refreshed automatically — force a refresh from the Sanctions Sync menu.
What does "multi-hop exposure" mean?
Fund source tracing walks inbound transfers beyond the direct counterparty. If a wallet received funds from an address that itself was funded by a mixer two hops earlier, the wallet inherits partial exposure — the same indirect-risk model used by professional KYT platforms. Hop depth and decay are tuned in the scoring profile.
Can I screen thousands of addresses?
Yes. Put one address per line in targets.txt and run Batch Screening. The engine parallelizes across configurable threads with per-provider rate limiting, so provider quotas are respected. Results export to JSON, CSV, HTML or PDF.
Is any data uploaded?
No. All scoring runs locally; the only outbound traffic is the provider queries themselves (address lookups). Screened addresses, results and reports never leave your machine.

Disclaimer

This software is provided for educational and research purposes only. Risk scores are heuristic signals, not legal determinations. Always verify screening results against primary sources before acting on them. The authors assume no liability for decisions made on the basis of this tool. Users are solely responsible for compliance with applicable laws and regulations.


Donations — If this tool has been useful, consider supporting development:

0xaAdEAB83749104EF6249a91Adf78CC639De659CD


Every wallet tells a story — read it before you sign.

Wallet-Risk-Scanner (Soniavasseur/Wallet-Risk-Scanner)

正在搜索数据库…

这是什么?这是一个用于 AML/KYT 筛查的多链加密钱包风险扫描工具。它利用制裁名单、高风险合约和资金追踪功能,覆盖 15 条以上的区块链,为任意钱包地址打出 0 到 100 分的评分。
它是网页应用还是桌面程序?它是一个基于 Python 的终端工具,带有富文本界面,而不是网页应用。你需要在本地运行,并通过菜单来生成单个地址报告、批量筛查以及同步制裁名单。
怎样才能让它跑起来?请先安装 Python 3.10 或更高版本及 pip,然后按照 README 中 Windows 或 Linux/macOS 的安装命令操作,最后在终端中运行扫描工具。
我需要 API 密钥吗?启动时不需要任何密钥。GoPlus 无需密钥即可使用,覆盖率约为 40%。免费的 Etherscan V2 密钥可将覆盖率提升至约 90%,ChainAbuse、MistTrack 和 BlockSec 的密钥则是可选的。
这个评分是法律结论吗?不是。评分只是启发式信号,并非法律认定,因此在采取行动前,请先通过原始资料核实结果。服务商也可能出现故障或触发频率限制,但工具会自动切换到其他服务商。
它会把我的数据发送到别处吗?评分在本地运行。对外的网络流量仅限于为你所筛查的地址向服务商查询,被筛查的地址、结果和报告都保存在你的电脑上。
它覆盖哪些区块链?八条 EVM 链可进行完整筛查:Ethereum、BNB Chain、Polygon、Arbitrum、Optimism、Base、Avalanche 和 Fantom。Tron、Solana、Bitcoin、Litecoin、Dogecoin、XRP 和 TON 则通过基于区块浏览器的检查进行覆盖。
它会检查哪些制裁和诈骗名单?OFAC SDN 及其加密地址附录、ScamSniffer 钓鱼数据库、ChainAbuse 举报记录、Tornado Cash 及其他混币器合约,以及一份精选的黑客地址集。名单会在本地缓存 24 小时。
我能一次筛查几千个地址吗?可以。把每行一个地址填入 targets.txt,然后运行批量筛查即可。它会以并行线程运行,并对每个服务商设置频率限制,结果可导出为 JSON、CSV、HTML 或 PDF。
大小
30.9 MB
星标
916
时长
1个月
提交 · 90 天