address.md

Address Service

The address service builds on the Bitcoin Service and the Database Service to add additional functionality for querying and subscribing to information based on bitcoin addresses. This will typically represent the core functionality for wallet applications.

API Documentation

These methods are exposed over the JSON-RPC interface and can be called directly from a node via:

node.services.address.<methodName>

Get Unspent Outputs

One of the most common uses will be to retrieve unspent outputs necessary to create a transaction, here is how to get the unspent outputs for an address:

var address = 'mgY65WSfEmsyYaYPQaXhmXMeBhwp4EcsQW';
var includeMempool = true;
node.services.address.getUnspentOutputs(address, includeMempool, function(err, unspentOutputs) {
  // see below
});

The unspentOutputs will have the format:

[
  {
    address: 'mgY65WSfEmsyYaYPQaXhmXMeBhwp4EcsQW',
    txid: '9d956c5d324a1c2b12133f3242deff264a9b9f61be701311373998681b8c1769',
    outputIndex: 1,
    height: 150,
    satoshis: 1000000000,
    script: '76a9140b2f0a0c31bfe0406b0ccc1381fdbe311946dadc88ac',
    confirmations: 3
  }
]

View Balances

var address = 'mgY65WSfEmsyYaYPQaXhmXMeBhwp4EcsQW';
var includeMempool = true;
node.services.address.getBalance(address, includeMempool, function(err, balance) {
  // balance will be in satoshis
});

View Address History

This method will give history of an address limited by a range of block heights by using the "start" and "end" arguments. The "start" value is the more recent, and greater, block height. The "end" value is the older, and lesser, block height. This feature is most useful for synchronization as previous history can be omitted. Furthermore for large ranges of block heights, results can be paginated by using the "from" and "to" arguments.

var addresses = ['mgY65WSfEmsyYaYPQaXhmXMeBhwp4EcsQW'];
var options = {
  start: 345000,
  end: 344000,
  queryMempool: true
};
node.services.address.getAddressHistory(addresses, options, function(err, history) {
  // see below
});

The history format will be:

{
  totalCount: 1, // The total number of items within "start" and "end"
  items: [
    {
      addresses: {
        'mgY65WSfEmsyYaYPQaXhmXMeBhwp4EcsQW': {
          inputIndexes: [],
          outputIndexes: [0]
        }
      },
      satoshis: 1000000000,
      height: 150, // the block height of the transaction
      confirmations: 3,
      timestamp: 1442948127, // in seconds
      fees: 191,
      tx: <Transaction> // the populated transaction
    }
  ]
}

View Address Summary

var address = 'mgY65WSfEmsyYaYPQaXhmXMeBhwp4EcsQW';
var options = {
  noTxList: false
};

node.services.address.getAddressSummary(address, options, function(err, summary) {
  // see below
});

The summary will have the format (values are in satoshis):

{
  totalReceived: 1000000000,
  totalSpent: 0,
  balance: 1000000000,
  unconfirmedBalance: 1000000000,
  appearances: 1, // number of transactions
  unconfirmedAppearances: 0,
  txids: [
    '3f7d13efe12e82f873f4d41f7e63bb64708fc4c942eb8c6822fa5bd7606adb00'
  ]
}

Events

For details on instantiating a bus for a node, see the Bus Documentation.

• Name: address/transaction, Arguments: [address, address...]
• Name: address/balance, Arguments: [address, address...]

Examples:

bus.subscribe('address/transaction', ['13FMwCYz3hUhwPcaWuD2M1U2KzfTtvLM89']);
bus.subscribe('address/balance', ['13FMwCYz3hUhwPcaWuD2M1U2KzfTtvLM89']);

bus.on('address/transaction', function(transaction) {

});

bus.on('address/balance', function(balance) {

});