Bitcoin URIs

Bitcoin URIs are formed with a Bitcoin address and some optional parameters, such as amount and label.
Example: bitcoin:19mP9FKrXqL46Si58pHdhGKow88SUPy1V8?amount=1&message=donation

You can configure your browser to launch your Bitcoin client when you click a Bitcoin URI.
The following Bitcoin clients currently support Bitcoin URIs: MultiBit and Electrum.

Started with the previous URI, the Electrum client will open its send tab with pre-filled fields [screenshot]

How to configure your browser

Firefox (version 3.5 and above)


To configure Chrome on Ubuntu 10.04 or maybe later versions to handle bitcoin URIs, do this first on the command-line:
$ gconftool-2 -t string -s /desktop/gnome/url-handlers/bitcoin/command "/path/to/ %s"
$ gconftool-2 -t bool -s /desktop/gnome/url-handlers/bitcoin/needs_terminal false
$ gconftool-2 -t bool -s /desktop/gnome/url-handlers/bitcoin/enabled true
This tells Gnome what to do with bitcoin URLs, and Chrome picks that up from Gnome.

Improvement proposals

This section describes improvement proposals that are not supported by the official Bitcoin client at this point.
They can be tested with Electrum (version 0.38).


Bitcoin aliases are pointers to Bitcoin addresses.
Update: In order to be used for signatures, Bitcoin aliases need to have the following properties:
 1.- cannot be hijacked (redirected to another Bitcoin address) by an attacker
 2.- cannot be tampered by their owner (i.e. the owner cannot secretely change their alias and pretend they did not sign something they actually signed). 
Aliases stored on a website and secured by their owner might have property 1, but they do not have the second property. 
I believe that Bitcoin aliases will need to be stored in a blockchain-based storage such as Namecoin or DIANNA.
The proposal below will be updated in order to reflect this.
Aliases may be server names (e.g. or email-like addresses (e.g.
The corresponding Bitcoin address is retrieved by the client, using a descriptor located at a canonical url.

Aliases may be entered in the Electrum client, or used in Bitcoin URIs (see below).

In order to prevent hijacking, aliases may be signed by a trusted authority.

If if the signing key of an alias is unknown, Electrum will ask the user to add it to its list of trusted keys [screenshot].
It will display a warning if the signing key has changed since the previous visit [screenshot].

Unsigned aliases

The descriptor of an unsigned alias contains the target address:

Signed aliases

A trusted authority (auth_name, auth_signing_key) signs a string that contains its name, the alias and the address.
The alias descriptor contains the target address, the authority's name and address, and the signature:
<target_address>:<auth_name>:<btc_address(auth_signing_key)>:<signature(auth_signing_key, auth_name:alias:address)>
Example: Descriptor:

Updating an alias

The target of an alias can be updated without owning the signing key.
The descriptor should include the full history of the target.
Each modification must be signed with the key corresponding to the previous target.
<target_address2>:signature(key_of_address1, alias:address2)> 
<target_address3>:signature(key_of_address2, alias:address3)> 
Example: Descriptor:

Signed URIs:

NOTE: the purpose of this proposal is not to protect merchants against attackers, but to protect customers against malicious merchants pretending they have not been paid.

Merchants typically use various receiving addresses to keep track of incoming orders. This has a drawback for customers: customers cannot prove that they are sending funds to the right person.
Signed URIs are bitcoin URIs that are signed with a key associated to the online reputation of the merchant. After payment, a signed URI is a proof that the owner of the signing key has been paid.

Syntax: bitcoin:<address>?<list_of_parameters>&signature=<identity:signature>
The identity parameter can be an address or an alias.

To generate the signature, bitcoind's signmessage command is used.
$ bitcoind signmessage 19mP9FKrXqL46Si58pHdhGKow88SUPy1V8 "bitcoin:15kfzDMX2Gr7hXrwRQQGkxrd5eBveKH777?amount=1&message=donation"
The signature is url-encoded and added to the URI:

When the user clicks on a signed URI, the Electrum client will display a 'send' tab with fields that are not editable, and it will show the signing address [screenshot]
If the user proceeds with the transaction, the client will archive the signed URI as a proof of payment.
The signature will be visible in the details of the transaction [screenshot].

If the signature verification fails, the client should display a warning.
Example (tampered signature): Pay here!

The signing identity can be an alias.
Example: bitcoin:15kfzDMX2Gr7hXrwRQQGkxrd5eBveKH777?amount=50&message=how%20are%20you&
In that case the Electrum client will display the alias instead of the key [screenshot]