Bitcoin QR codes: the BIP-21 URI explained

A Bitcoin QR code stores a BIP-21 URI containing an address and optionally an amount, label and message. Wallets prefill a send screen from it. The address is public information, so the code itself is safe to print, but always verify the first and last characters after scanning.

The payload

bitcoin:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq?amount=0.001&label=Coffee

BIP-21 defines the scheme. Parameters:

Param	Meaning
`amount`	BTC, up to 8 decimal places, not satoshis
`label`	Recipient name shown in the wallet
`message`	Note for the payer
`lightning`	An optional BOLT-11 invoice for a unified QR

amount=0.001 means one milli-bitcoin. Writing amount=100000 intending satoshis requests one hundred thousand BTC, which the wallet will happily display. Check the units before printing.

Uppercase bech32 makes smaller codes

Bech32 addresses (bc1…) are case-insensitive by design, precisely so they can be uppercased for QR encoding. Uppercase lets the encoder use alphanumeric mode at 5.5 bits per character instead of byte mode at 8, roughly 30% fewer modules for the same address.

Legacy base58 addresses (1…, 3…) are case-sensitive and cannot be uppercased. This is one of several practical reasons to prefer bech32.

Safety

The address is public: publishing it reveals nothing secret, and anyone can send to it. The risks are different in kind:

Address substitution. Clipboard-hijacking malware and stickers pasted over printed codes both work by swapping the address. After scanning, check the first four and last four characters against what is printed.
Irreversibility. There is no chargeback. A wrong address is a permanent loss.
Privacy. A single reused address on public signage makes every payment to you publicly linkable. Rotate addresses, or use a payment processor that derives fresh ones.

Lightning

For small amounts, on-chain fees can exceed the payment. A unified QR carrying both an on-chain address and a lightning= BOLT-11 invoice lets the wallet choose. Note that Lightning invoices usually carry an expiry, a printed one dies.

FAQ

What units does the amount parameter use?

BTC, with up to eight decimal places. It is not satoshis. amount=0.001 is one milli-bitcoin; writing a satoshi figure here requests a vastly larger sum.

Is it safe to print my Bitcoin address publicly?

The address itself is public information and reveals no secret. The real risks are someone pasting a different code over yours, and the privacy loss from a single reused address making all your payments linkable.

Why should I use a bech32 address?

Bech32 addresses are case-insensitive, so they can be uppercased and encoded in alphanumeric mode, about 30% fewer modules than a legacy address, giving a code that scans more easily.

Can one QR code hold both on-chain and Lightning?

Yes, using the lightning= parameter alongside the address. Be aware that Lightning invoices normally expire, so this is unsuitable for print.