Why it exists
BIP 321 updates the bitcoin: payment-link convention for modern wallets. It replaces BIP 21 while preserving its core purpose: carrying payment instructions in a clickable link or QR code that a wallet can review and act on with the user’s authorisation.
How it works
The address field can contain a recognised on-chain address or be empty when a query parameter supplies payment instructions. Defined options include lightning for BOLT 11 invoices, lno for BOLT 12 offers and sp for Silent Payments. Query keys are case-insensitive; their values may not be.
The amount field remains denominated in BTC. A wallet must reject unknown required parameters, marked with req-, instead of silently discarding them. It must also distinguish the available payment methods and ensure the user understands which one is being used.
A practical example
For illustration, a request could contain an ordinary on-chain destination plus a Lightning invoice for the same purchase. A compatible wallet can offer the supported route. A recipient wanting no static on-chain fallback can instead publish a URI whose payment instructions are entirely in its query parameters.
What to keep in mind
Compatibility is per payment method. Reading a bitcoin: link does not prove support for every contained option, nor does it establish the recipient’s identity. Multiple instructions need consistent amounts and expiry handling, and opening a link should not silently send funds.
Status & implementation
BIP 321 is Complete and replaces the Closed BIP 21 document. It documents modern URI behaviour and links a reference parser implementation. This is an application convention, not a change to Bitcoin’s consensus rules.
Specification status: Complete · Sources checked 13 November 2026
