BIP 0020: Difference between revisions

From Bitcoin Wiki
Jump to navigation Jump to search
BitterTea (talk | contribs)
934 (talk | contribs)
Update BIP text with latest version from https://github.com/bitcoin/bips/blob/b5723035e23896d0/bip-0020.mediawiki
 
(40 intermediate revisions by 11 users not shown)
Line 1: Line 1:
This is about creating a URI scheme for bitcoin.
{{bip}}
Previous discussion was in [http://www.bitcoin.org/smf/index.php?topic=55.0 this forum thread].
{{BipMoved|bip-0020.mediawiki}}
x-btc specification is at [[x-btc]].


==RFC 3986==
<pre>
'''the following is taken from wikipedia'''
  BIP: 20
  Layer: Applications
  Title: URI Scheme
  Author: Luke Dashjr <luke+bip@dashjr.org>
  Comments-Summary: No comments yet.
  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0020
  Status: Replaced
  Type: Standards Track
  Created: 2011-01-10
  License: BSD-2-Clause
</pre>


Internet standard [http://rfc.net/std0066.html STD 66] (also RFC 3986) defines the generic syntax to be used in all URI schemes. Every URI is defined as consisting of four parts, as follows:
BIP 0020 is based off an earlier document by Nils Schneider. '''And has been replaced by BIP 0021'''


<code><nowiki><scheme name> : <hierarchical part> [ ? <query> ] [ # <fragment> ]</nowiki></code>
==Abstract==
This BIP proposes a URI scheme for making Bitcoin payments.


The '''scheme name''' consists of a letter followed by any combination of letters, digits, and the plus ("+"), period ("."), or hyphen ("-") characters; and is terminated by a colon (":").
==Copyright==
This BIP is licensed under the BSD 2-clause license.


The '''hierarchical part''' of the URI is intended to hold identification information hierarchical in nature. Usually this part begins with a double forward slash ("//"), followed by an ''authority'' part and an optional ''path''.
==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.


* The '''authority''' part holds an optional user information part terminated with "@" (e.g. <code><nowiki>username:password@</nowiki></code>), a hostname (i.e. domain name or IP address), and an optional port number preceded by a colon ":".
==Specification==


* The '''path''' part is a sequence of segments (conceptually similar to directories, though not necessarily representing them) separated by a forward slash ("/"). Each segment can contain parameters separated from it using a semicolon (";"), though this is rarely used in practice.
=== General rules for handling (important!) ===


The '''query'''  is an optional part separated with a question mark, which contains additional identification information which is not hierarchical in nature. The query string syntax is not generically defined, but is commonly organized as a sequence of <code><nowiki><key>=<value></nowiki></code> pairs separated by a semicolon<ref>
Bitcoin clients MUST NOT act on URIs without getting the user's authorization.
RFC 1866 section 8.2.1 : by Tim Berners-Lee in 1995 encourages CGI authors to support ';' in addition to '&'.
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.
</ref><ref>
[http://www.w3.org/TR/REC-html40/appendix/notes.html#h-B.2.2 HTML 4.01 Specification: Implementation, and Design Notes]: "CGI implementors support the use of ";" in place of "&" to save authors the trouble of escaping "&" characters in this manner."
</ref><ref>
[http://www.w3.org/MarkUp/html-spec/html-spec_foot.html#FOOT26 Hypertext Markup Language - 2.0]
"CGI implementors are encouraged to support the use of ';' in place of '&' "
</ref> or separated by an ampersand, for example:
Semicolon: <code><nowiki>key1=value1;key2=value2;key3=value3</nowiki></code>
Ampersand: <code><nowiki>key1=value1&key2=value2&key3=value3</nowiki></code>


The '''fragment''' is an optional part separated from the front parts by a hash ("#"). It holds additional identifying information that provides direction to a secondary resource, e.g. a section heading in an article identified by the remainder of the URI.  When the primary resource is an HTML document, the '''fragment''' is often an <code>id</code> attribute of a specific element and web browsers will make sure this element is visible.
=== 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.


==Proposed specification==
=== BNF grammar ===


[] means optional, <> are placeholders
(See also [[#Simpler syntax|a simpler representation of syntax]])


  bitcoin:<address>[?][amount=<size>][&][label=<label>][&][message=<message>]
  bitcoinurn      = "bitcoin:" bitcoinaddress [ ";version=" bitcoinversion ] [ "?" bitcoinparams ]
bitcoinaddress  = base58 *base58
bitcoinversion  = "1.0"
bitcoinparams  = *bitcoinparam
bitcoinparam    = amountparam | labelparam | messageparam | sendparam | otherparam
amountparam    = "amount=" amount
amount         = amountdecimal | amounthex
amountdecimal  = *digit [ "." *digit ] [ "X" *digit ]
amounthex      = "x" *hexdigit [ "." *hexdigit ] [ "X" *hexdigit ]
labelparam      = "label=" *pchar
messageparam    = "message=" *pchar
sendparam      = "send=" *pchar
otherparam      = pchar *pchar "=" *pchar


=== Query Keys ===
=== Query Keys ===
Line 41: Line 58:
*label: Label for that address (e.g. name of receiver)
*label: Label for that address (e.g. name of receiver)
*address: bitcoin address
*address: bitcoin address
*message: optional message that is shown to the user after scanning the QR code
*message: message that shown to the user after scanning the QR code
*size: amount of base bitcoin units (uBTCents/TBCᵇ-- NOT full DecimalBitCoins/BTC nor TonalBitCoins/TBC; see below)
*size: amount of base bitcoin units ([[#Transfer amount/size|see below]])
*send: used to send bitcoin, rather than to request them
*(others): optional, for future extensions


==== Transfer amount/size ====
==== Transfer amount/size ====


If an amount is provided, it may be specified either in decimal or, when prefixed with a single "x" character, hexadecimal.
If an amount is provided, it may be specified either in decimal or, when prefixed with a single "x" character, hexadecimal.
The number SHOULD be followed by "X" <digits> to signify an exponent to the base multiplier.
The number SHOULD be followed by "X" &lt;digits&gt; to signify an exponent to the base multiplier.
That is, "X8" multiplies your number by 100,000,000.
Thus, "X8" multiplies your number by 100,000,000.
For decimal values, this means the standard BTC unit.
For decimal values, this means the standard BTC unit.
For hexadecimal values, this means ᵇTBC units (which are equivalent to 42.94967296 BTC).
For hexadecimal values, this means ᵇTBC units (which are equivalent to 42.94967296 BTC).
Line 54: Line 73:
I.e. amount=50.00 is treated as 50 BTC, and amount=x40 is treated as 40 TBC.
I.e. amount=50.00 is treated as 50 BTC, and amount=x40 is treated as 40 TBC.
When specifying bitcoin base units, "X0" SHOULD be used.
When specifying bitcoin base units, "X0" SHOULD be used.
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|BNF grammar]] above for the normative syntax.
[foo] means optional, &lt;bar&gt; are placeholders
<pre>
bitcoin:<address>[;version=1.0][?amount=<amount>][?label=<label>][?message=<message>][?send=<private key>]
</pre>


=== Examples ===
=== Examples ===


Just the address:
Just the address:
  bitcoin:1KczVqwopWXQdFLe5sNQbpCq7yGSmXx2oo
  bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L


Address with name:
Address with name:
  bitcoin:1KczVqwopWXQdFLe5sNQbpCq7yGSmXx2oo?label=Luke-Jr
  bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?label=Luke-Jr


Request to send 20.30 BTC to Luke-Jr:
Request 20.30 BTC to "Luke-Jr":
  bitcoin:1KczVqwopWXQdFLe5sNQbpCq7yGSmXx2oo?amount=20.3&label=Luke-Jr
  bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?amount=20.3X8&label=Luke-Jr


Request to send 400 TBC to Luke:
Request 400 TBC:
  bitcoin:1KczVqwopWXQdFLe5sNQbpCq7yGSmXx2oo?amount=x400
  bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?amount=x400X4


Request to send 4000 TBC to Luke:
Request 4000 TBC:
  bitcoin:1KczVqwopWXQdFLe5sNQbpCq7yGSmXx2oo?amount=x4X7
  bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?amount=x4X7


Request to send 5 uBTC:
Request 5 uBTC:
  bitcoin:1KczVqwopWXQdFLe5sNQbpCq7yGSmXx2oo?amount=500X0
  bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?amount=5X2


Request to send 50 BTC with message:
Request 50 BTC with message:
  bitcoin:1KczVqwopWXQdFLe5sNQbpCq7yGSmXx2oo?amount=5X9&label=Luke-Jr&message=Donation%20for%20project%20xyz
  bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?amount=50X8&label=Luke-Jr&message=Donation%20for%20project%20xyz
 
Send 1 BTC:
bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?amount=1X8&send=S4b3N3oGqDqR5jNuxEvDwf


Characters must be URI encoded properly.
Characters must be URI encoded properly.


=== BNF syntax ===
===Sending money via private key===
To send a payment to someone else first construct a new keypair. You may want to use a [[mini private key format]], or you may also use a full private key for more security depending on the amount being sent and how long you expect to pass before a claim. Now create and publish a transaction with an output of the amount you wish to send. Use this script in that output:
 
<pre>
<pubkey> OP_CHECKSIG
</pre>
 
Construct an address from the public key. Encode the URI as below:
 
<pre>
bitcoin:<address>?send=<base 58 encoded private key>
</pre>
 
You may optionally include amount or message fields as well. In a wallet to claim money sent this way search for an incoming transaction with the output script form above, where &lt;address&gt; matches the public key in the script. When you find the transaction create a claim transaction with an input script of this form:


  bitcoinurn      = "bitcoin:" bitcoinaddress [ ";version=" bitcoinversion ] [ "?" bitcoinparams ]
<pre>
bitcoinaddress  = FIXME :)
  <sig>
bitcoinversion  = "1.0"
</pre>
bitcoinparams  = *bitcoinparam
 
bitcoinparam    = amountparam | labelparam | messageparam
This claims the money you were sent. Until your claim transaction has confirmed the sender may take their money back.
amountparam    = "amount=" amount
 
amount          = amountdecimal | amounthex
== Reference Implementations ==
amountdecimal  = digits [ "X" digits ]
=== Bitcoin clients ===
amounthex      = "x" hexdigits [ "X" hexdigits ]
* [[Spesmilo]] supports all valid Bitcoin URIs, with Windows and KDE integration
labelparam      = "label=" *uchar
messageparam    = "label=" *uchar


=== Parsing amount ===
=== Parsing amount ===
==== ECMAScript ====
==== ECMAScript ====
<pre>
  reAmount = /^(([\d.]+)(X(\d+))?|x([\da-f]*)(\.([\da-f]*))?(X([\da-f]+))?)$/i;
  reAmount = /^(([\d.]+)(X(\d+))?|x([\da-f]*)(\.([\da-f]*))?(X([\da-f]+))?)$/i;
  function parseAmount(txt) {
  function parseAmount(txt) {
var m = txt.match(reAmount);
    var m = txt.match(reAmount);
return m[5] ? (
    return m[5] ? (
(
        (
parseInt(m[5], 16) +
            parseInt(m[5], 16) +
(m[7] ? (parseInt(m[7], 16) * Math.pow(16, -(m[7].length))) : 0)
            (m[7] ? (parseInt(m[7], 16) * Math.pow(16, -(m[7].length))) : 0)
) * (
        ) * (
m[9] ? Math.pow(16, parseInt(m[9], 16)) : 0x10000
            m[9] ? Math.pow(16, parseInt(m[9], 16)) : 0x10000
)
        )
) : (
    ) : (
m[2]
            m[2]
*
        *
(m[4] ? Math.pow(10, m[4]) : 1e8)
            (m[4] ? Math.pow(10, m[4]) : 1e8)
);
    );
  }
  }
</pre>
==== Python ====
<pre>
m = re.match(r'^(([\d.]+)(X(\d+))?|x([\da-f]*)(\.([\da-f]*))?(X([\da-f]+))?)$', amount, re.IGNORECASE)
if m.group(5):
    amount = float(int(m.group(5), 16))
    if m.group(7):
        amount += float(int(m.group(7), 16)) * pow(16, -(len(m.group(7))))
    if m.group(9):
        amount *= pow(16, int(m.group(9), 16))
    else:
        amount *= 0x10000
else:
    amount = Decimal(m.group(2))
    if m.group(4):
        amount *= 10 ** int(m.group(4))
    else:
        amount *= 100000000
</pre>


==== C# ====
==== C# ====
<pre>
  Regex amountExpression = new Regex(@"^(([\d.]+)(X(\d+))?|x([\da-f]*)(\.([\da-f]*))?(X([\da-f]+))?)$", RegexOptions.IgnoreCase);
  Regex amountExpression = new Regex(@"^(([\d.]+)(X(\d+))?|x([\da-f]*)(\.([\da-f]*))?(X([\da-f]+))?)$", RegexOptions.IgnoreCase);
  Match match = amountExpression.Match(value);
  Match match = amountExpression.Match(value);
Line 123: Line 213:
         if (match.Groups[7].Success)
         if (match.Groups[7].Success)
             hexDecimal = Convert.ToInt64(match.Groups[7].Value, 16) * (long)Math.Pow(16, -match.Groups[7].Length);
             hexDecimal = Convert.ToInt64(match.Groups[7].Value, 16) * (long)Math.Pow(16, -match.Groups[7].Length);
 
         long hexExponent = 0x10000;
         long hexExponent = 0x10000;
         if (match.Groups[9].Success)
         if (match.Groups[9].Success)
             hexExponent = (long)Math.Pow(16, Convert.ToInt32(match.Groups[9].Value, 16));
             hexExponent = (long)Math.Pow(16, Convert.ToInt32(match.Groups[9].Value, 16));
 
         Amount = (Convert.ToInt64(match.Groups[5].Value, 16) + hexDecimal) * hexExponent;
         Amount = (Convert.ToInt64(match.Groups[5].Value, 16) + hexDecimal) * hexExponent;
     }
     }
Line 138: Line 228:
     }
     }
  }
  }
 
</pre>
==Requirements==
 
===Payment identifiers, not person identifiers===
In my opinion, the most basic idea of the URI scheme (as this is a currency) is to facilitate payment. So the URIs should represent first and foremost payments. If it represents something else, this needs to be specified. Thus
<code>
bitcoin:13guMzcGPvdD3qjQvCoNc1w5XAgJ638KaQ
</code>
represents a '''payment''' to me using my bitcoin address, not my bitcoin address itself. So after parsing the URI (via link/qr/whatever) the application should open a transaction window with the address filled in. You then need to add an amount and confirm the payment.
If your application is smart, it will also have a button "just store the address". But the point I am trying to make is that the default use of the URI should be for payment, nor for exchanging addresses.
 
===Accessibility===
'''Imported from the forum:''' I like the simplicity of bitcoin:xxxxxxxxxxxxx and very much approve of its accessibility. Should someone from the outside happen to see such a URI, the protocol name already gives a description. A quick google search should then do the rest. x-btc sounds much more cryptic; the chance that someone googles that out of curiosity are much slimmer. Also, very likely, what s/he will find are mostly technical specifications. Not a good introduction to bitcoin.
 
For the same reason I am for using '&' as a delimiter for key-value pairs. People know it from URLs. Make it easy for people to understand what is going on.
 
===Keep it simple===
Don't explicitly write down information that can be inferred. Don't mark the address as an address. If there is no address, this does lose much of its utility. We could, however, specify 'address' as a reserved word, so that <code>
bitcoin:address?amount=50
</code>
would initiate a transaction with the amount filled in, but with a blank address. I am not convinced that there is a use case, though.
 
===Use-cases===
Before the URI scheme is finalised one should think long and hard about use cases. in what circumstances will which people use this, and for what?
* an online shop has a 'buy this' link, which uses the URI scheme.
**PROBLEM: click on the link opens the application; how does the merchant notice this?
***POSSIBLE SOLUTION: javascript can detect the click.
***POSSIBLE SOLUTION: the checkout site checks its bitcoin account for payment via HTTP request.
**PROBLEM: the time problem (~10 minutes) is very apparent here; nobody wants to wait 10 minutes for the transaction to be confirmed.
* a person only has an online client, no actual application
**PROBLEM: how to redirect the URI so that the online client gets a notice?
***POSSIBLE SOLUTION: Small application and/or browser plugins to redirect the handler call to the designated online wallet.
 
===Backwards compatibility===
We want URIs generated in 2011 to still work in 2036. Think about extensibility. Of course we can make only educated guesses (and nothing more!) 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. Version incompatibility is the easiest thing to drive users crazy: "I just upgraded to this shiny new version. What? It doesn't support the old format? AAAAAAARRRGH!"
 
==References==
<references/>

Latest revision as of 17:59, 24 September 2019

This page describes a BIP (Bitcoin Improvement Proposal).
Please see BIP 2 for more information about BIPs and creating them. Please do not just create a wiki page.

Please do not modify this page. This is a mirror of the BIP from the source Git repository here.

  BIP: 20
  Layer: Applications
  Title: URI Scheme
  Author: Luke Dashjr <luke+bip@dashjr.org>
  Comments-Summary: No comments yet.
  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0020
  Status: Replaced
  Type: Standards Track
  Created: 2011-01-10
  License: BSD-2-Clause

BIP 0020 is based off an earlier document by Nils Schneider. And has been replaced by BIP 0021

Abstract

This BIP proposes a URI scheme for making Bitcoin payments.

Copyright

This BIP is licensed under the BSD 2-clause license.

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 | sendparam | otherparam
amountparam     = "amount=" amount
amount          = amountdecimal | amounthex
amountdecimal   = *digit [ "." *digit ] [ "X" *digit ]
amounthex       = "x" *hexdigit [ "." *hexdigit ] [ "X" *hexdigit ]
labelparam      = "label=" *pchar
messageparam    = "message=" *pchar
sendparam       = "send=" *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)
  • send: used to send bitcoin, rather than to request them
  • (others): optional, for future extensions

Transfer amount/size

If an amount is provided, it may be specified either in decimal or, when prefixed with a single "x" character, hexadecimal. The number SHOULD be followed by "X" <digits> to signify an exponent to the base multiplier. Thus, "X8" multiplies your number by 100,000,000. For decimal values, this means the standard BTC unit. For hexadecimal values, this means ᵇTBC units (which are equivalent to 42.94967296 BTC). If exponent is omitted, implementations SHOULD assume X8 for decimal numbers, and X4 for hexadecimal numbers. I.e. amount=50.00 is treated as 50 BTC, and amount=x40 is treated as 40 TBC. When specifying bitcoin base units, "X0" SHOULD be used.

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>][?send=<private key>]

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.3X8&label=Luke-Jr

