Real-Time Notifications

Block.io updates you in real-time when your wallet addresses' balances change for Bitcoin, Dogecoin, and Litecoin. This features opens up a vast variety of ways you can integrate digital currencies in your applications, and we can't wait to see how you use these notifications.

We provide real-time notifications through Web Hooks, and Web Sockets:

  • Through Web Hooks, we push data to you through HTTP Post requests to web servers of your choice.
  • Through Web Sockets, you subscribe to updates while staying connected to a Block.io Notifications server.

The following document provides more details on each of these mechanisms.

Web Hooks

You can start using Web Hooks by creating a Notification on your Block.io account below. Keep in mind, however, that since we are pushing data to you, we need a web server of yours to communicate with through POST requests.

Some points of information regarding Web Hooks:

  • All notifications will be issued through n.block.io, so you can whitelist the domain if you use firewalls.
  • The source server (n.block.io) IP can change at any time.
  • Your Web Server must respond with a Status Code of 2xx (i.e., between 200-299) for us to consider the notification successful.
  • Unsuccessful notifications will be retried for ~24 hours with exponential back-off, after which your failing Web Hook will be disabled.
  • Web Hooks are available for Bitcoin, Dogecoin, Litecoin, and Bitcoin/Dogecoin Testnets.
  • All notification events will use JSON objects.

A notification event will use the following structure:

	
{ 
  "notification_id" : "...", // a unique identifier issued when you created the notification
  "delivery_attempt" : 1, // number of times we've tried deliverying this object
  "type" : "...", // the type of notification, helps you understand the data sent below
  "data" : {
    ... // the notification data
  },
  "created_at" : 1426104819 // timestamp of when we created this notification
}	
      

Create a Notification

You can create a Web Hook notification for the following types of events:

  • Account: Consists of balance changes for all your account's addresses for a given Network. Whenever an address' balance changes, this event is fired.
  • Address: This event is fired when balance changes for a given address (internal or external).
  • New-Blocks: Advanced. This event is fired whenever a new group of transactions is confirmed (i.e., a new block is mined).

Furthermore, when you create a notification, you will specify a URL where we can perform POST requests. This URL will receive the following object, and must respond with a Status Code between 200-299. If successful, the notification will be created.

        
{
  "type": "ping"
}
      

You can specify normal URLs guarded by parameters, or by a username/password (i.e., using Basic Auth), or just a simple URL without any parameters whatsoever. Securing this endpoint on your Web Server is completely up to you.

Finally, create a notification using the following endpoints. If you encounter any issues, please make sure the URL is URI encoded so it is distinguishable as a parameter value.


/api/v2/create_notification/?api_key=YOUR API KEY&type=account&url=YOUR URL
/api/v2/create_notification/?api_key=YOUR API KEY&type=address&address=ANY ADDRESS&url=YOUR URL
/api/v2/create_notification/?api_key=YOUR API KEY&type=new-transactions&url=YOUR URL
/api/v2/create_notification/?api_key=YOUR API KEY&type=new-blocks&url=YOUR URL

If successful, you will receive a response with the following structure:

	
{
  "status" : "success",
  "data" : {
    "network" : "BTC",
    "notification_id" : "306b6d...",
    "type" : "account",
    "enabled" : true,
    "url" : "..."
  }
}
      

Create a notification for balance changes for all your addresses

API KEY: (Your API Keys are in your Wallet)

URL:

TYPE:

Create a notification for balance changes for a specific address

API KEY: (Your API Keys are in your Wallet)

URL:

TYPE:

ADDRESS:

Create a notification for new blocks

API KEY: (Your API Keys are in your Wallet)

URL:

TYPE:


Disable a Notification

You can disable a given notification at any time using the following action:


/api/v2/disable_notification/?api_key=YOUR API KEY&notification_id=NOTIFICATION ID

Disable a given notification

API KEY: (Your API Keys are in your Wallet)

NOTIFICATION ID:


Enable a Notification

You can enable a given notification at any time using the following action:


/api/v2/enable_notification/?api_key=YOUR API KEY&notification_id=NOTIFICATION ID

Enable a given notification

API KEY: (Your API Keys are in your Wallet)

NOTIFICATION ID:


List Notifications

You can list notifications for a given Network (specified by the API Key). These notifications can be enabled, disabled, or deleted.

12/02/15: Going forward, only upto the last 10,000 notifications created are returned by this API call. Future versions will allow pagination for this method.


/api/v2/get_notifications/?api_key=YOUR API KEY
/api/v2/get_notifications/?api_key=YOUR API KEY&notification_ids=NOTIFICATION_ID1,NOTIFICATION_ID2,...

