BIPs 0321 · 0021
What can a bitcoin: link ask a wallet to do?
A bitcoin: link carries an address, an amount and other ways to pay, all in one link. BIP 321 says which parts a wallet must understand and which it may ignore.
Click a payment link on a web page, or scan a QR code, and a wallet opens with the payment filled in. Both carry the same thing: a bitcoin: URI. It is a request, not a payment: a wallet MUST NOT act on it without the user's approval.12
BIP 21, from 2012, set out the scheme. BIP 321 replaces it and describes how links were used by 2024. A link can carry several ways to pay, keys can be in any letter case, and there is room for new payment methods that older wallets can safely skip.34567
Source details
This chapter is an independent explanation, not the proposal itself. Preamble fields are shown as the pinned files record them, without author e-mail addresses. Status is the proposal’s own field. It is not an endorsement or a sign of consensus.
BIP 321: URI Scheme
- BIP
- 321
- Layer
- Applications
- Title
- URI Scheme
- Authors
- Matt Corallo
- Status
- Complete
- Type
- Specification
- Assigned
- 2024-11-15
- License
- BSD-2-Clause
- Replaces
- 21
BIP 21: URI Scheme
- BIP
- 21
- Layer
- Applications
- Title
- URI Scheme
- Authors
- Nils Schneider
Matt Corallo - Status
- Closed
- Type
- Specification
- Assigned
- 2012-01-29
- Replaces
- 20
- Proposed-Replacement
- 321
Fig. A21.1 One link, read by three wallets
Static view: the first of 8 published example links. With JavaScript you can choose the others.
Just the address: pays on-chain, for all three wallets.
What each wallet implements
- BIP 21 keys only
amount, label, message- Adds Lightning
amount, label, message, pop, lightning, lno- Every BIP 321 key
amount, label, message, pop, lightning, lno, pay, sp, bc, tb
BIP 321 line 149: “Just the address”, and the link on line 150. The example addresses are intentionally invalid. The three wallets are illustrations, not part of BIP 321; each reading applies its rules.
Amount, label and message: pays on-chain, for all three wallets.
What each wallet implements
- BIP 21 keys only
amount, label, message- Adds Lightning
amount, label, message, pop, lightning, lno- Every BIP 321 key
amount, label, message, pop, lightning, lno, pay, sp, bc, tb
BIP 321 line 158: “Request 50 BTC with message”, and the link on line 159. The example addresses are intentionally invalid. The three wallets are illustrations, not part of BIP 321; each reading applies its rules.
Lightning invoice with an on-chain fallback: BIP 21 keys only: pays on-chain; Adds Lightning: pays on-chain or with Lightning; Every BIP 321 key: pays on-chain or with Lightning.
What each wallet implements
- BIP 21 keys only
amount, label, message· ignoreslightning=lnbc420bogusinvoice- Adds Lightning
amount, label, message, pop, lightning, lno- Every BIP 321 key
amount, label, message, pop, lightning, lno, pay, sp, bc, tb
BIP 321 line 161: “Request funds to be paid over lightning to a BOLT 11 invoice with a fallback to on-chain payments”, and the link on line 162. The example addresses are intentionally invalid. The three wallets are illustrations, not part of BIP 321; each reading applies its rules.
Lightning invoice, no fallback: BIP 21 keys only: valid, but nothing it can pay with; Adds Lightning: pays with Lightning; Every BIP 321 key: pays with Lightning.
What each wallet implements
- BIP 21 keys only
amount, label, message· ignoreslightning=lnbc420bogusinvoice- Adds Lightning
amount, label, message, pop, lightning, lno- Every BIP 321 key
amount, label, message, pop, lightning, lno, pay, sp, bc, tb
BIP 321 line 164: “Request funds to be paid over lightning to a BOLT 11 invoice with no fallback”, and the link on line 165. The example addresses are intentionally invalid. The three wallets are illustrations, not part of BIP 321; each reading applies its rules.
Silent Payments address, no fallback: BIP 21 keys only: valid, but nothing it can pay with; Adds Lightning: valid, but nothing it can pay with; Every BIP 321 key: pays with sp.
What each wallet implements
- BIP 21 keys only
amount, label, message· ignoressp=sp1qsilentpayment- Adds Lightning
amount, label, message, pop, lightning, lno· ignoressp=sp1qsilentpayment- Every BIP 321 key
amount, label, message, pop, lightning, lno, pay, sp, bc, tb
BIP 321 line 173: “Request funds to be paid to a silent payments address with no fallback”, and the link on line 174. The example addresses are intentionally invalid. The three wallets are illustrations, not part of BIP 321; each reading applies its rules.
Unknown parameters, not required: pays on-chain, for all three wallets.
What each wallet implements
- BIP 21 keys only
amount, label, message· ignoressomethingyoudontunderstand=50, somethingelseyoudontget=999- Adds Lightning
amount, label, message, pop, lightning, lno· ignoressomethingyoudontunderstand=50, somethingelseyoudontget=999- Every BIP 321 key
amount, label, message, pop, lightning, lno, pay, sp, bc, tb· ignoressomethingyoudontunderstand=50, somethingelseyoudontget=999
BIP 321 line 182: “Some future version that has variables which are (currently) not understood but not required and thus valid”, and the link on line 183. The example addresses are intentionally invalid. The three wallets are illustrations, not part of BIP 321; each reading applies its rules.
Unknown parameters marked req-: invalid, because a required key, req-somethingyoudontunderstand, is not implemented, for all three wallets.
What each wallet implements
- BIP 21 keys only
amount, label, message- Adds Lightning
amount, label, message, pop, lightning, lno- Every BIP 321 key
amount, label, message, pop, lightning, lno, pay, sp, bc, tb
BIP 321 line 179: “Some future version that has variables which are (currently) not understood and required and thus invalid”, and the link on line 180. The example addresses are intentionally invalid. The three wallets are illustrations, not part of BIP 321; each reading applies its rules.
A label given twice: invalid, because the key label appears more than once, for all three wallets.
What each wallet implements
- BIP 21 keys only
amount, label, message- Adds Lightning
amount, label, message, pop, lightning, lno- Every BIP 321 key
amount, label, message, pop, lightning, lno, pay, sp, bc, tb
BIP 321 line 199: “Labels must not appear twice”, and the link on line 200. The example addresses are intentionally invalid. The three wallets are illustrations, not part of BIP 321; each reading applies its rules.
The parts of a link
A link is bitcoin:, an address, and optional parameters after a question mark, joined by ampersands. The address MUST be a base58 P2SH or P2PKH address, a bech32 SegWit version 0 or bech32m SegWit address, or empty.11
amount is in decimal BTC, with a period and no commas: amount=50.00 and amount=50 both mean 50 BTC. label names the recipient and message describes the payment. Characters outside the allowed set are encoded as UTF-8 and then percent-encoded, so a space becomes %20.121314
Fig. A21.2 A payment link, part by part
The scheme and the parameter keys are case-insensitive, while values and addresses can be case-sensitive. BIP 21 had made the keys case-sensitive, but QR codes mostly use uppercase, so reading keys in any case was already common.151617
Fig. A21.3 Lowercase and uppercase
More than one way to pay
Parameters can carry other ways to pay: lightning for a BOLT 11 invoice, lno for a BOLT 12 offer, pay for BIP 351 and sp for a Silent Payments address. These keys may repeat. New bech32 and bech32m formats SHOULD use their human-readable part as the key, which is why two SegWit addresses can appear as two bc parameters.181920
The address may be left out when at least one instruction is given, for a recipient who wants no on-chain fallback. Future address formats SHOULD go into parameters rather than the address, so that a wallet that only understands the address can still pay.621
One rule makes this safe. A wallet can safely ignore any parameter it does not implement, unless the key starts with req-. If it does not implement a required key, it MUST consider the whole link invalid. The hero's first wallet shows both sides. It pays a Lightning link's on-chain fallback, and it refuses a link with a req- key it does not know.79
Some keys must not repeat. Two labels, two messages or two pop values make a link invalid, and BIP 321's invalid examples add two amounts.20
Proof of payment
A link MAY include pop, a percent-encoded URI prefix. After paying, a wallet that supports it SHOULD decode the prefix once, append the key it paid with (onchain for the address), an equals sign and the payment information, and open the result. The payment information is the full transaction, witness data included, in hex, or, for a BOLT 11 invoice, the hex-encoded payment preimage.2223
Fig. A21.4 Proof of payment
Paid on-chain: it opens the prefix, “onchain=”, then the payment information.
Paid over Lightning: it opens the prefix, “lightning=”, then the payment information.
A callback to a web page: pay as usual, but never open it.
A required callback to a web page: the wallet must not pay.
A wallet MUST NOT open a callback that would open a web browser, such as an https one. The author's reason is privacy. Proof URIs must only be opened when they will simply switch back to the local app that started the payment, without revealing the sender's IP address to the recipient. Suppose the parameter was req-pop and the wallet will not open it, because the scheme is unsafe or it cannot return payment information for the method it used. Then the wallet MUST NOT pay at all.2425
One payment, or many
Best practice is a fresh address for every on-chain payment, so a link with an on-chain address MUST NOT stand for personal details, but for a one-time payment instruction. A link that carries only reusable instructions, such as a BOLT 12 offer or a Silent Payments address, MAY be reused.26
The example links use deliberately invalid addresses, as BIP 321 notes, and placeholder invoices. Never treat them as payment requests.10
What changed from BIP 21
BIP 21 allowed only base58 addresses, and its text made parameter keys case-sensitive. Compared with it, BIP 321 adds standard keys for other payment instructions, makes keys case-insensitive, allows bech32 and bech32m addresses and an empty address, and adds proof of payment.162227
BIP 21 (Nils Schneider and Matt Corallo) was assigned in 2012 and is recorded as Closed. BIP 321 (Matt Corallo) was assigned in 2024 and is recorded as Complete.34
Evidence
Each numbered marker in the text points here, and the ↩ links lead back to the text. Quotes are verbatim
from the BIP files at commit 3a10b5b, wiki markup
included. Links open the exact lines. Labels say what kind of statement each entry is: a rule, the
author’s rationale, history, a test vector, or our own inference.
-
↩ Author’s rationale The scheme exists so that users can pay by clicking a link on a web page or scanning a QR code.
Quoted source text (1)
The purpose of this URI scheme is to enable users to easily make payments by simply clicking links on webpages or scanning QR Codes.
-
↩ Rule Clients MUST NOT act on a URI without the user's authorization, and SHOULD ask the user to approve each payment individually, though they MAY let the user automate the decision in some cases.
Quoted source text (1)
Bitcoin clients MUST NOT act on URIs without getting the user's authorization. They SHOULD require the user to manually approve each payment individually, though in some cases they MAY allow the user to automatically make this decision.
-
↩ a b History BIP 21 (Schneider, Corallo), assigned in 2012, is recorded as Closed and superseded by BIP 321; it had itself replaced BIP 20.
Quoted source text (2)
Title: URI Scheme Authors: Nils Schneider <nils.schneider@gmail.com> Matt Corallo <bip21@bluematt.me> Status: Closed Type: Specification Assigned: 2012-01-29 Replaces: 20 Proposed-Replacement: 321
This BIP has been superseded and replaced with BIP 321.
-
↩ a b History BIP 321 (Corallo), URI Scheme, was assigned in 2024, is recorded as Complete, and replaces BIP 21.
Quoted source text (1)
Title: URI Scheme Authors: Matt Corallo <bip21@bluematt.me> Status: Complete Type: Specification Assigned: 2024-11-15 License: BSD-2-Clause Replaces: 21
-
↩ History BIP 321 modifies and replaces BIP 21, documenting modern query parameters and address types and how to add new payment instructions.
Quoted source text (1)
This BIP is a modification and intended replacement of [[bip-0021.mediawiki|BIP 0021]] to add information about the modern usage of bitcoin: URIs (including standard query parameters and modern address types) as well as provide forward-looking guidance on how to incorporate new payment instructions.
-
↩ a b Rule Future address formats SHOULD go into parameters rather than the body, so that a sender who only understands the body can still pay a recipient offering newer formats.
Quoted source text (2)
Future address formats SHOULD instead be placed in query keys as optional payment instructions to provide backwards compatibility during upgrade cycles.
This allows old senders to pay newer recipients which offer more modern payment instruction formats.
-
↩ a b c Rule A key prefixed with req- is required: a client that does not implement it MUST treat the whole URI as invalid. Other keys it does not implement can be safely ignored.
Quoted source text (1)
Query parameter keys which are prefixed with a req- are considered required. If a client does not implement handling a query parameter which has a key prefixed with req-, it MUST consider the entire URI invalid. Any other query parameters which are not implemented, but which are not prefixed with a req-, can be safely ignored.
-
↩ a b c d Test vector The model reads the 21 URIs in BIP 321's URIs and Invalid URIs lists as the BIP labels them, valid or invalid, and builds all four callbacks its five proof-of-payment examples publish.
BIP 321 L147 BIP 321 L197 BIP 321 L219
Quoted source text (3)
==== URIs ====
==== Invalid URIs ====
initiatingapp:onchain=$HEX_ENCODED_TRANSACTION
-
↩ a b Editorial inference The three wallets in the figures are our illustrations, not part of BIP 321: one implements only BIP 21's keys, one adds Lightning and proof of payment, one implements every key BIP 321 defines. Their readings apply BIP 321's rules to those key sets.
Quoted source text (2)
Any other query parameters which are not implemented, but which are not prefixed with a req-, can be safely ignored.
URIs seamlessly support various payment instructions while senders only need to support legacy instructions.
-
↩ a b Author’s rationale The addresses in BIP 321's examples are intentionally invalid, to prevent accidental transactions.
Quoted source text (1)
Note: The addresses used in these examples are intentionally invalid to prevent accidental transactions.
-
↩ a b Rule A URI is bitcoin:, an optional address body, and optional parameters after a question mark; the body MUST be a base58 P2SH or P2PKH address, a bech32 or bech32m SegWit address, or empty.
Quoted source text (2)
bitcoinurn = "bitcoin:" [ bitcoinaddress ] [ "?" bitcoinparams ] bitcoinaddress = *base58 / *bech32 / *bech32m
The bitcoinaddress body MUST be either a base58 P2SH or P2PKH address, bech32 Segwit version 0 address, bech32m Segwit address, or empty.
-
↩ a b Rule An amount MUST be decimal BTC with a period and no commas: amount=50 and amount=50.00 both mean 50 BTC, and amount=50,000.00 is invalid.
Quoted source text (1)
If an amount is provided, it MUST be specified in decimal BTC. All amounts MUST contain no commas and use a period (.) as the separating character to separate whole numbers and decimal fractions. I.e. amount=50.00 or amount=50 is treated as 50 BTC, and amount=50,000.00 is invalid.
-
↩ a b Rule Every URI may carry a label for the recipient, a message describing the transaction, and pop, a URI for proof of payment.
Quoted source text (1)
*label: Label for the recipient (e.g. name of receiver) *message: message that describes the transaction to the user ([[#examples|see examples below]]) *pop: a URI which the Bitcoin Wallet may return to in order to provide the application which initiated the payment with proof that a payment was completed.
-
↩ a b Rule Characters outside the valid range are encoded as UTF-8 and then percent-encoded.
Quoted source text (1)
These must first be encoded according to UTF-8, and then each octet of the corresponding UTF-8 sequence must be percent-encoded as described in RFC 3986.
-
↩ a b Rule The scheme and the parameter keys are case-insensitive; values and addresses may be case-sensitive.
Quoted source text (1)
The scheme component ("bitcoin:") is case-insensitive, and implementations must accept any combination of uppercase and lowercase letters. The query parameter keys are also case-insensitive. Query parameter values and bitcoin address fields may be case-sensitive depending on their content.
-
↩ a b History BIP 21 allowed only base58 addresses in the body, and its text made everything after the scheme case-sensitive, parameter keys included.
Quoted source text (2)
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ] bitcoinaddress = *base58
The rest of the URI is case-sensitive, including the query parameter keys.
-
↩ a b History Treating keys as case-insensitive was already common practice because of mostly-uppercase URIs in QR codes, and BIP 321 notes that all-uppercase URIs should be handled fine.
Quoted source text (2)
Note, however, that treating query parameters as case-insensitive is already common practice due to the use of mostly-uppercase URIs in QR codes.
Many QR codes utilize all-uppercase URIs, which should be handled fine
-
↩ a b Rule New bech32 or bech32m payment instructions SHOULD use their human-readable part as the key, which is why SegWit addresses appear under bc and tb in the examples.
Quoted source text (2)
New payment instructions using bech32 or bech32m encodings SHOULD reuse their address format's Human Readable Part as the parameter key.
Multiple segwit addresses may be included for various versions of segwit, note that the human-readable part for all of them is `bc`
-
↩ Rule Payment instructions use the keys lightning (BOLT 11 invoices), lno (BOLT 12 offers), pay (BIP 351) and sp (BIP 352 Silent Payments).
Quoted source text (1)
*lightning: Lightning BOLT 11 invoices *lno: Lightning BOLT12 offers *pay: [[bip-0351.mediawiki|BIP 351 Private Payment addresses]] *sp: [[bip-0352.mediawiki|BIP 352 Silent Payment addresses]]
-
↩ a b Rule A payment-instruction key MAY repeat, but label, message and pop MUST NOT; BIP 321's invalid examples also reject a repeated amount and a pop given as both pop and req-pop.
BIP 321 L61 BIP 321 L202–203 BIP 321 L208
Quoted source text (3)
Multiple query parameters with the same key MAY be included for query parameters representing payment instructions. Multiple query parameters with the same key MUST NOT be included for keys "label", "message", or "pop".
Amounts must not appear twice:
Multiple proof of payment URIs must not appear, even if they are sometimes prefixed with req-:
-
↩ Rule The address body MAY be empty when at least one payment instruction is given as a parameter, for recipients who want no on-chain fallback.
Quoted source text (1)
The bitcoinaddress part of the URI MAY be left empty if there is at least one payment instruction provided in a query parameter, allowing for recipients wishing to avoid a standard on-chain fallback.
-
↩ a b c Rule A URI MAY include a pop parameter, a percent-encoded URI prefix. After paying, a wallet that supports it SHOULD decode the prefix once, append the key the instructions came from (onchain for the body), an equals sign and the payment information, and open the result.
Quoted source text (2)
The URI MAY include a "pop" (or "req-pop") parameter whose value can be used to build a URI which the wallet application can, after payment completes, "open" to provide proof the payment was completed or other information about the payment.
The value of a "pop" (or "req-pop") parameter shall be a percent-encoded (per RFC 3986 section 2.1) URI prefix. The wallet application, if it supports providing payment information SHOULD percent-decode the provided URI once, append the query parameter key from which the payment instructions used were read, append a single =, and finally append the Payment Information to the resulting URI and open it with the default system handler for the URI. For payment instructions read from the body of the URI, "onchain" SHALL be used in place of the key.
-
↩ Rule The payment information is the full transaction in hex for an on-chain payment, and the payment preimage in hex for a BOLT 11 invoice.
Quoted source text (2)
For payments made using an on-chain transaction, the Payment Information shall be the full (including witness data) Bitcoin transaction as it was broadcasted to the Bitcoin network, encoded in hex.
For payments made using a BOLT 11 invoice (communicated via the `lightning` parameter), the Payment Information shall be the hex-encoded payment preimage.
-
↩ a b Rule A wallet MUST NOT open a pop URI whose scheme is http, https, file, javascript, mailto or anything else that opens a web browser; if it will not open a pop given as req-pop, it MUST NOT pay.
Quoted source text (2)
A wallet MUST validate that the provided URI's scheme is not (case-insensitive) "http", "https", "file", "javascript", "mailto" or any other scheme which will open in a web browser prior to opening it.
If a wallet will not open the pop scheme (either because it does not support returning payment information for the selected payment method or because it uses a URI scheme which should not be opened) and the parameter was passed as a "req-pop" parameter, the wallet MUST NOT initiate payment.
-
↩ Author’s rationale The author's reason: opening a callback only to switch to another local application avoids revealing the sender's IP address or other information to the recipient.
Quoted source text (1)
In order to avoid inadvertently revealing the sender's IP address or other information to the recipient, proof URIs must only be opened when they will simply switch to another locally-installed application (i.e. the application which initiated the payment).
-
↩ Rule A URI that contains an on-chain address MUST NOT stand for personal information but for a one-time payment instruction; one that carries only reusable instructions, such as BOLT 12 offers or Silent Payments, MAY be reused.
Quoted source text (1)
Best practices are that a unique address should be used for every transaction on-chain. Therefore, a URI which contains an on-chain payment address MUST NOT represent an exchange of personal information, but a one-time payment instruction. URIs which represent only reusable non-address-reusing payment instructions (like Lightning BOLT12 offers or Silent Payments) MAY be reused as a wallet sees fit.
-
↩ History Compared with BIP 21, BIP 321 adds standard payment-instruction parameters, makes parameter keys case-insensitive, allows bech32 and bech32m addresses in the body, and allows an empty body.
Quoted source text (1)
Compared to BIP 21, this document describes standard query parameters containing payment instructions, makes query parameters case-insensitive, allows bech32 and bech32m addresses in the `bitcoinaddress` field, and allows for URIs with an empty `bitcoinaddress` field.