Unified QR Codes for Bitcoin: Merging On-Chain, Lightning, and Silent Payment Addresses

Paying someone with Bitcoin should be simple: scan a QR code, confirm the amount, done. In practice, the experience is fragmented. On-chain wallets cannot pay Lightning invoices. Lightning wallets choke on raw Bitcoin addresses. BOLT 12 offers and silent payment addresses each introduce yet another format. A merchant who wants to accept Bitcoin from any wallet faces a choice no one should have to make: which QR code to display.

Unified QR codes solve this by encoding multiple payment methods into a single bitcoin: URI. The payer's wallet reads the URI, picks the best method it supports, and completes the payment. One QR code works for every wallet. The specification enabling this, BIP-321, formally codifies a pattern that wallets have been adopting since 2023: extending the original BIP-21 URI scheme with query parameters for Lightning, BOLT 12, and silent payments.

The Problem: Bitcoin's Fragmented QR Landscape

Bitcoin's payment ecosystem has evolved into multiple distinct protocols, each with its own address format. A user receiving Bitcoin today might need to produce any of the following:

Each format serves a real purpose, but the proliferation creates a UX problem. A merchant displaying an on-chain QR code loses Lightning customers who do not want to pay mining fees. A merchant displaying a Lightning invoice loses customers whose wallets only support on-chain transfers. And both formats lose privacy-conscious users who prefer silent payments to avoid address reuse.

The core tension: Bitcoin's payment protocol diversity is a strength for developers and a burden for end users. Unified QR codes resolve this by making protocol selection a wallet-level decision rather than a user-level one.

BIP-21 and BIP-321: The URI Foundation

The original BIP-21, authored by Nils Schneider and Matt Corallo in 2012, defined the bitcoin: URI scheme. Its format was straightforward:

bitcoin:<address>?amount=0.01&label=Alice

The spec was designed for a world where Bitcoin had one address format and no Layer 2 networks. It worked well for its time but lacked any mechanism for including alternative payment instructions.

BIP-321: The Modern Extension

BIP-321, also authored by Matt Corallo and assigned in November 2024, modernizes the URI specification with several changes:

• Support for bech32 and bech32m addresses in the address field
• An empty address field is now valid, enabling URIs that contain only Lightning or silent payment instructions with no on-chain fallback
• Standardized query parameter keys for modern payment methods
• Case-insensitive query parameter keys

The critical addition is the set of defined query parameters that transform a simple address URI into a multi-method payment request:

Any existing BIP-21 implementation is automatically compatible with BIP-321. Wallets that do not understand the new query parameters simply ignore them and fall back to the on-chain address.

How Unified QR Codes Work

A unified QR code encodes a single bitcoin: URI containing multiple payment instructions. The on-chain address goes in the address field; Lightning and other methods go in query parameters. Here is what the parsing flow looks like:

URI Construction

A merchant generating a payment request might produce a URI like this:

bitcoin:bc1qexample?amount=0.001&lightning=lnbc1m1...&lno=lno1pqq...

This single string encodes three payment paths: an on-chain Taproot address, a BOLT 11 Lightning invoice, and a reusable BOLT 12 offer. The resulting QR code works regardless of which protocol the payer's wallet supports.

Wallet Parsing Flow

When a wallet scans a unified QR code, it follows a decision process:

1. Parse the bitcoin: URI and extract all query parameters
2. Check for req- prefixed parameters: if any are present and unsupported, reject the entire URI (per BIP-321, the req- prefix marks a parameter as required)
3. Identify which payment methods the wallet supports
4. Select the preferred method based on wallet policy (typically: BOLT 12 > BOLT 11 > silent payment > on-chain address)
5. Present the selected method to the user for confirmation

The fallback design is the key insight. A Lightning-only wallet extracts the lightning parameter and ignores the on-chain address. An on-chain-only wallet reads the address field and ignores all query parameters it does not understand. Neither wallet fails: both complete the payment using their preferred method.

Required parameters: If a query parameter uses the req- prefix (e.g., req-lno=lno1...), any wallet that does not understand that parameter must reject the URI entirely rather than silently falling back to on-chain. This mechanism lets recipients enforce specific payment methods when needed.

BOLT 12 Offers: The Key to Compact Unified QR Codes

QR code density is a practical constraint. BOLT 12 offers are critical to making unified QR codes viable because of their size advantage. A typical BOLT 11 invoice is 200 to 800+ characters. Adding one to a BIP-321 URI with an on-chain address creates QR codes so dense that lower-quality cameras struggle to scan them.

