BIP 21 vs BIP 321: Bitcoin URI schemes

Q: How do I add a Lightning invoice to a bitcoin: URI?

Use the lightning parameter defined by BIP 321, for example bitcoin: ?lightning= . Wallets that support Lightning pay the invoice, and others fall back to the on-chain address. For a BOLT 12 offer, use lno instead. You can also leave the address empty, as in bitcoin:?lightning= , if you don't want an on-chain fallback.

Q: What is the pop parameter in BIP 321?

pop (proof of payment) is an optional URI prefix that the wallet opens after paying, with the payment information appended: the full transaction in hex for on-chain payments, or the preimage for a BOLT 11 payment. It lets the app that started the payment learn that it completed. Wallets must refuse web schemes such as https, and must not pay at all if a req-pop can't be honored.

BIP 321 is the updated bitcoin: URI scheme that replaces BIP 21. It keeps BIP 21's format and parameters (address, amount, label, message and the req- prefix), and adds standard keys for other payment methods such as Lightning and silent payments, allows the address to be left empty, makes parameter names case-insensitive, and defines an optional proof-of-payment callback.

Updated 2026-10-20 · 3 min read

At a glance

	BIP 21	BIP 321
Title	URI Scheme	URI Scheme
Status	Closed	Complete
Type	Specification	Specification
Assigned	2012-01-29	2024-11-15
Authors	Nils Schneider, Matt Corallo	Matt Corallo
In plain English	Defines the "bitcoin:" link format that packages an address, amount, label and message into one string, often shown as a QR code. Wallets read these links to fill in payment details automatically, reducing copy-and-paste mistakes.	Defines the "bitcoin:" link format that wallets use for payment requests in QR codes and clickable links. It specifies how to include an amount, label, message, and alternative payment methods, so scanning a code opens a wallet with the details filled in.

What BIP 21 defined

BIP 21, by Nils Schneider and Matt Corallo, defined the bitcoin: URI that wallets read from links and QR codes:

bitcoin:<address>[?amount=<amount>][&label=<label>][&message=<message>]

Amounts are in decimal BTC with a period as the separator. Unknown parameters can be ignored, except those starting with req-, which make the whole URI invalid if the wallet doesn't understand them. Wallets must not act on a URI without the user's authorization. BIP 21 was itself a modification of BIP 20 by Luke Dashjr.

What BIP 321 changes

BIP 321, by Matt Corallo, documents "the modern usage of bitcoin: URIs" and adds forward-looking rules. Its own list of changes compared with BIP 21:

Standard payment-instruction keys: lightning for BOLT 11 invoices, lno for BOLT 12 offers, sp for BIP 352 silent payments and pay for BIP 351 addresses. SegWit addresses can also be given in bc (mainnet) or tb (testnet) parameters.
Case-insensitive parameter names: keys match regardless of case, which suits the all-uppercase URIs used in QR codes. BIP 21 treated everything after the scheme as case-sensitive.
Modern addresses in the body: the address may be base58 P2PKH or P2SH, Bech32 SegWit version 0, or Bech32m SegWit. BIP 21's grammar listed only base58.
Optional address: the address may be empty if at least one payment instruction is given, for recipients who don't want an on-chain fallback.
Proof of payment: an optional pop (or req-pop) parameter gives a URI the wallet opens after paying, passing back the transaction in hex or a Lightning payment preimage. Wallets must refuse http, https, file, javascript, mailto and other schemes that would open a web browser.

BIP 321 also says future address formats should be added as query parameters rather than in the address field, so older senders can still pay the fallback address.

BIP 21 vs BIP 321 compared

	BIP 21	BIP 321
Address field	Required; base58 in the grammar	Base58, Bech32 or Bech32m, or empty
Parameter names	Case-sensitive	Case-insensitive
Other payment methods	Not specified	`lightning`, `lno`, `sp`, `pay`, `bc`, `tb`
Repeated parameters	Not addressed	`label`, `message`, `pop` and `amount` must not repeat; payment keys may
Proof of payment	None	`pop` and `req-pop`
Reusing a URI	One-time payment requests	URIs with only reusable instructions (BOLT 12 offers, silent payments) may be reused
`amount`, `label`, `message`, `req-`	Defined	Unchanged

Two examples from BIP 321, with intentionally invalid placeholders:

bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?lightning=lnbc420bogusinvoice
bitcoin:?lno=lno1bogusoffer&sp=sp1qsilentpayment

The first asks for a Lightning payment with an on-chain fallback; the second offers a BOLT 12 offer or a silent payment address, with no fallback.

How BIP 321 relates to BIP 21

BIP 321 replaces BIP 21, but it was written to be backward-compatible. In its own words, "any existing BIP 21 implementation should automatically be fully compliant with this BIP", with the one possible exception of case-insensitive parameter names, and BIP 21 software simply ignores the new pop parameter. Most of the changes describe what wallets were already doing by 2024, such as Bech32 addresses and the lightning parameter.

Which applies to you?

Wallet developers: treat parameter names case-insensitively, accept Bech32 and Bech32m addresses and empty bodies, and handle the payment keys you support.
Merchants and apps: one QR code can carry an on-chain address and a Lightning invoice; senders that don't understand lightning pay the address instead.
Users: nothing changes in practice. A wallet still has to ask you to approve each payment.

Build and decode URIs with the Bitcoin URI tool. The silent payments guide and Lightning BIPs guide explain the payment methods the new keys point to.

Frequently asked questions

Is BIP 21 still valid?

BIP 321 replaces BIP 21, but it was designed so that existing BIP 21 implementations remain compliant, with one possible exception: BIP 321 makes parameter names case-insensitive. A simple URI such as bitcoin:<address>?amount=0.01&label=Shop works the same under both. New software should follow BIP 321.

How do I add a Lightning invoice to a bitcoin: URI?

Use the lightning parameter defined by BIP 321, for example bitcoin:<address>?lightning=<BOLT 11 invoice>. Wallets that support Lightning pay the invoice, and others fall back to the on-chain address. For a BOLT 12 offer, use lno instead. You can also leave the address empty, as in bitcoin:?lightning=<invoice>, if you don't want an on-chain fallback.

Are bitcoin: URI parameters case-sensitive?

Under BIP 321, parameter names are case-insensitive, so AMOUNT and amount mean the same thing; the bitcoin: scheme itself was already case-insensitive in BIP 21. Values such as addresses and labels may still be case-sensitive depending on their content. BIP 21 had treated parameter names as case-sensitive.

Can a bitcoin: URI have no address?

Under BIP 321, yes, as long as at least one payment instruction is included as a query parameter, for example bitcoin:?sp=<silent payment address>. BIP 21 always required an address. Leaving it out means a sender that doesn't understand the other instruction has nothing to pay, so include an address when you want a fallback.

What is the pop parameter in BIP 321?

pop (proof of payment) is an optional URI prefix that the wallet opens after paying, with the payment information appended: the full transaction in hex for on-chain payments, or the preimage for a BOLT 11 payment. It lets the app that started the payment learn that it completed. Wallets must refuse web schemes such as https, and must not pay at all if a req-pop can't be honored.