BeeWallet API

Basic Corporate Wallet API

The BeeWallet API is a RESTful API based on HTTPS requests and JSON responses.

BeeWallet addresses by default require two signatures for all withdrawals: yours, and BeeWallet's. This method provides exponentially higher security for your Wallets and applications than single-signature addresses. This way, you spend coins yourself, without trusting BeeWallet with your credentials.

All addresses generated using this API are considered Green, i.e., they can send and receive funds without waiting for confirmations. This is possible since BeeWallet guarantees coins can never be spent twice. Furthermore, all transactions occur on the Blockchain.

Develop your applications together with BeeWallet and get worthy reward.



Getting Started

First, you will need your personal TOKEN (Located in "Your wallet" > Settings > Token) and API KEY (Located in "Your company" > Settings > API Key), which we provide for Bitcoin. You are required to use an API KEY when you interact with BeeWallet. It tells BeeWallet which network (e.g., Bitcoin) you wish to perform actions on.


You can access the API by making calls to links of this format:


curl -X GET https://api.beeqb.com/get_balance/?api_key=API KEY -H 'Authorization: Token TOKEN'

Check here API callbacks



Actions for Handling Addresses

Get Balance

Returns the balance of your entire "Company" as numbers to 8 decimal points, as strings.


/get_balance/?api_key=API KEY


Get New Invoice with Amount in company currency

Returns new invoice number with new address and amount in BTC.


/get_new_invoice/?api_key=API KEY&amounts=AMOUNT_WITHOUT_CURRENCY


Get New Invoice for BeeWallet User with Amount in company currency

Returns new invoice number with new address and amount in BTC and send current invoice to the BeeWallet user.


/get_new_invoice/?api_key=API KEY&amounts=AMOUNT_WITHOUT_CURRENCY&labels=@USERNAME_OR_#COMPANY



Withdrawal Actions

Overview

BeeWallet eases your burden of storing information regarding users' addresses, labels, and user IDs. Below, we provide various methods that allow you to make fine-grained withdrawals from your account. You can send the specified amounts to up to 2500 destination addresses, users, or labels in a single API call.

Please keep at least 0.000002 BTC for network fees. There are no BeeWallet fees. Larger transactions (in bytes) will incur larger amounts of network fees as per Bitcoin specifications. You can specify an additional parameter priority={economy,low,normal,high,instant} to increase the network fee paid in the given transaction. Use the get_network_fee_estimate API call to determine beforehand the network fee for a given set of withdrawal parameters.

Ensuring Uniqueness of Withdrawals Client-side human or machine error can lead to multiple executions of the same withdrawal request. If such an error occurs, you will lose money. To ensure the uniqueness of withdrawal requests, you can specify a nonce=value parameter with your withdrawal requests, where value is an alpha-numeric string between 1 and 64 characters long. Withdrawal requests that provide duplicate nonces less than 1 hour apart will be rejected. This is an optional but recommended security measure.

These methods support POST and GET, but only GET examples are shown below. We recommend using POST methods in your applications.

We recommend performing transaction signatures client-side. The methods below allow you to provide your SECRET PIN to enable BeeWallet to sign your transactions on your behalf as a measure of convenience. Note: Token & Secret Pin are personal value. For any accounts with large amounts of coins, please use client-side signing for withdrawals (it means that SECRET PIN you will enter manual, for every withdraw action. In this way argument &pin=SECRET PIN does not needed.).




Withdraw to address

Withdraws amount of coins from your account to up to 2500 destination addresses.


/withdraw/?api_key=API KEY&priority=instant&amounts=AMOUNT1,AMOUNT2,...&to_addresses=ADDRESS1,ADDRESS2,...&pin=SECRET PIN


Withdraw to BeeWallet

Withdraws AMOUNT coins from up to 2500 BeeWallet users at a time, and deposits it to upto 2500 destination addresses, or Users.


/withdraw/?api_key=API KEY&amounts=AMOUNT1,AMOUNT2,...&to_labels=@USERNAME1,#COMPANY1,...&pin=SECRET PIN

The amounts=AMOUNT1,AMOUNT2,... and to_addresses=ADDRESS1,ADDRESS2,... parameters specify that destination ADDRESS1 will receive AMOUNT1, ADDRESS2 will receive AMOUNT2, etc. The source addresses (from_addresses=...) will need at least SUM(AMOUNT1,AMOUNT2...)+Network Fees in balances for this withdrawal to succeed.



Estimate Network Fee

Estimates the Network Fee you will need to pay when you make a withdrawal request. The Network Fee is required by the Bitcoin networks, not BeeWallet.


/get_network_fee_estimate/?api_key=API KEY&amounts=AMOUNT1,AMOUNT2,...&to_addresses=ADDRESS1,ADDRESS2,...



Misc. Actions

Bitcoin to Wire P2P exchange Soon

Withdraws amount of coins from your account to EXCHANGER ID addresses.


/withdraw/?token=TOKEN&api_key=API KEY&amounts=AMOUNT&for_exchange=EXCHANGER ID&pin=SECRET PIN

