My Wallet API - Blockchain.info

The My Wallet API provides a simple interface Merchants can use interact with their wallet. Blockchain.info will decrypt the wallet on our server manipulate it as necessary and re-save. If you will be accessing this API from a server with a static ip address is recommended you enable the IP Lock found in the Security Section of your My Wallet account.

All bitcoin values are in Satoshi i.e. divide by 100000000 to get the amount in BTC. The Base URL for all requests: https://blockchain.info/merchant/$guid/. $guid should be replaced with your My Wallet identifier (found on the login page).

Want to send without a My Wallet account? If you do not have a My Wallet account $guid can be replaced with a hex encoded private key and the password parameters can be omitted.

Making Outgoing Payments

Send bitcoin from your wallet to another bitcoin address. All transactions include a 0.0005 BTC miners fee.

https://blockchain.info/merchant/$guid/payment?password=$main_password&second_password=$second_password&to=$address&amount=$amount&from=$from&shared=$shared&fee=$fee¬e=$note

$main_password Your Main My wallet password
$second_password Your second My Wallet password if double encryption is enabled.
$to Recipient Bitcoin Address.
$amount Amount to send in satoshi.
$from Send from a specific Bitcoin Address (Optional)
shared "true" or "false" indicating whether the transaction should be sent through a shared wallet. Fees apply. (Optional)
$fee Transaction fee value in satoshi (Must be greater than default fee) (Optional)
$note A public note to include with the transaction (Optional)

Response:

{ "message" : "Response Message" , "tx_hash": "Transaction Hash", "notice" : "Additional Message" }

{ "message" : "Sent 0.1 BTC to 1A8JiWcwvpY7tAopUkSnGuEYHmzGYfZPiq" , "tx_hash" : "f322d01ad784e5deeb25464a5781c3b20971c1863679ca506e702e3e33c18e9c" , "notice" : "Some funds are pending confirmation and cannot be spent yet (Value 0.001 BTC)" }

Send Many Transactions

Send a transaction to multiple recipients in the same transaction.

https://blockchain.info/merchant/$guid/sendmany?password=$main_password&second_password=$second_password&recipients=$recipients&shared=$shared&fee=$fee

$main_password Your Main My wallet password
$second_password Your second My Wallet password if double encryption is enabled.
$recipients Is a JSON Object using Bitcoin Addresses as keys and the amounts to send as values (See below).
$from Send from a specific Bitcoin Address (Optional)
$shared "true" or "false" indicating whether the transaction should be sent through a shared wallet. Fees apply. (Optional)
$fee Transaction fee value in satoshi (Must be greater than default fee) (Optional)
$note A public note to include with the transaction (Optional)

{
    "1JzSZFs2DQke2B3S4pBxaNaMzzVZaG4Cqh": 100000000,
    "12Cf6nCcRtKERh9cQm3Z29c9MWvQuFSxvT": 1500000000,
    "1dice6YgEVBf88erBFra9BHf6ZMoyvG88": 200000000
}

The above example would send 1 BTC to 1JzSZFs2DQke2B3S4pBxaNaMzzVZaG4Cqh, 15 BTC to 12Cf6nCcRtKERh9cQm3Z29c9MWvQuFSxvT and 2 BTC to 1dice6YgEVBf88erBFra9BHf6ZMoyvG88 in the same transaction.

Response:

{ "message" : "Response Message" , "tx_hash": "Transaction Hash" }

{ "message" : "Sent To Multiple Recipients" , "tx_hash" : "f322d01ad784e5deeb25464a5781c3b20971c1863679ca506e702e3e33c18e9c" }

PHP Example

<?

$guid="GUID_HERE";
$firstpassword="PASSWORD_HERE";
$secondpassword="PASSWORD_HERE";
$amounta = "10000000";
$amountb = "400000";
$addressa = "1A8JiWcwvpY7tAopUkSnGuEYHmzGYfZPiq";
$addressb = "1ExD2je6UNxL5oSu6iPUhn9Ta7UrN8bjBy";
$recipients = urlencode('{
                  "'.$addressa.'": '.$amounta.',
                  "'.$addressb.'": '.$amountb.'
               }');