Request 400 TBC:

bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?amount=x400X4

Request 4000 TBC:

bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?amount=x4X7

Request 5 uBTC:

bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?amount=5X2

Request 50 BTC with message:

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

Send 1 BTC:

bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?amount=1X8&send=S4b3N3oGqDqR5jNuxEvDwf

Characters must be URI encoded properly.

Sending money via private key

To send a payment to someone else first construct a new keypair. You may want to use a mini private key format, or you may also use a full private key for more security depending on the amount being sent and how long you expect to pass before a claim. Now create and publish a transaction with an output of the amount you wish to send. Use this script in that output:

 <pubkey> OP_CHECKSIG

Construct an address from the public key. Encode the URI as below:

 bitcoin:<address>?send=<base 58 encoded private key>

You may optionally include amount or message fields as well. In a wallet to claim money sent this way search for an incoming transaction with the output script form above, where <address> matches the public key in the script. When you find the transaction create a claim transaction with an input script of this form:

 <sig>

This claims the money you were sent. Until your claim transaction has confirmed the sender may take their money back.

Reference Implementations

Bitcoin clients

  • Spesmilo supports all valid Bitcoin URIs, with Windows and KDE integration

Parsing amount

ECMAScript

 reAmount = /^(([\d.]+)(X(\d+))?|x([\da-f]*)(\.([\da-f]*))?(X([\da-f]+))?)$/i;
 function parseAmount(txt) {
    var m = txt.match(reAmount);
    return m[5] ? (
        (
            parseInt(m[5], 16) +
            (m[7] ? (parseInt(m[7], 16) * Math.pow(16, -(m[7].length))) : 0)
        ) * (
            m[9] ? Math.pow(16, parseInt(m[9], 16)) : 0x10000
        )
    ) : (
            m[2]
        *
            (m[4] ? Math.pow(10, m[4]) : 1e8)
    );
 }