List all notifications

API KEY: (Your API Keys are in your Wallet)

Get a particular notification

API KEY: (Your API Keys are in your Wallet)

NOTIFICATION IDS:


Get Recent Notification Events

Produces a log of the last 10 notification events we pushed, or attempted to push, to your web server for a given Notification ID.


/api/v2/get_recent_notification_events/?api_key=YOUR API KEY&notification_id=NOTIFICATION ID

Get the last 10 events for a Web Hook

API KEY: (Your API Keys are in your Wallet)

NOTIFICATION ID:


Delete Notification

You can delete a given notification completely if you wish.


/api/v2/delete_notification/?api_key=YOUR API KEY&notification_id=NOTIFICATION ID

Delete a given notification

API KEY: (Your API Keys are in your Wallet)

NOTIFICATION ID:


Example Notifications

For reference, here is the structure of each type of notification.

Please note that Web Hooks of type account provide balance change notifications of type address.

Balance Change Notification
        
{
  "notification_id": "..."
  "delivery_attempt": 1,
  "created_at": 1426104819,
  "type": "address",
  "data": {
    "network": "BTC",
    "address": "3cBraN1Q...",
    "balance_change": "0.01000000", // net balance change, can be negative
    "amount_sent": "0.00000000",
    "amount_received": "0.01000000",
    "txid": "7af5cf9f2...", // the transaction's identifier (hash)
    "confirmations": X, // see below
    "is_green": false // was the transaction sent by a green address?
  }
}
// X = {0,1,3} for Bitcoin, {0,1,10} for Dogecoin, {0,1,5} for Litecoin
// if is_green=true, you can spend the funds (received) immediately, else
// if is_green=false, you need confirmations = 3 (Bitcoin), 10 (Dogecoin), 5 (Litecoin)
      
New Block Notification
        
{
  "notification_id": "..."
  "delivery_attempt": 1,
  "created_at": 1426104819,
  "type": "new-blocks",
  "data": {
    "network": "BTC",
    "block_hash": "fb0e1...", // the block identifier (hash)
    "previous_block_hash": "5b217...",
    "block_no": 456485, // the block's height
    "confirmations": 1, // number of times this block has been confirmed
                        // you will also receive an update at N confirmations:
                        // N = 3 (Bitcoin), 10 (Dogecoin), 5 (Litecoin)
    "merkle_root": "8173983...",
    "time": 1426062467,
    "nonce": 1544718438,
    "difficulty": "0.01240701",
    "txs": [
      // an array of txids
      "81739...", ...
      "ab123..."
    ]
  }
}
      
New Transaction Notification
        
{
  "notification_id": "..."
  "delivery_attempt": 1,
  "created_at": 1426104819,
  "type": "new-transactions",
  "data": {
    "network": "BTC",
    "txid": "cc5216...",
    "confirmations": 0, // unconfirmed transaction
    "block_hash": null,
    "block_no": null,
    "block_time": null,
    "received_at": 1426062224,
    "network_fee": "0.00010000",
    "amount_received": "0.01047313",
    "is_green": false, // was this transaction issued by a green address?
    "inputs": [ 
               // an array of old outputs (now inputs) spent by this transaction
      {
        "previous_txid": "34181...",
        "previous_output_no": 1,
        "type": "pubkeyhash",
        "address": "1GysXM...",
        "amount": "0.01057313",
        "script": "...", // script signed by the sender
        "input_no": 0
      }
    ],
    "outputs": [
                // an array of new outputs (unspent) where coins were sent
      {
        "output_no": 0,
        "type": "pubkeyhash",
        "address": "1HY2W...",
        "amount": "0.00115475",
        "script": "..." // the script to be signed to spend this output
      }
    ]
  }
}
      

Web Sockets

You can start subscribing to real-time events by using the following Web Sockets link. These Web Sockets are secured using 2,048 bit SSL, and run on port 443. All notifications issued from Block.io will occur through n.block.io.

	
	  wss://n.block.io/
      

Some important points to note:

  • The real-time Web Sockets are only available for Bitcoin, Dogecoin, Litecoin, and the Bitcoin/Dogecoin Testnets.
  • All requests/responses will use the JSON format.
  • The following example responses are commented for your convenience.
  • Web Sockets will not "replay" events that occurred in the past. You must stay connected to receive updates.
  • See working example.

Once connected to our Web Sockets, you will receive the following response from the server. Please note that any successful subscription to a real-time event will result in this response from our servers.

	
{
  "status": "success"
}
      

