A beginner-friendly command-line tool to explore Bitcoin blockchain data directly from your terminal. Built with Python 3, this project uses public APIs to fetch and display block, transaction, and address information without requiring a Bitcoin node.
Built as preparation for Summer of Bitcoin 🚀
- Fetch block information by height
- View block hash, timestamp, transaction count, size, and miner reward
- Display additional details like Merkle root, difficulty, and nonce
- Look up any transaction by its TXID
- See inputs, outputs, and total BTC sent
- View transaction fees and confirmation status
- Display fee rate in satoshis per byte
- Check balance for any Bitcoin address
- View total received and total sent amounts
- See the last 5 transactions for the address
- Support for Legacy (P2PKH, P2SH) and SegWit (Bech32) addresses
- Python 3.8+ - Core programming language
- requests - HTTP library for API calls
- argparse - Command-line argument parsing
- Blockstream API - Public Bitcoin blockchain data source
btc-explorer-cli/
├── explorer.py # Main entry point and CLI argument handling
├── api.py # API client for Blockstream Bitcoin API
├── formatter.py # Output formatting and display logic
├── utils.py # Validation and helper functions
├── requirements.txt # Python dependencies
└── README.md # This file
Clean, modular architecture makes it easy to understand and extend! 🎯
- Python 3.8 or higher
- pip (Python package manager)
- Internet connection (for API calls)
-
Clone or download this repository
cd btc-explorer-cli -
Install dependencies
pip install -r requirements.txt
-
Make the script executable (optional, for Unix/Linux/Mac)
chmod +x explorer.py
That's it! You're ready to explore the Bitcoin blockchain. 🎉
python explorer.py <command> <argument>Fetch details about a specific block by its height:
python explorer.py block <height>Example:
python explorer.py block 800000Output includes:
- Block hash
- Block height
- Timestamp (human-readable)
- Number of transactions
- Block size and weight
- Miner reward
- Merkle root, difficulty, and nonce
Look up a transaction by its TXID:
python explorer.py tx <txid>Example:
python explorer.py tx 3ba3edfd7a7b12b27ac72c3e67768f617fc81bc3888a51323a9fb8aa4b1e5e4aOutput includes:
- Transaction ID
- Confirmation status
- Size and weight
- Total BTC sent
- Transaction fee and fee rate
- List of inputs (with amounts and addresses)
- List of outputs (with amounts and addresses)
Check the balance and transaction history of a Bitcoin address:
python explorer.py address <btc_address>Example:
python explorer.py address 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNaOutput includes:
- Current balance (confirmed and unconfirmed)
- Total received
- Total sent
- Transaction count
- Last 5 transactions with amounts and status
# Check the genesis block (block 0)
python explorer.py block 0
# Look up Satoshi's first transaction
python explorer.py tx 4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b
# Check Satoshi's address
python explorer.py address 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNaThis project demonstrates:
✅ API Integration - Making HTTP requests and handling responses
✅ Error Handling - Graceful handling of network errors and invalid inputs
✅ CLI Development - Using argparse for command-line interfaces
✅ Code Organization - Modular design with separation of concerns
✅ Data Formatting - Converting raw API data into readable output
✅ Bitcoin Basics - Understanding blocks, transactions, and addresses
Perfect for students preparing for Summer of Bitcoin or anyone learning Bitcoin development! 🎯
======================================================================
📦 BLOCK INFORMATION
======================================================================
🔗 Block Hash: 00000000000000000001c9e6d0f0e6f8b3c8d2e5f7a9b1c3d5e7f9a1b3c5d7e9
📊 Height: 800,000
⏰ Timestamp: 2023-07-14 18:32:15
📝 Transactions: 3,251
💾 Size: 1.45 MB
⚖️ Weight: 3,992,547 WU
💰 Miner Reward: 6.28491055 BTC
======================================================================
======================================================================
💸 TRANSACTION INFORMATION
======================================================================
🆔 Transaction ID: 3ba3edfd7a7b12b27ac72c3e67768f617fc81bc3888a51323a9fb8aa4b1e5e4a
📊 Status: Confirmed ✓
💾 Size: 225 bytes
⚖️ Weight: 900 WU
💰 FINANCIAL SUMMARY:
Total Sent: 0.05000000 BTC
Fee Paid: 0.00002250 BTC
Fee Rate: 10.00 sat/byte
======================================================================
======================================================================
🏦 ADDRESS INFORMATION
======================================================================
🔑 Address: 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
💰 BALANCE:
Confirmed: 72.48391234 BTC
📊 STATISTICS:
Total Received: 72.48391234 BTC
Total Sent: 0.00000000 BTC
Transaction Count: 3,891
======================================================================
The tool handles various error scenarios gracefully:
- ❌ Invalid block height - "Block not found at height X"
- ❌ Invalid TXID - "Invalid transaction ID format"
- ❌ Invalid address - "Invalid Bitcoin address format"
- ❌ Network errors - "Connection error. Please check your internet connection"
- ❌ Rate limiting - Automatic delays between requests to respect API limits
This project uses the Blockstream API, a free public API for Bitcoin blockchain data:
- Base URL: https://blockstream.info/api
- Rate Limits: Respectful delays implemented (0.5s between requests)
- No Authentication Required
- Documentation: https://github.com/Blockstream/esplora/blob/master/API.md
Ideas for extending this project:
- Add mempool statistics viewer
- Support for testnet exploration
- Export data to JSON/CSV
- Interactive mode with command history
- Colored terminal output
- Transaction graph visualization
- UTXO set analysis
- Lightning Network integration
This is a learning project built for Summer of Bitcoin preparation. Feel free to:
- Fork and experiment
- Add new features
- Improve error handling
- Enhance the output formatting
- Add tests
This project is open source and available for educational purposes.
Built with ❤️ as preparation for Summer of Bitcoin
Happy Exploring! 🪙✨
- Blockstream for providing the free public API
- Summer of Bitcoin program for inspiration
- Bitcoin community for excellent documentation