BIP 21 Bitcoin payment URIs explained: parse addresses, amounts and required parameters safely, understand replacement by BIP 321 and test wallet handling.
This guide explains BIP 21 URI Scheme in plain English. It covers the problem behind the BIP, why it matters and whether the proposal is part of Bitcoin today.
BIP 21 URI Scheme: The bitcoin scheme is followed by an address and optional ampersand-separated query parameters. The scheme is case-insensitive while the remaining components retain case-sensitive rules.
A node operator is checking BIP 21 URI Scheme. Implementations must use a real URI parser, validate percent encoding and reject malformed separators rather than splitting arbitrary text casually.
The bitcoin scheme is followed by an address and optional ampersand-separated query parameters. The scheme is case-insensitive while the remaining components retain case-sensitive rules. Implementations must use a real URI parser, validate percent encoding and reject malformed separators rather than splitting arbitrary text casually.
The amount is decimal BTC with a period separator and no commas. A wallet should parse it into integer satoshis with an explicit eight-decimal limit, rejecting negatives, exponent notation, overflow and excess precision. Display units may vary, but the confirmed BTC or satoshi value must not be ambiguous.
label and message help the payer understand a request but are not authenticated by the URI. They can contain encoded text supplied by an attacker. Interfaces should escape them, limit lengths and keep them visually separate from the independently decoded address, amount, fee and network.
Unknown ordinary parameters may be ignored, but an unknown req- parameter makes the entire URI invalid. This rule allows future mandatory semantics without old wallets silently discarding them. Tests must include multiple unknown parameters and confirm that only the required prefix changes acceptance.
The specification says clients must not act without user authorisation and should require manual approval per payment. Protocol-handler registration, QR scanning and clipboard import are entry points, not signing permissions. The final trusted display must show destination, amount, fee and change before approval.
BIP 21 replaced BIP 20 and its record now points to BIP 321 as the modern successor. Wallets need an explicit compatibility matrix rather than assuming all bitcoin URIs mean the same revision. Generate the supported current form while accepting legacy syntax only where tests define the result.
Developers test the proposal with made-up data on an isolated test network. They check normal cases and deliberately invalid cases. Different implementations should reach the same result before anyone relies on the proposal.
BIP 21 URI Scheme: The bitcoin scheme is followed by an address and optional ampersand-separated query parameters.
The bitcoin scheme is followed by an address and optional ampersand-separated query parameters.
The amount is decimal BTC with a period separator and no commas.
label and message help the payer understand a request but are not authenticated by the URI.
BIP 21 made Bitcoin payment links interoperable, but the link remains untrusted input. Safe wallets parse strictly, honour required extensions, convert amounts exactly and require explicit confirmation while planning migration to the applicable successor specification.
Check the current specification status and the documentation for the exact implementation you operate before moving production funds or changing a mining node.
BIP 128 guide to Draft timelock-recovery plan storage, presigned transaction pairs, relative delay, checksums, monitoring, cancellation and reorg safety.
BIP 433 guide to Draft keyless Pay to Anchor outputs, CPFP fee bumping, standardness, ephemeral dust, TRUC anti-pinning and wallet safety.
What is BIP-110? Learn what Bitcoin’s reduced-data soft-fork proposal restricted, why it was controversial and why it later closed.
Join the ASIC Mining Discussion
Members can read and join the discussion
Log in to read comments from other miners. Create a free account if you would like to ask a question or share your experience.
Membership helps us protect the discussion from spam and keep answers useful.