BIP21 (Bitcoin URI Scheme)

BIP21 defines the bitcoin: URI scheme — the format that lets a single scannable string carry not just an address but the full context of a payment request. When you scan a merchant QR code or tap a payment link and your wallet opens with the address, amount, and a note already filled in, that is BIP21 at work. It is one of Bitcoin's oldest pieces of everyday plumbing, and its longevity comes from how little it tries to do.

The format

A BIP21 URI looks like bitcoin:<address>?amount=0.015&label=Coffee&message=Order%20123. The address is the payment destination; everything after the ? is optional query parameters, percent-encoded like any URL. The three standard parameters are amount (in decimal BTC, using a period as the separator — never commas, never satoshis), label (a name for the recipient, useful for the payer's address book), and message (a human-readable note shown to the payer). A practical detail for QR use: encoding works best when the URI is assembled consistently, which is why wallets generate these strings for you rather than expecting anyone to type one.

Forward compatibility with req-

BIP21's cleverest design decision is its extension rule. Any parameter prefixed with req- is mandatory: a wallet that does not understand a req- parameter must treat the entire URI as invalid rather than silently ignoring something the sender declared essential. Unknown parameters without the prefix are simply ignored, so new features degrade gracefully on older wallets. That one rule is why the scheme has absorbed fifteen years of protocol evolution without a redesign — most visibly in unified QR codes, where a lightning parameter embeds a Lightning Network invoice alongside the on-chain address and the payer's wallet picks whichever rail it supports. One code, both networks, no coordination needed.

A request, not an authorization

Critically, a BIP21 URI is a request: wallets must always require explicit user confirmation before sending. Nothing about scanning a QR code moves money. That boundary carries a security lesson worth internalizing — the URI came from the outside world, so verify the address and amount on a screen you trust before approving, ideally the confirmation display of a hardware wallet rather than the same computer that rendered the QR code. Malware that swaps addresses in QR codes and clipboards is a real, recurring attack; BIP21 defines the envelope, not the trust.

BIP21 is the lightweight, durable successor to the now-removed BIP70 payment protocol, whose X.509-certificate machinery added complexity and attack surface that the ecosystem ultimately rejected — a very Bitcoin outcome: the simple, verifiable format outlived the sophisticated one. Today it remains the everyday standard behind every receive QR your wallet generates, from a merchant terminal to the self-custody wallet collecting your mining payouts.

Why simple formats win

BIP21 is a small case study in protocol durability. It specifies almost nothing — a scheme name, one required field, three optional ones, and an extension rule — yet that minimalism is why every wallet ever written supports it and why it needed no versioning across a decade and a half of ecosystem churn. Formats that encode policy (BIP70's signed payment requests, refund addresses, certificate chains) age with the policy; formats that encode only structure age with the structure, which in Bitcoin's case barely changes. For anyone designing tools in this space, it is the pattern to copy: define the envelope precisely, leave the trust decisions to the endpoints, and let mandatory-extension semantics carry whatever the future needs. The humble payment QR on a shop counter is quietly one of the best-engineered artifacts in Bitcoin — proof that in protocol design, as on the repair bench, the part with the fewest ways to fail is the part that never does.