BIP-321 (Bitcoin unified QR)

Overview

BIP-321 is the modern Bitcoin URI scheme — the intended successor to and replacement for bip-21.[1][2] 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=).[1] These unified URIs are routinely rendered as a qr-code so that one scanned code lets a wallet choose whichever rail it supports.[1][3] BIP-321 is explicitly backward-compatible with bip-21.[1]

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.[1] It was proposed via bitcoin/bips PR #1555 ("Replace BIP 21 with a new BIP containing information about more modern usage of it").[1][2] 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.[1]

Technical specification

The URI grammar generalizes bip-21:[1]

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.[1]

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.[1]

Standard metadata parameters:[1]

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):[1]

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).[1] 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.[1]

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.[1][3]
• Lightning-first or privacy-first receiving: an address-less URI offers only a BOLT12 offer or a Silent Payment address.[1]
• Future payment formats: the req-/parameter model lets new instruction types be added without breaking old parsers.[1]

Implementations

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

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).[1]
• 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.[1]
• 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.[1][3]

Status

BIP-321's specification status is Complete (2024).[1] 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.[1]

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