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 · uv tool 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 -n signet). Python 3.11+, no dependencies; shell completions for bash, zsh and fish are in completions/ (the Homebrew formula installs them).

Commands

Command	Description
btc-toolkit opreturn <txid>	Decode OP_RETURN messages from a transaction
btc-toolkit tx <txid>	Transaction details: status, fees, size, input/output totals, RBF
btc-toolkit address <address>	Aggregated overview: type, balance, lifetime totals
btc-toolkit balance <address>	Confirmed + unconfirmed balance of any address
btc-toolkit fees	Recommended fee rates + mempool backlog
btc-toolkit block <height|hash|latest>	Block metadata by height, hash, or latest
btc-toolkit utxo <address>	Unspent outputs of any address
btc-toolkit verify <txid>	Check a transaction is in a block by computation: its Merkle proof and the header's proof of work
btc-toolkit decode <rawtx>	Decode a raw transaction offline (or --txid: fetch it and check its hash)
btc-toolkit validate <address>	Check an address offline: checksum, network, type — nothing is sent
btc-toolkit inscription <txid>	Ordinals inscription envelopes in a transaction: content type, size, SHA-256, text

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.

• Offline, nothing sent: validate, and decode given a raw transaction, work only from the bytes you give them.
• Checked by computation: verify recomputes the txid, the Merkle root and the proof of work instead of taking the API's "confirmed" on faith.
• Reported by the API: the other commands show what a Mempool API says — mempool.space by default, or your own instance on your own node with --api-url, so no third party sees your queries.

No command validates blocks or follows the most-work chain; for that, run Bitcoin Core. What each command computes and what it trusts: command reference; threat model: SECURITY.md.

verify — check a transaction is in a block

btc-toolkit verify c103de95817b43f2df635ec6f35ff126ca26a7c6d20570c4b01866b2b3e69a19

✓ VERIFIED means the block header carries strong proof of work; ⚠ CONSISTENT, WEAK WORK means everything matches but that work is cheap to fake. With --json, scripts that must reject forged proofs should require "work": "strong". How it works: command reference.

Scripting

Every command takes --json and has stable exit codes (0 ok · 1 network/API failure or a failed verify · 2 invalid input); the commands that take a txid, address or block read many items from stdin or --file:

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

Every command is also a typed Python function: docs/python-api.md. Output schemas: docs/json-schema.md. Copy-paste jq recipes: docs/cookbook.md.

Seen in the wild

• I Read a $320M Ransom Negotiation From My Terminal: the Liquid Network drain, negotiated on-chain via OP_RETURN, every message decoded with opreturn.
• 49 Messages to a Thief: the OP_RETURN messages sent to the wallet holding 562 BTC from the Coldcard hack.

Listed on bitcoin.org's Development page, among the developer tools in Jameson Lopp's Bitcoin resources, and in awesome-osint and awesome-blockchain.

Roadmap

Next: testnet4 (#64) and plain Esplora backends (#65). Out of scope, for good: keys, signing, broadcasting and runtime dependencies. Past releases: CHANGELOG.

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

Bug reports, ideas and pull requests are welcome: issues · CONTRIBUTING.md (stdlib only, tests with every change, claims verifiable on-chain).

---

Licensed under MIT · Built by @devdavidejesus

"Don't Trust, Verify."