btc-toolkit is a read-only Bitcoin explorer for the terminal. This document describes exactly what it does, what it protects you from, and — just as important — what it does not.

• Reads public blockchain data from a Mempool-compatible API: over HTTPS from https://mempool.space/api by default, or from any instance you point it at with --api-url / $BTC_TOOLKIT_API_URL (your own node stack, often plain HTTP on your local network).
• Validates input locally before any request is made: transaction IDs and block hashes must be 64 hex characters and heights non-negative integers; addresses are fully validated offline — checksum (Base58Check, bech32, bech32m), network and type — so a mistyped address is never sent. (With --api-url and no -n, the chain is unknown and any network is accepted.)
• Some checks do not depend on the API at all: validate and decode work offline, and verify recomputes a transaction's Merkle proof and its block's proof of work from raw bytes instead of trusting the API's "confirmed".
• Prints results. That's it.

• No private keys. It never generates, stores, imports, or touches keys, seeds, or wallets. There is nothing to steal from it.
• No transaction broadcasting. It cannot move funds.
• No telemetry, analytics, or crash reporting. Zero outbound requests other than the API queries you explicitly trigger.
• No background activity. Every run starts, queries, prints, and exits.
• No configuration files. State lives only in the flags and environment variables of the current invocation.

The package depends on the Python standard library only. It has no requirements file and no lockfile, and nothing is resolved at install time (the only lockfiles in the repository pin CI tools by hash). That means:

• No supply-chain surface through third-party packages: a compromised upstream library cannot ship inside btc-toolkit, because there are none.
• The full auditable surface is this repository — about fifteen small modules.
• Monetary math uses integer satoshis, never floating point.

• Supply-chain compromise via Python dependencies (there are none)
• Hidden telemetry or data exfiltration (there is no outbound traffic except your queries)
• Floating-point errors in balances and fee amounts (integer satoshis throughout; fee rates in sat/vB are decimal by nature)
• Terminal escape sequences hidden in on-chain text, API responses or input files (OP_RETURN messages, error messages and echoed input are printed with control characters escaped; hashes from the API must be hex)
• Crashes on malformed API responses (every field is type-checked: a wrong type is a clean error, exit code 1)
• Malformed transaction IDs and block references, and invalid addresses — a typo, a wrong network — reaching the network (validated locally first, checksums included; exit code 2)
• Hanging on a dead endpoint (configurable --timeout, bounded retries on transient errors only)

• A compromised or lying API backend. By default you are trusting mempool.space to report the chain honestly. --api-url lets you trust your own node instead — that is the intended path to sovereignty.
• Consensus validation. Most commands report what the API says. verify checks that a transaction is committed to by a header carrying valid proof of work, but not the block height (the API reports it) nor that the header is in the chain everyone follows. Its verdict depends only on the work proven: "strong" needs a mainnet header at difficulty 50 T or more (about 2^77.5 hashes to forge); anything less is reported as "weak" — consistent, but cheap to fake. Signet block signatures are not checked. Only a full node validates consensus.
• A compromised operating system, Python installation, or PyPI account. See Verifying releases below for what you can check.
• Privacy of your queries toward the API operator. Queries reveal which addresses/txids you look at. Use your own instance or a privacy network if that matters to you.

Releases from 1.5.0 on are built and published by GitHub Actions through PyPI Trusted Publishing, with PEP 740 attestations that anyone can verify; from 1.6.1 on, every file attached to a GitHub Release also carries a Sigstore bundle. Every release is a git tag vX.Y.Z (signed with the maintainer's SSH key from 1.5.0 on) matching the version in pyproject.toml and btc_toolkit/__init__.py. The published sdist on PyPI is built from that tag; you can diff its contents against the repository. See docs/releases.md for the exact process and how to verify a package before installing it.

Please do not open a public issue for security-sensitive reports. Report privately through GitHub: Report a vulnerability (the report is visible only to you and the maintainer). If you can't use GitHub, email the maintainer at the address on the GitHub profile (@devdavidejesus).

You will get an initial response within 14 days — usually much sooner. Fixes ship as patch releases, and the release notes identify the fixed issue.