This document describes a way to provide web applications a restricted access to user's Bitcoin wallets.

Introduction

The Bitcoin Wallet API is aimed to provide a uniform, privacy-oriented, restricted access to user's Bitcoin wallets to enable web applications seamless integration with the Bitcoin infrastructure.

The API is designed to provide the smallest possible range of functionality that would enable such integration. The functionality is limited to address generation, data & transaction preparation & signing. Other functionality, such as access to the blockchain, as well as bitcoin & cryptographic primitives are not part of this proposal.

          bitcoin.getWallet(function(w) {
            w.authorizeTransaction(100000000, null, 'Requesting 1 BTC for X', function(auth) {
              var tx = prepareTx(auth.inputs, auth.outputs);
              auth.sign(tx, auth.brodcast);
            })
          })

Security and privacy considerations

Implementation considerations

API Description

Common Types

HexEncodedBinary

HexEncodedBinary contains a hex-encoded binary string.

EncodedTransaction

EncodedTransaction contains a hex-encoded binary representation of a Bitcoin transaction.

Input

readonly attribute HexEncodedBinary txid
Hex-encoded to-be-used transaction hash
readonly attribute unsigned long vout
Non-negative integer indexing an output of the to-be-used transaction
readonly attribute HexEncodedBinary scriptPubKey
Hex-encoded scriptPubKey of the input
readonly attribute unsigned long? amount
Non-negative amount available in this input. Wallet MAY choose to not include it.
readonly attribute unsigned long? confirmations
Number of confirmations available for this input. Wallet MAY choose to not include it.

Output

readonly attribute unsigned long value
Non-negative amount
readonly attribute HexEncodedBinary scriptPubKey
Hex-encoded scriptPubKey

Bitcoin interface

void getWallet (WalletCallback successCallback, optional FailureCallback failureCallback)
Upon user's confirmation, wallet MUST return its interface. Wallet MAY cache the confirmation for a certain period of time for the origin domain only for the sake of convenience.

Wallet interface

const integer AUTHORIZATION_DENIED = 101
Error code used by authorizeTransaction in FailureCallback when the transaction authorization denied. The wallet MUST return this error in case of insufficient funds and MAY notify user about the reason of the authorization denial.
void authorizeTransaction (int amount, DOMTimeStamp? expiration, String? description, TransactionAuthorizationCallback successCallback, optional FailureCallback failureCallback)
Upon user's confirmation, wallet MUST return the transaction authorization. If user's confirmation is not given, wallet MUST return AUTHORIZATION_DENIED error code. In case of insufficient funds, wallet also MUST return AUTHORIZATION_DENIED error code to protect user's privacy.

TransactionAuthorization interface

readonly attribute DOMTimeStamp expiration
Authorization expiration
readonly attribute Uint8Array token
Authorization token
readonly attribute Input[] input
readonly attribute Output[] output
readonly attribute DOMString? description
const integer INVALID_TOKEN = 201
Error code used by sign and broadcast in FailureCallback when the transaction authorization token passed is invalid.
const integer EXPIRED_TOKEN = 202
Error code used by sign and broadcast in FailureCallback when the transaction authorization token passed has expired.
void sign (EncodedTransaction tx, TransactionCallback successCallback, optional FailureCallback failureCallback)
Sign the transaction. Note that the wallet MAY adjust its outputs to modify fees according to the transaction being signed. API users SHOULD verify the transaction's content upon its signature if they want to ensure it is still the same transaction. Wallet MAY ask the user for an additional signing confirmation.
void broadcast (EncodedTransaction tx, BroadcastCallback successCallback, optional FailureCallback failureCallback)
Broadcast the transaction. Wallet MAY ask the user for an additional signing confirmation.

Callbacks

FailureCallback

Any error

WalletCallback

Wallet wallet

TransactionAuthorizationCallback

TransactionAuthorization authorization

TransactionCallback

EncodedTransaction tx

BroadcastCallback

EncodedTransaction tx