btc-toolkit 1.8.2

Read and verify Bitcoin from your terminal. Zero dependencies, no Bitcoin Core required.

Reads the chain through the Mempool.space public API, or your own Mempool instance, and checks what it can by computation: address checksums offline, and a transaction against its block's Merkle proof and proof of work.

_{The $320M Liquid Network drain was negotiated on-chain. Two of its messages, decoded live — read the whole story.}

Quick start

pipx install btc-toolkit        # or: pip install btc-toolkit · brew install devdavidejesus/tap/btc-toolkit
btc-toolkit fees                # current fee rates
btc-toolkit opreturn f4ac7abcb689df30ec5e8d829733622f389ca91367c47b319bc582e653cd8cab
btc-toolkit verify c103de95817b43f2df635ec6f35ff126ca26a7c6d20570c4b01866b2b3e69a19   # check it is in a block
btc-toolkit validate bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq                         # offline: nothing sent

Try it without installing anything: uvx btc-toolkit block 0.

Options go after the command: btc-toolkit fees --network signet, not btc-toolkit --network signet fees. -n is short for --network, and btc-toolkit <command> --help lists every option of a command.

Commands

Every command, option and example: command reference.

What it verifies, and what it doesn't

Inspect Bitcoin data. Verify what you can. Know what you trust.

btc-toolkit is an explorer client for the terminal: a fast, scriptable way to inspect the Bitcoin blockchain without running infrastructure, for scripting, quick lookups, and learning how Bitcoin data is structured. It reads a Mempool API — mempool.space by default, or your own instance. Most commands report what that API says; some check it, or need no API at all:

What no command does: validate blocks, follow the most-work chain, or check consensus rules. For sovereign, trustless verification, run Bitcoin Core and query it directly. The full threat model is in SECURITY.md; how releases are built and how to verify one yourself, in docs/releases.md.

verify — check a transaction is in a block

btc-toolkit verify c103de95817b43f2df635ec6f35ff126ca26a7c6d20570c4b01866b2b3e69a19

Instead of taking the API's "confirmed" on faith, verify recomputes the txid from the raw transaction, folds it up the Merkle proof to the root (refusing 64-byte transactions posing as nodes, CVE-2017-12842), hashes the 80-byte header that must contain that root, and checks its proof of work against the target its bits encode. The verdict depends only on the work proven:

• ✓ VERIFIED ("work": "strong"): a mainnet header at difficulty 50 T or more (btc-toolkit's own threshold, not a consensus rule) — about 2^77.5 hashes to forge.
• ⚠ CONSISTENT, WEAK WORK ("work": "weak"): everything checks out, but the header carries less work. That is cheap to fake: treat it as consistency, not proof. With --json, verified is true in both cases, so a script that must reject forged proofs should also require "work": "strong".

It does not prove the block height (the API reports it) or that the block is in the chain everyone follows. Details: command reference.

Installation

Python 3.11+ (supported versions), no dependencies:

pipx install btc-toolkit                       # isolated, via pipx
pip install btc-toolkit                        # or with pip
uv tool install btc-toolkit                    # or with uv (uvx btc-toolkit ... runs it without installing)
brew install devdavidejesus/tap/btc-toolkit    # or Homebrew, on macOS and Linux
git clone https://github.com/devdavidejesus/btc-toolkit.git && pip install -e btc-toolkit   # or from source

Shell completion (optional): static scripts in completions/ for bash, zsh and fish — tab-complete commands, networks and flags. The Homebrew formula installs them for you.

Scripting

Every command takes --json, and the commands that take a txid, address or block read one item per line from stdin (-) or a file (--file), emitting JSON Lines:

cat txids.txt | btc-toolkit tx - --json | jq -r '.fee_rate_sat_vb'

Exit codes are a contract: 0 ok · 1 network/API failure (or a failed verify) · 2 invalid input. Output schemas and the stability policy: docs/json-schema.md; environment variables (BTC_TOOLKIT_API_URL, BTC_TOOLKIT_NETWORK, BTC_TOOLKIT_TIMEOUT, NO_COLOR), retries and timeouts: scripting and configuration.

Every command is also a plain, typed Python function (the package ships py.typed):

from btc_toolkit.opreturn import decode_op_return

for out in decode_op_return("c103de95817b43f2df635ec6f35ff126ca26a7c6d20570c4b01866b2b3e69a19"):
    print(out.decoded_text)   # we are whitehats. contact us on chain

Functions, result types and errors: docs/python-api.md.

Use your own Mempool instance

Every command accepts --api-url pointing to a self-hosted Mempool instance, which runs on top of your own Bitcoin node (Umbrel, Start9, RaspiBlitz and similar node stacks offer it as an app):

btc-toolkit balance <address> --api-url http://umbrel.local:3006/api -n mainnet

-n tells btc-toolkit which chain your instance serves. Without it the chain is custom (unknown): addresses of any Bitcoin network (mainnet, testnet/signet, regtest) are accepted, tx shows the API's addresses, and verify reports the work as weak. Results never link to mempool.space when you use your own instance. With your own instance, no third party sees your queries — the public mempool.space API is the zero-setup default, not a requirement.

Seen in the wild

• The $320M Liquid Network drain (Sept 2026) was negotiated on-chain via OP_RETURN — every message of it decoded with opreturn, transaction IDs included: I Read a $320M Ransom Negotiation From My Terminal.
• The wallet holding 562 BTC from the Coldcard hack (July 2026) became a message board: 49 OP_RETURN messages, read with opreturn --file: 49 Messages to a Thief.

btc-toolkit is listed on bitcoin.org's Development page and among the developer tools in Jameson Lopp's Bitcoin resources.

Roadmap

The original five-phase roadmap (OP_RETURN reader, balance, fees, blocks, UTXOs) shipped in v1.0.0; every release since is in the CHANGELOG. What's next lives in the issues — testnet4 (#64), plain Esplora backends (#65) and a --json cookbook (#63); good first issue marks the easy ones. Out of scope, for good: keys, signing, broadcasting and runtime dependencies.

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

Support

btc-toolkit is free, MIT-licensed and has no sponsor. If it's useful to you, you can support its development on-chain:

Bitcoin: bc1qulq8xfcmgxxumjx3yndkfktqgw2exh0rym45sn

(Public address — donations are visible on-chain, as everything here is.)

Contributing

Found a bug or want to propose or build a new command? Open an issue or a PR. Every contribution keeps the core rules — stdlib only, tests with every change, claims verifiable on-chain. The process, the project layout and how to run the tests are in CONTRIBUTING.md.