ChainSentry 🔍

Bitcoin wallet forensics tool — traces fund flows up to N hops deep using the free BlockCypher public API. No API key required.

---

Features

Feature	Detail
Balance & history	Fetches confirmed balance, total received/sent, transaction list
Fund-flow tracing	Recursively follows output addresses up to --hops levels deep
Loop prevention	Global visited-set ensures each address is fetched exactly once
Readable report	Colour-coded, indented transaction tree with hop-level summaries
Rate-limit safe	Built-in 400 ms delay between requests (free tier: ~3 req/s)

---

Requirements

• Python 3.11+
• requests library

pip install requests

---

Usage

python chainsentry.py <bitcoin_address> [--hops N]

Argument	Default	Description
address	—	Seed Bitcoin wallet address
--hops N	3	Maximum recursion depth (0 = seed only)

Examples

# Trace the genesis block address, 3 hops (default)
python chainsentry.py 1A1zP1eP5QGefi2DMPTfTL5SLmv7Divf1V

# Trace just 1 hop deep
python chainsentry.py 1A1zP1eP5QGefi2DMPTfTL5SLmv7Divf1V --hops 1

# Seed address only (no recursion)
python chainsentry.py 1A1zP1eP5QGefi2DMPTfTL5SLmv7Divf1V --hops 0

---

Architecture

chainsentry.py
│
├── BlockCypherClient          # API layer — HTTP + rate-limiting
│   ├── fetch_address()        # GET /addrs/{addr}/full
│   └── fetch_transaction()    # GET /txs/{txid}
│
├── Parsing layer              # Raw dict → typed dataclasses
│   ├── parse_tx_output()
│   ├── parse_transaction()
│   └── parse_wallet_info()
│
├── Forensics core
│   ├── collect_output_addresses()   # Identify fund destinations
│   └── trace_funds()               # Recursive DFS with visited set
│
└── Reporting layer            # Colour-coded terminal output
    ├── print_header()
    ├── print_wallet_summary()
    ├── print_tree()
    └── print_summary_stats()

---

Rate Limits

BlockCypher's free tier allows roughly 3 requests per second without an API token. ChainSentry sleeps 400 ms between calls by default (RATE_DELAY constant). Deep traces against active wallets may take a few minutes. You can register for a free BlockCypher token and add it as a query param (?token=<TOKEN>) in BlockCypherClient._get() to raise limits.

---

Disclaimer

ChainSentry is a research and educational tool. All data is sourced from the public Bitcoin blockchain via BlockCypher's API. Do not use this tool for any activity that violates applicable laws.