Bitcoin QR Codes: How They Work and the 2026 Complete Guide

Two layers matter: what the QR symbol is, and what the payload inside it says.

The symbol. A Bitcoin QR is a standard ISO/IEC 18004 QR code. Same finder patterns, same Reed-Solomon error correction, same alignment patterns, same decoder math you would find in a restaurant-menu URL QR. There is no Bitcoin-specific symbology. Any QR scanner can read it; whether the scanned string means anything depends on the receiving app.

The payload — option A: raw address. The simplest Bitcoin QR encodes only the destination address as a string: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq. Scan it, get a string, paste it into a wallet, enter the amount yourself. This is the pattern most paper wallets and the earliest Bitcoin signage used. The downside is obvious: the user has to type or paste the amount, and one fat-finger error is a money error.

The payload — option B: BIP21 URI. BIP21 defines a URI scheme that wraps the address with optional parameters: bitcoin:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq?amount=0.0025&label=Cafe%20Espresso&message=Order%20#4821. A BIP21-aware wallet recognises the bitcoin: scheme, prefills the destination address, prefills the amount in BTC, and shows the label as the payee name. The user reviews and confirms. This is the right pattern for most merchant flows.

The payload — option C: Lightning BOLT11 invoice. Lightning payments use a different payload entirely. A BOLT11 invoice is a bech32-encoded string starting with lnbc for mainnet (or lntb for testnet), encoding the amount, payment hash, expiry, destination node, and optional route hints. Invoices are single-use, expire after a configurable window (commonly one hour), and run anywhere from 200 characters for a simple invoice to over 1,000 characters when route hints are included.

The payload — option D: LNURL. LNURL is a bech32-encoded URL pointing at a Lightning server endpoint that mints invoices on demand. The QR encodes one string that can serve unlimited payments — at scan time, the wallet fetches a fresh BOLT11 invoice from the LNURL endpoint. This is the format that makes static printed Lightning QR codes practical.

A single QR can also encode a unified BIP21 URI with a Lightning fallback (bitcoin:bc1q...?lightning=lnbc...), letting on-chain wallets read the on-chain part and Lightning-capable wallets prefer the Lightning invoice. Wallet support is improving but still uneven in 2026.

Bitcoin has accumulated four address formats over its history, and each one changes how many characters the QR has to encode. More characters means a denser matrix, more required resolution, and more sensitivity to print and lighting.

Legacy P2PKH (Pay-to-Public-Key-Hash). Addresses start with 1 and run 26–35 characters, typically 34. Base58-encoded. These are the original Bitcoin addresses, supported by every wallet ever built. The encoding uses mixed-case alphanumeric which prevents the QR encoder from using the more efficient alphanumeric mode, so a typical P2PKH address encodes as a version 5 QR at H error correction — a 37x37 module matrix. Scannable from any modern phone at sensible sizes.

P2SH (Pay-to-Script-Hash). Addresses start with 3 and run 34 characters. Base58-encoded. Used for multi-signature setups and the older SegWit-wrapped format. Same QR density as legacy P2PKH.

Native SegWit / bech32. Addresses start with bc1q and run 42 characters. The bech32 character set is lowercase alphanumeric, which lets the QR encoder use the more compact alphanumeric mode. Despite the longer string, the density is roughly comparable to a 34-character base58 address — a version 6 or 7 QR at H, 41x41 or 45x45 modules.

Taproot / bech32m. Addresses start with bc1p and run 62 characters. Activated in November 2021, gradually rolling through the wallet ecosystem. The longer string pushes the QR to roughly version 9 at H — a 53x53 module matrix. Still readable, but the modules are smaller for the same print size and demand more camera resolution.

The practical takeaway: bech32 and bech32m addresses are fine in QR form, but you need to print them at adequate size. A 1cm by 1cm QR of a Taproot address on a thermal receipt may struggle on a tired camera. Our error correction guide covers the trade-off between ECC level and density, and the QR best practices guide covers print sizing in general.

BIP21 is the standard that turns a Bitcoin QR from a string-paste exercise into a real payment UI. The format is:

bitcoin:<address>?amount=<value>&label=<text>&message=<text>&lightning=<bolt11>

The address is mandatory. Every parameter after the ? is optional. The most useful three:

amount. A decimal number in BTC. amount=0.0025 means 0.0025 BTC, roughly $150 at a $60,000 BTC price. Some wallets accept sat-denominated amounts via the r query (BIP21 extension), but the canonical form is BTC-denominated. Wallets that respect this parameter prefill the send screen; wallets that ignore it show the address and require the user to enter the amount manually. The list of wallets that ignore BIP21 amount is shorter than it was in 2020 but still includes a few hardware-wallet companion apps and several developer-tool wallets.