BOLT 12 offers are typically 50 to 150 characters. They are also reusable: an offer does not expire after a single payment. This combination of compact size and reusability makes BOLT 12 the natural choice for the Lightning component of a unified QR code.

The payment flow for BOLT 12 within a unified URI works differently from BOLT 11. Instead of containing a complete invoice, the offer initiates an onion message exchange:

1. Payer's wallet extracts the lno parameter from the URI
2. Wallet sends an invoice_request via onion message through the offer's blinded path
3. Recipient's node generates a fresh invoice with a unique payment hash
4. Payer's wallet receives the invoice and pays it via standard HTLC routing

This two-step process preserves recipient privacy through blinded paths and generates a unique payment hash per transaction, preventing correlation attacks that BOLT 11 invoices are vulnerable to when reused.

Silent Payments in Unified URIs

BIP-352 silent payments solve the on-chain reusability problem. A silent payment address (prefixed sp1q) is a static public key that senders use to derive unique, one-time Taproot output addresses via ECDH. Only the recipient, holding the corresponding scan key, can identify incoming payments by scanning the blockchain.

In a BIP-321 URI, the silent payment address occupies the sp parameter:

bitcoin:?lno=lno1...offer&sp=sp1q...silentaddress

This URI has no traditional on-chain address at all. It contains two reusable, privacy-preserving payment methods: a BOLT 12 offer for Lightning and a silent payment address for on-chain. A wallet that supports silent payments will derive a fresh Taproot address. A wallet that supports BOLT 12 will pay via Lightning. Neither method requires generating a new QR code per payment.

The Privacy Advantage

Traditional unified QR codes that include a standard on-chain address face a tension with address reuse. BIP-321 explicitly states that URIs containing an on-chain address must not be reused, because paying the same address twice enables address clustering and reduces privacy for both sender and recipient.

Silent payments eliminate this constraint. Because each sender derives a unique output address from the same static silent payment address, the QR code can be displayed indefinitely: printed on a sign, embedded in a website, or tattooed on a forearm. No two payments to the same silent payment address produce the same on-chain output.

BIP-353: Human-Readable Payment Identifiers

QR codes are effective for in-person payments, but remote payments often start with a name, not a camera. BIP-353, authored by Matt Corallo and Bastien Teinturier, maps human-readable user@domain identifiers to BIP-321 URIs stored in DNSSEC-signed TXT records.

To receive payments at alice@example.com, Alice publishes a DNS TXT record at alice.user._bitcoin-payment.example.com containing a BIP-321 URI. When a sender enters Alice's address, their wallet queries DNS, validates the DNSSEC chain, and parses the returned URI exactly as it would parse a scanned QR code.

BIP-353 is the human-readable layer on top of the unified QR infrastructure. It replaces the LNURL-based Lightning Address protocol with a design that does not require an HTTP server, does not leak the sender's IP address to the recipient, and provides cryptographic proof of the mapping via DNSSEC. Wallets display these addresses with a Bitcoin symbol prefix: ₿alice@example.com.

Wallet Implementation Status

Unified QR adoption is uneven. Most wallets can scan unified URIs, but far fewer generate them. BOLT 12 and silent payment support remain concentrated in a subset of implementations.

The pattern is clear: scanning support is widespread, but generating unified QR codes and supporting newer protocols like BOLT 12 and silent payments lags behind. Phoenix and Zeus lead on BOLT 12 adoption, while Sparrow and Cake Wallet lead on silent payments. No single wallet yet supports the full stack: unified QR generation, BOLT 12, silent payments, and BIP-353 together.

How Wallets Prioritize Payment Methods

BIP-321 does not mandate a specific priority order. Each wallet decides which method to prefer when multiple options are available. In practice, wallet behavior falls into several categories:

The recommended approach, advocated by the Bitcoin Unified QR project, is for wallets supporting multiple methods to prefer Lightning (lower fees, faster settlement) while using the on-chain address as a universal fallback. This approach minimizes on-chain transaction fees while ensuring every wallet can complete the payment.

The Merchant Experience

For merchants, unified QR codes eliminate a painful operational decision. Today, a merchant accepting Bitcoin through BTCPay Server can generate a unified payment request that includes both an on-chain address and a Lightning invoice. The customer scans one QR code; their wallet automatically selects the appropriate method.

This matters because merchant adoption has historically been constrained by the support burden of multiple payment formats. Training staff to handle different QR codes for different wallet types is impractical at scale. A single QR code that works universally removes this friction entirely.

