btc-wallet.live updates you in real-time when your wallet addresses' balances change for Bitcoin, Ethereum, 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:
The following document provides more details on each of these mechanisms.
You can start using Web Hooks by creating a Notification on your btc-wallet.live 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:
45.56.79.5
45.56.123.170
45.33.20.161
45.33.4.167
2600:3c00::f03c:91ff:fe33:2e14
2600:3c00::f03c:91ff:fe89:bb9b
2600:3c00::f03c:91ff:fe33:d082
2600:3c00::f03c:92ff:fe5e:4219
A notification event will use the following structure:
{
"event_id" : "...", // event ID for debugging purposes
"notification_id" : "...", // a unique identifier issued when you created the notification
"delivery_attempt" : 1, // number of times we've tried delivering this event
"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
"signature" : "..." // signed hash of this data (excluding the signature key)
}
You can create a Web Hook notification for the following types of events:
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-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" : "..."
}
}
You can disable a given notification at any time using the following action:
/api/v2/disable_notification/?api_key=YOUR API KEY¬ification_id=NOTIFICATION ID
You can enable a given notification at any time using the following action:
/api/v2/enable_notification/?api_key=YOUR API KEY¬ification_id=NOTIFICATION ID
You can list notifications for a given Network (specified by the API Key). These notifications can be enabled, or disabled. Upto 2500 notifications per page. Page parameter is optional.
/api/v2/list_notifications/?api_key=YOUR API KEY&page=PAGE_NUMBER
/api/v2/list_notifications/?api_key=YOUR API KEY¬ification_ids=NOTIFICATION_ID1,NOTIFICATION_ID2,...&page=PAGE_NUMBER
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¬ification_id=NOTIFICATION ID
You can delete a given notification completely if you wish.
/api/v2/delete_notification/?api_key=YOUR API KEY¬ification_id=NOTIFICATION ID
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.
{
"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 // legacy, can be ignored
}
}
// X = {0,1,3} for Bitcoin, {0,1,10} for Ethereum, {0,1,5} for Litecoin
{
"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 (Ethereum), 5 (Litecoin)
"merkle_root": "8173983...",
"time": 1426062467,
"nonce": 1544718438,
"difficulty": "0.01240701",
"txs": [
// an array of txids
"81739...", ...
"ab123..."
]
}
}
You can start subscribing to real-time events by using the following Web Sockets link.
wss://ws.block.io/
Some important points to note:
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 the websocket server in case there is little activity due to your subscriptions. You can ignore this message.
{
"type": "ping"
}
You can subscribe to balance change updates for a specific address by issuing a request structured as follows. You can subscribe to a non-btc-wallet.live address' balance updates using this method.
{
"network": "BTC",
"type": "address",
"address": "3ran1Q..."
}
If successful, you will start receiving balance updates for the said address 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 // legacy, can be ignored
}
}
// X = {0,1,3} for Bitcoin, {0,1,10} for Ethereum, {0,1,5} for Litecoin
Advanced. You can also subscribe to new Blocks as they occur on the Bitcoin, Ethereum, 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 (Ethereum), 5 (Litecoin)
"merkle_root": "8173983...",
"time": 1426062467,
"nonce": 1544718438,
"difficulty": "0.01240701",
"txs": [
// an array of txids
"81739...", ...
"ab123..."
]
}
}
Confused? Contact Us!