wallet-tracker

Trace cryptocurrency wallet activity as an interactive transaction graph, with built-in threat-intelligence risk scoring. Supports Tron (TRC-20) and all major EVM chains (Ethereum, BSC, Polygon, Arbitrum, Optimism, Base).

The repo contains three independent tools:

Tool	What it does
wallet_tracker.py	Walks the on-chain transaction graph from a seed address (BFS) and emits an interactive HTML graph, an Excel workbook, and a text report — with per-wallet risk flags from GoPlus Security
tron_cli.py	Local Tron signer: check balances and send TRX / TRC-20 from the command line, with security-conscious key handling
wallet-app/index.html	Zero-build browser wallet page for TRC-20 USDT via the TronLink extension

Quick start

pip install -r requirements.txt
cp .env.example .env   # then fill in your API keys

Free API keys (all optional but recommended):

• ETHERSCAN_API_KEY — one Etherscan V2 key works across all supported EVM chains
• TRONGRID_API_KEY — TronGrid, for Tron traces
• GOPLUS_API_KEY — GoPlus Security, raises the rate limit for risk checks

Tracing a wallet

# Direct counterparties of a Tron wallet, USDT only, last 30 days
python wallet_tracker.py TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX --chain tron --token USDT --days 30

# Two hops deep on Ethereum
python wallet_tracker.py 0xYourAddress --chain ethereum --depth 2

Outputs land in ./output/:

• graph_*.html — interactive pyvis graph; risky wallets are highlighted, known exchange hot wallets (Binance, OKX, Bybit, …) are labeled and treated as terminal nodes
• report_*.xlsx — transactions sheet + per-wallet summary (inflow/outflow, counterparties, risk flags)
• report_*.txt — plain-text summary

Useful knobs: --depth, --max-edges (top counterparties by volume), --min-value, --days, --max-pages-seed / --max-pages-inner (pagination caps), and --skip-security-check. Run with --help for the full list.

Every discovered wallet is screened against the GoPlus address-security API for flags such as sanctioned, money_laundering, phishing_activities, mixer, and stealing_attack.

To preview how risky wallets are rendered without hitting any APIs:

python demo_risky.py

Tron CLI signer

# read-only balance check (no key needed)
python tron_cli.py balance --address TXXXX...

# send USDT (key from an encrypted keystore file; prompts for password)
python tron_cli.py send --keystore my.keystore.json --to TXXXX... --amount 10 --token USDT

# build + sign without broadcasting
python tron_cli.py send --to TXXXX... --amount 10 --token USDT --dry-run

Key sources, most secure first: --keystore (encrypted JSON), --keychain (OS credential store), --key-stdin, --seed-file / --seed-stdin (BIP-39), --key-file, --key-env. The tool warns loudly if a key file lives in a cloud-synced folder (Google Drive, OneDrive, Dropbox, iCloud). Testnets (shasta, nile) are supported via --network.

Browser wallet

Open wallet-app/index.html in a browser with the TronLink extension installed. It detects the network, shows TRX and USDT balances, and can send USDT — all client-side, no server and no build step.

Disclaimer

This software is provided for research, compliance, and personal use. Risk flags come from third-party intelligence (GoPlus Security) and may contain false positives or negatives — always verify independently before acting on them. Nothing here is financial advice. Use the signing tools at your own risk and never share your private keys or seed phrases.

License

MIT