Point-of-Sale Integration

Point-of-sale systems benefit particularly from the reusable URI model. With BOLT 12 offers, a merchant can generate a static QR code for their store that never expires. Each customer who scans it triggers the onion message exchange that produces a fresh invoice, so the merchant's node handles amount negotiation automatically. No invoice regeneration, no timeout errors, no stale QR codes.

Combined with a silent payment address in the sp parameter, even on-chain payments to this static QR code produce unique outputs. The merchant prints one QR code and never touches it again.

The Convergence: Three Layers of Addressing

The unified QR standard is part of a broader architectural convergence in Bitcoin payments. The emerging stack has three layers:

1. Human-readable layer: ₿alice@example.com (BIP-353), which resolves via DNSSEC to a BIP-321 URI
2. Container layer: the bitcoin: URI (BIP-321), encoding multiple payment methods in a single string
3. Payment method layer: BOLT 12 offers for Lightning, silent payment addresses for on-chain, and traditional addresses as a final fallback

The end state is a single, reusable, privacy-preserving identifier that any wallet can resolve to the best available payment method. No address reuse, no invoice expiry, no separate QR codes for separate protocols.

Challenges and Current Limitations

LND and BOLT 12

LND, the largest Lightning implementation by node count, does not natively support BOLT 12 offers. Version 0.21.0-beta (June 2026) added onion message forwarding as a prerequisite, but creating and paying offers requires the LNDK sidecar daemon as a workaround. Until LND ships native BOLT 12 support, a significant portion of the Lightning network cannot participate in the BOLT 12 component of unified URIs.

Silent Payment Scanning Cost

Receiving silent payments requires scanning every transaction on the blockchain to detect outputs derived from the recipient's scan key. This is computationally expensive, particularly for mobile wallets with limited resources. Bitcoin Core's wallet-level silent payment support remains in open pull requests as of mid-2026, and mobile implementations like Cake Wallet are actively developing background sync optimizations to make this viable.

QR Code Size

Including a BOLT 11 invoice in a unified URI produces large QR codes. A typical BOLT 11 invoice alone can exceed 800 characters; combined with an on-chain address and additional parameters, the resulting QR code may be difficult for lower-quality phone cameras to scan. BOLT 12 offers reduce this problem significantly, but until BOLT 12 adoption is universal, many unified QR implementations must still include BOLT 11 invoices for compatibility.

Generation Gap

Most wallets can scan unified QR codes, but few generate them. This asymmetry means the benefits of unified QR codes depend primarily on merchant and recipient-side tooling like BTCPay Server, rather than on sender wallets. The good news is that scanning support is the harder requirement: a wallet that can parse a unified URI already works with the system, even if it cannot produce one.

Where Layer 2 Protocols Fit

The BIP-321 query parameter model is extensible by design. Any new payment protocol can define its own parameter key and be included in unified URIs alongside existing methods. This creates a natural integration path for Layer 2 protocols beyond Lightning.

Spark, for example, could register a query parameter for its payment protocol. A unified URI might then include an on-chain address, a BOLT 12 offer, a silent payment address, and a Spark payment instruction. A wallet supporting Spark would select it for instant, low-cost settlement; a wallet without Spark support would fall back to Lightning or on-chain without any disruption. The fallback architecture means adding new payment methods never breaks existing wallets.

This composability is what makes the unified QR standard valuable beyond today's protocol landscape. As Bitcoin's Layer 2 ecosystem matures, the bitcoin: URI becomes a universal container for any payment method that can be expressed as a string parameter.

Extensibility without coordination: New payment protocols can join the unified QR ecosystem by defining a query parameter key. Wallets that do not understand the parameter ignore it and fall back to methods they support. No protocol upgrade is required across the ecosystem for a new method to participate.

Building With Unified QR Codes

Developers integrating Bitcoin payments today should design for unified URIs from the start. On the receiving side, generate BIP-321 URIs that include as many payment methods as your infrastructure supports. On the sending side, parse the full URI and select the best available method rather than assuming a single format.

The Spark SDK and wallets like General Bread are built on the principle that users should not need to understand payment protocol differences. Unified QR codes bring that same principle to the broader Bitcoin ecosystem. For deeper context on how different invoice and offer formats compare, see our guide to Lightning invoices and BOLT 12 offers.

This article is for educational purposes only. It does not constitute financial or investment advice. Bitcoin and Layer 2 protocols involve technical and financial risk. Always do your own research and understand the tradeoffs before using any protocol.