label. A URL-encoded string shown to the payer as the recipient name. label=Cafe%20Espresso displays as Cafe Espresso. This is what the user sees when they confirm the transaction — it is your one chance to give the payment a human-readable payee identity.

message. A URL-encoded note attached to the payment for the payer's reference. Common pattern: an order number or invoice reference. Note that this is a payer-side label, not a memo carried on-chain — Bitcoin transactions have no memo field at the protocol level.

lightning. An optional fallback Lightning BOLT11 invoice. Wallets that support Lightning will prefer it; on-chain-only wallets ignore the parameter and use the on-chain address.

The encoding rule that catches people: parameter values containing spaces, ampersands, or non-ASCII characters must be percent-encoded. A label of Joe's Coffee & Tea becomes Joe%27s%20Coffee%20%26%20Tea. Most QR generators that have a dedicated Bitcoin form handle this automatically; a generic URL generator will not, and an unencoded ampersand will silently truncate the URI at the next parameter. EZQR's URL QR generator accepts pre-encoded URIs cleanly.

BIP21 has been a Bitcoin standard since 2012, and adoption is nearly universal among modern wallets, but the long tail of compatibility issues still trips merchants. The categories that matter:

Wallets that fully respect BIP21 amount, label, and message. Mobile-first wallets in this category include BlueWallet, Muun, Phoenix, Zeus, Wallet of Satoshi, and Breez. The major exchange custodial wallets (Cash App, Strike, River) generally respect BIP21 when receiving on-chain. These are the wallets where a merchant-side BIP21 URI produces the cleanest customer UX — scan, review, confirm.

Wallets that respect address but partially ignore amount. Some hardware-wallet companion apps fall here. Ledger Live and Trezor Suite respect BIP21 in recent versions, but older builds and air-gapped signing flows often discard everything but the address, requiring manual amount entry on the desktop side before signing on the device.

Wallets that handle Lightning fallback poorly. The unified BIP21+Lightning URI (bitcoin:...?lightning=lnbc...) is the right pattern for a single printed QR that serves both on-chain and Lightning customers. Wallet support has improved through 2024 and 2025 — Muun, Phoenix, Breez, and Wallet of Satoshi handle it well. Older wallets see the lightning parameter, do not understand it, and fall back to on-chain — which is fine, but the merchant loses the Lightning fee advantage.

Wallets with quirky QR handling. Some exchange apps interpret a BIP21 URI as a deposit-address claim and refuse to send, requiring the user to switch to a different screen. A small handful of older wallets still require copy-paste of just the address.

The operational takeaway for a merchant: test your printed QR with the three or four wallets you expect your customers to use. The BIP21 URI is correct; wallet behavior is what introduces friction.

On-chain Bitcoin QR codes are well-trodden territory. Lightning QR codes are where the engineering trade-offs get sharp.

BOLT11 invoice format. A Lightning invoice is a bech32-encoded string starting with lnbc (mainnet), encoding the amount, payment hash, destination node, expiry, a description, and optional route hints. A simple invoice with no route hints is around 200 characters. A real-world invoice with multiple route hints and a 1-hour expiry runs 300–500 characters. An invoice from a node that needs many route hints to be reachable can exceed 1,000 characters.

What that does to the QR. A 200-character invoice fits in a version 13 QR at H — 69x69 modules. A 500-character invoice pushes to version 21 or 22 — 101x101 modules. A 1,000+ character invoice forces version 40, the largest QR version — 177x177 modules. At version 40 with H error correction, modules at a typical 3cm by 3cm print are roughly 0.17mm. A tired smartphone camera in low light loses focus, contrast, or both, and the scan fails.

The mitigation. Most Lightning wallets dropped from H to M (15%) for BOLT11 QR display, accepting less damage tolerance for a less dense matrix. The trade-off is acceptable for screen-displayed invoices scanned within seconds — the customer's phone is right next to the merchant's screen, lighting is fine, the QR is intact. It breaks down for printed Lightning invoices, which is one of the reasons LNURL exists.

Invoice expiry and single-use. BOLT11 invoices expire (commonly 1 hour) and can only be paid once. Two customers cannot pay the same invoice and both get credited. These are features that prevent stale prices and double-credit attacks, and they are why a printed BOLT11 invoice on signage is unworkable for ongoing merchant acceptance. The next section is where LNURL fixes both problems.

LNURL is a family of specifications (LUD-01 through LUD-21 and counting) that solve the multi-use and expiry problems by adding a server-side hop. The most relevant flavor for merchants is LNURL-pay.

