Skip to content
barcoder

Standards/bip-21

BIP-21

TypeQR Data Format
Completeness83%high

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. 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] 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] In modern usage the same URI also carries a lightning= parameter holding a bolt11 invoice, enabling a single "unified" QR to be paid either on-chain or over the Lightning Network.[5][6] BIP-21 replaced BIP 20 and has itself been superseded by BIP 321.[1][4]

History

BIP-21 was assigned on 2012-01-29 by Nils Schneider and Matt Corallo and is recorded as Replaces: BIP 20.[1] Its status is "Closed (Superseded by BIP 321)."[1] The original specification covers only on-chain payments — address, amount, label, message, and req- extensibility — and contains no Lightning parameter.[1][2] The lightning= convention emerged later: by 2022 wallets and services such as BTCPay Server, BlueWallet and Wallet of Satoshi began embedding a 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] 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]

Technical specification

ABNF grammar:[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] It follows RFC 3986.[1]
  • Path: the Bitcoin address.[1]
  • amount: decimal BTC; "all amounts MUST contain no commas and use a period (.) as the separating character."[1]
  • label: recipient identifier (e.g. name of receiver).[1]
  • message: transaction description.[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][2]
  • lightning= (modern usage / BIP 321): holds a bolt11 invoice, usually uppercased for QR alphanumeric-mode efficiency.[4][5]

Example URIs:[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]

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]
  • Unified / fallback QR: a single QR carrying both an address and a lightning= bolt11 invoice lets a Lightning-aware wallet pay instantly and a legacy wallet fall back to the on-chain address.[5][6]
  • Wallet interoperability: because every major wallet parses bitcoin: URIs, the scheme is the lingua franca for "scan to pay."[1]

Implementations

  • bitcoin/bips — the canonical spec repository (Wikitext); ~10.8k stars, active 2026.[1][3]
  • bitcoinjs/bip21 — JavaScript encode/decode library for BIP-21 URIs; ~58 stars, active 2026.[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]
  • BTCPay Server, BlueWallet and Wallet of Satoshi are cited as early implementers of the unified-QR lightning= convention.[5]

Comparison

  • BIP-21 vs bolt11: BIP-21 is a thin URI wrapper around an on-chain address; 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][4][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.[5][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]

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][2][4]
  • The bitcoin: scheme keyword is case-insensitive, but everything after it (notably the base58 address) is case-sensitive.[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][4][6]

Sources

1 BIP 21: URI Scheme — bitcoin/bips, 2012 2 BIP 0021 — Bitcoin Wiki, n.d. 3 bitcoinjs/bip21 — GitHub, 2026 4 BIP 321: URI Scheme — bips.dev, 2024 5 Unified QRs for Bitcoin — bitcoinqr.dev, 2024 6 BIP21 URIs with Lightning invoice fallback — support list — GitHub, 2024

Deployments

No country reports mention this standard by name.

Regions / aggregations not mapped to a single country

  • Universal
source · docs/standards/bip-21/index.md