API Documentation

Search

Balance

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 {{crypto_long}} addresses/xpubs>} POST https://bch.blockonomics.co/api/balance
Request body: {"addr": <Whitespace seperated list of {{crypto_long}} addresses/xpubs>}

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

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

History

Returns transaction history of multiple {{crypto_long}} 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 {{crypto_long}} addresses>} POST https://bch.blockonomics.co/api/searchhistory
Request body: {"addr": <Whitespace seperated list of {{crypto_long}} addresses>}

Example Request curl -d '{"addr":"1JJ5taVeiHcD6DXNkLLfocbHcE9Nzio1qV, 13A1W4jLPP75pzvn2qJ5KyyqG3qPSpb9jM"}' https://www.blockonomics.co/api/searchhistory curl -d '{"addr":"qz7m2j5qu2u5434qyxgqarq3xkc7w2dc9y5qdhy2v8, qqt6g6wul02yakpt05amm0hey67lhh7wagrrqxcmys"}' https://bch.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"}]} {"pending": [], "history": [{"time": 1495517482, "addr": ["qqt6g6wul02yakpt05amm0hey67lhh7wagrrqxcmys"], "value": 4532403, "txid": "98120f3d9834dc61839339123001717218428397ea8ab48412e53aa2bb8fbd64"}, {"time": 1443475345, "addr": ["qz7m2j5qu2u5434qyxgqarq3xkc7w2dc9y5qdhy2v8"], "value": -497100500, "txid": "ff6e8e30537908e60fc41552cf639df1332f74539cd666c7f429ec2ecd983510"}, {"time": 1443423780, "addr": ["qz7m2j5qu2u5434qyxgqarq3xkc7w2dc9y5qdhy2v8"], "value": 497100500, "txid": "5e4e03748327a22288623b02dab1721ac9f8082c7294aaa7f9581be49dced2c5"}, {"time": 1231660825, "addr": ["qqt6g6wul02yakpt05amm0hey67lhh7wagrrqxcmys"], "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> GET https://bch.blockonomics.co/api/tx_detail?txid=<txid>

Example Request curl https://www.blockonomics.co/api/tx_detail?txid=5e4e03748327a22288623b02dab1721ac9f8082c7294aaa7f9581be49dced2c5 curl https://bch.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} {"status": "Confirmed", "fee": 10000, "vout": [{"value": 497100500, "address": "qz7m2j5qu2u5434qyxgqarq3xkc7w2dc9y5qdhy2v8"}, {"value": 1256580430, "address": "qr80vemqsff95jc92exfdglxkr5z0gwze5sknhmjgr"}], "vin": [{"value": 1753690930, "address": "qqjarp8wquedxt4yr5yv9c3fhh49adwwvyawqun2q8"}], "time": 1443423780, "size": 258}

Transaction Receipt

Transaction receipt is an easy to share permalink for any {{crypto_long}} 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> https://bch.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 For same transaction, here is the payer receipt and here is the payee receipt

Limits

You can query max 100 addresses at a time. Please limit API calls to 2 requests/min. Higher rates can lead to banning of your IP.

Wallet Watcher

API Key

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

Insert/Update/Delete

Use this to insert/modify bitcoin address you want monitor

Use this to insert/modify bitcoin cash address 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>} POST https://bch.blockonomics.co/api/address
Request body: {"addr": <bitcoin cash address/xpub>, "tag":<tag name>}

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

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

Get

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

Use this to get balances of bitcoin cash 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 GET https://bch.blockonomics.co/api/address

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

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

Payments


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.

Using payments API you can easily receive bitcoin cash payments into your own bitcoin cash wallet. It enables you to quickly start accepting bitcoin cash payments on your website. To get started add your xpub into wallet watcher and also generate api key from settings.

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 not increment index and will keep giving last generated address. It 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 POST https://bch.blockonomics.co/api/new_address
POST https://bch.blockonomics.co/api/new_address?reset=1
POST https://bch.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 curl -d '' -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU' https://bch.blockonomics.co/api/new_address
curl -d '' -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU' https://bch.blockonomics.co/api/new_address?reset=1
curl -d '' -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU' https://bch.blockonomics.co/api/new_address?match_account=6D9qFC Example Response {"address": "qz7m2j5qu2u5434qyxgqarq3xkc7w2dc9y5qdhy2v8"}
{"address": "qz7m2j5qu2u5434qyxgqarq3xkc7w2dc9y5qdhy2v8", "reset": 1}
{"address": "qz7m2j5qu2u5434qyxgqarq3xkc7w2dc9y5qdhy2v8", "account": "xpub6D9qFCtaxyyP3aAMy..."} 