$json_url = "http://blockchain.info/merchant/$guid/sendmany?password=$firstpassword&second_password=$secondpassword&recipients=$recipients";

$json_data = file_get_contents($json_url);

$json_feed = json_decode($json_data);

$message = $json_feed->message;
$txid = $json_feed->tx_hash;

?>

Fetching the wallet balance

Fetch the balance of a wallet. This should be used as an estimate only and will include unconfirmed transactions and possibly double spends.

https://blockchain.info/merchant/$guid/balance?password=$main_password

Response:

{ "balance": Wallet Balance in Satoshi }

{ "balance": 1000}

Listing Addresses

List all active addresses in a wallet. Also includes a 0 confirmation balance which should be used as an estimate only and will include unconfirmed transactions and possibly double spends.

https://blockchain.info/merchant/$guid/list?password=$main_password

Response:

{
    "addresses": [
        {
            "balance": 1400938800,
            "address": "1Q1AtvCyKhtveGm3187mgNRh5YcukUWjQC",
            "label": "SMS Deposits",
            "total_received": 5954572400
        },
        {
            "balance": 79434360,
            "address": "1A8JiWcwvpY7tAopUkSnGuEYHmzGYfZPiq",
            "label": "My Wallet",
            "total_received": 453300048335
        },
        {
            "balance": 0,
            "address": "17p49XUC2fw4Fn53WjZqYAm4APKqhNPEkY",
            "total_received": 0
        }
    ]
}

Getting the balance of an address

Retreive the balance of a bitcoin address. Querying the balance of an address by label is depreciated.

https://blockchain.info/merchant/$guid/address_balance?password=$main_password&address=$address&confirmations=$confirmations

$main_password Your Main My wallet password
$address The bitcoin address to lookup
$confirmations Minimum number of confirmations required. 0 for unconfirmed.

Response:

{"balance" : Balance in Satoshi ,"address": "Bitcoin Address", "total_received" : Total Satoshi Received}

{"balance" : 50000000, "address" : "19r7jAbPDtfTKQ9VJpvDzFFxCjUJFKesVZ", "total_received" : 100000000}

Generating a new address

https://blockchain.info/merchant/$guid/new_address?password=$main_password&second_password=$second_password&label=$label

$main_password Your Main My wallet password
$second_password Your second My Wallet password if double encryption is enabled.
$label An optional label to attach to this address. It is recommended this is a human readable string e.g. "Order No : 1234". You May use this as a reference to check balance of an order (documented later)

Response:

{ "address" : "The Bitcoin Address Generated" , "label" : "The Address Label"}

{ "address" : "18fyqiZzndTxdVo7g9ouRogB4uFj86JJiy" , "label":  "Order No : 1234" }

HTTP callbacks are enabled in the notifications section of [Account Settings] in the web interface.

When a payment is received blockchain.info will notify the http URL specified in [Account Settings]. The parameters will be supplied in a http GET request. The callback url is limited to 255 characters in length.

Parameters

value The value of the payment received in satoshi (not including fees). Divide by 100000000 to get the value in BTC.
transaction_hash The transaction hash.
input_address The bitcoin address that received the transaction.
confirmations The number of confirmations of this transaction.
{Custom Parameters} Any parameters included in the callback URL will be past back to the callback URL in the notification.

Expected Response

In order to acknowledge successful processing of the callback the server should respond with the text "*ok*". If the server responds with anything else the callback will be resent again every new block (approximately every 10 minutes) up to 1000 times (1 week).

A notification will never be sent for the same transaction twice once acknowledged with *ok*. It is a good idea to record the transaction hash even if not needed to detect duplicates for logging purposes.

PHP Example

If the callback url provided is https://mystore.com

$transaction_hash = $_GET['transaction_hash'];
$value_in_btc = $_GET['value'] / 100000000;
$address = $_GET['address'];

