API

!!! RELEASE CANDIDATE VERSION, THIS IS NOT FINAL YET

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:
    • decimalSeparator: string - a comma or a dot, depending on user's system locale

In future this will probably include information about user's language and region settings etc.

Example:

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

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

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