Bitcoin URI (BIP-21)
A standardized URI scheme for encoding Bitcoin payment requests with address, amount, and label parameters, enabling one-click payments and QR code scanning.
Key Takeaways
- A Bitcoin URI encodes a payment request into a clickable link or QR code: it bundles a Bitcoin address, amount, label, and message into a single string that wallets can parse automatically.
- Originally defined by BIP-21, the scheme has been modernized by BIP-321 to support BOLT 11 invoices, BOLT 12 offers, and silent payments: this enables unified QR codes that work across on-chain and Lightning wallets.
- Bitcoin URIs are the backbone of merchant point-of-sale systems and payment links: they eliminate manual address copying and reduce user error in everyday Bitcoin transactions.
What Is a Bitcoin URI?
A Bitcoin URI is a standardized way to encode a payment request as a uniform resource identifier using the bitcoin: scheme. Defined by BIP-21, it allows a sender to click a link or scan a QR code and have their wallet automatically populate the recipient address, payment amount, and descriptive metadata. Instead of manually copying a long alphanumeric address and entering an amount, the user simply confirms and sends.
The format follows RFC 3986 generic URI syntax. The Bitcoin address sits in the path component, while optional parameters like amount and label appear as query string key-value pairs. Any wallet that registers as a handler for the bitcoin: scheme can intercept these URIs and present the payment details to the user for approval.
BIP-21 was introduced in 2012 and has since become the most widely supported payment request format in the Bitcoin ecosystem. In 2024, it was formally superseded by BIP-321, which extends the original scheme with support for modern address types, Lightning Network parameters, and silent payments.
How It Works
A Bitcoin URI follows a simple structure: the scheme name, a Bitcoin address, and optional query parameters separated by ampersands.
URI Format
The basic grammar is:
bitcoin:<address>?amount=<value>&label=<text>&message=<text>The bitcoin: scheme is case-insensitive, but everything after it (including query parameter keys) is case-sensitive. Non-ASCII characters in query values must be UTF-8 encoded and then percent-encoded per RFC 3986 rules.
Standard Parameters
BIP-21 defines three optional query parameters:
| Parameter | Description | Example |
|---|---|---|
amount | Payment amount in BTC. Uses a period as the decimal separator. Comma separators are not valid. | amount=0.005 |
label | A label for the address, typically the name of the recipient. Intended for the sender's address book. | label=Coffee%20Shop |
message | A message describing the purpose of the payment. Not stored on the blockchain. | message=Order%20%2312345 |
Any unrecognized parameter is allowed as long as it does not use the req- prefix. Parameters prefixed with req- are reserved for required extensions: if a wallet encounters an unknown req- parameter it does not understand, it must reject the entire URI rather than silently ignore a critical instruction.
URI Examples
# Minimal: address only
bitcoin:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq
# With amount
bitcoin:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq?amount=0.005
# Full payment request
bitcoin:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq?amount=0.005&label=Spark%20Store&message=Invoice%20%239001The address portion supports all standard Bitcoin address types, including legacy (P2PKH), SegWit (bech32), and Taproot (P2TR) addresses.
Unified QR Codes and BIP-321
The original BIP-21 scheme was designed for on-chain payments only. As the Lightning Network grew, merchants and wallets needed a way to accept both on-chain and Lightning payments from a single QR code. This led to the development of unified payment URIs.
BIP-321 formalizes this pattern by defining additional query parameters for Lightning and other payment methods:
| Parameter Key | Payment Method | Description |
|---|---|---|
lightning | BOLT 11 | A Lightning Network invoice for one-time payments |
lno | BOLT 12 | A reusable Lightning offer for recurring or static payments |
sp | Silent Payments | A BIP-352 silent payment address for on-chain privacy |
BIP-321 also allows the Bitcoin address to be omitted entirely, as long as at least one payment instruction exists in the query parameters. This means a URI like bitcoin:?lno=lno1... is valid for Lightning-only payments.
How Wallets Parse Unified URIs
When a wallet scans a unified QR code, it reads the full URI and selects the best payment method it supports:
- If the wallet supports Lightning and a
lightningorlnoparameter is present, it pays via Lightning for instant settlement - If the wallet is on-chain only, it falls back to the Bitcoin address in the path and creates a standard on-chain transaction
- If the wallet supports silent payments and an
spparameter is present, it can use that for enhanced privacy
This graceful degradation ensures that a single QR code works for every Bitcoin wallet, regardless of which protocols it supports. For a deeper look at how this works in practice, see Unified QR Codes for Bitcoin.
Unified URI Example
bitcoin:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq?amount=0.001&lightning=lnbc1m1pj...&lno=lno1qgs...This single URI contains an on-chain fallback address, a BOLT 11 invoice for immediate Lightning payment, and a BOLT 12 offer. Wallets like BTCPay Server, Phoenix, BlueWallet, and Zeus all support decoding unified BIP-21 URIs.
Use Cases
Merchant Point-of-Sale
Retail merchants display a QR code at checkout, and the customer scans it to pay. The URI pre-fills the exact amount and a label identifying the merchant. With unified URIs, the same QR code works whether the customer uses an on-chain wallet or a Lightning wallet. Payment processors like BTCPay Server generate these URIs automatically for every invoice.
Payment Links and Invoicing
Online merchants embed Bitcoin URIs as clickable links in invoices, emails, and websites. When a user clicks the link, their desktop or mobile wallet opens with the payment details pre-populated. This is especially useful for payment links shared via messaging apps or social media, where manual address entry would be impractical.
Donation Pages and Tip Jars
Content creators and nonprofits embed Bitcoin URI QR codes on their websites. Using BIP-321 with a BOLT 12 lno parameter, they can create static, reusable donation QR codes that support instant Lightning payments without needing to generate a new invoice for each visitor.
Wallet Interoperability
Bitcoin URIs serve as a universal interchange format between wallets and applications. Any application that needs to request a payment can generate a URI, and any wallet that handles the bitcoin: scheme can process it. This decoupling means payment requesters do not need to know which wallet the sender uses.
Comparison with Other Payment Formats
Bitcoin URIs are one of several payment request formats in the Bitcoin ecosystem. Each serves a different purpose:
| Format | Layer | Reusable | Expiry |
|---|---|---|---|
| BIP-21/321 URI | On-chain (with Lightning extensions) | Yes (address-only URIs) | None (unless Lightning parameter expires) |
| BOLT 11 | Lightning | No (single use) | Yes (typically 1 hour) |
| BOLT 12 | Lightning | Yes (offers are static) | Optional |
| LNURL | Lightning (HTTP-based) | Yes | Server-defined |
The key advantage of BIP-21/321 URIs is their ability to wrap multiple formats into a single string. Rather than choosing between BOLT 11 and an on-chain address, a merchant can include both. For a detailed comparison, see the Bitcoin Payment Protocol Comparison tool.
Risks and Considerations
Address Verification
Users should always verify the address displayed by their wallet before confirming a payment. Malware can intercept clipboard contents or tamper with QR codes to substitute a malicious address. This is a form of address poisoning that bypasses the convenience of URI-based payments.
Amount Formatting Errors
The amount parameter is denominated in BTC, not satoshis. A decimal point error can result in sending 1,000x more than intended. For example, amount=1 means 1 BTC (not 1 satoshi). Comma separators like amount=1,000 are invalid and will be rejected by compliant wallets, but non-compliant implementations could misparse them.
Expiration and Staleness
On-chain Bitcoin URIs do not expire: a QR code printed on a receipt remains valid indefinitely. However, if the URI includes a Lightning lightning parameter, that BOLT 11 invoice will expire (typically within one hour). Users scanning an old unified QR code may find the Lightning option unavailable while the on-chain fallback still works.
Privacy Implications
Reusing the same Bitcoin URI (and thus the same address) for multiple payments creates address reuse, which degrades privacy by allowing observers to link payments together. For privacy-sensitive use cases, BIP-321's silent payment parameter (sp) or generating a fresh address per request mitigates this risk.
Why It Matters
Bitcoin URIs bridge the gap between raw blockchain addresses and user-friendly payment experiences. Without them, every Bitcoin payment would require manually copying a 42-62 character address and separately entering an amount: a process prone to errors and hostile to non-technical users.
The evolution from BIP-21 to BIP-321 reflects the broader trend toward unified payment experiences in Bitcoin. Rather than forcing users to choose between on-chain and Lightning before scanning a QR code, unified URIs let the wallet make the optimal choice automatically. Platforms like Spark leverage this standard to provide seamless payment experiences where users interact with a single QR code regardless of the underlying settlement layer.
This glossary entry is for informational purposes only and does not constitute financial or investment advice. Always do your own research before using any protocol or technology.