-

Updated for version 0.17.6

-

Introduction

-

RippleAPI is the official client library to the Ripple Consensus Ledger. Currently, RippleAPI is only available in JavaScript. +

Introduction

+

RippleAPI is the official client library to the XRP Ledger. Currently, RippleAPI is only available in JavaScript. Using RippleAPI, you can:

RippleAPI only provides access to validated, immutable transaction data.

Boilerplate

Use the following boilerplate code to wrap your custom code using RippleAPI.

-
const {RippleAPI} = require('ripple-lib');
+
const RippleAPI = require('ripple-lib').RippleAPI;
 
 const api = new RippleAPI({
   server: 'wss://s1.ripple.com' // Public rippled server hosted by Ripple, Inc.
@@ -369,8 +380,8 @@ api.connect().then(() => {
   return api.disconnect();
 }).catch(console.error);
 

-
RippleAPI is designed to work in NodeJS (version 0.12.0 or greater) using Babel for ECMAScript 6 support.

-
The code samples in this documentation are written in ES6, but RippleAPI will work with ES5 also. Regardless of whether you use ES5 or ES6, the methods that return promises will return ES6-style promises.

+
RippleAPI is designed to work in Node.js version 6.9.0 or later. RippleAPI may work on older Node.js versions if you use Babel for ECMAScript 6 support.

+
The code samples in this documentation are written with ECMAScript 6 (ES6) features, but RippleAPI also works with ECMAScript 5 (ES5). Regardless of whether you use ES5 or ES6, the methods that return Promises return ES6-style promises.

 
@@ -451,26 +462,22 @@ The "error" event is emitted whenever an error occurs that cannot be associated
 
If you omit the server parameter, RippleAPI operates offline.

 
Installation

 
    
-
  1. Install NodeJS and the Node Package Manager (npm). Most Linux distros have a package for NodeJS, but make sure you have version 0.12.0 or higher.
    2. 
-
  2. Use npm to install Babel globally:
-      npm install -g babel-cli
    3. 
+
  3. Install Node.js and the Node Package Manager (npm). Most Linux distros have a package for Node.js, but make sure you have version 6.9.0 or higher.
    4. 
 
  4. Use npm to install RippleAPI:
       npm install ripple-lib
    5. 
 

-
After you have installed ripple-lib, you can create scripts using the boilerplate and run them using babel-node:
-      babel-node script.js

-
+
After you have installed ripple-lib, you can create scripts using the boilerplate and run them using the Node.js executable, typically named node:

+
  `node script.js`
+

 
Offline functionality

 
RippleAPI can also function without internet connectivity. This can be useful in order to generate secrets and sign transactions from a secure, isolated machine.

 
To instantiate RippleAPI in offline mode, use the following boilerplate code:

-
const {RippleAPI} = require('ripple-lib');
+
const RippleAPI = require('ripple-lib').RippleAPI;
 
 const api = new RippleAPI();
 /* insert code here */
 

-
Methods that depend on the state of the Ripple Consensus Ledger are unavailable in offline mode. To prepare transactions offline, you must specify  the fee, sequence, and maxLedgerVersion parameters in the transaction instructions. The following methods should work offline:

+
Methods that depend on the state of the XRP Ledger are unavailable in offline mode. To prepare transactions offline, you must specify  the fee, sequence, and maxLedgerVersion parameters in the transaction instructions. You can use the following methods while offline:

 
 
Basic Types

-
Ripple Address

+
Address

 
"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59"
 

-
Every Ripple account has an address, which is a base58-encoding of a hash of the account's public key. Ripple addresses always start with the lowercase letter r.

+
Every XRP Ledger account has an address, which is a base58-encoding of a hash of the account's public key. XRP Ledger addresses always start with the lowercase letter r.

 
Account Sequence Number

-
Every Ripple account has a sequence number that is used to keep transactions in order. Every transaction must have a sequence number. A transaction can only be executed if it has the next sequence number in order, of the account sending it. This prevents one transaction from executing twice and transactions executing out of order. The sequence number starts at 1 and increments for each transaction that the account makes.

+
Every XRP Ledger account has a sequence number that is used to keep transactions in order. Every transaction must have a sequence number. A transaction can only be executed if it has the next sequence number in order, of the account sending it. This prevents one transaction from executing twice and transactions executing out of order. The sequence number starts at 1 and increments for each transaction that the account makes.

 
Currency

-
Currencies are represented as either 3-character currency codes or 40-character uppercase hexadecimal strings. We recommend using uppercase ISO 4217 Currency Codes only. The string "XRP" is disallowed on trustlines because it is reserved for the Ripple native currency. The following characters are permitted: all uppercase and lowercase letters, digits, as well as the symbols ?, !, @, #, $, %, ^, &, *, <, >, (, ), {, }, [, ], and |.

+
Currencies are represented as either 3-character currency codes or 40-character uppercase hexadecimal strings. We recommend using uppercase ISO 4217 Currency Codes only. The string "XRP" is disallowed on trustlines because it is reserved for the XRP Ledger's native currency. The following characters are permitted: all uppercase and lowercase letters, digits, as well as the symbols ?, !, @, #, $, %, ^, &, *, <, >, (, ), {, }, [, ], and |.

 
Value

 
A value is a quantity of a currency represented as a decimal string. Be careful: JavaScript's native number format does not have sufficient precision to represent all values. XRP has different precision from other currencies.

 
XRP has 6 significant digits past the decimal point. In other words, XRP cannot be divided into positive values smaller than 0.000001 (1e-6). XRP has a maximum value of 100000000000 (1e11).

@@ -558,11 +565,11 @@ const api = new RippleAPI();
 
 
 order
-An order transaction creates a limit order. It defines an intent to exchange currencies, and creates an order in the Ripple Consensus Ledger's order book if not completely fulfilled when placed. Orders can be partially fulfilled.
+An order transaction creates a limit order. It defines an intent to exchange currencies, and creates an order in the XRP Ledger's order book if not completely fulfilled when placed. Orders can be partially fulfilled.
 
 
 orderCancellation
-An orderCancellation transaction cancels an order in the Ripple Consensus Ledger's order book.
+An orderCancellation transaction cancels an order in the XRP Ledger's order book.
 
 
 trustline
@@ -570,11 +577,11 @@ const api = new RippleAPI();
 
 
 settings
-A settings transaction modifies the settings of an account in the Ripple Consensus Ledger.
+A settings transaction modifies the settings of an account in the XRP Ledger.
 
 
 escrowCreation
-An escrowCreation transaction creates an escrow on the ledger, which locks XRP until a cryptographic condition is met or it expires. It is like an escrow service where the Ripple network acts as the escrow agent.
+An escrowCreation transaction creates an escrow on the ledger, which locks XRP until a cryptographic condition is met or it expires. It is like an escrow service where the XRP Ledger acts as the escrow agent.
 
 
 escrowCancellation
@@ -586,7 +593,6 @@ const api = new RippleAPI();
 
 
 
-
The three "escrow" transaction types are not supported by the production Ripple peer-to-peer network at this time. They are available for testing purposes if you configure RippleAPI to connect to the Ripple Test Net instead.

 
Transaction Flow

 
Executing a transaction with RippleAPI requires the following four steps:

 
    
@@ -606,7 +612,7 @@ const api = new RippleAPI();
 
  1. Verify - Verify that the transaction got validated by querying with getTransaction. This is necessary because transactions may fail even if they were successfully submitted.
    2. 
 

 
Transaction Fees

-
Every transaction must destroy a small amount of XRP as a cost to send the transaction. This is also called a transaction fee. The transaction cost is designed to increase along with the load on the Ripple network, making it very expensive to deliberately or inadvertently overload the network.

+
Every transaction must destroy a small amount of XRP as a cost to send the transaction. This is also called a transaction fee. The transaction cost is designed to increase along with the load on the XRP Ledger, making it very expensive to deliberately or inadvertently overload the peer-to-peer network that powers the XRP Ledger.

 
You can choose the size of the fee you want to pay or let a default be used. You can get an estimate of the fee required to be included in the next ledger closing with the getFee method.

 
Transaction Instructions

 
Transaction instructions indicate how to execute a transaction, complementary with the transaction specification.

@@ -651,7 +657,7 @@ const api = new RippleAPI();
 
 
 
-
We recommended that you specify a maxLedgerVersion so that you can quickly determine that a failed transaction will never succeeed in the future. It is impossible for a transaction to succeed after the network ledger version exceeds the transaction's maxLedgerVersion. If you omit maxLedgerVersion, the "prepare" method automatically supplies a maxLedgerVersion equal to the current ledger plus 3, which it includes in the return value from the "prepare" method.

+
We recommended that you specify a maxLedgerVersion so that you can quickly determine that a failed transaction will never succeeed in the future. It is impossible for a transaction to succeed after the XRP Ledger's consensus-validated ledger version exceeds the transaction's maxLedgerVersion. If you omit maxLedgerVersion, the "prepare" method automatically supplies a maxLedgerVersion equal to the current ledger plus 3, which it includes in the return value from the "prepare" method.

 
Transaction ID

 
"F4AB442A6D4CBB935D66E1DA7309A5FC71C7143ED4049053EC14E3875B0CF9BF"
 

@@ -1147,7 +1153,7 @@ const api = new RippleAPI();
 
 condition
 string
-Optional If present, fulfillment is required upon execution.
+Optional A hex value representing a PREIMAGE-SHA-256 crypto-condition. If present, fulfillment is required upon execution.
 
 
 destinationTag
@@ -1231,12 +1237,12 @@ const api = new RippleAPI();
 
 condition
 string
-Optional The original condition from the escrow creation transaction. This is sha256 hash of fulfillment string. It is replicated here so that the relatively expensive hashing operation can be delegated to a server without ledger history and the server with ledger history only has to do a quick comparison of the old condition with the new condition.
+Optional A hex value representing a PREIMAGE-SHA-256 crypto-condition. This must match the original condition from the escrow creation transaction.
 
 
 fulfillment
 string
-Optional A value that produces the condition when hashed. It must be 32 charaters long and contain only 8-bit characters.
+Optional A hex value representing the PREIMAGE-SHA-256 crypto-condition fulfillment for condition.
 
 
 memos
@@ -1277,7 +1283,7 @@ const api = new RippleAPI();
 
 settleDelay
 number
-Amount of time the source address must wait before closing the channel if it has unclaimed XRP.
+Amount of seconds the source address must wait before closing the channel if it has unclaimed XRP.
 
 
 publicKey
@@ -4243,10 +4249,120 @@ return api.getAccountInfo(address).then(info =>
   "previousAffectingTransactionLedgerVersion": 6614625
 }
 

+
getPaymentChannel

+
getPaymentChannel(id: string): Promise<Object>

+
Returns specified payment channel.

+
Parameters

+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
NameTypeDescription
idstring256-bit hexadecimal channel identifier.

+
Return Value

+
This method returns a promise that resolves with an object with the following structure:

+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
NameTypeDescription
accountaddressAddress that created the payment channel.
destinationaddressAddress to receive XRP claims against this channel.
amountvalueThe total amount of XRP funded in this channel.
balancevalueThe total amount of XRP delivered by this channel.
settleDelaynumberAmount of seconds the source address must wait before closing the channel if it has unclaimed XRP.
previousAffectingTransactionIDstringHash value representing the most recent transaction that affected this payment channel.
previousAffectingTransactionLedgerVersionintegerThe ledger version that the transaction identified by the previousAffectingTransactionID was validated in.
cancelAfterdate-time stringOptional Time when this channel expires as specified at creation.
destinationTagintegerOptional Destination tag.
expirationdate-time stringOptional Time when this channel expires.
publicKeystringOptional Public key of the key pair the source will use to sign claims against this channel.
sourceTagintegerOptional Source tag.

+
Example

+
const channelId =
+  'E30E709CF009A1F26E0E5C48F7AA1BFB79393764F15FB108BDC6E06D3CBD8415';
+return api.getPaymentChannel(channelId).then(channel =>
+  {/* ... */});
+

+
{
+  "account": "r6ZtfQFWbCkp4XqaUygzHaXsQXBT67xLj",
+  "amount": "10",
+  "balance": "0",
+  "destination": "rQf9vCwQtzQQwtnGvr6zc1fqzqg7QBuj7G",
+  "publicKey": "02A05282CB6197E34490BACCD9405E81D9DFBE123B0969F9F40EC3F9987AD9A97D",
+  "settleDelay": 10000,
+  "previousAffectingTransactionID": "F939A0BEF139465403C56CCDC49F59A77C868C78C5AEC184E29D15E9CD1FF675",
+  "previousAffectingTransactionLedgerVersion": 151322
+}
+

 
getLedger

 
getLedger(options: Object): Promise<Object>

 
Returns header information for the specified ledger (or the most recent validated ledger if no ledger is specified). Optionally, all the transactions that were validated in the ledger or the account state information can be returned with the ledger header.

-
Parameters

+
Parameters

 
@@ -4283,7 +4399,7 @@ return api.getAccountInfo(address).then(info =>
 

 
 

 
 

-
Return Value

+
Return Value

 
This method returns a promise that resolves with an object with the following structure:

 
@@ -4371,7 +4487,7 @@ return api.getAccountInfo(address).then(info =>
 

 
 
 

-
Example

+
Example

 
return api.getLedger()
   .then(ledger => {/* ... */});
 

@@ -4391,7 +4507,7 @@ return api.getAccountInfo(address).then(info =>
 
preparePayment

 
preparePayment(address: string, payment: Object, instructions: Object): Promise<Object>

 
Prepare a payment transaction. The prepared transaction must subsequently be signed and submitted.

-
Parameters

+
Parameters

 
@@ -4418,109 +4534,6 @@ return api.getAccountInfo(address).then(info =>
 

 
 

 
 

-
Return Value

-
This method returns a promise that resolves with an object with the following structure:

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
NameTypeDescription
txJSONstringThe prepared transaction in rippled JSON format.
instructionsobjectThe instructions for how to execute the transaction after adding automatic defaults.
instructions. feevalueAn exact fee to pay for the transaction. See Transaction Fees for more information.
instructions. sequencesequenceThe initiating account's sequence number for this transaction.
instructions. maxLedgerVersioninteger,nullThe highest ledger version that the transaction can be included in. Set to null if there is no maximum.

-
Example

-
const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
-const payment = {
-  "source": {
-    "address": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-    "maxAmount": {
-      "value": "0.01",
-      "currency": "USD",
-      "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM"
-    }
-  },
-  "destination": {
-    "address": "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo",
-    "amount": {
-      "value": "0.01",
-      "currency": "USD",
-      "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM"
-    }
-  }
-};
-return api.preparePayment(address, payment).then(prepared =>
-  {/* ... */});
-

-
{
-  "txJSON": "{\"Flags\":2147483648,\"TransactionType\":\"Payment\",\"Account\":\"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59\",\"Destination\":\"rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo\",\"Amount\":{\"value\":\"0.01\",\"currency\":\"USD\",\"issuer\":\"rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM\"},\"SendMax\":{\"value\":\"0.01\",\"currency\":\"USD\",\"issuer\":\"rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM\"},\"LastLedgerSequence\":8820051,\"Fee\":\"12\",\"Sequence\":23}",
-  "instructions": {
-    "fee": "0.000012",
-    "sequence": 23,
-    "maxLedgerVersion": 8820051
-  }
-}
-

-
prepareTrustline

-
prepareTrustline(address: string, trustline: Object, instructions: Object): Promise<Object>

-
Prepare a trustline transaction. The prepared transaction must subsequently be signed and submitted.

-
Parameters

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
NameTypeDescription
addressaddressThe address of the account that is creating the transaction.
trustlinetrustlineThe specification of the trustline to prepare.
instructionsinstructionsOptional Instructions for executing the transaction

 
Return Value

 
This method returns a promise that resolves with an object with the following structure: