BIP 0021

  BIP: 21
  Title: URI Scheme
  Author: Nils Schneider <nils.schneider@gmail.com>
          Matt Corallo
  Status: Draft
  Type: Standards Track
  Created: 29-01-2011

This BIP is a modification of an earlier BIP 0020 by Luke Dashjr. BIP 0020 was based off an earlier document by Nils Schneider. The alternative payment amounts in BIP 0020 have been removed.

Abstract

This BIP proposes a URI scheme for making Bitcoin payments.

Motivation

The purpose of this URI scheme is to enable users to easily make payments by simply clicking links on webpages or scanning QR Codes.

Specification

General rules for handling (important!)

Bitcoin clients MUST NOT act on URIs without getting the user's authorization. They SHOULD require the user to manually approve each payment individually, though in some cases they MAY allow the user to automatically make this decision.

Operating system integration

Graphical bitcoin clients SHOULD register themselves as the handler for the "bitcoin:" URI scheme by default, if no other handler is already registered. If there is already a registered handler, they MAY prompt the user to change it once when they first run the client.

BNF grammar

(See also a simpler representation of syntax)

bitcoinurn      = "bitcoin:" bitcoinaddress [ ";version=" bitcoinversion ] [ "?" bitcoinparams ]
bitcoinaddress  = base58 *base58
bitcoinversion  = "1.0"
bitcoinparams   = *bitcoinparam
bitcoinparam    = amountparam | labelparam | messageparam | otherparam
amountparam     = "amount=" *digit [ "." *digit ]
labelparam      = "label=" *pchar
messageparam    = "message=" *pchar
otherparam      = pchar *pchar "=" *pchar

Query Keys

• label: Label for that address (e.g. name of receiver)
• address: bitcoin address
• message: message that shown to the user after scanning the QR code
• size: amount of base bitcoin units (see below)
• (others): optional, for future extensions

Transfer amount/size

If an amount is provided, it must be specified in decimal BTC. I.e. amount=50.00 is treated as 50 BTC.

Bitcoin clients MAY display the amount in any format that is not intended to deceive the user. They SHOULD choose a format that is foremost least confusing, and only after that most reasonable given the amount requested. For example, so long as the majority of users work in BTC units, values should always be displayed in BTC by default, even if mBTC or TBC would otherwise be a more logical interpretation of the amount.

Rationale

Payment identifiers, not person identifiers

Current best practices are that a unique address should be used for every transaction. Therefore, a URI scheme should not represent an exchange of personal information, but a one-time payment.

Accessibility (URI scheme name)

Should someone from the outside happen to see such a URI, the URI scheme name already gives a description. A quick search should then do the rest to help them find the resources needed to make their payment. Other proposed names sound much more cryptic; the chance that someone googles that out of curiosity are much slimmer. Also, very likely, what he will find are mostly technical specifications - not the best introduction to bitcoin.

Forward compatibility

We want URIs generated in 2011 to still work in 2036: think about extensibility. Of course we can make only educated guesses about the future, but don't act as if there is none. This should be the best we can do, but it should not be seen as set in stone. Make it possible for later generations to improve our work, to mend our errors, without breaking the URIs created now.

Appendix

Simpler syntax

This section is non-normative and does not cover all possible syntax. Please see the BNF grammar above for the normative syntax.

[foo] means optional, <bar> are placeholders

bitcoin:<address>[;version=1.0][?amount=<amount>][?label=<label>][?message=<message>]

Examples

Just the address:

bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L

Address with name:

bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?label=Luke-Jr

Request 20.30 BTC to "Luke-Jr":

bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?amount=20.3&label=Luke-Jr

Request 50 BTC with message:

bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?amount=50&label=Luke-Jr&message=Donation%20for%20project%20xyz

Characters must be URI encoded properly.

Reference Implementations

Bitcoin clients

• Bitcoin-Qt supports all valid Bitcoin URIs, with Windows and KDE integration as of commit 70f55355e29c8e45b607e782c5d76609d23cc858.