How it works. The QR encodes a bech32-encoded URL pointing at an LNURL endpoint, for example https://yourdomain.com/.well-known/lnurlp/cafe. The encoded string starts with lnurl1 and runs 100–200 characters depending on the path length — short enough for a comfortable version 7 or 8 QR. When a customer scans the LNURL with a compatible wallet, the wallet fetches the endpoint, receives a description and a min/max payment range, and the customer enters an amount. The wallet then requests a BOLT11 invoice from the endpoint for that amount, and pays it. The merchant's server mints a fresh invoice for every payment.

Why this matters for printed QR. One printed LNURL QR can accept unlimited payments at varying amounts. There is no expiry on the QR itself — the QR points at a server, and as long as the server runs, the QR works. The BOLT11 invoices it mints are single-use and short-lived, but they never reach the printed surface.

Lightning Address — the human-readable form. Lightning Address (LUD-16) wraps LNURL-pay in an email-like format: [email protected]. Behind the scenes, the wallet does a .well-known/lnurlp/tip lookup on the domain and proceeds with LNURL-pay. For print, the QR still encodes the underlying LNURL string; the Lightning Address is the human-readable alias.

The trust trade-off. LNURL introduces a server. If the server is down, the QR does not work. If the server is compromised, the attacker can swap the destination node. This is fundamentally different from a static on-chain BIP21 QR, which has no server dependency. For self-hosted nodes, the operational burden of keeping the LNURL endpoint online is real. For wallet-as-a-service providers (Wallet of Satoshi, Alby, LNbits-as-a-service), the burden shifts to the provider but the trust assumption shifts too.

The fallback pattern. A merchant who wants the best of both worlds prints a single BIP21+Lightning URI: bitcoin:bc1q...?amount=0.0025&lightning=lnurl1.... Lightning-capable wallets prefer the LNURL. On-chain-only wallets fall back to the on-chain address.

Three patterns dominate Bitcoin acceptance at retail.

Static address QR — the simplest pattern. Print a BIP21 URI with no amount on signage. Customer scans, enters amount themselves, sends. Settlement on-chain takes 10 minutes to an hour for typical confirmation. Works without internet on the merchant side. Used by parking meters, small kiosks, and any merchant who wants the simplest possible setup. The downside: address reuse hurts customer privacy (anyone can see all incoming payments to that address), and amount-entry errors are on the customer.

Dynamic invoice QR on a display. A point-of-sale system generates a per-transaction BIP21 URI (with amount filled in) or a BOLT11 invoice, displays it on a tablet or POS screen, and the customer scans. This is the standard pattern for Bitcoin-accepting cafes, BTCPay Server merchants, OpenNode integrations, and IBEX. The merchant gets paid the exact amount, the customer scans a screen-displayed QR with crisp pixels in indoor lighting, the on-chain confirmation appears in seconds for zero-conf-friendly merchants and a few minutes for confirmation-required merchants. Lightning version of this pattern settles in under a second.

Static LNURL on signage with a tip jar or fixed-price model. Print an LNURL QR on a sign. Customer scans, wallet prompts for amount within the merchant's range, payment settles on Lightning in seconds. This is the dominant pattern for tip jars at Bitcoin conferences, donation buttons on websites that want a printable physical equivalent, and street vendors who want a single printed QR that does not need a per-transaction screen.

Hybrid BIP21+Lightning. The increasingly common pattern for merchants who want maximum wallet compatibility: a single QR carrying both an on-chain address (BIP21) and a Lightning invoice or LNURL. Lightning-capable wallets pay via Lightning; on-chain wallets pay on-chain. The merchant accepts both routes with one printed code.

For any of these patterns, our payment QR use case covers the broader signage and POS-side context, and the permanent QR code generator breakdown covers the related vendor-stability question for any printed payment QR that needs to survive vendor cancellations.

A paper wallet is a printed sheet with two QR codes: one encoding the public address (the receive QR) and one encoding the private key in WIF format (the spend QR). The pattern was common in 2013–2016 as a way to hold Bitcoin in cold storage.

Why it worked in theory. Generate the keypair on an air-gapped machine, print both QR codes, store the printout in a safe. To spend, scan the private-key QR into a hot wallet, broadcast the spend, and shred the paper.

Why the community moved on. Three failure modes turned out to be common. First, the generation step is the security boundary — a paper wallet generated on a compromised machine is compromised at birth, and verifying the air-gap rigorously is harder than it sounds. Second, the moment you scan the private key into a hot wallet to spend, the key touches an online device and any malware can sweep the entire balance. Third, partial spends are error-prone — if you sweep the paper wallet to spend a fraction, you have to carefully send the change back to a new cold address, or the remainder sits hot. Many users skipped this step and lost the cold-storage property without realizing it.