Withdraws amount of coins from your account payed invoice to EXCHANGER ID addresses.


/withdraw/?token=TOKEN&api_key=API KEY&invoice=NUMBER&for_exchange=EXCHANGER ID&pin=SECRET PIN

Create invoice with amount with direct sending coins to EXCHANGER ID addresses.


/get_new_invoice/?api_key=API KEY&amounts=AMOUNT&for_exchange=EXCHANGER ID&pin=SECRET PIN


Get Current Price

Returns the prices from your account, specified by the API KEY. Specifying the base currency is optional.


/get_current_price/?api_key=API KEY


Get Transactions

Returns various data for the last 25 transactions spent or received. You can optionally specify a before_tx parameter to get earlier transactions.

You can use this method to query for addresses that are not on your account.

Each result provides a confidence rating that shows the network's belief in the transaction's viability. This is useful if you need to validate transactions quickly (for e.g., in retail store settings) without waiting for confirmations. We recommend waiting for confidence ratings to reach 0.90-0.99 for unconfirmed transactions if you need to validate it. For unconfirmed transactions, you are also provided with the number of nodes (propagated_by_nodes) on the Network that approve of the given unconfirmed transaction (out of 150 sampled nodes).

If a double spend is detected for an unconfirmed transaction, its confidence rating falls to 0.0.


/get_transactions/?api_key=API KEY&type=sent
/get_transactions/?api_key=API KEY&type=received
/get_transactions/?api_key=API KEY&type=sent&to_labels=@USERNAME1,#COMPANY1,...
/get_transactions/?api_key=API KEY&type=received&from_labels=@USERNAME1,#COMPANY1,...


Get Invoices list

Returns various data for the last 25 invoices spent or received. You can optionally specify a to_labels ans form labels parameter to get filtering.


/get_invoices/?api_key=API KEY&type=sent
/get_invoices/?api_key=API KEY&type=received
/get_invoices/?api_key=API KEY&type=sent&to_labels=@USERNAME1,#COMPANY1,...
/get_invoices/?api_key=API KEY&type=received&from_labels=@USERNAME1,#COMPANY1,...


Real-Time Notifications

BeeWallet updates you in real-time when your wallet addresses' balances change. 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:

  1. Through Web Hooks, we push data to you through HTTP Post requests to web servers of your choice.
  2. Through Web Sockets, you subscribe to updates while staying connected to a api.beeqb.com 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 BeeWallet 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:

  1. All notifications will be issued through api.beeqb.com, so you can whitelist the domain if you use firewalls.
  2. The source server (api.beeqb.com) IP can change at any time.
  3. Your Web Server must respond with a Status Code of 2xx (i.e., between 200-299) for us to consider the notification successful.
  4. Unsuccessful notifications will be retried for ~24 hours with exponential back-off, after which your failing Web Hook will be disabled.
  5. 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 delivering 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.

/webhooks/create_notification/?api_key=API KEY&type=account&url=YOUR URL
/webhooks/create_notification/?api_key=API KEY&type=address&address=ANY ADDRESS&url=YOUR URL
/webhooks/create_notification/?api_key=API KEY&type=new-transactions&url=YOUR URL
/webhooks/create_notification/?api_key=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" : "..."
}
}


Disable a Notification

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

/webhooks/disable_notification/?api_key=API KEY&notification_id=NOTIFICATION ID


Enable a Notification

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

/webhooks/enable_notification/?api_key=API KEY&notification_id=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.

Going forward, only up to the last 10,000 notifications created are returned by this API call. Future versions will allow pagination for this method.

/webhooks/get_notifications/?api_key=API KEY
/webhooks/get_notifications/?api_key=API KEY&notification_id=NOTIFICATION_ID1,NOTIFICATION_ID2,...


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.

/webhooks/get_recent_notification_events/?api_key=API KEY&notification_id=NOTIFICATION ID


Delete Notification

You can delete a given notification completely if you wish.

/webhooks/delete_notification/?api_key=API KEY&notification_id=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?
}
}


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)
"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 Soon

You can start subscribing to real-time events by using the following Web Sockets link. These Web Sockets are secured using SSL, and run on port 443. All notifications issued from BEEQB will occur through api.beeqb.com.

wss://api.beeqb.com/


Some important points to note:

  1. The real-time Web Sockets are only available for Bitcoin.
  2. All requests/responses will use the JSON format.
  3. The following example responses are commented for your convenience.
  4. Web Sockets will not "replay" events that occurred in the past. You must stay connected to receive updates.
  5. 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

BEEQB provides a convenient method for you to subscribe to balance changes for all addresses on a given account for Bitcoin. 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": "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
// if is_green=true, you can spend the funds (received) immediately, else
// if is_green=false, you need confirmations.


Subscribing to a Single Address' Balance Updates

Alongside your account's addresses at BEEQB, 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-BEEQB 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 Transactions

You can similarly subscribe to all new, unmined transactions as they are received by the Bitcoin 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
}
]
}
}