API Documentation



Returns balance and unconfirmed amount(Amount waiting 2 confirmations) of multiple addresses. Balance units are in satoshis.

Definition POST https://www.blockonomics.co/api/balance
Request body: {"addr": <Whitespace seperated list of bitcoin addresses/xpubs>}

Example Request curl -d '{"addr":"1dice8EMZmqKvrGE4Qc9bUFf9PX3xaYDp 1dice97ECuByXAvqXpaYzSaQuPVvrtmz6"}' https://www.blockonomics.co/api/balance

Example Response {"response": [{"confirmed": 189412205, "addr": "1dice8EMZmqKvrGE4Qc9bUFf9PX3xaYDp", "unconfirmed": 012211 }, {"confirmed": 746599881, "addr": "1dice97ECuByXAvqXpaYzSaQuPVvrtmz6", "unconfirmed": 0}]}


Returns transaction history of multiple bitcoin addresses considering them part of the same wallet. For each transaction following paramters are returned:unix timestamp, txid, net value transacted from wallet in satoshis and subset of address involved in transaction. Transactions are sorted by latest time and a limit of 200 tx are returned. Pending transactions (having less than 2 confirmations) are returned in pending dict with status . Status codes: 0 - Unconfirmed, 1 - Partially Confirmed.

Definition POST https://www.blockonomics.co/api/searchhistory
Request body: {"addr": <Whitespace seperated list of bitcoin addresses>}

Example Request curl -d '{"addr":"1JJ5taVeiHcD6DXNkLLfocbHcE9Nzio1qV, 13A1W4jLPP75pzvn2qJ5KyyqG3qPSpb9jM"}' https://www.blockonomics.co/api/searchhistory

Example Response {"pending": [{"status": 1, "addr": ["1JJ5taVeiHcD6DXNkLLfocbHcE9Nzio1qV"], "time": 1443423780, "value": 497100500, "txid": "5e4e03748327a22288623b02dab1721ac9f8082c7294aaa7f9581be49dced2c5"}], "history": [{"time": 1231660825, "addr": ["13A1W4jLPP75pzvn2qJ5KyyqG3qPSpb9jM"], "value": 5000000000, "txid": "2d05f0c9c3e1c226e63b5fac240137687544cf631cd616fd34fd188fc9020866"}]}

Transaction Detail

Returns detail of input transaction id. List of transaction inputs and outputs are returned. time is the received unix timestamp of transaction, value is the amount of tx input/output in satoshis, fee is the transaction fees in satoshis, size is the transaction size in bytes.

Definition GET https://www.blockonomics.co/api/tx_detail?txid=<txid>

Example Request curl https://www.blockonomics.co/api/tx_detail?txid=5e4e03748327a22288623b02dab1721ac9f8082c7294aaa7f9581be49dced2c5

Example Response {"status": "Confirmed", "fee": 10000, "vout": [{"value": 497100500, "address": "1JJ5taVeiHcD6DXNkLLfocbHcE9Nzio1qV"}, {"value": 1256580430, "address": "1KsKNxMVnFhZaK5Doa6SMTcerPGYorD6M2"}], "vin": [{"value": 1753690930, "address": "14SxzkZ5kVnHTA7pRFzQknwypi7rRYrtG8"}], "time": 1443423780, "size": 107}

Transaction Receipt

Transaction receipt is an easy to share permalink for any bitcoin transaction/payment. User addresses' in the tx are highlighted and net amount is calculated accordingly

Format https://www.blockonomics.co/api/tx?txid=<txid>&addr=<list of user addreses>

Example For same transaction, here is the payer receipt and here is the payee receipt


You can query max 50 addresses at a time. For higher number you should upgrade your plan and set your API Key in http authorization header. Please limit API calls to 2 requests/min. Higher rates can lead to banning of your IP. Bitcoin blocks only arrive at an average rate of once in 10 minutes. So querying multiple times a second won't return you any new data. For realtime transaction updates on address, use our websocket API.

Wallet Watcher


All wallet watcher api requests require apikey for access. To generate apikey goto Wallet Watcher > Settings > Generate new API Key. To use apikey set the Authorization header of the https request. Authorization: Bearer <apikey>


Use this to insert/modify bitcoin address to you want monitor