<?php
$api_key = 'INSERT_API_KEY_HERE';
$url = 'https://www.blockonomics.co/api/new_address';

$options = array( 
    'http' => array(
        'header'  => 'Authorization: Bearer '.$api_key,
        'method'  => 'POST',
        'content' => '',
        'ignore_errors' => true
    )   
);  

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

// Check if address was generated successfully
if (isset($object->address)) {
  echo $object->address;
} else {
  // Show any possible errors
  echo $http_response_header[0]."\n".$contents;
}
        
                    
                    
<?php
$api_key = 'INSERT_API_KEY_HERE';
$url = 'https://bch.blockonomics.co/api/new_address';

$options = array( 
    'http' => array(
        'header'  => 'Authorization: Bearer '.$api_key,
        'method'  => 'POST',
        'content' => '',
        'ignore_errors' => true
    )   
);  

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

// Check if address was generated successfully
if (isset($object->address)) {
  echo $object->address;
} else {
  // Show any possible errors
  echo $http_response_header[0]."\n".$contents;
}
        
                    

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)
if r.status_code == 200:
  address = r.json()['address']
  print ('Payment receiving address ' + address)
else:
  print(r.status_code, r.text)
                    
                    
import requests
api_key = 'INSERT_API_KEY_HERE';
url = 'https://bch.blockonomics.co/api/new_address';

headers = {'Authorization': "Bearer " + api_key}
r = requests.post(url, headers=headers)
if r.status_code == 200:
  address = r.json()['address']
  print ('Payment receiving address ' + address)
else:
  print(r.status_code, r.text)
                    

const https = require('https');
const api_key = 'INSERT_API_KEY_HERE'

const options = {
  hostname: 'blockonomics.co',
  port: 443,
  path: '/api/new_address',
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + api_key,
    'Content-Type': 'application/json'
  }
}

const req = https.request(options, (res) => {
  console.log(`statusCode: ${res.statusCode}`)

  res.on('data', (d) => {
    process.stdout.write(d)
  })
})

req.on('error', (error) => {
  console.error(error)
})

req.write('')
req.end()
                    
                    
const https = require('https');
const api_key = 'INSERT_API_KEY_HERE'

const options = {
  hostname: 'bch.blockonomics.co',
  port: 443,
  path: '/api/new_address',
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + api_key,
    'Content-Type': 'application/json'
  }
}

const req = https.request(options, (res) => {
  console.log(`statusCode: ${res.statusCode}`)

  res.on('data', (d) => {
    process.stdout.write(d)
  })
})

req.on('error', (error) => {
  console.error(error)
})

req.write('')
req.end()

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 


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

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

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

$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);
$stmt->execute();

?>

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

Use this to get realtime notification of payment on your bitcoin cash address (Suitable for client side/browser notification). Parameters: addr is your bitcoin cash 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> Websocket connection to wss://bch.blockonomics.co/payment/<addr>?timestamp=<unix_timestamp>

Example Request var wsuri = "wss://www.blockonomics.co/payment/189CEMECgP36iXpCKQoBbRQn3dTCUPi5dm?timestamp=1470371384" var wsuri = "wss://bch.blockonomics.co/payment/qz7m2j5qu2u5434qyxgqarq3xkc7w2dc9y5qdhy2v8?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->Options>Order Hook URL)

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

Status Values:

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

Custom Data in Order

You can insert custom data on Order submission that can be fetched back via Get Order. This can be used to record subscriber/customer id pertaining to your website.

Specify this using the data-extra attribute for the button. You can change this attribute via JS and it will be picked up before form submission <a href="" class="blockoPayBtn" data-toggle="modal" data-extra="userid-91231" data-uid="f7570454529a11e7">

For a detailed tutorial on how to use custom data and accepting bitcoin for subscriptions, you can see this video

Button with Dynamic Price

If your site has an existing cart system, you can use a dynamic button on your checkout page. Just set the total cart value as the price of the button on checkout

Specify this using the data-price attribute for the button. You can change this attribute via JS and it will be picked up before form submission.Note: You need to have Donation Mode checked on for your button for this to work <a href="" class="blockoPayBtn" data-toggle="modal" data-price="1520" data-uid="f7570454529a11e7">

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.

You can test payment integration without spending any bitcoin cash! By using Merchant > Logs, you can simulate test payments to your bitcoin cash address. These test payment notifications are sent 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 all major API calls
  • 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.