btc-toolkit 1.0.0

Bitcoin CLI toolkit — OP_RETURN decoder, balance checker, fee estimator & more. Zero deps, no Bitcoin Core required.

₿ btc-toolkit

Bitcoin CLI toolkit — zero dependencies, no Bitcoin Core required.

Query the Bitcoin network directly via the Mempool.space public API.

---

Commands

Command	Description	Status
btc-toolkit opreturn <txid>	Decode OP_RETURN messages from a transaction	✅ Phase 1
btc-toolkit balance <address>	Confirmed + unconfirmed balance of any address	✅ Phase 2
btc-toolkit fees	Recommended fee rates + mempool backlog	✅ Phase 3
btc-toolkit block <height|hash>	Block metadata by height, hash, or latest	✅ Phase 4
btc-toolkit utxo <address>	Unspent outputs of any address	✅ Phase 5

Installation

Requirements: Python 3.10+

git clone https://github.com/devdavidejesus/btc-toolkit.git
cd btc-toolkit
pip install -e .

Usage

balance — check any address

btc-toolkit balance 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa

Shows confirmed balance, unconfirmed (mempool) balance, and total — in BTC and satoshis. Supports all address types: Legacy (P2PKH), P2SH, SegWit (Bech32), and Taproot.

# JSON output for scripting
btc-toolkit balance <address> --json

# Testnet
btc-toolkit balance <address> --network testnet

BTC conversion uses integer arithmetic (no floats) — satoshi-exact, always.

fees — current rates and mempool backlog

btc-toolkit fees

Shows the five recommended fee tiers (sat/vB) — fastest, half hour, hour, economy, minimum — plus mempool backlog: pending tx count, size in vMB, and a rough estimate of blocks needed to clear it.

# JSON output for scripting
btc-toolkit fees --json

# Testnet
btc-toolkit fees --network testnet

block — inspect any block

btc-toolkit block latest          # chain tip
btc-toolkit block 0               # by height (genesis)
btc-toolkit block 000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f   # by hash

Shows height, hash, mined timestamp (UTC), tx count, size, weight, difficulty, nonce, and previous block hash.

# JSON output for scripting
btc-toolkit block latest --json

# Testnet
btc-toolkit block latest --network testnet

utxo — unspent outputs of any address

btc-toolkit utxo bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq

Lists every UTXO sorted by value (largest first), with txid:vout, value in BTC and sats, confirmation status, and block height. Shows aggregate count and total value.

Known limitation: addresses with tens of thousands of UTXOs (e.g. Satoshi's genesis address, ~76k donation outputs) exceed the upstream electrs response limit and return HTTP 400. Use balance for aggregate stats on such addresses — discovered and verified in production.

# Only confirmed UTXOs
btc-toolkit utxo <address> --confirmed-only

# Show more than 15 entries
btc-toolkit utxo <address> --limit 50

# JSON output (always includes all UTXOs)
btc-toolkit utxo <address> --json

opreturn — decode embedded messages

btc-toolkit opreturn f4ac7abcb689df30ec5e8d829733622f389ca91367c47b319bc582e653cd8cab

# JSON output
btc-toolkit opreturn <txid> --json

# Raw hex only
btc-toolkit opreturn <txid> --raw

Transactions to Try

Real, verified OP_RETURN transactions on mainnet. Verify each one yourself on mempool.space.

TXID	Description
f4ac7abcb689df30ec5e8d829733622f389ca91367c47b319bc582e653cd8cab	"Craig Wright is a liar and a fraud" — 34 bytes (verify on-chain)
2033435de7ce307341231e818ed937cd3a5e8597381fd83a7e5b0234f61b38d3	"learnmeabitcoin" — 75-byte OP_RETURN with null-padded ASCII (verify on-chain)

Note: Satoshi's famous "Chancellor on brink of second bailout for banks" message is in the coinbase scriptSig of the genesis block — NOT in an OP_RETURN output. That's a common misconception. This tool reads OP_RETURN outputs only, which is the standard mechanism for embedding data in Bitcoin transactions (introduced as standard in Bitcoin Core v0.9.0, March 2014).

Architecture

btc-toolkit/
├── btc_toolkit/
│   ├── __init__.py       # Package version
│   ├── __main__.py       # python -m entry point
│   ├── cli.py            # Unified CLI with subcommands
│   ├── api.py            # Shared Mempool.space HTTP client
│   ├── colors.py         # Shared terminal color helpers
│   ├── opreturn.py       # Phase 1 — OP_RETURN decoder
│   ├── balance.py        # Phase 2 — Address balance checker
│   ├── fees.py           # Phase 3 — Fee estimator
│   ├── block.py          # Phase 4 — Block info explorer
│   └── utxo.py           # Phase 5 — UTXO set inspector
├── tests/
│   ├── test_opreturn.py  # 18 tests (mocked API + parser validation)
│   ├── test_balance.py   # 18 tests (sats math + API response parsing)
│   ├── test_fees.py      # 6 tests (rates + backlog parsing)
│   ├── test_block.py     # 12 tests (ref detection + genesis data)
│   └── test_utxo.py      # 8 tests (aggregates + filters)
├── pyproject.toml
├── LICENSE               # MIT
└── README.md

Every subcommand shares one HTTP client (api.py) — new phases add a module + a subcommand, nothing else.

Zero external dependencies — Python standard library only (urllib, json, argparse).

Testing

python -m pytest tests/ -v

62 tests, all API calls mocked — the suite runs offline.

How balance is computed

The Mempool.space /address endpoint returns chain_stats (confirmed) and mempool_stats (unconfirmed), each with funded_txo_sum and spent_txo_sum in satoshis.

confirmed   = chain_stats.funded_txo_sum   - chain_stats.spent_txo_sum
unconfirmed = mempool_stats.funded_txo_sum - mempool_stats.spent_txo_sum
total       = confirmed + unconfirmed

This is the same model used by Esplora/Electrs. Don't trust this README — verify against https://mempool.space/api/address/<address> yourself.

Roadmap

• Phase 1 — OP_RETURN Reader
• Phase 2 — Address Balance Checker
• Phase 3 — Fee Estimator (mempool-based)
• Phase 4 — Block Info Explorer
• Phase 5 — UTXO Set Inspector

All five phases complete — one philosophy throughout: zero dependencies, no Bitcoin Core, verify everything on-chain.

Don't Trust, Verify

Every txid, address, hex value, and technical claim in this README can be independently verified:

• Transaction data: https://mempool.space/api/tx/<txid>
• Address data: https://mempool.space/api/address/<address>
• Fee data: https://mempool.space/api/v1/fees/recommended
• Block data: https://mempool.space/api/block/<hash>
• UTXO data: https://mempool.space/api/address/<address>/utxo
• OP_RETURN spec: learnmeabitcoin.com/technical/script/return
• Esplora API model: github.com/Blockstream/esplora/blob/master/API.md

Contributing

Found a bug or want to help with a phase from the roadmap? Open an issue or a PR. Every contribution must keep the core rules: stdlib only, tests mocked, claims verifiable on-chain.

---

Licensed under MIT · Built by @devdavidejesus

"Don't Trust, Verify."