# BIP-321 (Bitcoin unified QR)

> Source: https://docs.barcoder.ai/docs/standards/bip-321
> research date 2026-06-04 · extracted at 2026-10-03
> Publisher: Barcoder — encyclopedia of QR, barcode and payment-code standards

Specifications:
- [BIP-321: URI Scheme](https://github.com/bitcoin/bips/blob/master/bip-0321.mediawiki)
- [BIP 321: URI Scheme (bips.dev)](https://bips.dev/321/)

## Overview

**BIP-321** is the modern Bitcoin URI scheme — the intended successor to and replacement for [BIP-21](https://docs.barcoder.ai/docs/standards/bip-21).<sup>[1][1]</sup><sup>[2][2]</sup> It keeps the `bitcoin:` scheme and the `bitcoin:<address>?<params>` shape but generalizes it into a **unified URI** that can carry multiple payment instructions at once: an on-chain address, a Lightning [BOLT11](https://docs.barcoder.ai/docs/standards/bolt11) invoice (`lightning=`), a BOLT12 offer (`lno=`), and a BIP-352 Silent Payment address (`sp=`).<sup>[1][1]</sup> These unified URIs are routinely rendered as a [QR Code](https://docs.barcoder.ai/docs/standards/qr-code) so that one scanned code lets a wallet choose whichever rail it supports.<sup>[1][1]</sup><sup>[3][3]</sup> BIP-321 is explicitly backward-compatible with [BIP-21](https://docs.barcoder.ai/docs/standards/bip-21).<sup>[1][1]</sup>

## History

BIP-321 was authored by **Matt Corallo**, licensed BSD-2-Clause, assigned on 2024-11-15, and carries the status **Complete**, explicitly listing [BIP-21](https://docs.barcoder.ai/docs/standards/bip-21) in its `Replaces` field.<sup>[1][1]</sup> It was proposed via bitcoin/bips PR #1555 ("Replace BIP 21 with a new BIP containing information about more modern usage of it").<sup>[1][1]</sup><sup>[2][2]</sup> The motivation was that recipients increasingly want to offer Lightning (when the sender supports it) or newer formats such as Silent Payments, which had led to ad-hoc use of [BIP-21](https://docs.barcoder.ai/docs/standards/bip-21) query parameters to encode extra payment instructions; BIP-321 codifies that practice and gives forward-looking guidance for adding future instruction types.<sup>[1][1]</sup>

## Technical specification

The URI grammar generalizes [BIP-21](https://docs.barcoder.ai/docs/standards/bip-21):<sup>[1][1]</sup>

```
bitcoinurn   = "bitcoin:" [ bitcoinaddress ] [ "?" bitcoinparams ]
bitcoinparams = bitcoinparam [ "&" bitcoinparams ]
```

**Address-less URIs.** The address part MAY be empty if at least one payment instruction is supplied as a query parameter — so a URI can offer only Lightning or only Silent Payments with no on-chain fallback.<sup>[1][1]</sup>

**Case-insensitivity.** The scheme and parameter *keys* are case-insensitive, which lets a URI be written all-uppercase (`BITCOIN:BC1Q...`) for more efficient [QR Code](https://docs.barcoder.ai/docs/standards/qr-code) encoding.<sup>[1][1]</sup>

**Standard metadata parameters:**<sup>[1][1]</sup>

| Param | Meaning |
|-------|---------|
| `label` | recipient identifier (at most once) |
| `message` | human description (at most once) |
| `amount` | amount in decimal BTC, period separator, no commas |
| `pop` / `req-pop` | proof-of-payment callback URI (at most once) |

**Payment-instruction parameters** (may appear multiple times, giving the wallet choices):<sup>[1][1]</sup>

| Param | Instruction |
|-------|-------------|
| `lightning` | a [BOLT11](https://docs.barcoder.ai/docs/standards/bolt11) invoice |
| `lno` | a BOLT12 offer |
| `sp` | a BIP-352 Silent Payment address |
| `bc` / `tb` | segwit (bech32 / bech32m) addresses |

**`req-` prefix.** Parameters prefixed with `req-` are mandatory; a client that does not understand a `req-` parameter MUST reject the URI (the same forward-compatibility rule as [BIP-21](https://docs.barcoder.ai/docs/standards/bip-21)).<sup>[1][1]</sup> URIs that contain only reusable, non-address-reusing instructions — such as BOLT12 offers or Silent Payments — may be reused by a wallet as it sees fit.<sup>[1][1]</sup>

## Use cases

- **Unified scan-to-pay QR**: a merchant publishes one [QR Code](https://docs.barcoder.ai/docs/standards/qr-code) carrying an on-chain address plus a Lightning instruction; each wallet picks the rail it supports.<sup>[1][1]</sup><sup>[3][3]</sup>
- **Lightning-first or privacy-first receiving**: an address-less URI offers only a BOLT12 offer or a Silent Payment address.<sup>[1][1]</sup>
- **Future payment formats**: the `req-`/parameter model lets new instruction types be added without breaking old parsers.<sup>[1][1]</sup>

## Implementations

- **bitcoin/bips** — the canonical BIP repository hosting BIP-321 (MediaWiki), active 2026.<sup>[1][1]</sup>
- **niteshbalusu11/bip-321** — a BIP-321 parsing and encoding library (TypeScript).<sup>[4][4]</sup>
- Unified-QR tooling and guidance is collected at bitcoinqr.dev, which documents the on-chain + `lightning=` composition.<sup>[3][3]</sup>

## Comparison

- **BIP-321 vs [BIP-21](https://docs.barcoder.ai/docs/standards/bip-21)**: BIP-321 keeps the `bitcoin:` scheme and is backward-compatible — any conforming [BIP-21](https://docs.barcoder.ai/docs/standards/bip-21) implementation should already comply — but generalizes it: it allows an empty address, makes parameter keys case-insensitive, and standardizes multiple/repeatable payment instructions (`lightning`, `lno`, `sp`).<sup>[1][1]</sup>
- **BIP-321 vs bare [BOLT11](https://docs.barcoder.ai/docs/standards/bolt11)**: a [BOLT11](https://docs.barcoder.ai/docs/standards/bolt11) invoice is one Lightning instruction; BIP-321 is the container that can carry that invoice (in `lightning=`) alongside on-chain and Silent-Payment options.<sup>[1][1]</sup>
- **vs Solana Pay / Lightning Address**: BIP-321 embeds concrete payment instructions directly in the URI, whereas [Lightning Address](https://docs.barcoder.ai/docs/standards/lightning-address) and Solana Pay transaction requests resolve an identifier or endpoint over HTTP before payment.<sup>[1][1]</sup><sup>[3][3]</sup>

## Status

BIP-321's specification status is **Complete** (2024).<sup>[1][1]</sup> Per the spec's own guidance, wallet adoption is still progressing: the priority is getting wallets to *scan* (parse) BIP-321 URIs first, after which projects can add *generating* them.<sup>[1][1]</sup>

## Sources

[1]: https://github.com/bitcoin/bips/blob/master/bip-0321.mediawiki
[2]: https://bips.dev/321/
[3]: https://bitcoinqr.dev/
[4]: https://github.com/niteshbalusu11/bip-321

[1] [BIP-321: URI Scheme](https://github.com/bitcoin/bips/blob/master/bip-0321.mediawiki) — bitcoin/bips, 2024
[2] [BIP 321: URI Scheme](https://bips.dev/321/) — bips.dev, 2024
[3] [Unified QRs for Bitcoin](https://bitcoinqr.dev/) — bitcoinqr.dev, 2024
[4] [niteshbalusu11/bip-321](https://github.com/niteshbalusu11/bip-321) — GitHub, 2026

## Deployments

_No country reports mention this standard by name._

## Regions / aggregations not mapped to a single country

- Universal