BIP 21 Bitcoin Payment URIs Explained and Safely Implemented

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.

Structure of a payment URI

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.

Amount parsing without floating point

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.

Labels and messages are untrusted

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.

Required and optional extensions

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.

User authorisation boundary

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.

Replacement and compatibility

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.

How specialists test it

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.

Conclusion

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.