API

API Specification

General rules

• all API calls are currently made through a single top level object named bitcoin
• all methods have a callback argument at the end, and will asynchronously return data through this callback (function return value will always be undefined)
• Bitcoin amounts are always passed through the API as integer values with amounts in satoshi, i.e. 0.5 BTC should be passed as 50000000

Getting information about the user

bitcoin.getUserInfo(callback)

Arguments:

• callback: function (required) - will be called with arguments:
  • info: hash - information about the user:
    • firstName: string
    • lastName: string
    • email: string
    • address: string - user's main (and currently the only) Bitcoin address

Example:

bitcoin.getUserInfo(function(info) { 
  alert('Hello, ' + info.firstName + ' ' + info.lastName + '!');
}

Getting information about system settings

bitcoin.getSystemInfo(callback)

Arguments:

• callback: function (required) - will be called with arguments:
  • info: hash - information about the system:
    • version: string - current Hive version (e.g. "0.9")
    • buildNumber: string - current Hive build (e.g. "2013120901")
    • decimalSeparator: string - a comma or a dot, depending on user's system locale
    • locale: string - the localization (language) currently used in Hive, e.g. "en" or "zh-Hans"
    • preferredCurrency: string - user's preferred fiat currency, e.g. "USD"

Example:

bitcoin.getSystemInfo(function(info) {
  $('#amount').val('0' + info.decimalSeparator + '005');
}

Getting information about fiat currency exchange rates

Subscribing for updates:

bitcoin.addExchangeRateListener(callback)

Arguments:

• callback: function (required) - will be called with arguments:
  • currency: string - currency code, e.g. "USD"
  • exchangeRate: number - value of one Bitcoin in that currency

Note: the callback might be called many times until you remove the listener, and it might not be called at all unless you also call updateExchangeRate (see below).

Example:

bitcoin.addExchangeRateListener(function(currency, amount) {
  $('#rate').text('1 BTC = ' + amount + ' ' + currency);
}

Unsubscribing:

bitcoin.removeExchangeRateListener(callback)

Arguments:

• callback: function (required) - callback used before in addExchangeRateListener

Triggering an update:

bitcoin.updateExchangeRate(currency)

Arguments:

• currency: string (required) - currency code

This will trigger a currency exchange rate update and will result in a call to any registered callbacks when the data is available. Note: this might not actually cause any network requests if the client has cached data and it decides it's fresh enough.

Getting information about previous transactions

bitcoin.getTransaction(transactionId, callback)

Arguments:

• transactionId: string (required) - ID of the transaction
• callback: function (required) - will be called with arguments:
  • info: hash - information about the transaction (if one is found):
    • id: string - transaction ID
    • amount: number - in satoshi
    • type: string - either "incoming" or "outgoing" (you can use bitcoin.TX_TYPE_INCOMING and bitcoin.TX_TYPE_OUTGOING constants)
    • timestamp: string - time of creating the transaction - a date string in ISO format, call new Date(timestamp) to get a Date object
    • inputAddresses: array[string]
    • outputAddresses: array[string]

If transaction can't be found, the callback will return null. If transaction ID is not even a valid ID, it should also return null (currently it crashes Hive, see https://github.com/grabhive/BitcoinKit/issues/8).

At the moment one of the inputAddresses/outputAddresses arrays will contain one address (the address to which you've sent or from which you've received Bitcoin) and the other will be empty. This will be changed in the future.

Example:

bitcoin.getTransaction(lastTransactionId, function(tx) {
  if (tx) {
    if (tx.type == bitcoin.TX_TYPE_INCOMING) {
      alert("You've received " + (tx.amount / bitcoin.BTC_IN_SATOSHI) + " BTC from " + tx.inputAddresses[0]);
    } else {
      alert("You've sent " + (tx.amount / bitcoin.BTC_IN_SATOSHI) + " BTC to " + tx.outputAddresses[0]);
    }
  } else {
    alert("Hmm, something went wrong...");
  }
});

Opening the "Send Bitcoin" window

bitcoin.sendMoney(address, amount, callback)

Arguments:

• address: string (required) - target Bitcoin address
• amount: number (optional) - requested amount, in satoshi; if not given, user will be able to choose any amount
• callback: function (optional) - will be called with arguments:
  • success: boolean - true if a transaction has been made, false if the user has closed the dialog without making one
  • transactionId: string - if a transaction has been made, this will contain the ID of the transaction that can be used to call getTransaction

You can use these constants to help with Bitcoin to satoshi conversions:

• bitcoin.BTC_IN_SATOSHI = 100000000
• bitcoin.MBTC_IN_SATOSHI = 100000
• bitcoin.UBTC_IN_SATOSHI = 100

Example:

bitcoin.sendMoney('142m1MpXHhymF4aASiWwYohe1Y55v5BQwc', 10 * bitcoin.MBTC_IN_SATOSHI, function(success, transactionId) {
  if (success) {
    bitcoin.getTransaction(transactionId, function(t) {
      var btc = t.amount / bitcoin.BTC_IN_SATOSHI;
      alert('Thanks for sending us ' + btc + ' BTC!');
    });
  }
});

Sending proxied requests to web APIs

bitcoin.makeRequest(url, options)

This can be used to connect to web APIs that don't support access from in-browser Javascript using methods like JSON or CORS. When you call this method, Hive will make an HTTP request to the given URL in native code on behalf of the app and will return the results to the callback functions set in the options hash. This lets you bypass same-origin policy restrictions, because the request doesn't have access to any user cookies.

For security reasons, you need to declare all hostnames to which you want to connect this way in the application manifest.

Arguments:

• url: string (required) - URL to which the request is sent
• options: dictionary (optional)

Possible options:

• type: string - the HTTP method to be used (default: "GET")
• dataType: string - expected response type; if set to "json", Hive will always try to parse the response as JSON, regardless of the returned content type (by default it will only attempt that if a JSON content type is returned)
• data: string/dictionary - data or parameters to be sent with the request:
  • for GET, HEAD and DELETE requests, this will be appended to the URL
  • for POST and PUT requests, this will be sent as POST data
  • if the argument is a dictionary, then its values should only be numbers or strings, and it will be converted to a proper params string
• headers: dictionary - list of key-value pairs of HTTP headers to be set (values should only be numbers or strings)
• success: function - callback to be called on successful response; will be called with arguments:
  • response: string/object - response text or parsed JSON object
  • status: number - HTTP status code
• error: function - callback to be called when request fails; will be called with arguments:
  • response: string - response text
  • status: number - HTTP status code
  • error: object - error details
• complete: function - callback to be called regardless if request succeeds or not, after the success or error callback, with the same arguments as one of those

Example:

bitcoin.makeRequest('https://www.bitstamp.net/api/ticker', {
  success: function(data) {
    console.log('1 BTC = ' + data.last + ' USD');
  }
});

Testing the API

Current builds have a WebKitDeveloperExtras option set to true in the preferences (this is set in HIAppDelegate). This means that you can right click inside any app, choose "Inspect" and you get access to the standard WebKit developer console, where you can play with the API, check error messages etc. If the default setting is changed in the future, you can always override it with:

defaults write com.grabhive.Hive WebKitDeveloperExtras TRUE