Bitcoin URI

A Bitcoin URI is a link, and clicking it opens your wallet with the payment already filled in. BIP21 fixed the format on January 29, 2012: the scheme bitcoin:, an address, then optional parameters after a question mark. Receiving one instead of a bare address removes the amount from the list of things you have to copy correctly.

How it works

The BIP21 grammar is deliberately small, which is the main reason the format has survived unchanged for more than a decade.

A complete URI reads bitcoin:bc1q...w5mdq?amount=0.00042&label=Coffee%20Shop&message=Order%20118. Everything between the colon and the question mark is the destination address. Everything after it is a set of name=value pairs joined by ampersands, and BIP21 defines only three:

• amount is a decimal number of bitcoin, never satoshis, written with a period and no commas or currency symbol. amount=0.01 means one hundredth of a bitcoin, which is 1,000,000 satoshis.
• label names the party being paid, such as a shop or a person.
• message says what the payment is for.

Both text fields are percent-encoded UTF-8, so a space becomes %20 and an ampersand inside a label becomes %26.

Two rules keep the format extensible. Unknown parameters are ignored, which lets an old wallet read a new URI without choking. Parameters prefixed with req- are the exception: a wallet that does not understand one must reject the whole URI rather than guess at what it was meant to do. That single rule is the entire upgrade mechanism, and it has absorbed every extension since without breaking older software.

Those extensions are where the format actually lives now:

• r=, added by BIP72, pointed at a BIP70 payment request. That path is dead.
• pj=, from BIP78, names a PayJoin endpoint so payer and payee can build a collaborative transaction together.
• lightning= carries a BOLT11 invoice alongside the on-chain address. Wallets that understand it pay over Lightning, wallets that do not fall back to the address, and merchant checkouts print the result as a single unified QR code.
• BIP353 publishes an entire URI inside a DNSSEC-signed TXT record under the _bitcoin-payment label, so a human-readable name resolves to payment instructions.

The address itself is optional. BIP21's grammar permits zero address characters, which is how bitcoin:?r=... worked and how an offer-only URI works today.

Why this matters when you buy bitcoin

The moment a Bitcoin URI matters most is the withdrawal, when coins leave an exchange you do not control and land somewhere you do.

Almost every exchange we cover, from Kraken and River through to Relai and Bitpanda, gives you a plain text box for the destination address. That box wants the address, not the URI. Paste bitcoin:bc1q... into it and you will usually get a validation error, occasionally a silently truncated field and a failed withdrawal. Take what sits between the colon and the question mark, and paste only that.

Traffic runs the other way too. Your own hardware wallet's receive screen, a merchant checkout, and a peer-to-peer trade all hand you URIs rather than bare addresses. A URI is safer in exactly one respect: the amount travels with it, so you cannot mistype the total. It is no safer in the respect that matters most. Nothing in a URI is signed. The label field is free text chosen by whoever built the string, so a phishing page can write label=Kraken%20Withdrawal and your wallet will display those words without comment.

That is why the hardware wallet screen is the control that counts. Whatever a URI claims, a signing device shows you the address it is about to pay on a display that clipboard malware cannot rewrite. Compare the leading and trailing characters there, on the device, not in the browser tab that produced the link.

A worked example: paying a coffee shop invoice

Say a till prints a QR code and your phone reads bitcoin:bc1q...w5mdq?amount=0.00042&label=Kaffeehaus&message=Table%207.

Your wallet parses three facts out of that: pay 0.00042 bitcoin, send it to that address, and show the words Kaffeehaus and Table 7 on the confirmation screen. It then does several things the URI never asked for. It picks which of your unspent outputs to spend, estimates a fee rate from its own view of the mempool, adds a change output, and waits for your approval.

What it does not do is verify anything about the recipient. It has not checked that the shop controls the address, that 0.00042 bitcoin is the agreed price, or that the label is honest. Those checks are yours. On a coffee the downside is a lost coffee. On a five figure transfer it is worth reading the address off the signing device in groups of four characters before approving.

Bitcoin URI vs address

An address is the destination on its own, with no instructions attached. A modern bech32 address runs to 42 characters for a single-key segwit output and 62 for a taproot output, and it says nothing about how much to send or to whom. A URI is a container: an address plus an optional amount, label, and message. You can always recover the address from a URI by reading the text between the scheme and the first question mark. You cannot go the other way, because an address never carried an amount to begin with.

Bitcoin URI vs BOLT11 invoice

A BOLT11 invoice is the Lightning equivalent, and it behaves differently in three ways that matter. It is single use, it commits to a payment hash rather than an address, and it expires, defaulting to 3,600 seconds when the merchant sets no value. A Bitcoin URI never expires and can be paid twice, which is a feature on a donation page and a hazard on an invoice. The unified QR code avoids choosing by putting a BOLT11 string inside the lightning= parameter of an ordinary URI, letting each wallet take the rail it supports.