Balance

Returns balance and unconfirmed amount(Amount waiting 2 confirmations) of multiple addresses/xpubs. Balance units are in satoshis.
This request now requires an APIKey set in the request header

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"}' -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU' https://www.blockonomics.co/api/balance

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

History

Returns transaction history of multiple bitcoin addresses/xpubs 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.
This request now requires an APIKey set in the request header

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

Example Request curl -d '{"addr":"1JJ5taVeiHcD6DXNkLLfocbHcE9Nzio1qV, 13A1W4jLPP75pzvn2qJ5KyyqG3qPSpb9jM"}' -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU' 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. For unconfirmed transactions an rbf attribute may be returned. 1 value of rbf means Opted-In RBF signalling, 2 value means RBF due to inherited signalling (ancestor tx has RBF flag)

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

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

Example Response {"status": "Confirmed", "fee": 100000, "vout": [{"value": 10000, "address": "1FnQjXQc8F6jyjF8L92yLpnMhSWpw8t8jo"}, {"value": 4824404598, "address": "1AEgdWjJrEbroURgWmPrXkFdzxGxdF7c4G"}, {"value": 899950000, "address": "33wBKF7y471qK9zuWQDHbesnGX8JL5YCbW"}], "vin": [{"value": 5724464598, "address": "1AEgdWjJrEbroURgWmPrXkFdzxGxdF7c4G"}], "time": 1577166893, "size": 257}

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/#/search?q=<txid>&addr=<list of user addreses>

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

Limits

You can query max 100 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.

API Key

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>

Insert/Update/Delete

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

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

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"}]

Basic Info

• Payments API Blog Tutorial

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

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..."}

• PHP
• Python
• NodeJS

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

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");

$header = "Authorization: Bearer " . $api_key;
$headers = array();
$headers[] = $header;
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$contents = curl_exec($ch);
if (curl_errno($ch)) {
  echo "Error:" . curl_error($ch);
}

$responseObj = json_decode($contents);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close ($ch);

if ($status == 200) {
    echo $responseObj->address;
} else {
    echo "ERROR: " . $status . ' ' . $responseObj->message;
}
                    

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)
                    

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()
                    

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
• For unconfirmed transactions an rbf attribute may be returned

Warning about zero confirmations: It is always recommended to wait for atleast one confirmation to deliver your product/service. Sometimes you may want to accept zero confirmation for fast delivery of digital goods. In such cases you should reject unconfirmed payments that have rbf attribute. This is because RBF payments can be easily cancelled or reversed

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

• PHP

 <?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. 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>

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

BTC Price

You can use this endpoint to fetch the current bitcoin to fiat price. Our prices are same as that of BitPay. We support all major fiat currencies. Here is the list of currency codes supported

Definition GET https://www.blockonomics.co/api/price?currency=<currency_code>

Example Request curl https://www.blockonomics.co/api/price?currency=EUR Example Response {"price": 7866.85}

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 Buttons & links>Add a Product. In the below requests you have to set apikey as the Authorization header of the request.

Returns detail of payment button order. order_id is the unique identifier of the order. GET /api/merchant_order/<order_id> 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).

Order Hook

Each new/updated order will be notified using the order hook url. This url can be configured in Blockonomic's Dashboard (Dashboard->Buttons & links->Options>Order Hook URL)

Status Values:

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

Checkouts - Temp Products

Checkouts provide a dynamic way to collect charge from customers and add custom data to your products. This is achieved by creating temporary products via API which can be shown via payment button/link/widget. Few points about temp products:

• Temp product by default inherits all fields from its parent product. You can create a parent product via Buttons
• Temp products are automatically deleted after 7 days. Note that orders received via the temp product will still remain in the system

Definition POST https://www.blockonomics.co/api/create_temp_product
Request body: {"parent_uid":<uid of parent product>,"product_name"(Optional): <name>, "product_description"(Optional):<description>, "value"(Optional):<price of product>, "extra_data"(Optional): <custom data>}
Headers: {Authorization: Bearer APIKey}

Example1 (Cart Checkout)
You have a custom website / e-commerce store. On checkout you want the customer to pay the cart value in bitcoin curl -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU' -d'{"parent_uid": "b5c04c7c395011ea", "product_name": "Order #412", "product_description": "1 Red T-shirt\n2 Khaki Trousers", "value":500}' https://www.blockonomics.co/api/create_temp_product Example2 (Customized Product)
Create a customized product of the selected color/addons curl -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU' -d'{"parent_uid": "b5c04c7c395011ea", "product_description":"Redmi 32GB (Yellow)": "value": 412}' https://www.blockonomics.co/api/create_temp_product Example3 (Attach custom data)
Attach customer userid/special notes to product curl -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU' -d'{"parent_uid": "b5c04c7c395011ea", "extra_data":"user_id-19120"}' https://www.blockonomics.co/api/create_temp_product

Displaying Checkout
API will return a temp product uid like this f7570454529a11e7-1ee5f340. You can set this uid to a payment button/link/widget

Payment Button <a> href="" class="blockoPayBtn" data-toggle="modal" data-uid="f7570454529a11e7-1ee5f340"><img width=160 src="https://www.blockonomics.co/img/pay_with_bitcoin_medium.png"></a> Payment Link https://pay-link.s3.us-west-2.amazonaws.com/index.html?uid=f7570454529a11e7-1ee5f340 Payment Widget <script src="https://blockonomics.co/js/pay_widget.js"></script><script> function pay() { Blockonomics.widget({ msg_area: 'payment_area', uid: 'f7570454529a11e7-1ee5f340', email: 'customer@email.com' }); }

Sending Bitcoin

We provide a self hosting free to use wallet service that you can deploy and use for sending bitcoin. Here are the details:

• Blog
• Github repo

Test Payments

You can test payment integration without spending any bitcoins! By using Test Bench, 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.