Why it exists
BIP 21 turns a Bitcoin payment request into a link or QR code. Instead of copying an address and separately typing an amount, a wallet can read both from one request. The link prepares a payment; it does not sign or send it.
How it works
The URI starts with bitcoin:, followed by a destination and optional query parameters. The amount parameter uses BTC, not satoshis or local currency. A label identifies the request in the interface, while a message can describe its purpose. Text containing spaces or special characters needs URI encoding.
Wallets parse the fields and show a confirmation screen. Unknown optional parameters can be ignored, but an unknown parameter beginning req- makes the request unusable: the sender cannot safely assume an unimplemented requirement is irrelevant. Names and messages are supplied by the requester, not authenticated identities.
A practical example
For an illustrative request, bitcoin:<recipient-address>?amount=0.0025&label=Workshop asks for 0.0025 BTC, or 250,000 sats. The angle-bracket address is a placeholder, not a payable destination. A wallet should display the actual address and amount for review before requesting a signature.
What to keep in mind
A copied QR code can contain an attacker’s address while retaining a familiar label. Parsing success proves only that the request is intelligible. It does not validate the merchant, prove a purchase agreement, or guarantee that the displayed amount remains appropriate.
Status & implementation
BIP 21 is Closed and superseded by BIP 321. Existing bitcoin: links remain relevant, but new implementations should follow BIP 321 for modern address types and additional payment methods.
Specification status: Closed · Sources checked 13 November 2026