The modern alternative. Hardware wallets (Ledger, Trezor, Coldcard, BitBox, Foundation Passport) keep the private key isolated on a dedicated signing device. The QR pattern still appears — newer air-gapped hardware wallets (Coldcard, Passport, Keystone) use QR codes to ferry unsigned transactions in and signed transactions out, never connecting the device to a computer. This is the QR-as-air-gap pattern, and it is the legitimate use of Bitcoin QR for cold storage in 2026.

If you still want a paper wallet. Generate it offline using a verified tool. Print on archival paper. Tamper-evident sleeves. Test the spend flow with a tiny amount before committing real funds. And honestly — reconsider, because a hardware wallet is more secure and not much more expensive.

The threat model for a printed Bitcoin QR is not the same as for a marketing QR. Three categories of attack have produced documented losses.

Typo-swap attacks (QR overlay stickers). Attackers print a sticker with their own address QR and paste it over the merchant's legitimate QR on signage. Customers scan, pay, and the funds go to the attacker. This has been reported on parking-meter Bitcoin QR codes, conference donation jars, and at least one well-known Bitcoin ATM. The mitigation: print under tamper-evident laminate, inspect signage daily, and where possible use a destination format (LNURL on your own domain) where the attacker would need to compromise DNS rather than just slap on a sticker.

Misread under low contrast. Bitcoin addresses have built-in checksums — the last few characters validate the rest, and a wallet will refuse an address that fails checksum. But a Lightning BOLT11 invoice's bech32 encoding has similar protection that only catches certain kinds of error. A QR printed on faded thermal paper, scanned in a dim cafe, can produce a checksum-valid but wrong scan if multiple modules misread in compensating ways. Rare, but documented. The mitigation: error correction level H for printed codes, ECC level M only for screen-displayed codes that will be scanned in known good lighting.

Screen-shoulder reading of one-time addresses. A customer-presented BOLT11 QR shown on a phone screen at a busy POS is photographable by anyone in the queue behind. The next person can scan the same invoice from a photo and pay the merchant — which is what the customer wanted — but a hostile actor can also analyze the invoice to learn payment patterns. Not a direct theft vector, but a privacy issue. Single-use invoices and short expiries mitigate this.

Fake merchant QR on online materials. Phishing emails with a Bitcoin QR claiming to be an invoice from a vendor the recipient does business with. The QR encodes the attacker's address. The recipient scans, the BIP21 URI shows a plausible label, and the payment goes to the attacker. Mitigation: verify any Bitcoin payment request out-of-band before paying, especially for amounts above a small threshold.

QR error correction levels (L, M, Q, H) give 7%, 15%, 25%, and 30% damage recovery respectively, at the cost of more redundancy in the matrix. For most use cases, level M is the sweet spot for screens, level H for print. Bitcoin QR codes pull harder on this trade-off than any other common QR application.

On-chain addresses are easy. A 34-character base58 P2PKH or 42-character bech32 native SegWit address fits in a version 5 or 6 QR even at H. Print at 2cm by 2cm and it scans from any modern phone in any reasonable lighting.

Taproot is harder. A 62-character bech32m address at H pushes to version 9 — 53x53 modules. At 2cm by 2cm modules are roughly 0.38mm. Scannable on a modern phone with autofocus, but a five-year-old camera in a dim restaurant starts to struggle.

BIP21 with amount and label is harder still. The URI prefix bitcoin:, the address, and the ?amount=...&label=...&message=... parameters can push the payload to 120–150 characters. At H, that lands at version 12 or 13 — 65x65 modules. Print at 3cm by 3cm for a comfortable scan.

Lightning BOLT11 is the breaking point. A 500-character BOLT11 invoice at H is version 22, 101x101 modules. At 3cm by 3cm modules are 0.30mm — past the edge of comfortable smartphone decode in poor lighting. The wallet ecosystem responded by dropping BOLT11 QR display to ECC level M, which puts a 500-char invoice at version 17, more readable but with less damage tolerance.

The version 40 cliff. A 1,000-character invoice exceeds H-level capacity and must use M or L. At L, version 40 (177x177) carries roughly 4,200 alphanumeric characters — the densest QR can produce. Fine for a steady camera held close to a screen, terrible for anything else.

The rule: on-chain Bitcoin QR uses level H, any reasonable size, ship it. Lightning BOLT11 on screen uses level M, 5cm or larger if you can spare the space. Lightning BOLT11 on print: do not. Use LNURL, which keeps the QR small and the indirection on the server side.