//Commented out to test, uncomment when live
if ($_GET['test'] == true) {
    return;
}

echo $address . ' received a payment of ' . $value_in_btc . ' transaction hash ' . $transaction_hash;

Check Callback Response Log Enter a Callback URL to view the log of callback attempts

Callback URL:

The URL must be exactly equal to when it was passed to the create address method (including parameters). There is no fuzzy matching.

Callback Security

The server must check the the callback request is being made by blockchain.info by validating the ip address of the requester matches that of the blockchain.info domain.

A secret parameter should be included in the callback URL. When the callback is received the secret parameter should be checked for validity.

Test notifications sent using the "Call the API" tool will include the parameter "test" with a value of "true". Callback processing scripts should always check for this testing flag.

Archiving an address

To improve wallet performance addresses which have not been used recently should be moved to an archived state. They will still be held in the wallet but will no longer be included in the "list" or "list-transactions" calls.

For example if an invoice is generated for a user once that invoice is paid the address should be archived.

Or if a unique bitcoin address is generated for each user, users who have not logged in recently (~30 days) their addresses should be archived.

https://blockchain.info/merchant/$guid/archive_address?password=$main_password&second_password=$second_password&address=$address

$main_password Your Main My wallet password
$second_password Your second My Wallet password if double encryption is enabled.
$address The bitcoin address to archive

Response:

{"archived" : "18fyqiZzndTxdVo7g9ouRogB4uFj86JJiy"}

Unarchive an address

Unarchive an address. Will also restore consolidated addresses (see below).

https://blockchain.info/merchant/$guid/unarchive_address?password=$main_password&second_password=$second_password&address=$address

$main_password Your Main My wallet password
$second_password Your second My Wallet password if double encryption is enabled.
$address The bitcoin address to unarchive

Response:

{"active" : "18fyqiZzndTxdVo7g9ouRogB4uFj86JJiy"}

Consolidating Addresses

Queries to wallets with over 10 thousand addresses will become sluggish especially in the web interface. The auto_consolidate command will remove some inactive archived addresses from the wallet and insert them as forwarding addresses (see receive payments API). You will still receive callback notifications for these addresses however they will no longer be part of the main wallet and will be stored server side.

If generating a lot of addresses it is a recommended to call this method at least every 48 hours. A good value for days is 60 i.e. addresses which have not received transactions in the last 60 days will be consolidated.

https://blockchain.info/merchant/$guid/auto_consolidate?password=$main_password&second_password=$second_password&days=$days

$main_password Your Main My wallet password
$second_password Your second My Wallet password if double encryption is enabled.
$days Addresses which have not received any transactions in at least this many days will be consolidated.

Response:

{ "consolidated" : ["18fyqiZzndTxdVo7g9ouRogB4uFj86JJiy"]}

Common Error Responses

{"error":"Error Decrypting Wallet"}

{"error":"Error decoding private key for address x"}

{"error":"Second password incorrect"}

{"error":"You must provide an address and amount"}

{"error":"Wallet Checksum did not validate. Serious error: Restore a backup if necessary."}

{"error":"Two factor authentication currently not enabled in the Merchant API"}

{"error":"Label must be between 0 & 255 characters"}

{"error":"Error saving wallet"}

{"error":"Wallets are currently restricted to 5000 transactions"}

{"error":"Wallet identifier not found"}

{"error":"Uknown method"}

Blockchain Wallet API Simple API for My Wallet Users to send and receive bitcoin payments.

Making Outgoing Payments

Response:

Send Many Transactions

Response:

PHP Example

Fetching the wallet balance

Response:

Listing Addresses

Response:

Getting the balance of an address

Response:

Generating a new address

Response:

Http Callbacks Processing the callback sent from blockchain.info

Parameters

Expected Response

PHP Example

Check Callback Response Log Enter a Callback URL to view the log of callback attempts

Callback Security

Address Management

Archiving an address

Response:

Unarchive an address

Response:

Consolidating Addresses

Response:

Common Error Responses

An Example In Java