A phone on a desk stand beside everyday belongings in a sunlit coastal setting, editorial illustration
BIP 321 / PAYMENTS

Modern Bitcoin payment links.

The replacement for BIP 21 documents current bitcoin: URI usage and extensible payment instructions.

Read the explanation
← All standards

Why it exists

BIP 321 updates the bitcoin: payment-link convention for modern wallets. It replaces BIP 21 while preserving its core purpose: carrying payment instructions in a clickable link or QR code that a wallet can review and act on with the user’s authorisation.

How it works

The address field can contain a recognised on-chain address or be empty when a query parameter supplies payment instructions. Defined options include lightning for BOLT 11 invoices, lno for BOLT 12 offers and sp for Silent Payments. Query keys are case-insensitive; their values may not be.

The amount field remains denominated in BTC. A wallet must reject unknown required parameters, marked with req-, instead of silently discarding them. It must also distinguish the available payment methods and ensure the user understands which one is being used.

PUT IT IN CONTEXT

A practical example

For illustration, a request could contain an ordinary on-chain destination plus a Lightning invoice for the same purchase. A compatible wallet can offer the supported route. A recipient wanting no static on-chain fallback can instead publish a URI whose payment instructions are entirely in its query parameters.

What to keep in mind

Compatibility is per payment method. Reading a bitcoin: link does not prove support for every contained option, nor does it establish the recipient’s identity. Multiple instructions need consistent amounts and expiry handling, and opening a link should not silently send funds.

Status & implementation

BIP 321 is Complete and replaces the Closed BIP 21 document. It documents modern URI behaviour and links a reference parser implementation. This is an application convention, not a change to Bitcoin’s consensus rules.

Specification status: Complete · Sources checked 13 November 2026

Read the sources

Put the standard in context.

Explore the practical guide

Find your next answer.

Search the complete field guide · Esc to close