REFERENCE.md

#stellar-lib API Reference

(More examples coming soon!)

###In this document:

1. Remote options
2. Remote functions

• Server info functions
• Ledger query functions
• Transaction query functions
• Account query functions
• Order book query functions
• Transaction submission functions

3. Transaction events
4. Amount objects

###Also see:

1. The stellar-lib README
2. The stellar-lib GUIDES

#1. Remote options

/* Loading stellar-lib with Node.js */
var Remote = require('stellar-lib').Remote;

/* Loading stellar-lib in a webpage */
// var Remote = stellar.Remote;

var remote = new Remote({options});

A new Remote can be created with the following options:

• trace Log all of the events emitted (boolean)
• max_listeners Set maxListeners for remote; prevents EventEmitter warnings (number)
• connection_offset Connect to remote servers on supplied interval (number in seconds)
• trusted truthy, if remote is trusted (boolean)
• local_fee Set whether the transaction fee range will be set locally (boolean, default is true, see A note on transaction fees)
• fee_cushion Extra fee multiplier to account for async fee changes (number, e.g. 1.5, see A note on transaction fees)
• max_fee Maximum acceptable transaction fee (number in Stroop, see A note on transaction fees)
• servers Array of server objects of the following form:

{ 
  host:    <string>
  , port:    <number>
  , secure:  <boolean>
}

• local_signing

#2. Remote functions

##Server info functions

requestServerInfo([callback])

Returns information about the state of the server. If you are connected to multiple servers and want to select by a particular host, use request.set_server. Example:

var request = remote.request_server_info();
request.set_server('my.hostname');
request.callback(function(err, res) {

});
request.request();

##Ledger query functions

requestSubscribe(streams, [callback])

Start receiving selected streams from the server.

requestUnsubscribe(streams, [callback])

Stop receiving selected streams from the server.

##Transaction query functions

requestTransactionEntry(hash, [ledger_hash], [callback])

Searches a particular ledger for a transaction hash. Default ledger is the open ledger.

requestTx(hash, [callback])

Searches ledger history for validated transaction hashes.

##Account query functions

requestAccountInfo(account, [callback])

Return information about the specified account.

{
  ledger_current_index: <number>,
  account_data: {
    Account:            <string>,
    Balance:            <number>,
    Flags:              <number>,
    LedgerEntryType:    <string>,
    OwnerCount:         <number>,
    PreviousTxnID:      <string>,
    PreviousTxnLgrSeq:  <number>,
    Sequence:           <number> ,
    index:              <string>
  }
}

requestAccountLines(accountID, account_index, current, [callback])

requestAccountOffers(accountID, account_index, current, [callback])

Return the specified account's outstanding offers.

requestAccountTx(opts, [callback])

Fetch a list of transactions that applied to this account.

Options:

• account
• ledger_index_min deprecated, -1
• ledger_index_max deprecated, -1
• binary false
• count false
• descending false
• offset 0
• limit
• forward false
• fwd_marker
• rev_marker

requestAccountBalance(account, ledger, [callback])

Get the balance for an account. Returns an Amount object.

requestAccountFlags(account, current, [callback])

Return the flags for an account.

requestOwnerCount(account, current, [callback])

Return the owner count for an account.

requestRippleBalance(account, issuer, currency, current, [callback])

Return a request to get a ripple balance

##Order book query functions

requestBookOffers(gets, pays, taker, [callback])

Return the offers for an order book as one or more pages.

var request = remote.request_book_offers({
  gets: {
    'currency':'STR'
  },
  pays: {
    'currency':'USD',
    'issuer': 'ganVp9o5emfzpwrG5QVUXqMv8AgLcdvySb'
  }
});

request.request();

##Transaction submission functions

requestSign(secret, tx_json, [callback])

Sign a transaction.

• requires trusted remote

requestSubmit([callback])

Submit a transaction to the network. This command is used internally to submit transactions with a greater degree of reliability. See Submitting a payment to the network for details.

requestRipplePathFind(src_account, dst_account, dst_amount, src_currencies, [callback])

transaction([destination], [source], [amount], [callback])

Returns a Transaction object

#3. Transaction events

Transaction objects are EventEmitters. They may emit the following events.

• final Transaction has erred or succeeded. This event indicates that the transaction has finished processing.
• error Transaction has erred. This event is a final state.
• success Transaction succeeded. This event is a final state.
• submitted Transaction has been submitted to the network. The submission may result in a remote error or success.
• proposed Transaction has been submitted successfully to the network. The transaction at this point is awaiting validation in a ledger.
• timeout Transaction submission timed out. The transaction will be resubmitted.
• resubmit Transaction is beginning resubmission.
• fee_adjusted Transaction fee has been adjusted during its pending state. The transaction fee will only be adjusted if the remote is configured for local fees, which it is by default.
• abort Transaction has been aborted. Transactions are only aborted by manual calls to #abort.
• missing Four ledgers have closed without detecting validated transaction
• lost Eight ledgers have closed without detecting validated transaction. Consider the transaction lost and err/finalize.