Definition POST https://www.blockonomics.co/api/address
Request body: {"addr": <bitcoin address/xpub>, "tag":<tag name>}

POST https://www.blockonomics.co/api/delete_address
Request body: {"addr": <bitcoin address/xpub>}

Example Request curl -d '{"addr":"1C1ENNWdkPMyhZ7xTEM4Kwq1FTUifZNCRd", "tag":"mining"}' -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU' https://www.blockonomics.co/api/address


Use this to get balances of bitcoin addresses you are monitoring. Returns: createdon which is the timestamp when address was added into wallet watcher, balance in satoshis, address and tag

Definition GET https://www.blockonomics.co/api/address

Example Request curl -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU' https://www.blockonomics.co/api/address

Example Response [{"createdon": 1424097689.582884, "balance": 0, "tag": "mining", "address": "1AraZwQD3euXSeEJSTEiy8m2GSCvRMVkLY"}, {"createdon": 1442657078.386882, "balance": 5000000000, "tag": "", "address": "1BW18n7MfpU35q4MTBSk8pse3XzQF8XvzT"}]


Using payments API you can easily receive bitcoin payments into your own bitcoin wallet. It enables you to quickly start accepting bitcoin payments on your website. To get started add your xpub into wallet watcher and also generate api key from settings. Feel free to copy code from our open source shopping cart.
Infographic of payments API (Click to expand)

New Address

This will return a new address from your wallet to which the payer must send the payment. This call will increment index on server, so that each time you get a new address. To reset index you can use parameter reset=1. This will reset index to last unused address before generating new address, and is useful for testing purposes.
If you have multiple xpubs under same emailid, you can choose the source xpub using the parameter match_account. This will match given string within your xpub to find matching account

Definition POST https://www.blockonomics.co/api/new_address
POST https://www.blockonomics.co/api/new_address?reset=1
POST https://www.blockonomics.co/api/new_address?match_account=6D9qFC

Example Request curl -d '' -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU' https://www.blockonomics.co/api/new_address
curl -d '' -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU' https://www.blockonomics.co/api/new_address?reset=1
curl -d '' -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU' https://www.blockonomics.co/api/new_address?match_account=6D9qFC
Example Response {"address": "14gaB2Xb7T1gGx65Sy2vdP37oU2TrJHWAA"}
{"address": "13C84DfUxXWsbi5haUc1uYacP9DmXg6bsc", "reset": 1}
{"address": "13C84DfUxXWsbi5haUc1uYacP9DmXg6bsc", "account": "xpub6D9qFCtaxyyP3aAMy..."}

