BIP21 Payment URI

A BIP21 payment URI is a standardized bitcoin: link that lets a payer initiate a transaction by clicking a link or scanning a QR code instead of copying a raw address by hand. The scheme follows the form bitcoin:<address>?amount=<btc>&label=<name>&message=<text>, where the amount is expressed in decimal BTC with a period separator. The bitcoin: scheme prefix itself is case-insensitive, while the address portion remains case-sensitive — a distinction worth remembering when generating URIs programmatically.

The whole point of the scheme is to remove the single most error-prone step in paying someone: transcribing a long string of characters by hand. A Bitcoin address is deliberately unforgiving — one wrong character and, in the worst case, funds go somewhere unrecoverable — so any mechanism that lets a wallet ingest the address, and optionally the amount and a label, without any human retyping is a genuine safety improvement rather than a mere convenience. Encoding all of that information inside a single scannable QR code or clickable link is exactly what BIP21 standardizes and what has kept it in universal use. It is one of those quiet pieces of infrastructure that almost nobody consciously thinks about, precisely because, when it works, the payment simply opens pre-filled and correct.

How the parameters work

The optional query parameters carry the payer's intent so a wallet can pre-fill the details. amount sets the requested value, label names the recipient, and message describes the purpose of the payment. A req- prefix marks a parameter as required: a compliant client must refuse a URI containing an unrecognized required parameter rather than silently ignore it, which prevents a wallet from acting on an instruction it does not fully understand. Critically, the standard states that a client must never act on a URI without first obtaining the user's explicit authorization — the URI proposes a payment, it does not command one, preserving the human-in-the-loop control that self-custody depends on.

Why the format is deliberately minimal

Part of BIP21's longevity is how little it tries to do. It encodes a request — an address, optionally an amount and some human-readable labels — and nothing more; it carries no keys, no signatures, and no authority to move funds. That minimalism is a security property, because the worst a malicious URI can do is propose an address and amount that your wallet will still show you before anything is signed. It also made the scheme trivial to implement, which is why virtually every wallet on every platform understands one, and why a printed QR code at a market stall works the same as a link in a web page.

Practical use and successor

Payment URIs quietly power a large share of everyday Bitcoin commerce: point-of-sale QR codes, donation buttons, invoice links, and the "scan to pay" flow in nearly every mobile wallet. Their durability comes from being simple and easy to extend. The original BIP21 has since been generalized by BIP321, which broadens the scheme to carry newer payment instructions — silent-payment addresses, Lightning data — alongside an on-chain fallback, so a single link can offer a wallet several ways to pay and let it choose the best one it supports.

Verifying what you sign

For a sovereign Bitcoiner, understanding the URI format is part of verifying what you are actually about to sign rather than trusting a pretty QR code. A malicious or malformed URI can only ever propose an address and amount; your wallet still shows you both before you approve, so the discipline is to read that confirmation screen and confirm the address and value match what you intended, every time. The UTXO your payment consumes is chosen by your wallet, not the URI, which is where deliberate control comes in: combine BIP21 with disciplined coin control and UTXO labeling so that every outgoing payment is intentional, privacy-aware, and auditable after the fact. A link is a convenience; the signature is the commitment.