Python

 m = re.match(r'^(([\d.]+)(X(\d+))?|x([\da-f]*)(\.([\da-f]*))?(X([\da-f]+))?)$', amount, re.IGNORECASE)
 if m.group(5):
     amount = float(int(m.group(5), 16))
     if m.group(7):
         amount += float(int(m.group(7), 16)) * pow(16, -(len(m.group(7))))
     if m.group(9):
         amount *= pow(16, int(m.group(9), 16))
     else:
         amount *= 0x10000
 else:
     amount = Decimal(m.group(2))
     if m.group(4):
         amount *= 10 ** int(m.group(4))
     else:
         amount *= 100000000

C#

 Regex amountExpression = new Regex(@"^(([\d.]+)(X(\d+))?|x([\da-f]*)(\.([\da-f]*))?(X([\da-f]+))?)$", RegexOptions.IgnoreCase);
 Match match = amountExpression.Match(value);
 if (match.Success)
 {
     if (match.Groups[5].Success)
     {
         long hexDecimal = 0;
         if (match.Groups[7].Success)
             hexDecimal = Convert.ToInt64(match.Groups[7].Value, 16) * (long)Math.Pow(16, -match.Groups[7].Length);

         long hexExponent = 0x10000;
         if (match.Groups[9].Success)
             hexExponent = (long)Math.Pow(16, Convert.ToInt32(match.Groups[9].Value, 16));

         Amount = (Convert.ToInt64(match.Groups[5].Value, 16) + hexDecimal) * hexExponent;
     }
     else
     {
         long decimalExponent = 100000000;
         if (match.Groups[4].Success)
             decimalExponent = (long)Math.Pow(10, int.Parse(match.Groups[4].Value));
         Amount = (long)(decimal.Parse(match.Groups[2].Value) * decimalExponent);
     }
 }