Bitcoin URI scheme
Also covering BIP21 and BIP321
Bitcoin URI scheme encodes a payment instruction in one string: the bitcoin: scheme, an address, and optional parameters such as an amount or a label. BIP21 requires a legacy P2PKH address as the body, but wallets commonly put other address formats there, and the scheme is increasingly used to carry persistent identifiers for silent payments and offers. BIP321 replaced BIP21 in 2025 and is now the recommendation.
BIP21 defines bitcoin: URIs: the scheme, a Bitcoin address, and optional
parameters encoded like an HTTP query string, for example
bitcoin:1Bob...?amount=0.001&label=.... The specification defines the
amount, label and message parameters; later proposals added parameters
for other address formats (such as bech32m=), for payjoin
and for other payment protocols.
The specification requires the body to be a legacy P2PKH address, with other address types passed as parameters. That is not how the scheme is used in practice: wallets routinely put bech32 or bech32m addresses in the body, and some leave the body empty when only an alternative payment protocol is used. The URI is also increasingly used to carry persistent identifiers, such as those for silent payments and offers, which is a different job from naming an address.
In 2024, Josie Baker reopened the question of how the scheme is specified and how it is actually used. BIP321, merged in 2025, proposes a modern URI scheme that describes payment instructions as a set of parameters rather than a single address, and BIP21 has since been marked as replaced by it. BIP21 itself was based on BIP20, which it replaced.
Primary code and documentation
Optech newsletter and website mentions
2025
2024
Previous Topic:
Bech32(m)
Next Topic:
BIP70 payment protocol