|
|
---------------------------------------------------
|
|
|
BIP: 21
|
|
|
Title: URI Scheme
|
|
|
Author: Nils Schneider <nils.schneider@gmail.com>
|
|
|
Matt Corallo <bip21@bluematt.me>
|
|
|
Status: Accepted
|
|
|
Type: Standards Track
|
|
|
Created: 2012-01-29
|
|
|
---------------------------------------------------
|
|
|
|
|
|
This BIP is a modification of an earlier link:bip-0020.mediawiki[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]]
|
|
|
Abstract
|
|
|
~~~~~~~~
|
|
|
|
|
|
This BIP proposes a URI scheme for making Bitcoin payments.
|
|
|
|
|
|
[[motivation]]
|
|
|
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]]
|
|
|
Specification
|
|
|
~~~~~~~~~~~~~
|
|
|
|
|
|
[[general-rules-for-handling-important]]
|
|
|
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]]
|
|
|
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.
|
|
|
|
|
|
[[general-format]]
|
|
|
General Format
|
|
|
^^^^^^^^^^^^^^
|
|
|
|
|
|
Bitcoin URIs follow the general format for URIs as set forth in RFC
|
|
|
3986. The path component consists of a bitcoin address, and the query
|
|
|
component provides additional payment options.
|
|
|
|
|
|
Elements of the query component may contain characters outside the valid
|
|
|
range. These must first be encoded according to UTF-8, and then each
|
|
|
octet of the corresponding UTF-8 sequence must be percent-encoded as
|
|
|
described in RFC 3986.
|
|
|
|
|
|
[[abnf-grammar]]
|
|
|
ABNF grammar
|
|
|
^^^^^^^^^^^^
|
|
|
|
|
|
(See also link:#Simpler_syntax[a simpler representation of syntax])
|
|
|
|
|
|
`bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]` +
|
|
|
`bitcoinaddress = *base58` +
|
|
|
`bitcoinparams = bitcoinparam [ "&" bitcoinparams ]` +
|
|
|
`bitcoinparam = [ amountparam / labelparam / messageparam / otherparam / reqparam ]` +
|
|
|
`amountparam = "amount=" *digit [ "." *digit ]` +
|
|
|
`labelparam = "label=" *qchar` +
|
|
|
`messageparam = "message=" *qchar` +
|
|
|
`otherparam = qchar *qchar [ "=" *qchar ]` +
|
|
|
`reqparam = "req-" qchar *qchar [ "=" *qchar ]`
|
|
|
|
|
|
Here, "qchar" corresponds to valid characters of an RFC 3986 URI query
|
|
|
component, excluding the "=" and "&" characters, which this BIP takes as
|
|
|
separators.
|
|
|
|
|
|
The scheme component ("bitcoin:") is case-insensitive, and
|
|
|
implementations must accept any combination of uppercase and lowercase
|
|
|
letters. The rest of the URI is case-sensitive, including the query
|
|
|
parameter keys.
|
|
|
|
|
|
[[query-keys]]
|
|
|
Query Keys
|
|
|
^^^^^^^^^^
|
|
|
|
|
|
* label: Label for that address (e.g. name of receiver)
|
|
|
* address: bitcoin address
|
|
|
* message: message that describes the transaction to the user
|
|
|
(link:#Examples[see examples below])
|
|
|
* size: amount of base bitcoin units (link:#Transfer_amount/size[see
|
|
|
below])
|
|
|
* (others): optional, for future extensions
|
|
|
|
|
|
[[transfer-amountsize]]
|
|
|
Transfer amount/size
|
|
|
++++++++++++++++++++
|
|
|
|
|
|
If an amount is provided, it MUST be specified in decimal BTC. All
|
|
|
amounts MUST contain no commas and use a period (.) as the separating
|
|
|
character to separate whole numbers and decimal fractions. I.e.
|
|
|
amount=50.00 or amount=50 is treated as 50 BTC, and amount=50,000.00 is
|
|
|
invalid.
|
|
|
|
|
|
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]]
|
|
|
Rationale
|
|
|
~~~~~~~~~
|
|
|
|
|
|
[[payment-identifiers-not-person-identifiers]]
|
|
|
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]]
|
|
|
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]]
|
|
|
Forward compatibility
|
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
Variables which are prefixed with a req- are considered required. If a
|
|
|
client does not implement any variables which are prefixed with req-, it
|
|
|
MUST consider the entire URI invalid. Any other variables which are not
|
|
|
implemented, but which are not prefixed with a req-, can be safely
|
|
|
ignored.
|
|
|
|
|
|
[[backward-compatibility]]
|
|
|
Backward compatibility
|
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
As this BIP is written, several clients already implement a bitcoin: URI
|
|
|
scheme similar to this one, however usually without the additional
|
|
|
"req-" prefix requirement. Thus, it is recommended that additional
|
|
|
variables prefixed with req- not be used in a mission-critical way until
|
|
|
a grace period of 6 months from the finalization of this BIP has passed
|
|
|
in order to allow client developers to release new versions, and users
|
|
|
of old clients to upgrade.
|
|
|
|
|
|
[[appendix]]
|
|
|
Appendix
|
|
|
~~~~~~~~
|
|
|
|
|
|
[[simpler-syntax]]
|
|
|
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>[?amount=<amount>][?label=<label>][?message=<message>]`
|
|
|
|
|
|
[[examples]]
|
|
|
Examples
|
|
|
^^^^^^^^
|
|
|
|
|
|
Just the address:
|
|
|
|
|
|
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W`]
|
|
|
|
|
|
Address with name:
|
|
|
|
|
|
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?label=Luke-Jr[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?label=Luke-Jr`]
|
|
|
|
|
|
Request 20.30 BTC to "Luke-Jr":
|
|
|
|
|
|
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=20.3&label=Luke-Jr[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=20.3&label=Luke-Jr`]
|
|
|
|
|
|
Request 50 BTC with message:
|
|
|
|
|
|
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=50&label=Luke-Jr&message=Donation%20for%20project%20xyz[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=50&label=Luke-Jr&message=Donation%20for%20project%20xyz`]
|
|
|
|
|
|
Some future version that has variables which are (currently) not
|
|
|
understood and required and thus invalid:
|
|
|
|
|
|
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?req-somethingyoudontunderstand=50&req-somethingelseyoudontget=999[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?req-somethingyoudontunderstand=50&req-somethingelseyoudontget=999`]
|
|
|
|
|
|
Some future version that has variables which are (currently) not
|
|
|
understood but not required and thus valid:
|
|
|
|
|
|
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?somethingyoudontunderstand=50&somethingelseyoudontget=999[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?somethingyoudontunderstand=50&somethingelseyoudontget=999`]
|
|
|
|
|
|
Characters must be URI encoded properly.
|
|
|
|
|
|
[[reference-implementations]]
|
|
|
Reference Implementations
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
[[bitcoin-clients]]
|
|
|
Bitcoin clients
|
|
|
^^^^^^^^^^^^^^^
|
|
|
|
|
|
* Bitcoin-Qt supports the old version of Bitcoin URIs (ie without the
|
|
|
req- prefix), with Windows and KDE integration as of commit
|
|
|
70f55355e29c8e45b607e782c5d76609d23cc858.
|
|
|
|
