BIP-321 (Bitcoin unified QR)

Overview

BIP-321 is the modern Bitcoin URI scheme — the intended successor to and replacement for BIP-21.¹² It keeps the bitcoin: scheme and the bitcoin:<address>?<params> shape but generalizes it into a unified URI that can carry multiple payment instructions at once: an on-chain address, a Lightning BOLT11 invoice (lightning=), a BOLT12 offer (lno=), and a BIP-352 Silent Payment address (sp=).¹ These unified URIs are routinely rendered as a QR Code so that one scanned code lets a wallet choose whichever rail it supports.¹³ BIP-321 is explicitly backward-compatible with BIP-21.¹

History

BIP-321 was authored by Matt Corallo, licensed BSD-2-Clause, assigned on 2024-11-15, and carries the status Complete, explicitly listing BIP-21 in its Replaces field.¹ It was proposed via bitcoin/bips PR #1555 ("Replace BIP 21 with a new BIP containing information about more modern usage of it").¹² The motivation was that recipients increasingly want to offer Lightning (when the sender supports it) or newer formats such as Silent Payments, which had led to ad-hoc use of BIP-21 query parameters to encode extra payment instructions; BIP-321 codifies that practice and gives forward-looking guidance for adding future instruction types.¹

Technical specification

The URI grammar generalizes BIP-21:¹

bitcoinurn   = "bitcoin:" [ bitcoinaddress ] [ "?" bitcoinparams ]
bitcoinparams = bitcoinparam [ "&" bitcoinparams ]

Address-less URIs. The address part MAY be empty if at least one payment instruction is supplied as a query parameter — so a URI can offer only Lightning or only Silent Payments with no on-chain fallback.¹

Case-insensitivity. The scheme and parameter keys are case-insensitive, which lets a URI be written all-uppercase (BITCOIN:BC1Q...) for more efficient QR Code encoding.¹

Standard metadata parameters:¹

Param	Meaning
label	recipient identifier (at most once)
message	human description (at most once)
amount	amount in decimal BTC, period separator, no commas
pop / req-pop	proof-of-payment callback URI (at most once)

Payment-instruction parameters (may appear multiple times, giving the wallet choices):¹

Param	Instruction
lightning	a BOLT11 invoice
lno	a BOLT12 offer
sp	a BIP-352 Silent Payment address
bc / tb	segwit (bech32 / bech32m) addresses

req- prefix. Parameters prefixed with req- are mandatory; a client that does not understand a req- parameter MUST reject the URI (the same forward-compatibility rule as BIP-21).¹ URIs that contain only reusable, non-address-reusing instructions — such as BOLT12 offers or Silent Payments — may be reused by a wallet as it sees fit.¹

Use cases

• Unified scan-to-pay QR: a merchant publishes one QR Code carrying an on-chain address plus a Lightning instruction; each wallet picks the rail it supports.¹³
• Lightning-first or privacy-first receiving: an address-less URI offers only a BOLT12 offer or a Silent Payment address.¹
• Future payment formats: the req-/parameter model lets new instruction types be added without breaking old parsers.¹

Implementations

• bitcoin/bips — the canonical BIP repository hosting BIP-321 (MediaWiki), active 2026.¹
• niteshbalusu11/bip-321 — a BIP-321 parsing and encoding library (TypeScript).⁴
• Unified-QR tooling and guidance is collected at bitcoinqr.dev, which documents the on-chain + lightning= composition.³

Comparison

• BIP-321 vs BIP-21: BIP-321 keeps the bitcoin: scheme and is backward-compatible — any conforming BIP-21 implementation should already comply — but generalizes it: it allows an empty address, makes parameter keys case-insensitive, and standardizes multiple/repeatable payment instructions (lightning, lno, sp).¹
• BIP-321 vs bare BOLT11: a BOLT11 invoice is one Lightning instruction; BIP-321 is the container that can carry that invoice (in lightning=) alongside on-chain and Silent-Payment options.¹
• vs Solana Pay / Lightning Address: BIP-321 embeds concrete payment instructions directly in the URI, whereas Lightning Address and Solana Pay transaction requests resolve an identifier or endpoint over HTTP before payment.¹³

Status

BIP-321's specification status is Complete (2024).¹ Per the spec's own guidance, wallet adoption is still progressing: the priority is getting wallets to scan (parse) BIP-321 URIs first, after which projects can add generating them.¹

Sources

1 BIP-321: URI Scheme — bitcoin/bips, 2024 2 BIP 321: URI Scheme — bips.dev, 2024 3 Unified QRs for Bitcoin — bitcoinqr.dev, 2024 4 niteshbalusu11/bip-321 — GitHub, 2026

Deployments

No country reports mention this standard by name.

Regions / aggregations not mapped to a single country

• Universal