$api_key = 'INSERT_API_KEY_HERE';
$url = 'https://www.blockonomics.co/api/new_address';
$data = '';
//Unique ID of item being sold 
$options = array( 
    'http' => array(
        'header'  => 'Authorization: Bearer '.$api_key,
        'method'  => 'POST',
        'content' => $data

$context = stream_context_create($options);
$contents = file_get_contents($url, false, $context);
$object = json_decode($contents);

$db = new SQLite3('payments_db.sqlite');
//Associate address with itemid in DB
$stmt = $db->prepare("INSERT into payments(invoiceid, addr) values(:invoiceid, :addr)");
$stmt->bindParam(":invoiceid", $invoiceid);
$stmt->bindParam(":addr", $object->address);

echo 'For item#'.$invoiceid. ' waiting for payment on ' . $object->address;

import requests
api_key = 'INSERT_API_KEY_HERE';
url = 'https://www.blockonomics.co/api/new_address';

headers = {'Authorization': "Bearer " + api_key}
r = requests.post(url, headers=headers)
address = r.json()['address']

print ('Payment receiving address ' + address)

HTTP Callback

Blockonomics will send http callback for payments on your address. For each callback following parameters are returned:

  • status is the status of tx. 0-Unconfirmed, 1-Partially Confirmed, 2-Confirmed
  • addr is the receiving address
  • value is the recevied payment amount in satoshis
  • txid is the id of the paying transaction
A callback succeeds when the server returns 200 HTTP status. Callback are retried 7 times with an exponential backoff of 4 seconds. Use Merchant Wizard to configure callback for your server. Your callback url can also contain a secret paramater for additional security.

Example Callback /api/callback_url?status=2&addr=1C3FrYaGgUJ8R21jJcwzryQQUFCWFpwcrL&value=10000&txid=4cb3 0849ffcaf61c0e97e8351cca2a32722ceb6ad5f34e630b4acb7c6dc1e73b

$secret = 'Mabcdas122olkdd';
$txid = $_GET['txid'];
$value = $_GET['value'];
$status = $_GET['status'];
$addr = $_GET['addr'];

//Match secret for security
if ($_GET['secret'] != $secret) {

if ($status != 2) {
//Only accept confirmed transactions

$db = new SQLite3('payments_db.sqlite', SQLITE3_OPEN_READWRITE);

//Mark address in database as paid
$stmt = $db->prepare("UPDATE payments set addr=:addr,txid=:txid,".
                        "value=:value where addr=:addr");
$stmt->bindParam(":addr", $addr);
$stmt->bindParam(":txid", $txid);
$stmt->bindParam(":value", $value);


Payment Notification

Use this to get realtime notification of payment on your bitcoin address (Suitable for client side/browser notification). Parameters: addr is your bitcoin address, timestamp is an optional parameter (default value is current timestamp). Only payments received after the given unix timestamp are notified. It is recommended to set this as the time of checkout/payment request. A websocket message is returned on successful payment containing the following fields:

  • status is the status of tx. 0-Unconfirmed, 1-Partially Confirmed, 2-Confirmed
  • timestamp is the unix timestamp of tx
  • value is the recevied payment amount in satoshis
  • txid is the id of the paying transaction

Definition Websocket connection to wss://www.blockonomics.co/payment/<addr>?timestamp=<unix_timestamp>

Example Request var wsuri = "wss://www.blockonomics.co/payment/189CEMECgP36iXpCKQoBbRQn3dTCUPi5dm?timestamp=1470371384" Example Response {"status": 0, "timestamp": 1470371749, "value": 167377096, "txid": "aed36253434b90e45ded86ccf1729f5d2acd78bd7665c54e62d5000035a8f6d8"} {"status": 1, "timestamp": 1470371749, "value": 167377096, "txid": "aed36253434b90e45ded86ccf1729f5d2acd78bd7665c54e62d5000035a8f6d8"}

Payment Buttons

Below are various API endpoints to get information about orders generated using payment buttons.To use any of these, you need to first create payment buttons at Merchants>Payment Buttons>Create. In the below requests you have to set apikey as the Authorization header of the request.

Get Order

Returns detail of payment button order. address is the bitcoin address of the order

GET /api/merchant_order/<address> Get Order List

Returns list of all payment button orders in descending order of time. You can use limit to restrict the number of records (Default is 500).

GET /api/merchant_orders?limit=<number>

Order Hook

Each new/updated order will be notified using the order hook url. This url can be configured at Blockonomic's merchants page (Merchants->Payment Buttons->Hooks)

Example callback from server <OrderHook_URL>?status=2&addr=1C3FrYaGgUJ8R21jJcwzryQQUFCWFpwcrL

Status Values:

  • -1 : PAYMENT_ERROR (Happens when Paid BTC amount is not matching expected value)
  •  0 : UNPAID
  •  1 : IN_PROCESS
  •  2 : PAID

Test Payments

You can test payment integration without spending any bitcoins! By using Merchant > Logs, you can simulate test payments to your bitcoin address. These test payment notifications are send from our server (following API format), but not actually sent to the bitcoin network.

Client Source Code

Following are examples of source code using blockonomics API in various languages. If you have developed an open source project that uses blockonomics api, feel free to mail us, and we would be happy to include it here.

  • NodeJS: Client library having major API calls developed/maintained by SGS Shankar.
  • Python: Moneywagon is universal bitcoin/altcoin blockchain client library for python. Instead of depending on one service provider, user can choose to sample multiple/random API service.
  • Shopping Cart (PHP): Open source implementation of a web shopping cart using blockonomics API.
  • Prestashop bitcoin plugin: Prestashop payment module to enable bitcoin payments on your website.
  • Wordpress bitcoin plugin: Woocommerce plugin to accept bitcoin payments on your wordpress site.
  • Automated Invoices (Python): Source code to create automated blockonomics bitcoin invoices. Useful for creating recurring / on demand invoices.