If your request is invalid, the following error response will be received by you instead:

	
{
  "status": "fail",
  "error_message": "An exception occurred. Please check your JSON object for accuracy and try again."
}
      

The notifications server will send the following connectedness check every 30 seconds to keep your connection to our Web Sockets server alive. This helps us maintain your connection to n.block.io in case there is little activity due to your subscriptions. You can ignore this message.

        
{
  "type": "ping"
}
      

Subscribing to Account Balance Changes

Block.io provides a convenient method for you to subscribe to balance changes for all addresses on a given account for Bitcoin, Dogecoin, and Litecoin. In order to subscribe to an all your account's address balance changes, you must provide the API Key for the account in the following request:

	
{
  "type": "account",
  "api_key": "YOUR-API-KEY"
}
      

Please note that when you create new addresses on your account, you will need to re-issue the above request to subscribe to the new address' balance updates.

If successful, you will start receiving balance updates for all addresses on your account in the following format.

        
{
  "type": "address",
  "data": {
    "network": "BTC",
    "address": "3cBraN1Q...",
    "balance_change": "0.01000000", // net balance change, can be negative
    "amount_sent": "0.00000000",
    "amount_received": "0.01000000",
    "txid": "7af5cf9f2...", // the transaction's identifier (hash)
    "confirmations": X, // see below
    "is_green": false // was the transaction sent by a green address?
  }
}
// X = {0,1,3} for Bitcoin, {0,1,10} for Dogecoin, {0,1,5} for Litecoin
// if is_green=true, you can spend the funds (received) immediately, else
// if is_green=false, you need confirmations = 3 (Bitcoin), 10 (Dogecoin), 5 (Litecoin)
      

Subscribing to a Single Address' Balance Updates

Alongside your account's addresses at Block.io, you can also subscribe to balance change updates for a specific address by issuing a request structured as follows. You can subscribe to a non-Block.io address' balance updates using this method.

	
{
  "network": "BTC",
  "type": "address",
  "address": "3ran1Q..."
}
      

The balance change update will be similar to the previous section's response.


Subscribing to New Blocks (ADVANCED)

Advanced. You can also subscribe to new Blocks as they occur on the Bitcoin, Dogecoin, Litecoin Block Chains. You can do this using requests structured as follows:

	
{
  "network": "BTC",
  "type": "new-blocks"
}
      

If successful, you will start receiving updates when new Blocks are mined for the specified Network. A block update response will be structured as follows:

        
{
  "type": "new-blocks",
  "data": {
    "network": "BTC",
    "block_hash": "fb0e1...", // the block identifier (hash)
    "previous_block_hash": "5b217...",
    "block_no": 456485, // the block's height
    "confirmations": 1, // number of times this block has been confirmed
                        // you will also receive an update at N confirmations:
                        // N = 3 (Bitcoin), 10 (Dogecoin), 5 (Litecoin)
    "merkle_root": "8173983...",
    "time": 1426062467,
    "nonce": 1544718438,
    "difficulty": "0.01240701",
    "txs": [
      // an array of txids
      "81739...", ...
      "ab123..."
    ]
  }
}
      

Subscribing to New Transactions (ADVANCED)

You can similarly subscribe to all new, unmined transactions as they are received by the Bitcoin, Dogecoin, and Litecoin networks. You can do this by issuing a request structured as follows:

	
{
  "network": "BTC",
  "type": "new-transactions"
}
      

If successful, you will start receiving data for new transactions. The updates will be structured as follows:

        
{
  "type": "new-transactions",
  "data": {
    "network": "BTC",
    "txid": "cc5216...",
    "confirmations": 0, // unconfirmed transaction
    "block_hash": null,
    "block_no": null,
    "block_time": null,
    "received_at": 1426062224,
    "network_fee": "0.00010000",
    "amount_received": "0.01047313",
    "is_green": false, // was this transaction issued by a green address?
    "inputs": [ 
               // an array of old outputs (now inputs) spent by this transaction
      {
        "previous_txid": "34181...",
        "previous_output_no": 1,
        "type": "pubkeyhash",
        "address": "1GysXM...",
        "amount": "0.01057313",
        "script": "...", // script signed by the sender
        "input_no": 0
      }
    ],
    "outputs": [
                // an array of new outputs (unspent) where coins were sent
      {
        "output_no": 0,
        "type": "pubkeyhash",
        "address": "1HY2W...",
        "amount": "0.00115475",
        "script": "..." // the script to be signed to spend this output
      }
    ]
  }
}
      

Confused? Contact Us!