API

API Specification

=== Warning: Hive app store is deprecated and will be removed soon. ===

General rules

• all API calls are currently made through a single top level object named bitcoin
• all methods have one or more callback arguments and will asynchronously return data through the callbacks (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

API version

Current API version is 0.2. You can check that by accessing bitcoin.apiVersionMajor and bitcoin.apiVersionMinor properties. Minor version will change when new features are added, and major version will only change when there are any major changes that make it incompatible with existing apps.

Apps can specify required major version and minimum minor version in their manifest - if the current Hive version doesn't match, user will get an error message when trying to run the app.

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 + '!');
})

Note that on Hive Android currently users do not provide an email address and this field will therefore be missing there.

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"
    • availableCurrencies: array of strings - display currencies available to the users (with exchange rates, etc.)
    • preferredCurrency: string - user's preferred fiat currency, e.g. "USD"
    • preferredBitcoinFormat: string - user's preferred Bitcoin format (currently "BTC", "mBTC", or "µBTC")
    • platform: string - either "osx" or "android" depending on whether the user is running Hive OSX or Hive Android
    • testnet: boolean - true if Hive is running in testnet mode

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

Note: Hive Android currently fetches exchange rate data only once per Hive app startup and no continuous updates are provided. This limit should be lifted in the future. Let us know if this feature is important to you!

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 or the ID is invalid, the callback will return null.

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');
  }
});

Note: Setting headers is currently not supported for Hive Android. Please get in touch if this feature is important to you.

Installing other Hive apps

bitcoin.installApp(url, callback)

Downloads and installs a .hiveapp from given URL (if user confirms the installation). Only HTTPS URLs are accepted.

Arguments:

• url: string (required) - location of the .hiveapp file
• callback: function (optional) - will be called with arguments:
  • err: object - contains an error message if file could not be downloaded or is invalid, otherwise it's set to null
  • installed: boolean - tells if the application was actually installed in Hive

Example:

bitcoin.installApp('https://hivewallet.com/apps/coinbase.hiveapp', function(err, installed) {
  $('.coinbase .status').removeClass('loading');

  if (installed) {
    $('.coinbase .status').addClass('installed');
  } else if (err) {
    alert(err.message);
  } else {
    // user cancelled installation - ignore
  }
});

API version: 0.1+

Getting information about installed applications

bitcoin.getApplication(applicationId, callback)

Arguments:

• applicationId: string (required) - ID of the application
• callback: function (required) - will be called with the application manifest JSON in response

If application with given id is not installed, the callback will return null.

Example:

bitcoin.getApplication('com.hivewallet.coinbase', function(app) {
  if (app) {
    alert("Coinbase app is installed (version " + app.version + ").");
  } else {
    alert("Coinbase app is not installed.");
  }
});

API version: 0.2+

Formatting and parsing

The API provides functions for formatting and parsing values according to the user's locale and settings. Use these to present and read user values, never as part of an API call or external protocol.

bitcoin.userStringForSatoshi(value)

Arguments:

• value: number (required) - satoshi amount
• returns: string - the amount formatted as preferred by the user

bitcoin.satoshiFromUserString(string)

Arguments:

• string: string (required) - string to convert to a satoshi amount
• returns: number - the satoshi amount

bitcoin.userStringForCurrencyValue(value, currency)

Arguments:

• value: number (required) - value to format
• currency: string (optional) - currency code (affects the number of decimal places, defaults to preferred currency)
• returns: string - the value formatted as preferred by the user for this currency

bitcoin.valueFromUserString(string)

Arguments:

• string: string (required) - string to convert to a number
• returns: number - the number

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

Hive Android limitations

Hive Android currently has the limitation, that the Hive API is only available for the first page loaded. If your app uses subpages, the API will not automatically be available there. While this limitation exists, you can use the following Javascript snippet as a workaround, to load the API even on subpages:

if (!window.bitcoin && window.hive) window.eval(hive.init());