Bitcoin Payment URI (BIP 321)

Definition: A Bitcoin payment URI is a bitcoin: link that packages a Bitcoin address and optional payment details so a wallet can prepare a request opened from a link or QR code. BIP 321 updates the earlier BIP 21 format for modern address types and additional payment methods; it does not send a payment by itself.1

Date created BIP 21 was assigned January 29, 2012; BIP 321 was assigned November 15, 2024. 2 1
Protocol specification Read BIP 321
Directories Bitcoin Directory

What the URI contains

A URI starts with the bitcoin: scheme. Its path can contain an on-chain address, while query parameters can add details such as an amount, label, or message. BIP 321 accepts common Base58, bech32, and bech32m address forms. It also permits an empty address field when at least one payment instruction is supplied, allowing a request without an on-chain fallback.1

Payment-instruction keys can point to a Lightning BOLT 11 invoice (lightning), a BOLT 12 offer (lno), a BIP 351 private-payment address (pay), or a BIP 352 Silent Payment address (sp). These are formats the specification describes; wallet support can vary. If an amount is present, it is written as decimal BTC, without commas.1

The req- prefix marks an extension as required. A wallet that does not understand a required parameter must reject the URI; it may ignore an unknown parameter without that prefix. This lets the format add optional fields while avoiding silent misinterpretation of instructions marked essential.1

What a wallet should do

Opening a payment URI should prepare payment details for the user to review. BIP 321 says a Bitcoin client must not act on a URI without the user’s authorization and recommends manual approval of each payment. A link or QR code is therefore an input to a wallet, not evidence that the recipient, amount, or payment method is trustworthy. Verify the details shown by the wallet before approving.1

BIP 321 also defines an optional proof-of-payment return parameter. It can let a wallet open a callback URI after payment with information about the completed payment, subject to the specification’s handling rules. This is an optional extension, not a universal receipt system.1

BIP 21 and BIP 353

BIP 21 proposed the bitcoin: URI scheme for payment links and QR codes. BIP 21 is now closed and marked as superseded by BIP 321. The later specification keeps the URI model while documenting modern address encodings and payment-instruction parameters.2

BIP 353 is a related but separate standard: it stores a BIP 21-style payment URI in a DNS TXT record so a human-readable name can resolve to payment instructions. Its specification requires DNSSEC signatures and says wallets must prefer a direct Bitcoin address or URI when one is available. A BIP 353 name is not itself a BIP 321 query parameter.3

History

  • January 29, 2012: BIP 21, “URI Scheme,” was assigned as a proposed Bitcoin payment URI standard.2
  • February 10, 2024: BIP 353, “DNS Payment Instructions,” was assigned to standardize payment instructions stored in DNS TXT records.3
  • November 15, 2024: BIP 321, “URI Scheme,” was assigned as the replacement specification for BIP 21 and marked Complete in the BIP repository.1

Last updated: 2026-11-11

Related Terms

Related Articles

These broader articles offer context on Bitcoin wallets, network economics, and Bitcoin’s use in financial products; they do not explain BIP 321 itself.

See Also

Sources

  1. Bitcoin Improvement Proposals, “BIP 321: URI Scheme,” assigned November 15, 2024, GitHub, accessed November 11, 2026.
  2. Bitcoin Improvement Proposals, “BIP 21: URI Scheme,” assigned January 29, 2012, closed and superseded by BIP 321, GitHub, accessed November 11, 2026.
  3. Bitcoin Improvement Proposals, “BIP 353: DNS Payment Instructions,” assigned February 10, 2024, GitHub, accessed November 11, 2026.