# RippleAPI Reference - [Introduction](#introduction) - [Boilerplate](#boilerplate) - [Offline functionality](#offline-functionality) - [Basic Types](#basic-types) - [Address](#address) - [Account Sequence Number](#account-sequence-number) - [Currency](#currency) - [Value](#value) - [Amount](#amount) - [Transaction Overview](#transaction-overview) - [Transaction Types](#transaction-types) - [Transaction Flow](#transaction-flow) - [Transaction Fees](#transaction-fees) - [Transaction Instructions](#transaction-instructions) - [Transaction ID](#transaction-id) - [Transaction Memos](#transaction-memos) - [Transaction Specifications](#transaction-specifications) - [Account Delete](#account-delete) - [Check Cancel](#check-cancel) - [Check Cash](#check-cash) - [Check Create](#check-create) - [Deposit Preauth](#deposit-preauth) - [Escrow Cancellation](#escrow-cancellation) - [Escrow Creation](#escrow-creation) - [Escrow Execution](#escrow-execution) - [Order](#order) - [Order Cancellation](#order-cancellation) - [Payment](#payment) - [Payment Channel Claim](#payment-channel-claim) - [Payment Channel Create](#payment-channel-create) - [Payment Channel Fund](#payment-channel-fund) - [Settings](#settings) - [Ticket Create](#ticket-create) - [Trustline](#trustline) - [rippled APIs](#rippled-apis) - [Listening to streams](#listening-to-streams) - [request](#request) - [hasNextPage](#hasnextpage) - [requestNextPage](#requestnextpage) - [Static Methods](#static-methods) - [computeBinaryTransactionHash](#computebinarytransactionhash) - [classicAddressToXAddress](#classicaddresstoxaddress) - [xAddressToClassicAddress](#xaddresstoclassicaddress) - [renameCounterpartyToIssuer](#renamecounterpartytoissuer) - [formatBidsAndAsks](#formatbidsandasks) - [API Methods](#api-methods) - [connect](#connect) - [disconnect](#disconnect) - [isConnected](#isconnected) - [getServerInfo](#getserverinfo) - [getFee](#getfee) - [getLedgerVersion](#getledgerversion) - [getTransaction](#gettransaction) - [getTransactions](#gettransactions) - [getTrustlines](#gettrustlines) - [getBalances](#getbalances) - [getBalanceSheet](#getbalancesheet) - [getPaths](#getpaths) - [getOrders](#getorders) - [getOrderbook](#getorderbook) - [getSettings](#getsettings) - [getAccountInfo](#getaccountinfo) - [getAccountObjects](#getaccountobjects) - [getPaymentChannel](#getpaymentchannel) - [getLedger](#getledger) - [parseAccountFlags](#parseaccountflags) - [prepareTransaction](#preparetransaction) - [preparePayment](#preparepayment) - [prepareTrustline](#preparetrustline) - [prepareOrder](#prepareorder) - [prepareOrderCancellation](#prepareordercancellation) - [prepareSettings](#preparesettings) - [prepareEscrowCreation](#prepareescrowcreation) - [prepareEscrowCancellation](#prepareescrowcancellation) - [prepareEscrowExecution](#prepareescrowexecution) - [preparePaymentChannelCreate](#preparepaymentchannelcreate) - [preparePaymentChannelClaim](#preparepaymentchannelclaim) - [preparePaymentChannelFund](#preparepaymentchannelfund) - [prepareCheckCreate](#preparecheckcreate) - [prepareCheckCancel](#preparecheckcancel) - [prepareCheckCash](#preparecheckcash) - [prepareTicketCreate](#prepareticketcreate) - [sign](#sign) - [combine](#combine) - [submit](#submit) - [generateXAddress](#generatexaddress) - [generateAddress](#generateaddress) - [isValidAddress](#isvalidaddress) - [isValidSecret](#isvalidsecret) - [deriveKeypair](#derivekeypair) - [deriveAddress](#deriveaddress) - [generateFaucetWallet](#generatefaucetwallet) - [signPaymentChannelClaim](#signpaymentchannelclaim) - [verifyPaymentChannelClaim](#verifypaymentchannelclaim) - [computeLedgerHash](#computeledgerhash) - [xrpToDrops](#xrptodrops) - [dropsToXrp](#dropstoxrp) - [iso8601ToRippleTime](#iso8601torippletime) - [rippleTimeToISO8601](#rippletimetoiso8601) - [txFlags](#txflags) - [AccountSet Flags](#accountset-flags) - [schemaValidator](#schemavalidator) - [schemaValidate](#schemavalidate) - [API Events](#api-events) - [ledger](#ledger) - [error](#error) - [connected](#connected) - [disconnected](#disconnected) # Introduction RippleAPI (ripple-lib) is the official client library to the XRP Ledger. Currently, RippleAPI is only available in JavaScript/TypeScript. Using RippleAPI, you can: * [Query transactions from the XRP Ledger history](#gettransaction) * [Sign](#sign) transactions securely without connecting to any server * [Submit](#submit) transactions to the XRP Ledger, including [Payments](#payment), [Orders](#order), [Settings changes](#settings), and [other types](#transaction-types) * [Generate a new XRP Ledger Address](#generateaddress) * ... and [much more](#api-methods). This page contains documentation for ripple-lib. To use ripple-lib with npm/yarn, begin with the [Getting Started](https://github.com/ripple/ripple-lib#getting-started) steps. **What is ripple-lib used for?** Here's a [list of applications that use `ripple-lib`](https://github.com/ripple/ripple-lib/blob/develop/APPLICATIONS.md). Open a PR to add your app or project to the list! ## Boilerplate Use the following [boilerplate code](https://en.wikipedia.org/wiki/Boilerplate_code) to wrap your custom code using RippleAPI. ```javascript const RippleAPI = require('ripple-lib').RippleAPI; const api = new RippleAPI({ server: 'wss://xrplcluster.com' // Public cluster }); api.on('error', (errorCode, errorMessage) => { console.log(errorCode + ': ' + errorMessage); }); api.on('connected', () => { console.log('connected'); }); api.on('disconnected', (code) => { // code - [close code](https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent) sent by the server // the code is 1000 for a normal closure console.log('disconnected, code:', code); }); api.connect().then(() => { /* insert code here */ }).then(() => { return api.disconnect(); }).catch(console.error); ``` [Node.js v14](https://nodejs.org/) is recommended. Other versions may work but are not frequently tested. ### Parameters The RippleAPI constructor optionally takes one argument, an object with the following options: Name | Type | Description ---- | ---- | ----------- authorization | string | *Optional* Username and password for HTTP basic authentication to the rippled server in the format **username:password**. certificate | string | *Optional* A string containing the certificate key of the client in PEM format. (Can be an array of certificates). connectionTimeout | integer | *Optional* Connection timeout, in milliseconds, before considering connect() to have failed. feeCushion | number | *Optional* Factor to multiply estimated fee by to provide a cushion in case the required fee rises during submission of a transaction. Defaults to `1.2`. key | string | *Optional* A string containing the private key of the client in PEM format. (Can be an array of keys). maxFeeXRP | string | *Optional* Maximum fee to use with transactions, in XRP. Must be a string-encoded number. Defaults to `'2'`. passphrase | string | *Optional* The passphrase for the private key of the client. proxy | uri string | *Optional* URI for HTTP/HTTPS proxy to use to connect to the rippled server. proxyAuthorization | string | *Optional* Username and password for HTTP basic authentication to the proxy in the format **username:password**. server | uri string | *Optional* URI for rippled websocket port to connect to. Must start with `wss://`, `ws://`, `wss+unix://`, or `ws+unix://`. timeout | integer | *Optional* Request timeout in milliseconds before considering a request to have failed. See also: connectionTimeout. trace | boolean | *Optional* If true, log rippled requests and responses to stdout. trustedCertificates | array\ | *Optional* Array of PEM-formatted SSL certificates to trust when connecting to a proxy. This is useful if you want to use a self-signed certificate on the proxy server. Note: Each element must contain a single certificate; concatenated certificates are not valid. If you omit the `server` parameter, RippleAPI operates [offline](#offline-functionality). ### Installation ### 1. Install [Node.js](https://nodejs.org) and [Yarn](https://yarnpkg.com/en/docs/install). Most Linux distros have a package for Node.js; check that it's the version you want. 2. Use yarn to install RippleAPI: `yarn add ripple-lib` After you have installed ripple-lib, you can create scripts using the [boilerplate](#boilerplate) and run them using the Node.js executable, typically named `node`: `node script.js` ## Offline functionality RippleAPI can also function without internet connectivity, so you can generate secrets and sign transactions from a secure, isolated machine. To instantiate RippleAPI in offline mode, use the following code: ```javascript const RippleAPI = require('ripple-lib').RippleAPI; const api = new RippleAPI(); /* insert code here */ ``` 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](#transaction-instructions). You can use the following methods while offline: * [preparePayment](#preparepayment) * [prepareTrustline](#preparetrustline) * [prepareOrder](#prepareorder) * [prepareOrderCancellation](#prepareordercancellation) * [prepareSettings](#preparesettings) * [prepareEscrowCreation](#prepareescrowcreation) * [prepareEscrowCancellation](#prepareescrowcancellation) * [prepareEscrowExecution](#prepareescrowexecution) * [sign](#sign) * [generateAddress](#generateaddress) * [generateXAddress](#generatexaddress) * [computeLedgerHash](#computeledgerhash) # Basic Types ## Address ```json "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59" ``` ```json "X7AcgcsBL6XDcUb289X4mJ8djcdyKaB5hJDWMArnXr61cqZ" ``` An *address* refers to a specific XRP Ledger account. It is a base-58 encoding of a hash of the account's public key. There are two kinds of addresses in common use: ### Classic Address A *classic address* encodes a hash of the account's public key and a checksum. It has no other data. This kind of address always starts with the lowercase letter `r`. ### X-address An *X-address* encodes a hash of the account's public key, a tag, and a checksum. This kind of address starts with the uppercase letter `X` if it is intended for use on the production XRP Ledger (mainnet). It starts with the uppercase letter `T` if it is intended for use on a test network such as Testnet or Devnet. ## Account Sequence Number Every XRP Ledger account has a *sequence number* that is used to keep transactions in order. Every transaction must have a sequence or a ticketSequence number. A transaction can only be executed if it has the next sequence number in order, of the account sending it, or uses a previously generated ticketSequence number. 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](http://www.xe.com/iso4217.php) 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). This smallest unit is called a "drop". XRP has a maximum value of `100000000000` (1e11). Some RippleAPI methods accept XRP to maintain compatibility with older versions of the API. For consistency with the `rippled` APIs, we recommend formally specifying XRP values in *drops* in all API requests, and converting them to XRP for display. This is like Bitcoin's *satoshis* and Ethereum's *wei*. 1 XRP = 1,000,000 drops. **Non-XRP values** have 16 decimal digits of precision, with a maximum value of `9999999999999999e80`. The smallest positive non-XRP value is `1e-81`. ## Amount Example 100.00 USD amount: ```json { "currency": "USD", "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM", "value": "100" } ``` Example 3.0 XRP amount, in drops: ```json { "currency": "drops", "value": "3000000" } ``` (Requires `ripple-lib` version 1.0.0 or higher.) An *amount* is an object specifying a currency, a quantity of that currency, and the counterparty (issuer) on the trustline that holds the value. For XRP, there is no counterparty. A *lax amount* allows the counterparty to be omitted for all currencies. If the counterparty is not specified in an amount within a transaction specification, then any counterparty may be used for that amount. A *lax lax amount* allows either or both the counterparty and value to be omitted. A *balance* is an amount than can have a negative value. Name | Type | Description ---- | ---- | ----------- currency | [currency](#currency) | The three-character code or hexadecimal string used to denote currencies, or "drops" for the smallest unit of XRP. counterparty | [address](#address) | *Optional* The XRP Ledger address of the account that owes or is owed the funds (omitted if `currency` is "XRP" or "drops") value | [value](#value) | *Optional* The quantity of the currency, denoted as a string so that it does not lose precision # Transaction Overview ## Transaction Types A transaction type is specified by the strings in the first column in the table below. Type | Description ---- | ----------- [payment](#payment) | A `payment` transaction represents a transfer of value from one account to another. Depending on the [path](https://xrpl.org/paths.html) taken, additional exchanges of value may occur atomically to enable the payment. [order](#order) | 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](#order-cancellation) | An `orderCancellation` transaction cancels an order in the XRP Ledger's order book. [trustline](#trustline) | A `trustline` transaction creates or modifies a trust line between two accounts. [settings](#settings) | A `settings` transaction modifies the settings of an account in the XRP Ledger. [escrowCreation](#escrow-creation) | 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](#escrow-cancellation) | An `escrowCancellation` transaction unlocks the funds in an escrow and sends them back to the creator of the escrow, if the escrow has expired. [escrowExecution](#escrow-execution) | An `escrowExecution` transaction unlocks the funds in an escrow and sends them to the destination of the escrow, if the conditions for the escrow are met. [checkCreate](#check-create) | A `checkCreate` transaction creates a check on the ledger, which is a deferred payment that can be cashed by its intended destination. [checkCancel](#check-cancel) | A `checkCancel` transaction cancels an unredeemed Check, removing it from the ledger without sending any money. [checkCash](#check-cash) | A `checkCash` transaction redeems a Check to receive up to the amount authorized by the corresponding `checkCreate` transaction. Only the `destination` address of a Check can cash it. [paymentChannelCreate](#payment-channel-create) | A `paymentChannelCreate` transaction opens a payment channel between two addresses with XRP set aside for asynchronous payments. [paymentChannelFund](#payment-channel-fund) | A `paymentChannelFund` transaction adds XRP to a payment channel and optionally sets a new expiration for the channel. [paymentChannelClaim](#payment-channel-claim) | A `paymentChannelClaim` transaction withdraws XRP from a channel and optionally requests to close it. [ticketCreate](#ticket-create) | A successful `ticketCreate` transaction adds a Ticket in the directory of the owning account. ## Transaction Flow Executing a transaction with `RippleAPI` requires the following four steps: 1. Prepare - Create an unsigned transaction based on a [specification](#transaction-specifications) and [instructions](#transaction-instructions). There is a method to prepare each type of transaction: * [preparePayment](#preparepayment) * [prepareTrustline](#preparetrustline) * [prepareOrder](#prepareorder) * [prepareOrderCancellation](#prepareordercancellation) * [prepareSettings](#preparesettings) * [prepareEscrowCreation](#prepareescrowcreation) * [prepareEscrowCancellation](#prepareescrowcancellation) * [prepareEscrowExecution](#prepareescrowexecution) * [prepareCheckCreate](#preparecheckcreate) * [prepareCheckCancel](#preparecheckcancel) * [prepareCheckCash](#preparecheckcash) * [prepareTicketCreate](#prepareticketcreate) 2. [Sign](#sign) - Cryptographically sign the transaction locally and save the [transaction ID](#transaction-id). Signing is how the owner of an account authorizes a transaction to take place. For multisignature transactions, the `signedTransaction` fields returned by `sign` must be collected and passed to the [combine](#combine) method. 3. [Submit](#submit) - Submit the transaction to the connected server. 4. Verify - Verify that the transaction got validated by querying with [getTransaction](#gettransaction). This is necessary because transactions may fail even if they were successfully submitted. ## Transaction Fees Every transaction must destroy a small amount of XRP as a cost to apply the transaction to the ledger. 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](#getfee) method. For a multi-signed transaction, ripple-lib automatically multiplies the `fee` by (1 + Number of Signatures Provided). For example, if you set `instructions.fee = '0.000020'` and `instructions.signersCount = 2`, the prepared transaction's `Fee` is 20 drops × (1 + 2 Signatures) = 60 drops. See [Transaction Cost](https://xrpl.org/transaction-cost.html). ## Transaction Instructions Transaction instructions indicate how to execute a transaction, complementary with the [transaction specification](#transaction-specifications). Name | Type | Description ---- | ---- | ----------- fee | [value](#value) | *Optional* An exact fee to pay for the transaction, before multiplying for multi-signed transactions. See [Transaction Fees](#transaction-fees) for more information. maxFee | [value](#value) | *Optional* Deprecated: Use `maxFeeXRP` in the RippleAPI constructor instead. The maximum fee to pay for this transaction. If this exceeds `maxFeeXRP`, use `maxFeeXRP` instead. See [Transaction Fees](#transaction-fees) for more information. maxLedgerVersion | integer,null | *Optional* The highest ledger version that the transaction can be included in. If this option and `maxLedgerVersionOffset` are both omitted, the default is 3 greater than the current validated ledger version (equivalent to `maxLedgerVersionOffset=3`). Use `null` to not set a maximum ledger version. If not null, this must be an integer greater than 0, or one of the following strings: 'validated', 'closed', 'current'. maxLedgerVersion | string,null | *Optional* The highest ledger version that the transaction can be included in. If this option and `maxLedgerVersionOffset` are both omitted, the default is 3 greater than the current validated ledger version (equivalent to `maxLedgerVersionOffset=3`). Use `null` to not set a maximum ledger version. If not null, this must be an integer greater than 0, or one of the following strings: 'validated', 'closed', 'current'. maxLedgerVersionOffset | integer | *Optional* Offset from current validated ledger version to highest ledger version that the transaction can be included in. sequence | [sequence](#account-sequence-number) | *Optional* The initiating account's sequence number for this transaction. `sequence` and `ticketSequence` are mutually exclusive, only one of them can be set. signersCount | integer | *Optional* Number of signers that can multi-sign this transaction. ticketSequence | [ticket-sequence](#account-sequence-number) | *Optional* The ticket sequence to be used for this transaction. `sequence` and `ticketSequence` are mutually exclusive, only one of them can be set. We recommend that you specify a `maxLedgerVersion` so that you can quickly determine that a failed transaction can never succeed 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 ```json "F4AB442A6D4CBB935D66E1DA7309A5FC71C7143ED4049053EC14E3875B0CF9BF" ``` A transaction ID is a 64-bit hexadecimal string that uniquely identifies the transaction. The transaction ID is derived from the transaction instruction and specifications, using a strong hash function. You can look up a transaction by ID using the [getTransaction](#gettransaction) method. ## Transaction Memos Every transaction can optionally have an array of memos for user applications. The `memos` field in each [transaction specification](#transaction-specifications) is an array of objects with the following structure: Name | Type | Description ---- | ---- | ----------- data | string | *Optional* Arbitrary string, conventionally containing the content of the memo. format | string | *Optional* Conventionally containing information on how the memo is encoded, for example as a [MIME type](http://www.iana.org/assignments/media-types/media-types.xhtml). Only characters allowed in URLs are permitted. type | string | *Optional* Conventionally, a unique relation (according to [RFC 5988](http://tools.ietf.org/html/rfc5988#section-4)) that defines the format of this memo. Only characters allowed in URLs are permitted. # Transaction Specifications A *transaction specification* specifies what a transaction should do. Each [Transaction Type](#transaction-types) has its own type of specification, which corresponds to the [native XRP Ledger transaction types](https://xrpl.org/transaction-types.html). ## Account Delete Delete your account and send the remaining XRP elsewhere. (Native transaction type: [AccountDelete](https://xrpl.org/accountdelete.html)) Name | Type | Description ---- | ---- | ----------- destination | [address](#address) | *Optional* Address of an account to receive any leftover XRP after deleting the sending account. Must be a funded account in the ledger, and must not be the sending account. destinationTag | integer | *Optional* (Optional) Arbitrary destination tag that identifies a hosted recipient or other information for the recipient of the deleted account's leftover XRP. destinationXAddress | [address](#address) | *Optional* X-address of an account to receive any leftover XRP after deleting the sending account. Must be a funded account in the ledger, and must not be the sending account. memos | [memos](#transaction-memos) | *Optional* Array of memos to attach to the transaction. > **Note:** To prepare an Account Delete transaction, use [`prepareTransaction()`](#preparetransaction) with the [native transaction format](https://xrpl.org/accountdelete.html). ## Check Cancel Cancel a Check that has not been redeemed. (Native transaction type: [CheckCancel](https://xrpl.org/checkcancel.html)) Name | Type | Description ---- | ---- | ----------- checkID | string | The ID of the Check ledger object to cancel, as a 64-character hexadecimal string. memos | [memos](#transaction-memos) | *Optional* Array of memos to attach to the transaction. #### Example ```json { "checkID": "49647F0D748DC3FE26BDACBC57F251AADEFFF391403EC9BF87C97F67E9977FB0" } ``` ## Check Cash Redeem a Check for up to its stated value. (Native transaction type: [CheckCash](https://xrpl.org/checkcash.html)) Name | Type | Description ---- | ---- | ----------- checkID | string | The ID of the Check ledger object to cash, as a 64-character hexadecimal string. amount | [laxAmount](#amount) | *Optional* Redeem the Check for exactly this amount, if possible. The currency must match that of the sendMax of the corresponding CheckCreate transaction. You must provide either this field or deliverMin. deliverMin | [laxAmount](#amount) | *Optional* Redeem the Check for at least this amount and for as much as possible. The currency must match that of the sendMax of the corresponding CheckCreate transaction. You must provide either this field or amount. memos | [memos](#transaction-memos) | *Optional* Array of memos to attach to the transaction. #### Example ```json { "amount": { "currency": "drops", "value": "1000000" }, "checkID": "838766BA2B995C00744175F69A1B11E32C3DBC40E64801A4056FCBD657F57334" } ``` ## Check Create Create a Check, a deferred payment that can be redeemed by the destination. (Native transaction type: [CheckCreate](https://xrpl.org/checkcreate.html)) Name | Type | Description ---- | ---- | ----------- destination | [address](#address) | Address of the account that can cash the check. sendMax | [laxAmount](#amount) | Amount of source currency the check is allowed to debit the sender, including transfer fees on non-XRP currencies. destinationTag | integer | *Optional* Destination tag that identifies the reason for the check, or a hosted recipient to pay. expiration | date-time string | *Optional* Time after which the check is no longer valid. invoiceID | string | *Optional* 256-bit hash, as a 64-character hexadecimal string, representing a specific reason or identifier for this check. memos | [memos](#transaction-memos) | *Optional* Array of memos to attach to the transaction. #### Example ```json { "destination": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW", "sendMax": { "currency": "drops", "value": "1000000" } } ``` ## Deposit Preauth Preauthorize an sender to deposit money at an account using [Deposit Authorization](https://xrpl.org/depositauth.html). (Native transaction type: [DepositPreauth](https://xrpl.org/depositpreauth.html)) Name | Type | Description ---- | ---- | ----------- authorize | [address](#address) | *Optional* Address of the account that can cash the check. memos | [memos](#transaction-memos) | *Optional* Array of memos to attach to the transaction. unauthorize | [address](#address) | *Optional* Address of the account that can cash the check. > **Note:** To prepare a Deposit Preauth transaction, use [`prepareTransaction()`](#preparetransaction) with the [native transaction format](https://xrpl.org/depositpreauth.html). ## Escrow Cancellation Cancel an Escrow that has passed its expiration. (Native transaction type: [EscrowCancel](https://xrpl.org/escrowcancel.html)) Name | Type | Description ---- | ---- | ----------- owner | [address](#address) | The address of the owner of the escrow to cancel. escrowSequence | [sequence](#account-sequence-number) | The [account sequence number](#account-sequence-number) of the [Escrow Creation](#escrow-creation) transaction for the escrow to cancel. memos | [memos](#transaction-memos) | *Optional* Array of memos to attach to the transaction. #### Example ```json { "owner": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59", "escrowSequence": 1234 } ``` ## Escrow Creation Create an Escrow that locks up XRP until a given time or condition is met. (Native transaction type: [EscrowCreate](https://xrpl.org/escrowcreate.html)) Name | Type | Description ---- | ---- | ----------- amount | [value](#value) | Amount of XRP for sender to escrow. destination | [address](#address) | Address to receive escrowed XRP. allowCancelAfter | date-time string | *Optional* If present, the escrow may be cancelled after this time. allowExecuteAfter | date-time string | *Optional* If present, the escrow can not be executed before this time. condition | string | *Optional* A hex value representing a [PREIMAGE-SHA-256 crypto-condition](https://tools.ietf.org/html/draft-thomas-crypto-conditions-02#section-8.1). If present, `fulfillment` is required upon execution. destinationTag | integer | *Optional* Destination tag. memos | [memos](#transaction-memos) | *Optional* Array of memos to attach to the transaction. sourceTag | integer | *Optional* Source tag. #### Example ```json { "destination": "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo", "amount": "0.01", "allowExecuteAfter": "2014-09-24T21:21:50.000Z", "allowCancelAfter": "2017-01-01T00:00:00.000Z" } ``` ## Escrow Execution Deliver XRP from an Escrow after its conditions have been met. (Native transaction type: [EscrowFinish](https://xrpl.org/escrowfinish.html)) Name | Type | Description ---- | ---- | ----------- owner | [address](#address) | The address of the owner of the escrow to execute. escrowSequence | [sequence](#account-sequence-number) | The [account sequence number](#account-sequence-number) of the [Escrow Creation](#escrow-creation) transaction for the escrow to execute. condition | string | *Optional* A hex value representing a [PREIMAGE-SHA-256 crypto-condition](https://tools.ietf.org/html/draft-thomas-crypto-conditions-02#section-8.1). This must match the original `condition` from the escrow creation transaction. fulfillment | string | *Optional* A hex value representing the [PREIMAGE-SHA-256 crypto-condition](https://tools.ietf.org/html/draft-thomas-crypto-conditions-02#section-8.1) fulfillment for `condition`. memos | [memos](#transaction-memos) | *Optional* Array of memos to attach to the transaction. #### Example ```json { "owner": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59", "escrowSequence": 1234, "condition": "A0258020E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855810100", "fulfillment": "A0028000" } ``` ## Order Create and execute a limit order in the decentralized exchange. (Native transaction type: [OfferCreate](https://xrpl.org/offercreate.html)) Name | Type | Description ---- | ---- | ----------- direction | string | Equal to "buy" for buy orders and "sell" for sell orders. quantity | [amount](#amount) | The amount of currency to buy or sell. totalPrice | [amount](#amount) | The total price to be paid for the `quantity` to be bought or sold. expirationTime | date-time string | *Optional* Time after which the offer is no longer active, as an [ISO 8601 date-time](https://en.wikipedia.org/wiki/ISO_8601). fillOrKill | boolean | *Optional* Treat the offer as a [Fill or Kill order](http://en.wikipedia.org/wiki/Fill_or_kill). Only attempt to match existing offers in the ledger, and only do so if the entire quantity can be exchanged. This cannot be used with `immediateOrCancel`. immediateOrCancel | boolean | *Optional* Treat the offer as an [Immediate or Cancel order](http://en.wikipedia.org/wiki/Immediate_or_cancel). If enabled, do not create an object in the ledger that can be matched later: instead, only execute as much as can be fulfilled immediately. This cannot be used with `fillOrKill`. memos | [memos](#transaction-memos) | *Optional* Array of memos to attach to the transaction. orderToReplace | [sequence](#account-sequence-number) | *Optional* The [account sequence number](#account-sequence-number) of an order to cancel before the new order is created, effectively replacing the old order. passive | boolean | *Optional* If enabled, the offer does not consume offers that exactly match it, and instead becomes an Offer node in the ledger. It still consumes offers that cross it. The following invalid flag combination causes a `ValidationError`: `immediateOrCancel` and `fillOrKill`. These fields are mutually exclusive, and cannot both be set at the same time. #### Example ```json { "direction": "buy", "quantity": { "currency": "USD", "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM", "value": "10.1" }, "totalPrice": { "currency": "drops", "value": "2000000" }, "passive": false, "fillOrKill": true } ``` ## Order Cancellation Cancel an order in the decentralized exchange. (Native transaction type: [OfferCancel](https://xrpl.org/offercancel.html)) Name | Type | Description ---- | ---- | ----------- orderSequence | [sequence](#account-sequence-number) | The [account sequence number](#account-sequence-number) of the order to cancel. memos | [memos](#transaction-memos) | *Optional* Array of memos to attach to the transaction. #### Example ```json { "orderSequence": 23 } ``` ## Payment Send value from one account to another. (Native transaction type: [Payment](https://xrpl.org/payment.html)) Name | Type | Description ---- | ---- | ----------- source | object | The source of the funds to be sent. *source.* address | [address](#address) | The address to send from. *source.* amount | [laxAmount](#amount) | An exact amount to send. If the counterparty is not specified, amounts with any counterparty may be used. (This field cannot be used with source.maxAmount) *source.* tag | integer | *Optional* An arbitrary 32-bit unsigned integer. It typically maps to an off-ledger account; for example, a hosted wallet or exchange account. *source.* maxAmount | [laxAmount](#amount) | The maximum amount to send. (This field cannot be used with source.amount) destination | object | The destination of the funds to be sent. *destination.* address | [address](#address) | An address representing the destination of the transaction. *destination.* amount | [laxAmount](#amount) | An exact amount to deliver to the recipient. If the counterparty is not specified, amounts with any counterparty may be used. (This field cannot be used with `destination.minAmount`.) *destination.* tag | integer | *Optional* An arbitrary 32-bit unsigned integer. It typically maps to an off-ledger account; for example, a hosted wallet or exchange account. *destination.* minAmount | [laxAmount](#amount) | The minimum amount to be delivered. (This field cannot be used with destination.amount) allowPartialPayment | boolean | *Optional* If true, this payment can deliver less than the full amount. invoiceID | string | *Optional* A 256-bit hash that can be used to identify a particular payment. limitQuality | boolean | *Optional* Only take paths where all the conversions have an input:output ratio that is equal or better than the ratio of destination.amount:source.maxAmount. memos | [memos](#transaction-memos) | *Optional* Array of memos to attach to the transaction. noDirectRipple | boolean | *Optional* If true and paths are specified, the sender would like the XRP Ledger to disregard any direct paths from the source account to the destination account. This may be used to take advantage of an arbitrage opportunity or by gateways wishing to issue balances from a hot wallet to a user who has mistakenly set a trustline directly to the hot wallet. paths | string | *Optional* The paths of trustlines and orders to use in executing the payment. #### Example ```json { "source": { "address": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59", "maxAmount": { "value": "0.01", "currency": "USD", "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM" } }, "destination": { "address": "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo", "amount": { "value": "0.01", "currency": "USD", "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM" } } } ``` ## Payment Channel Claim Redeem XRP from a Payment Channel. (Native transaction type: [PaymentChannelClaim](https://xrpl.org/paymentchannelclaim.html)) Name | Type | Description ---- | ---- | ----------- channel | string | 256-bit hexadecimal channel identifier. amount | [value](#value) | *Optional* Amount of XRP authorized by this signature. balance | [value](#value) | *Optional* Total XRP balance delivered by this channel after claim is processed. close | boolean | *Optional* Request to close the channel. If the channel has no XRP remaining or the destination address requests it, closes the channel immediately (returning unclaimed XRP to the source address). Otherwise, sets the channel to expire after settleDelay seconds have passed. memos | [memos](#transaction-memos) | *Optional* Array of memos to attach to the transaction. publicKey | string | *Optional* Public key of the channel. (For verifying the signature.) renew | boolean | *Optional* Clear the channel's expiration time. signature | string | *Optional* Signed claim authorizing withdrawal of XRP from the channel. (Required except from the channel's source address.) #### Example ```json { "channel": "C1AE6DDDEEC05CF2978C0BAD6FE302948E9533691DC749DCDD3B9E5992CA6198" } ``` ## Payment Channel Create Create a Payment Channel with XRP set aside for asynchronous payments. (Native transaction type: [PaymentChannelCreate](https://xrpl.org/paymentchannelcreate.html)) Name | Type | Description ---- | ---- | ----------- amount | [value](#value) | Amount of XRP for sender to set aside in this channel. destination | [address](#address) | Address to receive XRP claims against this channel. settleDelay | number | Amount of seconds the source address must wait before closing the channel if it has unclaimed XRP. publicKey | string | Public key of the key pair the source may use to sign claims against this channel. cancelAfter | date-time string | *Optional* Time when this channel expires. This expiration cannot be changed after creating the channel. destinationTag | integer | *Optional* Destination tag. memos | [memos](#transaction-memos) | *Optional* Array of memos to attach to the transaction. sourceTag | integer | *Optional* Source tag. #### Example ```json { "amount": "1", "destination": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW", "settleDelay": 86400, "publicKey": "32D2471DB72B27E3310F355BB33E339BF26F8392D5A93D3BC0FC3B566612DA0F0A" } ``` ## Payment Channel Fund Add XRP to a Payment Channel. (Native transaction type: [PaymentChannelFund](https://xrpl.org/paymentchannelfund.html)) Name | Type | Description ---- | ---- | ----------- amount | [value](#value) | Amount of XRP to fund the channel with. channel | string | 256-bit hexadecimal channel identifier. expiration | date-time string | *Optional* New expiration for this channel. (This does not change the cancelAfter expiration, if the channel has one.) Cannot move the expiration sooner than settleDelay seconds from time of the request. memos | [memos](#transaction-memos) | *Optional* Array of memos to attach to the transaction. #### Example ```json { "channel": "C1AE6DDDEEC05CF2978C0BAD6FE302948E9533691DC749DCDD3B9E5992CA6198", "amount": "1" } ``` ## Settings Change account settings. (Native transaction types: [AccountSet](https://xrpl.org/accountset.html), [SetRegularKey](https://xrpl.org/setregularkey.html), [SignerListSet](https://xrpl.org/signerlistset.html)) Name | Type | Description ---- | ---- | ----------- defaultRipple | boolean | *Optional* Enable [rippling](https://xrpl.org/rippling.html) on this account’s trust lines by default. Currency issuers should enable this setting; most others should not. depositAuth | boolean | *Optional* Enable [Deposit Authorization](https://xrpl.org/depositauth.html) on this account. If set, transactions cannot send value of any kind to this account unless the sender of those transactions is the account itself. (Requires the [DepositAuth amendment](https://xrpl.org/known-amendments.html#depositauth)) disableMasterKey | boolean | *Optional* Disallows use of the master key to sign transactions for this account. To disable the master key, you must authorize the transaction by signing it with the master key pair. You cannot use a regular key pair or a multi-signature. You can re-enable the master key pair using a regular key pair or multi-signature. See [AccountSet](https://xrpl.org/accountset.html). disallowIncomingXRP | boolean | *Optional* Indicates that client applications should not send XRP to this account. Not enforced by rippled. domain | string | *Optional* The domain that owns this account, as a hexadecimal string representing the ASCII for the domain in lowercase. emailHash | string,null | *Optional* Hash of an email address to be used for generating an avatar image. Conventionally, clients use Gravatar to display this image. Use `null` to clear. enableTransactionIDTracking | boolean | *Optional* Track the ID of this account’s most recent transaction. globalFreeze | boolean | *Optional* Freeze all assets issued by this account. memos | [memos](#transaction-memos) | *Optional* Array of memos to attach to the transaction. messageKey | string | *Optional* Public key for sending encrypted messages to this account. Conventionally, it should be a secp256k1 key, the same encryption that is used by the rest of Ripple. noFreeze | boolean | *Optional* Permanently give up the ability to freeze individual trust lines. This flag can never be disabled after being enabled. passwordSpent | boolean | *Optional* Indicates that the account has used its free SetRegularKey transaction. regularKey | [address](#address),null | *Optional* The public key of a new keypair, to use as the regular key to this account, as a base-58-encoded string in the same format as an account address. Use `null` to remove the regular key. requireAuthorization | boolean | *Optional* If set, this account must individually give other users permission to hold this account’s issued tokens. requireDestinationTag | boolean | *Optional* Requires incoming payments to specify a destination tag. signers | object | *Optional* Settings that determine what sets of accounts can be used to sign a transaction on behalf of this account using multisigning. *signers.* threshold | integer | A target number for the signer weights. A multi-signature from this list is valid only if the sum weights of the signatures provided is equal or greater than this value. To delete the signers setting, use the value `0`. *signers.* weights | array | *Optional* Weights of signatures for each signer. *signers.* weights[] | object | An association of an address and a weight. *signers.weights[].* address | [address](#address) | An account address on the XRP Ledger *signers.weights[].* weight | integer | The weight that the signature of this account counts as towards the threshold. tickSize | string | *Optional* Tick size to use for offers involving a currency issued by this address. The exchange rates of those offers is rounded to this many significant digits. Valid values are 3 to 15 inclusive, or 0 to disable. transferRate | number,null | *Optional* The fee to charge when users transfer this account’s issuances, as the decimal amount that must be sent to deliver 1 unit. Has precision up to 9 digits beyond the decimal point. Use `null` to set no fee. walletLocator | string,null | *Optional* Transaction hash or any other 64 character hexadecimal string, that may or may not represent the result of a hash operation. Use `null` to clear. #### Example ```json { "domain": "example.com", "memos": [ { "type": "test", "format": "text/plain", "data": "texted data" } ] } ``` ## Ticket Create Set aside account Sequence numbers as Tickets to be used by later transactions. > **Caution:** As of 2021-01-22, Tickets are not yet available on the XRP Ledger. > **Note:** To prepare a Ticket Create transaction, use [`prepareTransaction()`](#preparetransaction) with the native transaction format. ## Trustline Create or modify a trust line between two accounts, for an issued currency. (Native transaction type: [TrustSet](https://xrpl.org/trustset.html)) Name | Type | Description ---- | ---- | ----------- currency | [currency](#currency) | The currency this trustline applies to. counterparty | [address](#address) | The address of the account this trustline extends trust to. limit | [value](#value) | The maximum amount that the owner of the trustline can be owed through the trustline. authorized | boolean | *Optional* If true, authorize the counterparty to hold issuances from this account. frozen | boolean | *Optional* If true, the trustline is frozen, which means that funds can only be sent to the owner. memos | [memos](#transaction-memos) | *Optional* Array of memos to attach to the transaction. qualityIn | number | *Optional* Incoming balances on this trustline are valued at this ratio. qualityOut | number | *Optional* Outgoing balances on this trustline are valued at this ratio. ripplingDisabled | boolean | *Optional* If true, payments cannot ripple through this trustline. #### Example ```json { "currency": "USD", "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM", "limit": "10000", "qualityIn": 0.91, "qualityOut": 0.87, "ripplingDisabled": true, "frozen": false, "memos": [ { "type": "test", "format": "text/plain", "data": "texted data" } ] } ``` # rippled APIs ripple-lib uses the XRP Ledger's [WebSocket API](https://xrpl.org/rippled-api.html) for online functionality. You can use ripple-lib to call these APIs directly. Use the `request()`, `hasNextPage()`, and `requestNextPage()` methods: * Use `request()` to issue any `rippled` command, including `account_currencies`, `subscribe`, and `unsubscribe`. [Full list of API Methods](https://xrpl.org/public-rippled-methods.html). * Use `hasNextPage()` to determine whether a response has more pages. This is true when the response includes a [`marker` field](https://xrpl.org/markers-and-pagination.html). * Use `requestNextPage()` to request the next page of data. When using rippled APIs: * [Specify XRP amounts in drops](https://xrpl.org/basic-data-types.html#specifying-currency-amounts). * [Specify timestamps as the number of seconds since the "Ripple Epoch"](https://xrpl.org/basic-data-types.html#specifying-time). * Instead of `counterparty`, use `issuer`. ## Listening to streams The `rippled` server can push updates to your client when various events happen. Refer to [Subscriptions in the `rippled` API docs](https://xrpl.org/subscribe.html) for details. Note that the `streams` parameter for generic streams takes an array. For example, to subscribe to the `validations` stream, use `{ streams: [ 'validations' ] }`. The string names of some generic streams to subscribe to are in the table below. (Refer to `rippled` for an up-to-date list of streams.) Type | Description ---- | ----------- `server` | Sends a message whenever the status of the `rippled` server (for example, network connectivity) changes. `ledger` | Sends a message whenever the consensus process declares a new validated ledger. `transactions` | Sends a message whenever a transaction is included in a closed ledger. `transactions_proposed` | Sends a message whenever a transaction is included in a closed ledger, as well as some transactions that have not yet been included in a validated ledger and may never be. Not all proposed transactions appear before validation. Even some transactions that don't succeed are included in validated ledgers because they take the anti-spam transaction fee. `validations` | Sends a message whenever the server receives a validation message, also called a validation vote, regardless of whether the server trusts the validator. `manifests` | Sends a message whenever the server receives a manifest. `peer_status` | (Admin-only) Information about connected peer `rippled` servers, especially with regards to the consensus process. When you subscribe to a stream, you must also listen to the relevant message type(s). Some of the available message types are in the table below. (Refer to `rippled` for an up-to-date list of message types.) Type | Description ---- | ----------- `ledgerClosed` | Sent by the `ledger` stream when the consensus process declares a new fully validated ledger. The message identifies the ledger and provides some information about its contents. `validationReceived` | Sent by the `validations` stream when the server receives a validation message, also called a validation vote, regardless of whether the server trusts the validator. `manifestReceived` | Sent by the `manifests` stream when the server receives a manifest. `transaction` | Sent by many subscriptions including `transactions`, `transactions_proposed`, `accounts`, `accounts_proposed`, and `book` (Order Book). See [Transaction Streams](https://xrpl.org/subscribe.html#transaction-streams) for details. `peerStatusChange` | (Admin-only) Reports a large amount of information on the activities of other `rippled` servers to which the server is connected. `path_find` | Asynchronous follow-up response to the currently open path\_find request. See [rippled path\_find method](https://xrpl.org/path_find.html) for details. To register your listener function, use `connection.on(type, handler)`. Here is an example of listening for transactions on given account(s): ``` const account = 'rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn' // Replace with the account you want notifications for api.connect().then(() => { // 'transaction' can be replaced with the relevant `type` from the table above api.connection.on('transaction', (event) => { // Do something useful with `event` console.log(JSON.stringify(event, null, 2)) }) api.request('subscribe', { accounts: [ account ] }).then(response => { console.log('Successfully subscribed') }).catch(error => { // Handle `error` }) }) ``` The subscription ends when you unsubscribe or the WebSocket connection is closed. For full details, see the [subscribe method](https://xrpl.org/subscribe.html). ## request `request(command: string, options: object): Promise