# BIP-21
> Source: https://docs.barcoder.ai/docs/standards/bip-21
> research date 2026-06-03 · extracted at 2026-10-03
> Publisher: Barcoder — encyclopedia of QR, barcode and payment-code standards
Specifications:
- [BIP 21: URI Scheme (bitcoin/bips)](https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki)
- [BIP 321: URI Scheme (successor)](https://bips.dev/321/)
## Overview
**BIP-21** ("URI Scheme") defines the `bitcoin:` URI scheme used to express a Bitcoin payment request as a clickable link or a [QR Code](https://docs.barcoder.ai/docs/standards/qr-code). Authored by Nils Schneider and Matt Corallo and assigned 2012-01-29, its stated purpose is to let users "easily make payments by simply clicking links on webpages or scanning QR Codes."[1][1] The URI carries a base58 Bitcoin address as its path and optional query parameters — `amount`, `label`, `message` — and an extensibility convention based on a `req-` prefix.[1][1] In modern usage the same URI also carries a `lightning=` parameter holding a [BOLT11](https://docs.barcoder.ai/docs/standards/bolt11) invoice, enabling a single "unified" QR to be paid either on-chain or over the Lightning Network.[5][5][6][6] BIP-21 replaced BIP 20 and has itself been superseded by BIP 321.[1][1][4][4]
## History
BIP-21 was assigned on 2012-01-29 by Nils Schneider and Matt Corallo and is recorded as *Replaces: BIP 20*.[1][1] Its status is "Closed (Superseded by BIP 321)."[1][1] The original specification covers only on-chain payments — address, `amount`, `label`, `message`, and `req-` extensibility — and contains no Lightning parameter.[1][1][2][2] The `lightning=` convention emerged later: by 2022 wallets and services such as BTCPay Server, BlueWallet and Wallet of Satoshi began embedding a [BOLT11](https://docs.barcoder.ai/docs/standards/bolt11) invoice in a `lightning=` query parameter on a `bitcoin:` URI so that a single QR works for both rails, the on-chain address acting as fallback.[5][5] This pattern was formalised in 2024 by **BIP 321** ("a modification and intended replacement of BIP 0021"), authored by Matt Corallo and marked Complete as of 15 November 2024, which generalises the scheme to multiple payment-instruction types (`lightning` for BOLT 11, `lno` for BOLT 12 offers, `sp` for silent payments, `pay` for BIP 351).[4][4]
## Technical specification
ABNF grammar:[1][1]
```
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]
bitcoinaddress = *base58
bitcoinparams = bitcoinparam [ "&" bitcoinparams ]
bitcoinparam = [ amountparam / labelparam / messageparam / otherparam / reqparam ]
amountparam = "amount=" *digit [ "." *digit ]
labelparam = "label=" *qchar
messageparam = "message=" *qchar
otherparam = qchar *qchar [ "=" *qchar ]
reqparam = "req-" qchar *qchar [ "=" *qchar ]
```
- **Scheme**: `bitcoin:` — case-insensitive; the remainder of the URI is case-sensitive.[1][1] It follows RFC 3986.[1][1]
- **Path**: the Bitcoin address.[1][1]
- **`amount`**: decimal BTC; "all amounts MUST contain no commas and use a period (.) as the separating character."[1][1]
- **`label`**: recipient identifier (e.g. name of receiver).[1][1]
- **`message`**: transaction description.[1][1]
- **`req-` prefix**: any parameter prefixed `req-` is required; if a client does not implement a `req-` parameter it "MUST consider the entire URI invalid." Non-`req-` parameters that a client does not implement may be safely ignored. The spec recommends a ~6-month grace period before relying on `req-` in mission-critical use.[1][1][2][2]
- **`lightning=` (modern usage / BIP 321)**: holds a [BOLT11](https://docs.barcoder.ai/docs/standards/bolt11) invoice, usually uppercased for QR alphanumeric-mode efficiency.[4][4][5][5]
Example URIs:[1][1]
```
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=20.3&label=Luke-Jr
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=50&label=Luke-Jr&message=Donation%20for%20project%20xyz
```
Unified on-chain + Lightning example:[5][5]
```
bitcoin:BC1QYLH3U67J673H6Y6ALV70M0PL2YZ53TZHVXGG7U?amount=0.00001&label=sbddesign%3A%20For%20lunch%20Tuesday&lightning=LNBC10U1P3PJ257PP5...
```
## Use cases
- **On-chain payment requests**: merchants and individuals share a `bitcoin:` link or print a QR; the payer's wallet pre-fills address, amount and label.[1][1]
- **Unified / fallback QR**: a single QR carrying both an address and a `lightning=` [BOLT11](https://docs.barcoder.ai/docs/standards/bolt11) invoice lets a Lightning-aware wallet pay instantly and a legacy wallet fall back to the on-chain address.[5][5][6][6]
- **Wallet interoperability**: because every major wallet parses `bitcoin:` URIs, the scheme is the lingua franca for "scan to pay."[1][1]
## Implementations
- **bitcoin/bips** — the canonical spec repository (Wikitext); ~10.8k stars, active 2026.[1][1][3][3]
- **bitcoinjs/bip21** — JavaScript encode/decode library for BIP-21 URIs; ~58 stars, active 2026.[3][3]
- **theDavidCoen/BIP21-URIs-with-Lightning-invoice-fallback** — community matrix tracking wallets/exchanges/ATMs that support `lightning=` in BIP-21; lists Wallet of Satoshi, Phoenix, Muun, Breez, Zeus, BlueWallet, Strike, Cash App, Bitkit, Alby, Sparrow and others.[6][6]
- BTCPay Server, BlueWallet and Wallet of Satoshi are cited as early implementers of the unified-QR `lightning=` convention.[5][5]
## Comparison
- **BIP-21 vs [BOLT11](https://docs.barcoder.ai/docs/standards/bolt11)**: BIP-21 is a thin URI wrapper around an on-chain address; [BOLT11](https://docs.barcoder.ai/docs/standards/bolt11) is a self-contained, signed, bech32-encoded Lightning invoice. They are complementary rather than competing — the unified QR embeds a BOLT11 invoice inside a BIP-21 URI's `lightning=` parameter.[1][1][4][4][5][5]
- **BIP-21 vs BIP-21+lightning (unified)**: the base scheme is on-chain only; the unified extension lets one QR serve both rails, with the on-chain address as fallback for wallets that cannot read [BOLT11](https://docs.barcoder.ai/docs/standards/bolt11).[5][5][6][6]
- **BIP-21 vs BIP-321**: BIP-321 keeps the `bitcoin:` scheme but generalises it to many instruction types (BOLT 11, BOLT 12 `lno`, silent payments `sp`, BIP 351 `pay`), formalising the `lightning=` practice that grew up around BIP-21.[4][4]
## Fun facts
- Although the `lightning=` parameter is now ubiquitous in "unified QR" deployments, it appears nowhere in the original BIP-21 text — it was a community convention later codified by BIP 321.[1][1][2][2][4][4]
- The `bitcoin:` scheme keyword is case-insensitive, but everything after it (notably the base58 address) is case-sensitive.[1][1]
## Status
BIP-21 is "Closed" but remains the in-the-wild standard that essentially every Bitcoin wallet implements for scan-to-pay; its successor BIP 321 (Complete, Nov 2024) extends rather than retires the `bitcoin:` scheme, and the `lightning=` fallback enjoys broad wallet support.[1][1][4][4][6][6]
## Sources
[1]: https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki
[2]: https://en.bitcoin.it/wiki/BIP_0021
[3]: https://github.com/bitcoinjs/bip21
[4]: https://bips.dev/321/
[5]: https://bitcoinqr.dev/
[6]: https://github.com/theDavidCoen/BIP21-URIs-with-Lightning-invoice-fallback-to-on-chain-support
[1] [BIP 21: URI Scheme](https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki) — bitcoin/bips, 2012
[2] [BIP 0021](https://en.bitcoin.it/wiki/BIP_0021) — Bitcoin Wiki, n.d.
[3] [bitcoinjs/bip21](https://github.com/bitcoinjs/bip21) — GitHub, 2026
[4] [BIP 321: URI Scheme](https://bips.dev/321/) — bips.dev, 2024
[5] [Unified QRs for Bitcoin](https://bitcoinqr.dev/) — bitcoinqr.dev, 2024
[6] [BIP21 URIs with Lightning invoice fallback — support list](https://github.com/theDavidCoen/BIP21-URIs-with-Lightning-invoice-fallback-to-on-chain-support) — GitHub, 2024
## Deployments
_No country reports mention this standard by name._
## Regions / aggregations not mapped to a single country
- Universal