rippled

The core peer-to-peer server that operates the Ripple Network is called rippled. Each rippled server connects to the Ripple Network, relays cryptographically signed transactions, and maintains a local copy of the complete shared global ledger. The source code for rippled is written in C++, and is available on GitHub under an open-source license.

• rippled Setup
• API Reference
• Transaction Reference
• Client Library - Javascript

WebSocket and JSON-RPC APIs

If you want to communicate directly with the rippled server, you can use either the WebSocket API or the JSON-RPC API. Both APIs use the same list of commands, with almost entirely the same parameters in each command. Whereas the Ripple-REST API provides a simplified interface on top of the WebSocket API for easier integration, these APIs provide the full power of Ripple but require slightly more complexity:

• The WebSocket API uses the WebSocket protocol, available in most browsers and Javascript implementations, to achieve persistent two-way communication. There is not a 1:1 correlation between requests and responses. Some requests prompt the server to send multiple messages back asynchronously; other times, responses may arrive in a different order than the requests that prompted them. The rippled server can be configured to accept secured (wss:), unsecured (ws:) WebSocket connections, or both.
• The JSON-RPC API relies on simple request-response communication via HTTP or HTTPS. (The rippled server can be configured to accept HTTP, HTTPS, or both.) For commands that prompt multiple responses, you can provide a callback URL.
• The rippled program can also be used as a quick commandline client to make JSON-RPC requests to a running rippled server. This is only intended for administrative purposes, and is not a supported API.

In general, we recommend using WebSocket, because WebSocket's push paradigm has less latency and less network overhead. JSON-RPC must open and close an HTTP connection for each individual message. WebSocket is also more reliable; you can worry less about missing messages and establishing multiple connections. However, all three have valid use cases and will continue to be supported for the foreseeable future.

Changes to the APIs

The WebSocket and JSON-RPC APIs are still in development, and are subject to change. If you want to be notified of upcoming changes and future versions of rippled, subscribe to the Ripple Server mailing list:

https://groups.google.com/forum/#!forum/ripple-server

Connecting to rippled

Before you can run any commands against a rippled server, you must know which server you are connecting to. Most servers are configured not to accept requests directly from the outside network.

Alternatively, you can run your own local copy of rippled. This is required if you want to access any of the Admin Commands. In this case, you should use whatever IP and port you configured the server to bind. (For example, 127.0.0.1:54321) Additionally, in order to access admin functionality, you must connect from a port/IP address marked as admin in the config file.

The example config file listens for connections on the local loopback network (127.0.0.1), with JSON-RPC (HTTP) on port 5005 and WebSocket (WS) on port 6006, and treats all connected clients as admin.

WebSocket API

If you are just looking to try out some methods on the Ripple network, you can skip writing your own WebSocket code and go straight to using the API at the Ripple WebSocket API Tool. Later on, when you want to connect to your own rippled server, you can build your own client in Javascript to run in a browser (See this example ) or possibly Node.js.

Currently Ripple Labs maintains a set of public WebSocket servers at:

Domain	Port
s1.ripple.com	443

These public servers are not for sustained or business use, and they may become unavailable at any time. For regular use, you should run your own rippled server or contract someone you trust to do so.

JSON-RPC

You can use any HTTP client (like Poster for Firefox or Postman for Chrome) to make JSON-RPC calls a rippled server.

Currently, Ripple Labs maintains a set of public JSON-RPC servers at:

Domain	Port
s1.ripple.com	51234

These public servers are not for sustained or business use, and they may become unavailable at any time. For regular use, you should run your own rippled server or contract someone you trust to do so.

Commandline

The commandline interface connects to the same service as the JSON-RPC one, so the public servers and server configuration are the same. As a commandline client, rippled connects to the local instance. For example:

rippled --conf=/etc/rippled.cfg server_info

Request Formatting

Both the WebSocket API and the JSON-RPC API use JSON for requests and responses. The methods and parameters available on both APIs are generally the same, but the exact formatting is slightly different between the two. The commandline interface supports the same commands, with the parameters in the commandline as well.

• A WebSocket request puts the command name in the "command" field alongside the command's parameters at the top level of the JSON object, with an optional "id" field that will be returned with the response, so you can identify responses that come back out of order.
• A JSON-RPC request puts the command in the "method" field, with parameters in a separate object, as the first member of a "params" array. There is no "id" field, since all responses are direct replies to the requests.
• The commandline puts the command after any normal (dash-prefaced) commandline options, followed by a limited set of parameters, separated by spaces.

Example Request

Response Formatting

Example Successful Response

The fields of a successful response include:

Field	Type	Description
id	(Varies)	(WebSocket only) ID provided in the request that prompted this response
status (WebSocket) <br> result.status (JSON-RPC and Commandline)	String	"success" if the request successfully completed. In the WebSocket API responses, this is included at the top level; in JSON-RPC and Commandline responses, this is included as a sub-field of the "result" object.
type	String	(WebSocket only) Typically "response", which indicates a successful response to a command. Asynchronous notifications use a different value such as "ledgerClosed" or "transaction".
result	Object	The result of the query; contents vary depending on the command.

Commandline

The response format for commandline methods is identical to JSON-RPC responses, because they use the same interface.

Error Responses

It is impossible to enumerate all the possible ways an error can occur. Some may occur in the transport layer (for example, loss of network connectivity), in which case the results will vary depending on what client and transport you are using. However, if the rippled server successfully receives your request, it will try to respond in a standardized error format.

Some example errors:

WebSocket API Error Response Format

Field	Type	Description
id	(Varies)	ID provided in the Web Socket request that prompted this response
status	String	"error" if the request caused an error
type	String	Typically "response", which indicates a successful response to a command.
error	String	A unique code for the type of error that occurred
request	Object	A copy of the request that prompted this error, in JSON format. Caution: If the request contained any account secrets, they are copied here!

JSON-RPC API Error Response Format

Some JSON-RPC requests will respond with an error code on the HTTP layer. In these cases, the response is a plain-text explanation in the response body. For example, if you forgot to specify the command in the method parameter, the response is like this:

HTTP Status: 400 Bad Request
Null method

For other errors that returned with HTTP status code 200 OK, the responses are formatted in JSON, with the following fields:

Field	Type	Description
result	Object	Object containing the response to the query
result.error	String	A unique code for the type of error that occurred
result.status	String	"error" if the request caused an error
result.request	Object	A copy of the request that prompted this error, in JSON format. Caution: If the request contained any account secrets, they are copied here! Note: The request is re-formatted in WebSocket format, regardless of the request made. This may be changed in the future: See RIPD-279.

Caution on Errors

When your request results in an error, the entire request is copied back as part of the response, so that you can try to debug the error. However, this also includes any secrets that were passed as part of the request. When sharing error messages, be very careful not to accidentally expose important account secrets to others.

Universal Errors

All methods can potentially return any of the following values for the error code:

• unknownCmd - The request does not contain a command that the rippled server recognizes.
• `jsonInvalid1 - (WebSocket only) The request is not a proper JSON object.
  • JSON-RPC returns a 400 Bad Request HTTP error in this case instead.
• missingCommand - (WebSocket only) The request did not specify a command field.
  • JSON-RPC returns a 400 Bad Request HTTP error in this case instead.
• tooBusy - The server is under too much load to perform this command right now. Generally not returned if you are connected as an admin.
• noNetwork - The server is having trouble connecting to the rest of the Ripple Network (and is not running in stand-alone mode).
• noCurrent - The server does not know what the current ledger is, due to high load, network problems, validator failures, incorrect configuration, or some other problem.
• noClosed - The server does not have a closed ledger, typically because it has not finished starting up.
• wsTextRequired - (WebSocket only) The request's opcode is not text.

Formatting Conventions

The WebSocket and JSON-RPC APIs generally take the same arguments, although they're provided in a different way (See Request Formatting for details). Many similar parameters appear throughout the APIs, and there are conventions for how to specify these parameters.

All field names are case-sensitive. In responses, fields that are taken directly from Ledger Node or Transaction objects start with upper-case letters. Other fields, including ones that are dynamically generated for a response, are lower case.

Unique Identifiers

Different types of objects are uniquely identified in different ways:

Accounts are identified by their address, a base-58-encoded string, for example "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59". Addresses always start with "r". You can also provide an un-encoded hex representation instead.

Transactions are identified by their hash, which is a SHA-512 hash of the transaction's binary format. Transaction hashes are represented as hex strings.

Each instance of the Ripple Ledger has a sequence number and a hash value. See Specifying a Ledger Instance for details.

Specifying a Ledger Instance

Many API methods require you to specify an instance of the ledger, with the data retrieved being considered accurate and up-to-date as of that particular version of the shared ledger. The commands that accept a ledger version all work the same way. There are three ways you can specify which ledger you want to use:

1. Specify a ledger by its Sequence Number in the ledger_index parameter. Each closed ledger has an identifying sequence number that is 1 higher than the previously-validated ledger. (The Genesis Ledger has sequence number 0)
2. Specify a ledger by its hash value in the ledger_hash parameter.
3. Specify a ledger by one of the following shortcuts, in the ledger_index parameter:
   • validated for the most recent ledger that has been validated by the whole network
   • closed for the most recent ledger that has been closed for modifications and proposed for validation by the node
   • current for the node's current working version of the ledger.

There is also a deprecated ledger parameter which accepts any of the above three formats. Do not use this parameter; it may be removed without further notice.

If you do not specify a ledger, the current (in-progress) ledger will be chosen by default. If you provide more than one field specifying ledgers, the deprecated ledger field will be used first if it exists, falling back to ledger_hash. The ledger_index field is ignored unless neither of the other two are present. Note: Do not rely on this default behavior; it is subject to change. Instead, you should always specify a ledger version in each call.

The sequence number indicates the order of the ledgers; the hash value identifies the exact contents of the ledger. Two ledgers with the same hash are always identical. For closed ledgers, hash values and sequence numbers are equally valid and correlate 1:1. However, this is not true for in-progress ledgers:

• Two different rippled servers may have different contents for a current ledger with the same sequence number, due to transactions not being fully propagated throughout the network.
• A current ledger's contents change over time, which would cause its hash to change, even though its sequence number stays the same. Therefore, the hash of a ledger is not calculated until it is closed.

Specifying Currency Amounts

Some API methods require you to specify an amount of currency. Depending on whether you are dealing in the network's native XRP currency or other currency units (sometimes referred to as IOUs), the style for specifying it is very different.

XRP

Amounts of XRP are represented as strings. (JSON integers are limited to 32 bits, so integer overflows are possible.) XRP is formally specified in "drops", which are equivalent to 0.000001 (one 1-millionth) of an XRP each. Thus, to represent 1.0 XRP in a JSON document, you would write:

"1000000"

Do not specify XRP as an object.

Unit tests are permitted to submit values of XRP (not drops) with a decimal point - for example, "1.23" meaning 1.23 XRP. All other cases should always specify XRP in drops, with no decimal point: e.g. "1230000" meaning 1.23 XRP.

Non-XRP

If you are specifying non-XRP currency (including fiat dollars, precious metals, cryptocurrencies, or other custom currency) you must specify it with a currency specification object. This is a JSON object with three fields:

Field	Type	Description
currency	String	3-character currency code. We recommend using uppercase ISO 4217 Currency Codes only. The string "XRP" is disallowed. The following characters are permitted: all uppercase and lowercase letters, digits, as well as the symbols ?, !, @, #, $, %, ^, &, *, <, >, (, ), {, }, [, ], and |. Instead of a 3-character code, this field could also be a 40-character hex value according to the internal Currency format.
value	String	Quoted decimal representation of the amount of currency
issuer	String	Unique account address of the entity issuing the currency. In other words, the person or business where the currency can be redeemed.

For example, to represent $153.75 US dollars issued by account r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59, you would specify:

{
    "currency": "USD",
    "value": "153.75",
    "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59"
}

Unit tests are permitted to submit amounts of non-XRP currencies as a slash-separated string in the format "amount/currency/issuer". All other cases should use the JSON object format above.

Specifying Currencies Without Amounts

If you are specifying a non-XRP currency without an amount (typically for defining an order book of currency exchange offers) you should specify it as above, but omit the value field.

If you are specifying XRP without an amount (typically for defining an order book) you should specify it as a JSON object with only a currency field. Never include an issuer field for XRP.

Finally, if you are specifying a non-currency for a payment or path definition, and the recipient account of the payment trusts multiple gateways that issue the same currency, you can indicate that the payment should be made in any combination of issuers that the recipient accepts. To do this, specify the recipient account's address as the issuer value in the JSON object.

Specifying Time

The rippled server and its APIs represent time as an unsigned integer. This number measures the number of seconds since the "Ripple Epoch" of January 1, 2000 (00:00 UTC). This is similar to the way the Unix epoch works, except the Ripple Epoch is 946684800 seconds after the Unix Epoch.

Don't convert Ripple Epoch times to UNIX Epoch times in 32-bit variables: this could lead to integer overflows.

Possible Server States

Depending on how the rippled server is configured, how long it has been running, and other factors, a server may be participating in the global Ripple Network to different degrees. This is represented as the server_state field in the responses to the server_info and server_state commands. The possible responses follow a range of ascending interaction, with each subsequent value superseding the previous one. Their definitions are as follows (in order of increasing priority):

Value	Description
disconnected	The server is not connected to the Ripple Network whatsoever. It may be running in offline mode, or it may not be able to access the network for whatever reason.
connected	The server believes it is connected to the network.
syncing	The server is currently behind on ledger versions. (It is normal for a server to spend a few minutes catching up after you start it.)
tracking	The server is in agreement with the network
full	The server is fully caught-up with the network and could participate in validation, but is not doing so (possibly because it has not been configured as a validator).
validating	The server is currently participating in validation of the ledger
proposing	The server is participating in validation of the ledger and currently proposing its own version.

Note: The distinction between full, validating, and proposing is based on synchronization with the rest of the global network, and it is normal for a server to fluctuate between these states as a course of general operation.

Markers and Pagination

Some methods return more data than can efficiently fit into one response. When there are more results than contained, the response includes a marker field. You can use this to retrieve more pages of data across multiple calls. In each subsequent request, pass the marker value from the previous response in order to resume from the point where you left off. If the marker is omitted from a response, then you have reached the end of the data set.

The format of the marker field is intentionally undefined. Each server can define a marker field as desired, so it may take the form of a string, a nested object, or another type. Different servers, and different methods provided by the same server, can have different marker definitions. Each marker is ephemeral, and may not work as expected after 10 minutes.

Modifying the Ledger

All changes to Ripple's global shared ledger happen as the result of transactions. Consequently, this means that there is only one public API method that causes a change in the state of the Ripple Network at all: the submit command. Most of the other methods represent different ways to view the data represented in the Ripple Network, and the remaining ones just generate data for your convenience. (The wallet_propose, path_find, and random commands fall into this category.)

For more information on the various transactions you can submit, consult the Transaction Format.

API Methods

API methods for the Websocket and JSON-RPC APIs are defined by command names, and are divided into Public Commands and Admin Commands. Public Commands are not necessarily meant for the general public, but they are used by any client attached to the server. (Think of Public Commands as being for members or customers of the organization running the server, while the Admin Commands are for the personnel in charge of keeping the server operational.) Public Commands include the general operations for Ripple use, including checking the state of the ledger, finding a path to connecting users, and submitting a transaction, among others. Admin Commands, on the other hand, are meant only for the operators of the server, and include commands for managing the state of the server, the nodes it uses for validation, and other administrative features.

List of Public Commands

• account_currencies - Get a list of currencies an account can send or receive
• account_info - Get basic data about an account
• account_lines - Get info about an account's trust lines
• account_objects - Get all ledger objects owned by an account
• account_offers - Get info about an account's currency exchange offers
• account_tx - Get info about an account's transactions
• book_offers - Get info about offers to exchange two currencies
• gateway_balances - Calculate total amounts issued by an account
• ledger - Get info about a ledger version
• ledger_closed - Get the latest closed ledger version
• ledger_current - Get the current working ledger version
• ledger_data - Get the raw contents of a ledger version
• ledger_entry - Get one element from a ledger version
• noripple_check - Get recommended changes to an account's DefaultRipple and NoRipple settings
• path_find - Find a path for a payment between two accounts and receive updates
• ping - Confirm connectivity with the server
• random - Generate a random number
• ripple_path_find - Find a path for payment between two accounts, once
• server_info - Retrieve status of the server in human-readable format
• server_state - Retrieve status of the server in machine-readable format
• sign - Cryptographically sign a transaction
• submit - Send a transaction to the network
• subscribe - Listen for updates about a particular subject
• transaction_entry - Retrieve info about a transaction from a particular ledger version
• tx - Retrieve info about a transaction from all the ledgers on hand
• tx_history - Retrieve info about all recent transactions
• unsubscribe - Stop listening for updates about a particular subject

The owner_info command is deprecated. Use account_objects instead.

List of Admin Commands

• can_delete - Allow online deletion of ledgers up to a specific ledger
• connect - Force the rippled server to connect to a specific peer
• consensus_info - Get information about the state of consensus as it happens
• fetch_info - Get information about the server's sync with the network
• get_counts - Get statistics about the server's internals and memory usage
• ledger_accept - Close and advance the ledger in stand-alone mode
• ledger_cleaner - Configure the ledger cleaner service to check for corrupted data
• ledger_request - Query a peer server for a specific ledger version
• log_level - Get or modify log verbosity
• logrotate - Reopen the log file
• peers - Get information about the peer servers connected
• print - Get information about internal subsystems
• stop - Shut down the rippled server
• validation_create - Generate keys for a new rippled validator
• validation_seed - Temporarily set key to be used for validating
• wallet_propose - Generate keys for a new account

The following admin commands are deprecated and may be removed without further notice:

• ledger_header - Use the ledger command instead.
• unl_add, unl_delete, unl_list, unl_load, unl_network, unl_reset, unl_score - Use the configuration file for UNL management instead.
• wallet_seed - Use wallet_propose instead.

Commandline Access

The rippled application, in addition to acting as a server, can be run (as a separate instance) to act as a JSON-RPC client. In this mode, it has syntax for triggering most API methods with a single line from the command prompt, as described in each method. However, some methods don't have a commandline shortcut, so it also provides the following catch-all method for performing commands:

• json - Pass JSON through the commandline

Account Information

Accounts are the core unit of authentication in the Ripple Network. Each account can hold balances in multiple currencies, and all transactions must be signed by an account's secret key. In order for an account to exist in a validated ledger version, it must hold a minimum reserve amount of XRP. (The reserve for an account increases with the amount of data it is responsible for in the shared ledger.) It is expected that accounts will correspond loosely to individual users.

account_currencies

[Source]

The account_currencies command retrieves a simple list of currencies that an account can send or receive, based on its trust lines. (This is not a thoroughly confirmed list, but it can be used to populate user interfaces.)

Request Format

An example of the request format:

Try it! >

The request includes the following parameters:

Field	Type	Description
account	String	A unique identifier for the account, most commonly the account's address.
strict	Boolean	(Optional) If true, only accept an address or public key for the account parameter. Defaults to false.
ledger_hash	String	(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger)
ledger_index	String or Unsigned Integer	(Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)

The following field is deprecated and should not be provided: account_index.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
ledger_hash	String	(May be omitted) The identifying hash of the ledger version used to retrieve this data, as hex.
ledger_index	Integer	The sequence number of the ledger version used to retrieve this data.
receive_currencies	Array of Strings	Array of currency codes for currencies that this account can receive. Each currency is either a 3-letter ISO 4217 Currency Code or a 160-bit hex value according to the currency format.
send_currencies	Array of Strings	Array of currency codes for currencies that this account can send. Each currency is either a 3-letter ISO 4217 Currency Code or a 160-bit hex value according to the currency format.
validated	Boolean	If true, this data comes from a validated ledger.

Note: The currencies that an account can send or receive are defined based on a simple check of its trust lines. If an account has a trust line for a currency and enough room to increase its balance, it can receive that currency. If the trust line's balance can go down, the account can send that currency. This method does not check whether the trust line is frozen or authorized.

Possible Errors

• Any of the universal error types.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
• actNotFound - The address specified in the account field of the request does not correspond to an account in the ledger.
• lgrNotFound - The ledger specified by the ledger_hash or ledger_index does not exist, or it does exist but the server does not have it.

account_info

[Source]

The account_info command retrieves information about an account, its activity, and its XRP balance. All information retrieved is relative to a particular version of the ledger.

Request Format

An example of an account_info request:

Try it! >

The request contains the following parameters:

Field	Type	Description
account	String	A unique identifier for the account, most commonly the account's address.
strict	Boolean	(Optional, defaults to False) If set to True, then the account field will only accept a public key or account address.
ledger_hash	String	(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger)
ledger_index	String or Unsigned Integer	(Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)

The following fields are deprecated and should not be provided: ident, account_index, ledger.

Response Format

An example of a successful response:

The response follows the standard format, with the result containing the requested account, its data, and a ledger to which it applies, as the following fields:

Field	Type	Description
account_data	Object	Information about the requested account
account_data.Account	String	Address of the requested account
account_data.Balance	String	XRP balance in "drops" represented as a string
account_data.Flags	32-bit unsigned integer	Integer with different bits representing the status of several account flags
account_data.LedgerEntryType	String	"AccountRoot" is the type of ledger entry that holds an account's data
account_data.OwnerCount	Integer	Number of other ledger entries (specifically, trust lines and offers) attributed to this account. This is used to calculate the total reserve required to use the account.
account_data.PreviousTxnID	String	Hash value representing the most recent transaction that affected this account node directly. Note: This does not include all changes to the account's trust lines and offers. Use account_tx to get a more inclusive list.
account_data.Sequence	Integer	The sequence number of the next valid transaction for this account. (Each account starts with Sequence = 1 and increases each time a transaction is made.)
account_data.index	String	A unique index for the AccountRoot node that represents this account in the ledger.
ledger_current_index	Integer	(Omitted if ledger_index is provided instead) The sequence number of the most-current ledger, which was used when retrieving this information. The information does not contain any changes from ledgers newer than this one.
ledger_index	Integer	(Omitted if ledger_current_index is provided instead) The sequence number of the ledger used when retrieving this information. The information does not contain any changes from ledgers newer than this one.
validated	Boolean	True if this data is from a validated ledger version; if omitted or set to false, this data is not final. (New in version 0.26)

Possible Errors

• Any of the universal error types.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
• actNotFound - The address specified in the account field of the request does not correspond to an account in the ledger.
• lgrNotFound - The ledger specified by the ledger_hash or ledger_index does not exist, or it does exist but the server does not have it.

account_lines

[Source]

The account_lines method returns information about the account's lines of trust, including balances in all non-XRP currencies and assets. All information retrieved is relative to a particular version of the ledger.

Request Format

An example of the request format:

Try it! >

The request accepts the following paramters:

Field	Type	Description
account	String	A unique identifier for the account, most commonly the account's address as a base-58 string.
ledger_hash	String	(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger)
ledger_index	String or Unsigned Integer	(Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)
peer	String	(Optional) A unique ID for a second account. If provided, show only lines of trust connecting the two accounts.
limit	Integer	(Optional, default varies) Limit the number of transactions to retrieve. The server is not required to honor this value. Cannot be smaller than 10 or larger than 400. (New in 0.26.4)
marker	(Not Specified)	(Optional) Server-provided value to specify where to resume retrieving data from. (New in 0.26.4)

The following parameters are deprecated and may be removed without further notice: ledger and peer_index.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the address of the account and an array of trust-line objects. Specifically, the result object contains the following fields:

Field	Type	Description
account	String	Unique address of the account this request corresponds to
lines	Array	Array of trust-line objects, as described below. If the number of trust-lines is large, only returns up to the limit at a time.
ledger_current_index	Integer	(Omitted if ledger_hash or ledger_index provided) Sequence number of the ledger version used when retrieving this data. (New in 0.26.4-sp1)
ledger_index	Integer	(Omitted if ledger_current_index provided instead) Sequence number, provided in the request, of the ledger version that was used when retrieving this data. (New in 0.26.4-sp1)
ledger_hash	String	(May be omitted) Hex hash, provided in the request, of the ledger version that was used when retrieving this data. (New in 0.26.4-sp1)
marker	(Not Specified)	Server-defined value. Pass this to the next call in order to resume where this call left off. Omitted when there are no additional pages after this one. (New in 0.26.4)

Each trust-line object has some combination of the following fields, although not necessarily all of them:

Field	Type	Description
account	String	The unique address of the account this line applies to.
balance	String	Representation of the numeric balance currently held against this line. A positive balance means that the account holds value; a negative balance means that the account owes value.
currency	String	The currency this line applies to
limit	String	The maximum amount of the given currency that the account is willing to owe the peer account
limit_peer	String	The maximum amount of currency that the peer account is willing to owe the account
no_ripple	Boolean	Whether or not the account has the NoRipple flag set for this line
no_ripple_peer	Boolean	Whether or not the peer account has the NoRipple flag set for the other direction of this trust line
quality_in	Unsigned Integer	Rate at which the account values incoming balances on this trust line, as a ratio of this value per 1 billion units. (For example, a value of 500 million represents a 0.5:1 ratio.) As a special case, 0 is treated as a 1:1 ratio.
quality_out	Unsigned Integer	Rate at which the account values outgoing balances on this trust line, as a ratio of this value per 1 billion units. (For example, a value of 500 million represents a 0.5:1 ratio.) As a special case, 0 is treated as a 1:1 ratio.

Possible Errors

• Any of the universal error types.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
• actNotFound - The address specified in the account field of the request does not correspond to an account in the ledger.
• lgrNotFound - The ledger specified by the ledger_hash or ledger_index does not exist, or it does exist but the server does not have it.
• actMalformed - If the marker field provided is not acceptable. (See RIPD-684)

account_offers

[Source]

The account_offers method retrieves a list of offers made by a given account that are outstanding as of a particular ledger version.

Request Format

An example of the request format:

Try it! >

A request can include the following parameters:

Field	Type	Description
account	String	A unique identifier for the account, most commonly the account's address as a base-58 string.
ledger	Unsigned integer, or String	(Deprecated, Optional) A unique identifier for the ledger version to use, such as a ledger sequence number, a hash, or a shortcut such as "validated".
ledger_hash	String	(Optional) A 20-byte hex string identifying the ledger version to use.
ledger_index	(Optional) Unsigned integer, or String	(Optional, defaults to current) The sequence number of the ledger to use, or "current", "closed", or "validated" to select a ledger dynamically. (See Ledger Indexes.)
limit	Integer	(Optional, default varies) Limit the number of transactions to retrieve. The server is not required to honor this value. Cannot be lower than 10 or higher than 400. (New in 0.26.4)
marker	(Not Specified)	Server-provided value to specify where to resume retrieving data from. (New in 0.26.4)

The following parameter is deprecated and may be removed without further notice: ledger.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
account	String	Unique address identifying the account that made the offers
offers	Array	Array of objects, where each object represents an offer made by this account that is outstanding as of the requested ledger version. If the number of offers is large, only returns up to limit at a time.
ledger_current_index	Integer	(Omitted if ledger_hash or ledger_index provided) Sequence number of the ledger version used when retrieving this data. (New in 0.26.4-sp1)
ledger_index	Integer	(Omitted if ledger_current_index provided instead) Sequence number, provided in the request, of the ledger version that was used when retrieving this data. (New in 0.26.4-sp1)
ledger_hash	String	(May be omitted) Hex hash, provided in the request, of the ledger version that was used when retrieving this data. (New in 0.26.4-sp1)
marker	(Not Specified)	Server-defined value. Pass this to the next call in order to resume where this call left off. Omitted when there are no pages of information after this one. (New in 0.26.4)

Each offer object contains the following fields:

Field	Type	Description
flags	Unsigned integer	Options set for this offer entry as bit-flags.
seq	Unsigned integer	Sequence number of the transaction that created this entry. (Transaction sequence numbers are relative to accounts.)
taker_gets	String or Object	The amount the account accepting the offer receives, as a String representing an amount in XRP, or a currency specification object. (See Specifying Currency Amounts)
taker_pays	String or Object	The amount the account accepting the offer provides, as a String representing an amount in XRP, or a currency specification object. (See Specifying Currency Amounts)

Possible Errors

• Any of the universal error types.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
• actNotFound - The address specified in the account field of the request does not correspond to an account in the ledger.
• lgrNotFound - The ledger specified by the ledger_hash or ledger_index does not exist, or it does exist but the server does not have it.
• actMalformed - If the marker field provided is not acceptable. (See RIPD-684)

account_objects

[Source]

The account_objects command returns the raw ledger format for all objects owned by an account, such as outstanding offers, trust lines in non-default state, and tickets (which are part of forthcoming multi-sign code). For getting the balance of an account's trust lines, we recommend account_lines instead.

Request Format

An example of the request format:

The request includes the following parameters:

Field	Type	Description
account	String	A unique identifier for the account, most commonly the account's address.
type	String	(Optional) If included, filter results to include only this type of ledger node. Valid types include state (trust lines), offer (offers), and ticket (part of the forthcoming signing process).
ledger_hash	String	(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger)
ledger_index	String or Unsigned Integer	(Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)
limit	Unsigned Integer	(Optional) The maximum number of objects to include in the results. Cannot be less than 10 or higher than 400 on non-admin connections. Defaults to 200.
marker	(Not Specified)	(Optional) Server-provided value to specify where to resume retrieving data from.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
account	String	Unique address of the account this request corresponds to
account_objects	Array	Array of objects owned by this account. Each object is in its raw ledger format.
ledger_hash	String	(May be omitted) The identifying hash of the ledger that was used to generate this response.
ledger_index	Number	(May be omitted) The sequence number of the ledger version that was used to generate this response.
ledger_current_index	Number	(May be omitted) The sequence number of the current in-progress ledger version that was used to generate this response.
limit	Number	(May be omitted) The limit that was used in this request, if any.
marker	(Not Specified)	Server-defined value. Pass this to the next call in order to resume where this call left off. Omitted when there are no additional pages after this one.
validated	Boolean	If true, this information comes from ledger version that has been validated by consensus.

Possible Errors

• Any of the universal error types.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
• actNotFound - The address specified in the account field of the request does not correspond to an account in the ledger.
• lgrNotFound - The ledger specified by the ledger_hash or ledger_index does not exist, or it does exist but the server does not have it.

account_tx

[Source]

The account_tx method retrieves a list of transactions that involved the specified account.

Request Format

An example of the request format:

Try it! >

The request includes the following parameters:

Field	Type	Description
account	String	A unique identifier for the account, most commonly the account's address.
ledger_index_min	Integer	Use to specify the earliest ledger to include transactions from. A value of -1 instructs the server to use the earliest validated ledger version available.
ledger_index_max	Integer	Use to specify the most recent ledger to include transactions from. A value of -1 instructs the server to use the most recent validated ledger version available.
ledger_hash	String	(Optional) Use instead of ledger_index_min and ledger_index_max to look for transactions from a single ledger only. (See Specifying a Ledger)
ledger_index	String or Unsigned Integer	(Optional) Use instead of ledger_index_min and ledger_index_max to look for transactions from a single ledger only. (See Specifying a Ledger)
binary	Boolean	(Optional, defaults to False) If set to True, return transactions as hex strings instead of JSON.
forward	boolean	(Optional, defaults to False) If set to True, return values indexed with the oldest ledger first. Otherwise, the results are indexed with the newest ledger first. (Each page of results may not be internally ordered, but the pages are overall ordered.)
limit	Integer	(Optional, default varies) Limit the number of transactions to retrieve. The server is not required to honor this value.
marker	(Not Specified)	Server-provided value to specify where to resume retrieving data from. This value is stable even if there is a change in the server's range of available ledgers.

[Source]
There is also a deprecated legacy variation of the account_tx method. For that reason, we recommend not using any of the following fields: offset, count, descending, ledger_max, ledger_min.

Iterating over queried data

As with other paginated methods, you can use the marker field to return multiple pages of data.

In the time between requests, "ledger_index_min": -1 and "ledger_index_max": -1 may change to refer to different ledger versions than they did before. The marker field can safely paginate even if there are changes in the ledger range from the request, so long as the marker does not indicate a point outside the range of ledgers specified in the request.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
account	String	Unique address identifying the related account
ledger_index_min	Integer	The sequence number of the earliest ledger actually searched for transactions.
ledger_index_max	Integer	The sequence number of the most recent ledger actually searched for transactions.
limit	Integer	The limit value used in the request. (This may differ from the actual limit value enforced by the server.)
marker	(Not Specified)	Server-defined value. Pass this to the next call in order to resume where this call left off.
offset	Integer	The offset value used in the request.
transactions	Array	Array of transactions matching the request's criteria, as explained below.
validated	Boolean	If included and set to true, the information in this request comes from a validated ledger version. Otherwise, the information is subject to change.

Note: The server may respond with different values of ledger_index_min and ledger_index_max than you provided in the request, for example if it did not have the versions you specified on hand.

Each transaction object includes the following fields, depending on whether it was requested in JSON or hex string ("binary":true) format.

Field	Type	Description
ledger_index	Integer	The sequence number of the ledger version that included this transaction.
meta	Object (JSON) or String (Binary)	If binary is True, then this is a hex string of the transaction metadata. Otherwise, the transaction metadata is included in JSON format.
tx	Object	(JSON mode only) JSON object defining the transaction
tx_blob	String	(Binary mode only) Unique hashed String representing the transaction.
validated	Boolean	Whether or not the transaction is included in a validated ledger. Any transaction not yet in a validated ledger is subject to change.

Possible Errors

• Any of the universal error types.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
• actMalformed - If the address specified in the account field of the request is not formatted properly.
• actBitcoin - If the address specified in the account field is formatted like a Bitcoin address instead of a Ripple address.
• lgrIdxsInvalid - If the ledger specified by the ledger_index_min or ledger_index_max does not exist, or if it does exist but the server does not have it.

noripple_check

[Source]

The noripple_check command provides a quick way to check the status of the DefaultRipple field for an account and the NoRipple flag of its trust lines, compared with the recommended settings.

Request Format

An example of the request format:

Note: There is no command-line syntax for this method. Use the json command to access this from the command line.

The request includes the following parameters:

Field	Type	Description
account	String	A unique identifier for the account, most commonly the account's address.
role	String	Whether the account refers to a gateway or user. Recommendations depend on the role of the account. Gateways must have DefaultRipple enabled and must disable NoRipple on all trust lines. Users should have DefaultRipple disabled, and should enable NoRipple on all trust lines.
transactions	Boolean	(Optional) If true, include an array of suggested transactions, as JSON objects, that you can sign and submit to fix the problems. Defaults to false.
limit	Unsigned Integer	(Optional) The maximum number of trust line problems to include in the results. Defaults to 300.
ledger_hash	String	(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger)
ledger_index	String or Unsigned Integer	(Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
ledger_current_index	Number	The sequence number of the ledger used to calculate these results.
problems	Array	Array of strings with human-readable descriptions of the problems. This includes up to one entry if the account's DefaultRipple setting is not as recommended, plus up to limit entries for trust lines whose NoRipple setting is not as recommended.
transactions	Array	(May be omitted) If the request specified transactions as true, this is an array of JSON objects, each of which is the JSON form of a transaction that should fix one of the described problems. The length of this array is the same as the problems array, and each entry is intended to fix the problem described at the same index into that array.

Possible Errors

• Any of the universal error types.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
• actNotFound - The address specified in the account field of the request does not correspond to an account in the ledger.
• lgrNotFound - The ledger specified by the ledger_hash or ledger_index does not exist, or it does exist but the server does not have it.

gateway_balances

[Source]

The gateway_balances command calculates the total balances issued by a given account, optionally excluding amounts held by specific "hot wallet" addresses. (New in version 0.28.2.)

Request Format

An example of the request format:

The request includes the following parameters:

Field	Type	Description
account	String	The address of the account to use
strict	Boolean	(Optional) If true, only accept an address or public key for the account parameter. Defaults to false.
hotwallet	String or Array	The address of a hot wallet account to exclude from the balances issued, or an array of such addresses.
ledger_hash	String	(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger)
ledger_index	String or Unsigned Integer	(Optional) The sequence number of the ledger version to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)

Response Format

An example of a successful response:

Note: There is no command-line syntax for this method. Use the json command to access this from the command line.

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
obligations	Object	(Omitted if empty) Total amounts issued to accounts that are not hot wallets, as a map of currencies to the total value issued.
balances	Object	(Omitted if empty) Amounts issued to the hotwallet accounts from the request. The keys are hot wallet addresses and the values are arrays of currency amounts they hold. The issuer (omitted from the currency amounts) is the account from the request.
assets	Object	(Omitted if empty) Total amounts held that are issued by others. For the recommended gateway configuration, there should be none.
ledger_hash	String	(May be omitted) The identifying hash of the ledger that was used to generate this response.
ledger_index	Number	(May be omitted) The sequence number of the ledger version that was used to generate this response.
ledger_current_index	Number	(May be omitted) The sequence number of the current in-progress ledger version that was used to generate this response.

Possible Errors

• Any of the universal error types.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
• invalidHotWallet - One or more of the addresses specified in the hotwallet field is not the address of an account holding currency issued by the account from the request.
• actNotFound - The address specified in the account field of the request does not correspond to an account in the ledger.
• lgrNotFound - The ledger specified by the ledger_hash or ledger_index does not exist, or it does exist but the server does not have it.

wallet_propose

[Source]

Use the wallet_propose method to generate the keys needed for a new account. The account created this way will only become officially included in the Ripple network when it receives a transaction that provides enough XRP to meet the account reserve. (The wallet_propose command does not affect the global network. Technically, it is not strictly necessary for creating a new account: you could generate keys some other way, but that is not recommended.)

The wallet_propose request is an admin command that cannot be run by unpriviledged users! (Since admin commands are not transmitted over the outside network this command is protected against people sniffing the network for account secrets.)

Request Format

An example of the request format:

The request can contain the following parameter:

Field	Type	Description
passphrase	String	(Optional) Specify a passphrase, for testing purposes. If omitted, the server will use a random number to generate the master key. Outside of testing purposes, keys should always be randomly generated. Some values, which resemble Ripple addresses and some other formats, are prohibited.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing various important information about the new account, including the following fields:

Field	Type	Description
master_seed	String	The master seed from which all other information about this account is derived, in Ripple's base-58 encoded string format.
master_seed_hex	String	The master seed, in hex format.
master_key	String	The master seed, in RFC 1751 format.
account_id	String	The public address of the account.
public_key	String	The public key of the account, in encoded string format.
public_key_hex	String	The public key of the account, in hex format.

The key generated by this method can also be used as a regular key for an account if you use the SetRegularKey transaction type to do so.

Possible Errors

• Any of the universal error types.
• badSeed - The passphrase field of the request has an invalid value, such as an empty string, or a format resembling a Ripple address or Ripple secret.

Ledger Information

The globally-shared ledger is the core of the Ripple Network. Each rippled server keeps a current version of the ledger, which contains all the accounts, transactions, offers, and other data in the network in an optimized tree format. As transactions and offers are proposed, each server incorporates them into its current copy of the ledger, closes it periodically, and (if configured) participates in the process of advancing the globally-validated version. After concensus is reached in the network, that ledger version is validated and becomes permanently immutable. Any transactions that were not included in one ledger become candidates to be included in the next validated version.

ledger

[Source]

Retrieve information about the public ledger.

Request Format

An example of the request format:

Try it! >

The request can contain the following parameters:

Field	Type	Description
accounts	Boolean	(Optional, defaults to false) If true, return information on accounts in the ledger. Admin required. If enabled, this method returns a large amount of data, which may cause the request to fail due to a timeout, depending on the server load and capabilities.
transactions	Boolean	(Optional, defaults to false) If true, return information on transactions in the specified ledger version.
full	Boolean	(Optional, defaults to false) If true, return full information on the entire ledger. (Equivalent to enabling transactions, accounts, and expand Admin required
expand	Boolean	(Optional, defaults to false) Provide full JSON-formatted information for transaction/account information instead of just hashes
ledger_hash	String	(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger)
ledger_index	String or Unsigned Integer	(Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)
binary	Boolean	(Optional, defaults to false) If transactions and expand are both true, and this option is also true, return transaction information in binary format instead of JSON format. (New in rippled v0.28.0)

The ledger field is deprecated and may be removed without further notice.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing information about the ledger, including the following fields:

Field	Type	Description
account_hash	String	Hash of all account state information in this ledger, as hex
close_time	Integer	The time this ledger was closed, in seconds since the Ripple Epoch
close_time_human	String	The time this ledger was closed, in human-readable format
close_time_resolution	Integer	Approximate number of seconds between closing one ledger version and closing the next one
closed	Boolean	Whether or not this ledger has been closed
ledger_hash	String	Unique identifying hash of the entire ledger.
ledger_index	String	Ledger sequence number as a quoted integer
parent_hash	String	Unique identifying hash of the ledger that came immediately before this one.
total_coins	String	Total number of XRP drops in the network, as a quoted integer. (This decreases as transaction fees cause XRP to be destroyed.)
transaction_hash	String	Hash of the transaction information included in this ledger, as hex
validated	Boolean	(Upcoming) If included and set to true, the information in this request describes a validated ledger version. Otherwise, the information is subject to change.

The following fields are deprecated and may be removed without further notice: accepted, hash, seqNum, totalCoins.

Possible Errors

• Any of the universal error types.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
• lgrNotFound - The ledger specified by the ledger_hash or ledger_index does not exist, or it does exist but the server does not have it.
• noPermission - If you specified full or accounts as true, but are not connected to the server as an admin (usually, admin requires connecting on a local port).

ledger_closed

[Source]

The ledger_closed method returns the unique identifiers of the most recently closed ledger. (This ledger is not necessarily validated and immutable yet.)

Request Format

An example of the request format:

Try it! >

This method accepts no parameters.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
ledger_hash	String	20-byte hex string with a unique hash of the ledger
ledger_index	Unsigned Integer	Sequence number of this ledger

Possible Errors

• Any of the universal error types.

ledger_current

[Source]

The ledger_current method returns the unique identifiers of the current in-progress ledger. This command is mostly useful for testing, because the ledger returned is still in flux.

Request Format

An example of the request format:

Try it! >

The request contains no parameters.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following field:

Field	Type	Description
ledger_current_index	Unsigned Integer	Sequence number of this ledger

A ledger_hash field is not provided, because the hash of the current ledger is constantly changing along with its contents.

Possible Errors

• Any of the universal error types.

ledger_data

[Source]

The ledger_data method retrieves contents of the specified ledger. You can iterate through several calls in order to retrieve the entire contents of a single ledger version.

Request Format

An example of the request format:

Note: There is no commandline syntax for ledger_data. You can use the json command to access this method from the commandline instead.

A request can include the following fields:

Field	Type	Description
id	(Arbitrary)	(WebSocket only) Any identifier to separate this request from others in case the responses are delayed or out of order.
ledger_hash	String	(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger)
ledger_index	String or Unsigned Integer	(Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)
binary	Boolean	(Optional, defaults to False) If set to true, return data nodes as hashed hex strings instead of JSON.
limit	Integer	(Optional, default varies) Limit the number of nodes to retrieve. The server is not required to honor this value.
marker	(Not Specified)	Server-provided value to specify where to resume retrieving data from.

The ledger field is deprecated and may be removed without further notice.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
ledger_index	Unsigned Integer	Sequence number of this ledger
ledger_hash	String	Unique identifying hash of the entire ledger.
state	Array	Array of JSON objects containing data from the tree, as defined below
marker	(Not Specified)	Server-defined value. Pass this to the next call in order to resume where this call left off.

The format of each object in the state array depends on whether binary was set to true or not in the request. Each state object may include the following fields:

Field	Type	Description
data	String	(Only included if "binary":true) Hex representation of the requested data
LedgerEntryType	String	(Only included if "binary":false) String indicating what type of ledger node this object represents. See ledger format for the full list.
(Additional fields)	(Various)	(Only included if "binary":false) Additional fields describing this object, depending on which LedgerEntryType it is.
index	String	Unique identifier for this ledger entry, as hex.

Possible Errors

• Any of the universal error types
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
• lgrNotFound - The ledger specified by the ledger_hash or ledger_index does not exist, or it does exist but the server does not have it.

ledger_entry

[Source]

The ledger_entry method returns a single ledger node from the Ripple Consensus Ledger. See ledger format for information on the different types of objects you can retrieve.

Note: There is no commandline version of this method. You can use the json command to access this method from the commandline instead.

Request Format

An example of the request format:

Try it! >

This method can retrieve several different types of data. You can select which type of item to retrieve by passing the appropriate parameters. Specifically, you should provide exactly one of the following fields:

1. index - Retrieve an individual ledger node by its unique index
2. account_root - Retrieve an account node, similar to the account_info command
3. directory - Retrieve a directory node, which contains a list of IDs linking things
4. offer - Retrieve an offer node, which defines an offer to exchange currency
5. ripple_state - Retrieve a RippleState node, which is a trust line where non-XRP balances are held

If you specify more than one of the above items, the server will retrieve only of them; it is undefined which one will be chosen.

The full list of parameters recognized by this method is as follows:

Field	Type	Description
index	String	(Optional) Specify the unique identifier of a single ledger entry to retrieve.
account_root	String	(Optional) Specify the unique address of an account object to retrieve.
directory	Object or String	(Optional) Specify a directory node to retrieve from the tree. (Directory nodes each contain a list of IDs for things contained in them.) If a string, interpret as the unique key to the directory, in hex. If an object, requires either dir_root or owner as a sub-field, plus optionally a sub_index sub-field.
directory.sub_index	Unsigned Integer	(Optional) If provided, jumps to a further sub-node in the directory linked-list.
directory.dir_root	String	(Required if directory is specified as an object and directory.owner is not provided) Unique index identifying the directory to retrieve, as a hex string.
directory.owner	String	(Required if directory is specified as an object and directory.dir_root is not provided) Unique address of the account associated with this directory
offer	Object or String	(Optional) Specify an offer to retrieve. If a string, interpret as a 256-key hex hash. If an object, requires the sub-fields account and seq to uniquely identify the offer.
offer.account	String	(Required if offer specified) The unique address of the account making the offer to retrieve.
offer.seq	Unsigned Integer	(Required if offer specified) The sequence number of the transaction making the offer to retrieve.
ripple_state	Object	(Optional) Object specifying the RippleState entry to retrieve. The accounts and currency sub-fields are required to uniquely specify the RippleState entry to retrieve.
ripple_state.accounts	Array	(Required if ripple_state specified) 2-length array of account address strings, defining the two accounts linked by this RippleState entry
ripple_state.currency	String	(Required if ripple_state specified) String representation of a currency that this RippleState entry relates to, as either a 3-letter currency code or a 40-character hex code
binary	Boolean	(Optional, defaults to false) If true, return hashed data as hex strings. Otherwise, return data in JSON format.
ledger_hash	String	(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger)
ledger_index	String or Unsigned Integer	(Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)

The generator and ledger parameters are deprecated and may be removed without further notice.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
index	String	Unique identifying key for this ledger_entry
ledger_index	Unsigned Integer	Unique sequence number of the ledger from which this data was retrieved
node	Object	("binary":false only) Object containing the data of this ledger node, according to the ledger format.
node_binary	String	("binary":true only) Binary data of the ledger node retrieved, as hex.

Possible Errors

• Any of the universal error types.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
• lgrNotFound - The ledger specified by the ledger_hash or ledger_index does not exist, or it does exist but the server does not have it.

ledger_request

[Source]

The ledger_request command tells server to fetch a specific ledger version from its connected peers. This only works if one of the server's immediately-connected peers has that ledger. You may need to run the command several times to completely fetch a ledger.

The ledger_request request is an admin command that cannot be run by unpriviledged users!

Request Format

An example of the request format:

The request includes the following parameters:

Field	Type	Description
ledger_index	Number	(Optional) Retrieve the specified ledger by its sequence number.
ledger_hash	String	(Optional) Retrieve the specified ledger by its identifying hash.

You must provide either ledger_index or ledger_hash but not both.

Response Format

The response follows the standard format. However, the request returns a failure response if it does not have the specified ledger even if it successfully instructed the rippled server to start retrieving the ledger.

Note: In order to retrieve a ledger, the rippled server must have a direct peer with that ledger in its history. If none of the peers have the requested ledger, you can use the connect command or the fixed_ips section of the config file to add Ripple Labs' full-history server at s2.ripple.com and then make the ledger_request request again.

A failure response indicates the status of fetching the ledger. A successful response contains the information for the ledger in a similar format to the ledger command.

The fields of the "failure" response (the ledger was requested, but has not been fully retrieved yet) can include any of the following:

Field	Type	Description
hash	String	The hash of the requested ledger, if the server knows it.
have_header	Boolean	Whether the server has the header section of the requested ledger.
have_state	Boolean	(May be omitted) Whether the server has the state section of the requested ledger.
have_transactions	Boolean	(May be omitted) Whether the server has the transaction section of the requested ledger.
needed_state_hashes	Array of Strings	(May be omitted) Up to 16 hashes of nodes in the state tree that the server still needs to retrieve.
needed_transaction_hashes	Array of Strings	(May be omitted) Up to 16 hashes of nodes in the transaction tree that the server still needs to retrieve.
peers	Number	How many peers the server is querying in its attempt to find this ledger.

Possible Errors

• Any of the universal error types.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing. This error can also occur if you specify a ledger index equal or higher than the current in-progress ledger.
• ledgerNotFound - If the ledger is not yet available. This indicates that the server has started fetching the ledger, although it may fail if none of its connected peers have the requested ledger.

ledger_accept

[Source]

The ledger_accept method forces the server to close the current-working ledger and move to the next ledger number. This method is intended for testing purposes only, and is only available when the rippled server is running stand-alone mode.

The ledger_accept method is an admin command that cannot be run by unpriviledged users!

Request Format

An example of the request format:

The request accepts no parameters.

Response Format

An example of a successful response:

{
  "id": "Accept my ledger!",
  "status": "success",
  "type": "response",
  "result": {
    "ledger_current_index": 6643240
  }
}

The response follows the standard format, with a successful result containing the following field:

Field	Type	Description
ledger_current_index	Unsigned Integer	Sequence number of the newly created 'current' ledger

Note: When you close a ledger, rippled determines the canonical order of transactions in that ledger and replays them. This can change the outcome of transactions that were provisionally applied to the current ledger.

Possible Errors

• Any of the universal error types.
• notStandAlone - If the rippled server is not currently running in stand-alone mode.

Transactions

Transactions are the only thing that can modify the shared global ledger of the Ripple Network. All business on the Ripple Network takes the form of transactions, which include not only payments, but also currency-exchange offers, account settings, and changes to the properties of the network itself (like adopting new features).

There are several sources of complication in transactions. Unlike traditional banking, where a trusted third party (the bank, or the ACH) verifies the participants' identities and ensures their balances are adjusted accurately, Ripple uses cryptography and decentralized computing power to accomplish the same thing. Sending XRP, the Ripple Network's native crypto-currency, requires no third party aside from the distributed network itself. However, that is missing out on the key feature of Ripple: unlike individual crypto-currencies, the Ripple Network natively supports balances in any currency. This brings far more power, but it also means that the system must account for counterparty risk, currency conversions, and other issues. The Ripple Network must be robust to keep track of which transactions have been completely validated, even when subject to hardware failures, attacks, or natural disasters.

tx

[Source]

The tx method retrieves information on a single transaction.

Request Format

An example of the request format:

Try it! >

The request includes the following parameters:

Field	Type	Description
transaction	String	The 256-bit hash of the transaction, as hex.
binary	Boolean	(Optional, defaults to false) If true, return transaction data and metadata as hex strings instead of JSON

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the fields of the Transaction object as well as the following additional fields:

Field	Type	Description
hash	String	The SHA-512 hash of the transaction
inLedger	Unsigned Integer	(Deprecated) Alias for ledger_index.
ledger_index	Unsigned Integer	The sequence number of the ledger that includes this transaction.
meta	Object	Various metadata about the transaction.
validated	Boolean	True if this data is from a validated ledger version; if omitted or set to false, this data is not final.
(Various)	(Various)	Other fields from the Transaction object

Possible Errors

• Any of the universal error types.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
• txnNotFound - Either the transaction does not exist, or it was part of an older ledger version that rippled does not have available.

transaction_entry

[Source]

The transaction_entry method retrieves information on a single transaction from a specific ledger version. (The tx command, by contrast, searches all ledgers for the specified transaction. We recommend using that method instead.)

Request Format

An example of the request format:

Try it! >

The request includes the following parameters:

Field	Type	Description
ledger_hash	String	(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger)
ledger_index	String or Unsigned Integer	(Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)
tx_hash	String	Unique hash of the transaction you are looking up

Note: This method does not support retrieving information from the current in-progress ledger. You must specify a ledger version in either ledger_index or ledger_hash.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
ledger_index	Unsigned Integer	Sequence number of the ledger version the transaction was found in; this is the same as the one from the request.
ledger_hash	String	(May be omitted) Unique hash of the ledger version the transaction was found in; this is the same as the one from the request.
metadata	Object	Various metadata about the transaction.
tx_json	Object	JSON representation of the Transaction object

There are a couple possible reasons the server may fail to find the transaction:

• The transaction just does not exist
• The transaction exists, but not in the specified ledger version
• The server does not have the specified ledger version available. Another server that has the correct version on hand may have a different response.

Possible Errors

• Any of the universal error types.
• fieldNotFoundTransaction - The tx_hash field was omitted from the request
• notYetImplemented - A ledger version was not specified in the request.
• lgrNotFound - The ledger specified by the ledger_hash or ledger_index does not exist, or it does exist but the server does not have it.
• transactionNotFound - The transaction specified in the request could not be found in the specified ledger. (It might be in a different ledger version, or it might not be available at all.)

tx_history

[Source]

The tx_history method retrieves a selection of the most recent transactions made.

Caution: This method is deprecated, and may be removed without further notice.

Request Format

An example of the request format:

Try it! >

The request includes the following parameters:

Field	Type	Description
start	Unsigned Integer	Number of transactions to skip over.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
index	Unsigned Integer	The value of start used in the request.
txs	Array	Array of transaction objects.

The fields included in each transaction object vary slightly depending on the type of transaction. See Transaction Format for details.

Possible Errors

• Any of the universal error types.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
• noPermission - The start field specified was greater than 10000, but you are not connected to the server as an admin.

path_find

[Source]

WebSocket API only! The path_find method searches for a path along which a transaction can possibly be made, and periodically sends updates when the path changes over time. For a simpler version that is supported by JSON-RPC, see ripple_path_find. For payments occurring strictly in XRP, it is not necessary to find a path, because XRP can be sent directly to any account.

There are three different modes, or sub-commands, of the path_find command. Specify which one you want with the subcommand parameter:

• create - Start sending pathfinding information
• close - Stop sending pathfinding information
• status - Get the information of the currently-open pathfinding request

Although the rippled server attempts to find the cheapest path or combination of paths for making a payment, it is not guaranteed that the paths returned by this method are, in fact, the best paths. Due to server load, pathfinding may not find the best results. Additionally, you should be careful with the pathfinding results from untrusted servers. A server could be modified to return less-than-optimal paths in order to earn money for its operators. If you do not have your own server that you can trust with pathfinding, you should compare the results of pathfinding from multiple servers operated by different parties, to minimize the risk of a single server returning poor results. (Note: A server returning less-than-optimal results is not necessarily proof of malicious behavior; it could also be a symptom of heavy server load.)

path_find create

[Source]

The create subcommand of path_find creates an ongoing request to find possible paths along which a payment transaction could be made from one specified account such that another account receives a desired amount of some currency. The initial response contains a suggested path between the two addresses that would result in the desired amount being received. After that, the server sends additional messages, with "type": "path_find", with updates to the potential paths. The frequency of updates is left to the discretion of the server, but it usually means once every few seconds when there is a new ledger version.

A client can only have one pathfinding request open at a time. If another pathfinding request is already open on the same connection, the old request is automatically closed and replaced with the new request.

Request Format

An example of the request format:

Try it! >

The request includes the following parameters:

Field	Type	Description
subcommand	String	Use "create" to send the create subcommand
source_account	String	Unique address of the account to find a path from. (In other words, the account that would be sending a payment.)
destination_account	String	Unique address of the account to find a path to. (In other words, the account that would receive a payment.)
destination_amount	String or Object	Currency amount that the destination account would receive in a transaction. Special case: (New in rippled 0.30.0) You can specify "-1" (for XRP) or provide -1 as the contents of the value field (for non-XRP currencies). This requests a path to deliver as much as possible, while spending no more than the amount specified in send_max (if provided).
send_max	String or Object	(Optional) Currency amount that would be spent in the transaction. Not compatible with source_currencies. (New in rippled 0.30.0)
paths	Array	(Optional) Array of arrays of objects, representing paths to confirm. You can use this to keep updated on changes to particular paths you already know about, or to check the overall cost to make a payment along a certain path.

The server also recognizes the following fields, but the results of using them are not guaranteed: source_currencies, bridges. These fields should be considered reserved for future use.

Response Format

An example of a successful response:

The initial response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
alternatives	Array	Array of objects with suggested paths to take, as described below. If empty, then no paths were found connecting the source and destination accounts.
destination_account	String	Unique address of the account that would receive a transaction
destination_amount	String or Object	Currency amount that the destination would receive in a transaction
id	(Various)	(WebSocket only) The ID provided in the WebSocket request is included again at this level.
source_account	String	Unique address of the account that would initiate a transaction
full_reply	Boolean	If false, this is the result of an incomplete search, and a subsequent reply may have a better path. If true, then this is the best path found. (It is still theoretically possible that a better path could exist, but rippled won't find it.) Until you close the pathfinding request, rippled will continue to send updates each time a new ledger closes. (New in rippled 0.29.0)

Each element in the alternatives array is an object that represents a path from one possible source currency (held by the initiating account) to the destination account and currency. This object has the following fields:

Field	Type	Description
paths_computed	Array	Array of arrays of objects defining payment paths
source_amount	String or Object	Currency amount that the source would have to send along this path in order for the destination to receive the desired amount

Possible Errors

• Any of the universal error types.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
• noEvents - You are using a protocol that does not support asynchronous callbacks, for example JSON-RPC. (See ripple_path_find for a pathfinding method that is compatible with JSON-RPC.)

Asynchronous Follow-ups

In addition to the initial response, the server sends more messages in a similar format to update on the status of the paths over time. These messages include the id of the original WebSocket request so you can tell which request prompted them, and the field "type": "path_find" at the top level to indicate that they are additional responses. The other fields are defined in the same way as the initial response.

If the follow-up includes "full_reply": true, then this is the best path that rippled can find as of the current ledger.

Here is an example of an asychronous follow-up from a path_find create request:

path_find close

[Source]

The close subcommand of path_find instructs the server to stop sending information about the current open pathfinding request.

Request Format

An example of the request format:

The request includes the following parameters:

Field	Type	Description
subcommand	String	Use "close" to send the close subcommand

Response Format

If a pathfinding request was successfully closed, the response follows the same format as the initial response to path_find create, plus the following field:

Field	Type	Description
closed	Boolean	The value true indicates this reply is in response to a path_find close command.

If there was no outstanding pathfinding request, an error is returned instead.

Possible Errors

• Any of the universal error types.
• invalidParams - If any fields are specified incorrectly, or any required fields are missing.
• noEvents - If you tried to use this method on a protocol that does not support asynchronous callbacks, for example JSON-RPC. (See ripple_path_find for a pathfinding method that is compatible with JSON-RPC.)
• noPathRequest - You tried to close a pathfinding request when there is not an open one.

path_find status

[Source]

The status subcommand of path_find requests an immediate update about the client's currently-open pathfinding request.

Request Format

An example of the request format:

The request includes the following parameters:

Field	Type	Description
subcommand	String	Use "status" to send the status subcommand

Response Format

If a pathfinding request is open, the response follows the same format as the initial response to path_find create, plus the following field:

Field	Type	Description
status	Boolean	The value true indicates this reply is in response to a path_find status command.

If there was no outstanding pathfinding request, an error is returned instead.

Possible Errors

• Any of the universal error types.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
• noEvents - You are using a protocol that does not support asynchronous callbacks, for example JSON-RPC. (See ripple_path_find for a pathfinding method that is compatible with JSON-RPC.)
• noPathRequest - You tried to check the status of a pathfinding request when there is not an open one.

ripple_path_find

[Source]

The ripple_path_find method is a simplified version of path_find that provides a single response to be used to make a payment transaction immediately. It is available in both the WebSocket and JSON-RPC APIs. However, the results tend to become outdated as time passes. Instead of making many subsequent calls, you should use path_find instead where possible.

Although the rippled server attempts to find the cheapest path or combination of paths for making a payment, it is not guaranteed that the paths returned by this method are, in fact, the best paths. Due to server load, pathfinding may not find the best results. Additionally, you should be careful with the pathfinding results from untrusted servers. A server could be modified to return less-than-optimal paths in order to earn money for its operators. If you do not have your own server that you can trust with pathfinding, you should compare the results of pathfinding from multiple servers operated by different parties, to minimize the risk of a single server returning poor results. (Note: A server returning less-than-optimal results is not necessarily proof of malicious behavior; it could also be a symptom of heavy server load.)

Request Format

An example of the request format:

Try it! >

The request includes the following parameters:

Field	Type	Description
source_account	String	Unique address of the account that would send funds in a transaction
destination_account	String	Unique address of the account that would receive funds in a transaction
destination_amount	String or Object	Currency amount that the destination account would receive in a transaction. Special case: (New in rippled 0.30.0) You can specify "-1" (for XRP) or provide -1 as the contents of the value field (for non-XRP currencies). This requests a path to deliver as much as possible, while spending no more than the amount specified in send_max (if provided).
send_max	String or Object	(Optional) Currency amount that would be spent in the transaction. Not compatible with source_currencies. (New in rippled 0.30.0)
source_currencies	Array	(Optional, defaults to all available) Array of currencies that the source account might want to spend. Each entry in the array should be a JSON object with a mandatory currency field and optional issuer field, similar to currency amounts.
ledger_hash	String	(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger)
ledger_index	String or Unsigned Integer	(Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
alternatives	Array	Array of objects with possible paths to take, as described below. If empty, then there are no paths connecting the source and destination accounts.
destination_account	String	Unique address of the account that would receive a payment transaction
destination_currencies	Array	Array of strings representing the currencies that the destination accepts, as 3-letter codes like "USD" or as 40-character hex like "015841551A748AD2C1F76FF6ECB0CCCD00000000"

Each element in the alternatives array is an object that represents a path from one possible source currency (held by the initiating account) to the destination account and currency. This object has the following fields:

Field	Type	Description
paths_computed	Array	Array of arrays of objects defining payment paths
source_amount	String or Object	Currency amount that the source would have to send along this path in order for the destination to receive the desired amount

The following fields are deprecated, and may be omitted: paths_canonical, and paths_expanded. If they appear, you should disregard them.

Possible Errors

• Any of the universal error types.
• tooBusy - The server is under too much load to calculate paths. Not returned if you are connected as an admin.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
• srcActMissing - The source_account field is omitted from the request.
• srcActMalformed - The source_account field in the request is not formatted properly.
• dstActMissing - The destination_account field is omitted from the request.
• dstActMalformed - The destination_account field in the request is not formatted properly.
• srcCurMalformed - The source_currencies field is not formatted properly.
• srcIsrMalformed - The issuer field of one or more of the currency objects in the request is not valid.

sign

[Source]

The sign method takes a transaction, specified as JSON, and a secret key, and returns a signed binary representation of the transaction that can be submitted. The result is always different, even when you provide the same transaction JSON and secret key.

Note: It is possible and preferable to sign a transaction without connecting to a server instead of using this command, by using ripple-lib. You should prefer to do offline signing of a transaction, especially when you do not control the server you are sending a transaction to. An untrustworthy server can abuse its position to change the transaction before signing it, or worse, use your secret to sign additional arbitrary transactions as if they came from you.

Request Format

An example of the request format:

Try it! >

The request includes the following parameters:

Field	Type	Description
tx_json	Object	Transaction definition in JSON format
secret	String	Secret key of the account supplying the transaction, used to sign it. Do not send your secret to untrusted servers or through unsecured network connections.
offline	Boolean	(Optional, defaults to false) If true, when constructing the transaction, do not attempt to automatically fill in or validate values.
build_path	Boolean	(Optional) If provided for a Payment-type transaction, automatically fill in the Paths field before signing. Caution: The server looks for the presence or absence of this field, not its value. This behavior may change. (See RIPD-173 for status.)
fee_mult_max	Integer	(Optional) If the transaction Fee is omitted, this field limits the Fee value that is automatically filled so that it is less than or equal to the long-term base fee times this value.

The server automatically attempts to fill in certain fields from the tx_json object if they are omitted, unless you specified offline as true. Otherwise, the following fields from the transaction format are automatically filled in:

• Sequence - The server automatically uses the next Sequence number from the sender's account information. Be careful: the next sequence number for the account is not incremented until this transaction is applied. If you sign multiple transactions without submitting and waiting for the response to each one, you must provide the correct sequence numbers in the request. Automatically filled unless offline is true.
• Fee - The server can automatically fill in an appropriate transaction fee (in drops of XRP) unless you specified offline as true. Otherwise, you must fill in the appropriate fee. Be careful: a malicious server can specify an excessively high fee. Automatically filled unless offline is true.
  • If fee_mult_max is included, and the automatically generated Fee is greater than the long-term base fee times fee_mult_max, then the transaction fails with the error rpcHIGH_FEE. This way, you can let the server fill in the current minimum Fee value as long as the current load fee is not too high.
• Paths - For Payment-type transactions (excluding XRP-to-XRP transfers), the Paths field can be automatically filled, as if you did a ripple_path_find. Only filled if build_path is provided.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
tx_blob	String	Binary representation of the fully-qualified, signed transaction, as hex
tx_json	Object	JSON specification of the complete transaction as signed, including any fields that were automatically filled in

Caution: If this command results in an error messages, the message can contain the account secret from the request. Make sure that these errors are not visible to others, including:

• Do not write this error to a log file that can be seen by multiple people
• Do not paste this error to a public place for debugging
• Do not display the error message on a website, even by accident

Possible Errors

• Any of the universal error types.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
• highFee - The fee_mult_max parameter was specified, but the server's current fee multiplier exceeds the specified one.
• tooBusy - The transaction did not include paths, but the server is too busy to do pathfinding right now. Does not occur if you are connected as an admin.
• noPath - The transaction did not include paths, and the server was unable to find a path by which this payment can occur.

submit

[Source]

The submit method sends a transaction to the network to be confirmed and included in future ledgers.

This command has two modes:

• Submit-only mode takes a signed, serialized transaction as a binary blob, and submits it to the network as-is. Since signed transaction objects are immutable, no portion of the transaction can be modified or automatically filled in after submission.
• Sign-and-submit mode takes a JSON-formatted Transaction object, completes and signs the transaction in the same manner as the sign command, and then submits the signed transaction. We recommend only using this mode for testing and development.

To send a transaction as robustly as possible, you should construct and sign it in advance, persist it somewhere that you can access even after a power outage, then submit it as a tx_blob. After submission, monitor the network with the tx command to see if the transaction was successfully applied; if a restart or other problem occurs, you can safely re-submit the tx_blob transaction: it won't be applied twice since it has the same sequence number as the old transaction.

Submit-Only Mode

A submit-only request includes the following parameters:

Field	Type	Description
tx_blob	String	Hex representation of the signed transaction to submit.
fail_hard	Boolean	(Optional, defaults to false) If true, and the transaction fails locally, do not retry or relay the transaction to other servers

Request Format

Try it! >

Sign-and-Submit Mode

A sign-and-submit request includes the following parameters:

Field	Type	Description
tx_json	Object	Transaction definition in JSON format, optionally omitting any auto-fillable fields.
secret	String	(Required if tx_json is supplied) Secret key of the account supplying the transaction, used to sign it. Do not send your secret to untrusted servers or through unsecured network connections.
fail_hard	Boolean	(Optional, defaults to false) If true, and the transaction fails locally, do not retry or relay the transaction to other servers
offline	Boolean	(Optional, defaults to false) If true, when constructing the transaction, do not attempt to automatically fill in or validate values.
build_path	Boolean	(Optional) If provided for a Payment-type transaction, automatically fill in the Paths field before signing. You must omit this field if the transaction is a direct XRP-to-XRP transfer. Caution: The server looks for the presence or absence of this field, not its value. This behavior may change. (See RIPD-173 for status.)
fee_mult_max	Integer	(Optional) If the transaction Fee is omitted, this field limits the Fee value that is automatically filled so that it is less than or equal to the long-term base fee times this value.

See the sign command for detailed information on how the server automatically fills in certain fields.

Request Format

An example of the request format:

Try it! >

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
engine_result	String	Code indicating the status of the transaction, for example tesSUCCESS
engine_result_code	Integer	Numeric code indicating the status of the transaction, directly correlated to engine_result
engine_result_message	String	Human-readable explanation of the status of the transaction
tx_blob	String	The complete transaction in hex string format
tx_json	Object	The complete transaction in JSON format

Caution: Even if the WebSocket response has "status":"success", indicating that the command was successfully received, that does not necessarily indicate that the transaction has taken place. There are many cases that can prevent a transaction from processing successfully, such as a lack of trust lines connecting the two accounts in a payment, or changes in the state of the network since the time the transaction was constructed. Even if nothing is wrong, it may take several seconds to close and validate the ledger version that includes the transaction. See the full list of transaction responses for details, and do not consider the transaction's results final until they appear in a validated ledger version.

Caution: If this command results in an error messages, the message can contain an account secret, if one was provided in the request. (This is not a problem if the request contained a signed tx_blob instead.) Make sure that these errors are not visible to others, including:

• Do not write an error including your secret to a log file that can be seen by multiple people
• Do not paste an error including your secret to a public place for debugging
• Do not display an error message including your secret on a website, even by accident

Possible Errors

• Any of the universal error types.
• invalidTransaction - The transaction is malformed or otherwise invalid.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
• highFee - The fee_mult_max parameter was specified, but the server's current fee multiplier exceeds the specified one. (Sign-and-Submit mode only)
• tooBusy - The transaction did not include paths, but the server is too busy to do pathfinding right now. Does not occur if you are connected as an admin. (Sign-and-Submit mode only)
• noPath - The transaction did not include paths, and the server was unable to find a path by which this payment can occur. (Sign-and-Submit mode only)
• internalTransaction - An internal error occurred when processing the transaction. This could be caused by many aspects of the transaction, including a bad signature or some fields being malformed.
• internalSubmit - An internal error occurred when submitting the transaction. This could be caused by many aspects of the transaction, including a bad signature or some fields being malformed.
• internalJson - An internal error occurred when serializing the transaction to JSON. This could be caused by many aspects of the transaction, including a bad signature or some fields being malformed.

book_offers

[Source]

The book_offers method retrieves a list of offers, also known as the order book, between two currencies. If the results are very large, a partial result is returned with a marker so that subsequent requests can resume from where the previous one left off.

Request Format

An example of the request format:

Try it! >

The request includes the following parameters:

Field	Type	Description
ledger_hash	String	(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger)
ledger_index	String or Unsigned Integer	(Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)
limit	Unsigned Integer	(Optional) If provided, the server will not provide more than this many offers in the results. Note: Depending on the number of unfunded orders in the ledger, fewer results may be returned.
taker	String	(Optional, defaults to ACCOUNT_ONE) Unique base-58 address of an account to use as point-of-view. (This affects which unfunded offers are returned.)
taker_gets	Object	Specification of which currency the account taking the offer would receive, as an object with currency and issuer fields (omit issuer for XRP), similar to currency amounts.
taker_pays	Object	Specification of which currency the account taking the offer would pay, as an object with currency and issuer fields (omit issuer for XRP), similar to currency amounts.

Note: The other parameters of this command (marker, proof, and autobridge) cannot be fully implemented with the current design. (See RIPD-295 for more information).

Normally, offers that are not funded are omitted; however, offers made by the specified taker account are always displayed. This allows you to look up your own unfunded offers in order to cancel them with an OfferCancel transaction.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
ledger_current_index	Integer	(Omitted if ledger version provided) Sequence number of the ledger version used when retrieving this data.
ledger_index	Integer	(Omitted if ledger_current_index provided instead) Sequence number, provided in the request, of the ledger version that was used when retrieving this data.
ledger_hash	String	(May be omitted) Hex hash, provided in the request, of the ledger version that was used when retrieving this data.
offers	Array	Array of offer objects, each of which has the fields of an OfferCreate transaction

In addition to the standard Offer fields, the following fields may be included in members of the offers array:

Field	Type	Description
taker_gets_funded	String (XRP) or Object (non-XRP)	(Only included in partially-funded offers) The maximum amount of currency that the taker can get, given the funding status of the offer.
taker_pays_funded	String (XRP) or Object (non-XRP)	(Only included in partially-funded offers) The maximum amount of currency that the taker would pay, given the funding status of the offer.
quality	Number	The exchange rate, as the ratio taker_pays divided by taker_gets. For fairness, offers that have the same quality are automatically taken first-in, first-out. (In other words, if multiple people offer to exchange currency at the same rate, the oldest offer is taken first.)

Possible Errors

• Any of the universal error types.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
• lgrNotFound - The ledger specified by the ledger_hash or ledger_index does not exist, or it does exist but the server does not have it.
• srcCurMalformed - The taker_pays field in the request is not formatted properly.
• dstAmtMalformed - The taker_gets field in the request is not formatted properly.
• srcIsrMalformed - The issuer field of the taker_pays field in the request is not valid.
• dstIsrMalformed - The issuer field of the taker_gets field in the request is not valid.
• badMarket - The desired order book does not exist; for example, offers to exchange a currency for itself.

Subscriptions

Using subscriptions, you can have the server push updates to your client when various events happen, so that you can know right away and react accordingly. Subscriptions are only supported in the WebSocket API, where you can receive additional responses in the same channel.

JSON-RPC support for subscription callbacks is deprecated and may not work as expected.

subscribe

[Source]

The subscribe method requests periodic notifications from the server when certain events happen.

Request Format

An example of the request format:

Try it! >

The request includes the following parameters:

Field	Type	Description
streams	Array	(Optional) Array of string names of generic streams to subscribe to, as explained below
accounts	Array	(Optional) Array with the unique base-58 addresses of accounts to monitor for validated transactions. The server sends a notification for any transaction that affects at least one of these accounts.
accounts_proposed	Array	(Optional) Like accounts, but include transactions that are not yet finalized.
books	Array	(Optional) Array of objects defining order books to monitor for updates, as detailed below.
url	String	(Optional for Websocket; Required otherwise) URL where the server will send a JSON-RPC callback with each event. Admin-only.
url_username	String	(Optional) Username to provide for basic authentication at the callback URL.
url_password	String	(Optional) Password to provide for basic authentication at the callback URL.

The following parameters are deprecated and may be removed without further notice: user, password, rt_accounts.

The streams parameter provides access to the following default streams of information:

• 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, however. (Note: Even some transactions that don't succeed are included in validated ledgers, because they take the anti-spam transaction fee.)

Each member of the books array, if provided, is an object with the following fields:

Field	Type	Description
taker_gets	Object	Specification of which currency the account taking the offer would receive, as a currency object with no amount.
taker_pays	Object	Specification of which currency the account taking the offer would pay, as a currency object with no amount.
taker	String	Unique base-58 account address to use as a perspective for viewing offers. (This affects the funding status and fees of offers.)
snapshot	Boolean	(Optional, defaults to false) If true, return the current state of the order book once when you subscribe before sending updates
both	Boolean	(Optional, defaults to false) If true, return both sides of the order book.

The field proof is reserved for future use.

Response Format

An example of a successful response:

The response follows the standard format. The fields contained in the response vary depending on what subscriptions were included in the request.

• accounts and accounts_proposed - No fields returned
• Stream: server - Information about the server status, such as load_base (the current load level of the server), random (a randomly-generated value), and others, subject to change.
• Stream: transactions and Stream: transactions_proposed - No fields returned
• Stream: ledger - Information about the ledgers on hand and current fee schedule, such as fee_base (current base fee for transactions in XRP), fee_ref (current base fee for transactions in fee units), ledger_hash (hash of the latest validated ledger), reserve_base (minimum reserve for accounts), and more.
• books - No fields returned by default. If "snapshot": true is set in the request, returns offers (an array of offer definition objects defining the order book)

Possible Errors

• Any of the universal error types.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
• noPermission - The request included the url field, but you are not connected as an admin.
• unknownStream - One or more the members of the streams field in the request was not recognized as a valid stream name.
• malformedStream - The streams field of the request was not formatted properly.
• malformedAccount - One of the addresses in the accounts or accounts_proposed fields of the request is not a properly-formatted Ripple address. (Note: You can subscribe to the stream of an address that does not yet have an entry in the global ledger; if your subscription is still active, you will get a message when that account receives the payment that creates it.)
• srcCurMalformed - One or more taker_pays sub-fields of the books field in the request is not formatted properly.
• dstAmtMalformed - One or more taker_gets sub-fields of the books field in the request is not formatted properly.
• srcIsrMalformed - The issuer field of one or more taker_pays sub-fields of the books field in the request is not valid.
• dstIsrMalformed - The issuer field of one or more taker_gets sub-fields of the books field in the request is not valid.
• badMarket - One or more desired order books in the books field does not exist; for example, offers to exchange a currency for itself.

Subscription Stream Messages

When you subscribe to a particular stream, you will receive periodic responses on that stream until you unsubscribe or close the WebSocket connection. The content of those responses depends on what you subscribed to. Here are some examples:

Stream: ledger Message

The ledger stream only sends ledgerClosed messages when the consensus process declares a new validated ledger. The message identifies the ledger and provides some information about its contents.

{
  "type": "ledgerClosed",
  "fee_base": 10,
  "fee_ref": 10,
  "ledger_hash": "687F604EF6B2F67319E8DCC8C66EF49D84D18A1E18F948421FC24D2C7C3DB464",
  "ledger_index": 7125358,
  "ledger_time": 455751310,
  "reserve_base": 20000000,
  "reserve_inc": 5000000,
  "txn_count": 7,
  "validated_ledgers": "32570-7125358"
}

The fields from a ledger stream message are as follows:

Field	Type	Description
type	String	ledgerClosed indicates this is from the ledger stream
fee_base	Unsigned Integer	Cost of the 'reference transaction' in drops of XRP. (See Transaction Fee Terminology If the ledger includes a SetFee pseudo-transaction the new transaction cost applies to all transactions after this ledger.
fee_ref	Unsigned Integer	Cost of the 'reference transaction' in 'fee units'. (See Transaction Fee Terminology
ledger_hash	String	Unique hash of the ledger that was closed, as hex
ledger_index	Unsigned Integer	Sequence number of the ledger that was closed
ledger_time	Unsigned Integer	The time this ledger was closed, in seconds since the Ripple Epoch
reserve_base	Unsigned Integer	The minimum reserve, in drops of XRP, that is required for an account. If the ledger includes a SetFee pseudo-transaction the new base reserve applies after this ledger.
reserve_inc	Unsigned Integer	The increase in account reserve that is added for each item the account owns, such as offers or trust lines. If the ledger includes a SetFee pseudo-transaction the new owner reserve applies after this ledger.
txn_count	Unsigned Integer	Number of new transactions included in this ledger
validated_ledgers	String	Range of ledgers that the server has available. This may be discontiguous.

Transaction Messages

Most other subscriptions result in messages about transactions. The transactions_proposed stream, strictly speaking, is a superset of the transactions stream: it includes all validated transactions, as well as some suggested transactions that have not yet been included in a validated ledger and may never be. You can identify these "in-flight" transactions by their fields:

• The validated field is missing or has a value of false.
• There is no meta or metadata field.
• Instead of ledger_hash and ledger_index fields specifying in which ledger version the transactions were finalized, there is a ledger_current_index field specifying in which ledger version they are currently proposed.

Otherwise, the messages from the transactions_proposed stream are identical to ones from the transactions stream.

Since the only thing that can modify an account or an order book is a transaction, the messages that are sent as a result of subscribing to particular accounts or books also take the form of transaction messages, the same as the ones in the transactions stream. The only difference is that you only receive messages for transactions that affect the accounts or order books you're watching.

The accounts_proposed subscription works the same way, except it also includes unconfirmed transactions, like the transactions_proposed stream, for the accounts you're watching.

{
  "status": "closed",
  "type": "transaction",
  "engine_result": "tesSUCCESS",
  "engine_result_code": 0,
  "engine_result_message": "The transaction was applied.",
  "ledger_hash": "989AFBFD65D820C6BD85301B740F5D592F060668A90EEF5EC1815EBA27D58FE8",
  "ledger_index": 7125442,
  "meta": {
    "AffectedNodes": [
      {
        "ModifiedNode": {
          "FinalFields": {
            "Flags": 0,
            "IndexPrevious": "0000000000000000",
            "Owner": "rRh634Y6QtoqkwTTrGzX66UYoCAvgE6jL",
            "RootIndex": "ABD8CE2D1205D0C062876E9E1F3CBDC902ED8EF4E8D3D071B962C7ED0E113E68"
          },
          "LedgerEntryType": "DirectoryNode",
          "LedgerIndex": "0BBDEE7D0BE120F7BF27640B5245EBFE0C5FD5281988BA823C44477A70262A4D"
        }
      },
      {
        "DeletedNode": {
          "FinalFields": {
            "Account": "rRh634Y6QtoqkwTTrGzX66UYoCAvgE6jL",
            "BookDirectory": "892E892DC63D8F70DCF5C9ECF29394FF7DD3DC6F47DB8EB34A03920BFC5E99BE",
            "BookNode": "0000000000000000",
            "Flags": 0,
            "OwnerNode": "000000000000006E",
            "PreviousTxnID": "58A17D95770F8D07E08B81A85896F4032A328B6C2BDCDEC0A00F3EF3914DCF0A",
            "PreviousTxnLgrSeq": 7125330,
            "Sequence": 540691,
            "TakerGets": "4401967683",
            "TakerPays": {
              "currency": "BTC",
              "issuer": "rNPRNzBB92BVpAhhZr4iXDTveCgV5Pofm9",
              "value": "0.04424"
            }
          },
          "LedgerEntryType": "Offer",
          "LedgerIndex": "386B7803A9210747941B0D079BB408F31ACB1CB98832184D0287A1CBF4FE6D00"
        }
      },
      {
        "DeletedNode": {
          "FinalFields": {
            "ExchangeRate": "4A03920BFC5E99BE",
            "Flags": 0,
            "RootIndex": "892E892DC63D8F70DCF5C9ECF29394FF7DD3DC6F47DB8EB34A03920BFC5E99BE",
            "TakerGetsCurrency": "0000000000000000000000000000000000000000",
            "TakerGetsIssuer": "0000000000000000000000000000000000000000",
            "TakerPaysCurrency": "0000000000000000000000004254430000000000",
            "TakerPaysIssuer": "92D705968936C419CE614BF264B5EEB1CEA47FF4"
          },
          "LedgerEntryType": "DirectoryNode",
          "LedgerIndex": "892E892DC63D8F70DCF5C9ECF29394FF7DD3DC6F47DB8EB34A03920BFC5E99BE"
        }
      },
      {
        "ModifiedNode": {
          "FinalFields": {
            "Account": "rRh634Y6QtoqkwTTrGzX66UYoCAvgE6jL",
            "Balance": "11133297300",
            "Flags": 0,
            "OwnerCount": 9,
            "Sequence": 540706
          },
          "LedgerEntryType": "AccountRoot",
          "LedgerIndex": "A6C2532E1008A513B3F822A92B8E5214BD0D413DC20AD3631C1A39AD6B36CD07",
          "PreviousFields": {
            "Balance": "11133297310",
            "OwnerCount": 10,
            "Sequence": 540705
          },
          "PreviousTxnID": "484D57DFC4E446DA83B4540305F0CE836D4E007361542EC12CC0FFB5F0A1BE3A",
          "PreviousTxnLgrSeq": 7125358
        }
      }
    ],
    "TransactionIndex": 1,
    "TransactionResult": "tesSUCCESS"
  },
  "transaction": {
    "Account": "rRh634Y6QtoqkwTTrGzX66UYoCAvgE6jL",
    "Fee": "10",
    "Flags": 2147483648,
    "OfferSequence": 540691,
    "Sequence": 540705,
    "SigningPubKey": "030BB49C591C9CD65C945D4B78332F27633D7771E6CF4D4B942D26BA40748BB8B4",
    "TransactionType": "OfferCancel",
    "TxnSignature": "30450221008223604A383F3AED25D53CE7C874700619893A6EEE4336508312217850A9722302205E0614366E174F2DFF78B879F310DB0B3F6DA1967E52A32F65E25DCEC622CD68",
    "date": 455751680,
    "hash": "94CF924C774DFDBE474A2A7E40AEA70E7E15D130C8CBEF8AF1D2BE97A8269F14"
  },
  "validated": true
}

Field	Type	Description
type	String	transaction indicates this is the notification of a transaction, which could come from the transactions or transactions_proposed streams, or from watching a particular account
engine_result	String	String Transaction result code
engine_result_code	Number	Numeric transaction response code, if applicable.
engine_result_message	String	Human-readable explanation for the transaction response
ledger_current_index	Unsigned Integer	(Omitted for validated transactions) Sequence number of the current ledger version for which this transaction is currently proposed
ledger_hash	String	(Omitted for unvalidated transactions) Unique hash of the ledger version that includes this transaction, as hex
ledger_index	Unsigned Integer	(Omitted for unvalidated transactions) Sequence number of the ledger version that includes this transaction
meta	Object	(Omitted for unvalidated transactions) Various metadata about the transaction, including which ledger entries it affected
transaction	Object	The definition of the transaction in JSON format
validated	Boolean	If true, this transaction is included in a validated ledger. Responses from the transaction stream should always be validated.

unsubscribe

[Source]

The unsubscribe command tells the server to stop sending messages for a particular subscription or set of subscriptions.

Request Format

An example of the request format:

Try it! >

The parameters in the request are specified almost exactly like the parameters to subscribe, except that they are used to define which subscriptions to end instead. The parameters are:

Field	Type	Description
streams	Array	(Optional) Array of string names of generic streams to unsubscribe from, including ledger, server, transactions, and transactions_proposed.
accounts	Array	(Optional) Array of unique base-58 account addresses to stop receiving updates for. (This only stops those messages if you previously subscribed to those accounts specifically. You cannot use this to filter accounts out of the general transactions stream.)
accounts_proposed	Array	(Optional) Like accounts, but for accounts_proposed subscriptions that included not-yet-validated transactions.
books	Array	(Optional) Array of objects defining order books to unsubscribe from, as explained below.

The rt_accounts and url parameters, and the rt_transactions stream name, are deprecated and may be removed without further notice.

The objects in the books array are defined almost like the ones from subscribe, except that they don't have all the fields. The fields they have are as follows:

Field	Type	Description
taker_gets	Object	Specification of which currency the account taking the offer would receive, as an object with currency and issuer fields (omit issuer for XRP), similar to currency amounts.
taker_pays	Object	Specification of which currency the account taking the offer would pay, as an object with currency and issuer fields (omit issuer for XRP), similar to currency amounts.
both	Boolean	(Optional, defaults to false) If true, remove a subscription for both sides of the order book.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing no fields.

Possible Errors

• Any of the universal error types.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
• noPermission - The request included the url field, but you are not connected as an admin.
• Unknown Stream - One or more the members of the streams field in the request was not recognized as a valid stream name. (The response does not use an exact code; this is a bug. See RIPD-702 for details and status.)
• malformedStream - The streams field of the request was not formatted properly.
• malformedAccount - One of the addresses in the accounts or accounts_proposed fields of the request is not a properly-formatted Ripple address. (Note: You can subscribe to the stream of an address that does not yet have an entry in the global ledger; if your subscription is still active, you will get a message when that account receives the payment that creates it.)
• srcCurMalformed - One or more taker_pays sub-fields of the books field in the request is not formatted properly.
• dstAmtMalformed - One or more taker_gets sub-fields of the books field in the request is not formatted properly.
• srcIsrMalformed - The issuer field of one or more taker_pays sub-fields of the books field in the request is not valid.
• dstIsrMalformed - The issuer field of one or more taker_gets sub-fields of the books field in the request is not valid.
• badMarket - One or more desired order books in the books field does not exist; for example, offers to exchange a currency for itself.

Server Information

There are also commands that retrieve information about the current state of the server. These may be useful for monitoring the health of the server, or in preparing for making other API methods. For example, you may query for the current fee schedule before sending a transaction, or you may check which ledger versions are available before digging into the ledger history for a specific record.

server_info

[Source]

The server_info command asks the server for a human-readable version of various information about the rippled server being queried.

Request Format

An example of the request format:

Try it! >

The request does not takes any parameters.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing an info object as its only field.

The info object may have some arrangement of the following fields:

Field	Type	Description
build_version	String	The version number of the running rippled version.
complete_ledgers	String	Range expression indicating the sequence numbers of the ledger versions the local rippled has in its database. It is possible to be a disjoint sequence, e.g. "2500-5000,32570-7695432".
hostid	String	On an admin request, returns the hostname of the server running the rippled instance; otherwise, returns a unique four letter word.
io_latency_ms	Number	Amount of time spent waiting for I/O operations to be performed, in milliseconds. If this number is not very, very low, then the rippled server is probably having serious load issues.
last_close	Object	Information about the last time the server closed a ledger, including the amount of time it took to reach a consensus and the number of trusted validators participating.
load	Object	Admin only Detailed information about the current load state of the server
load.job_types	Array	Admin only Information about the rate of different types of jobs being performed by the server and how much time it spends on each.
load.threads	Number	Admin only The number of threads in the server's main job pool, performing various Ripple Network operations.
load_factor	Number	The load factor the server is currently enforcing, as a multiplier on the base transaction fee. The load factor is determined by the highest of the individual server's load factor, cluster's load factor, and the overall network's load factor. See Calculating Transaction Fees for more details. Note: This load_factor is calculated as the ratio of the load_factor and the load_base that are reported by the server_state command
peers	Number	How many other rippled servers the node is currently connected to.
pubkey_node	String	Public key used to verify this node for internal communications; this key is automatically generated by the server the first time it starts up. (If deleted, the node can just create a new pair of keys.)
pubkey_validator	String	Admin only Public key used by this node to sign ledger validations; .
server_state	String	A string indicating to what extent the server is participating in the network. See Possible Server States for more details.
validated_ledger	Object	Information about the fully-validated ledger with the highest sequence number (the most recent)
validated_ledger.age	Unsigned Integer	The time since the ledger was closed, in seconds
validated_ledger.base_fee_xrp	Number	Base fee, in XRP. This may be represented in scientific notation such as 1e-05 for 0.00005
validated_ledger.hash	String	Unique hash for the ledger, as hex
validated_ledger.reserve_base_xrp	Unsigned Integer	Minimum amount of XRP (not drops) necessary for every account to keep in reserve
validated_ledger.reserve_inc_xrp	Unsigned Integer	Amount of XRP (not drops) added to the account reserve for each object an account is responsible for in the ledger
validated_ledger.seq	Unsigned Integer	Identifying sequence number of this ledger version
validation_quorum	Number	Minimum number of trusted validations required in order to validate a ledger version. Some circumstances may cause the server to require more validations.

Possible Errors

• Any of the universal error types.

server_state

[Source]

The server_state command asks the server for various machine-readable information about the rippled server's current state. The results are very similar to server_info, but generally the units are chosen to be easier to process instead of easier to read. (For example, XRP values are given in integer drops instead of scientific notation or decimal values, and time is given in milliseconds instead of seconds.)

Request Format

An example of the request format:

Try it! >

The request does not takes any parameters.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing a state object as its only field.

The state object may have some arrangement of the following fields:

Field	Type	Description
build_version	String	The version number of the running rippled version.
complete_ledgers	String	Range expression indicating the sequence numbers of the ledger versions the local rippled has in its database. It is possible to be a disjoint sequence, e.g. "2500-5000,32570-7695432".
io_latency_ms	Number	Amount of time spent waiting for I/O operations to be performed, in milliseconds. If this number is not very, very low, then the rippled server is probably having serious load issues.
load	Object	Admin only Detailed information about the current load state of the server
load.job_types	Array	Admin only Information about the rate of different types of jobs being performed by the server and how much time it spends on each.
load.threads	Number	Admin only The number of threads in the server's main job pool, performing various Ripple Network operations.
load_base	Number	This amount of server load is the baseline that is used to decide how much to charge in transaction fees; if the load_factor is equal to the load_base then only the base fee is enforced; if the load_factor is double the load_base then transaction fees are doubled. See Calculating Transaction Fees for more details.
load_factor	Number	The load factor the server is currently enforcing. The ratio between this value and the load_base determines the multiplier for transaction fees. The load factor is determined by the highest of the individual server's load factor, cluster's load factor, and the overall network's load factor.
peers	Number	How many other rippled servers the node is currently connected to.
pubkey_node	String	Public key used by this server (along with the corresponding private key) for secure communications between nodes. This key pair is automatically created and stored in rippled's local database the first time it starts up; if lost or deleted, a new key pair can be generated with no ill effects.
pubkey_validator	String	Admin only Public key used by this server (along with the corresponding private key) to sign proposed ledgers for validation.
server_state	String	A string indicating to what extent the server is participating in the network. See Possible Server States for more details.
validated_ledger	Object	Information about the fully-validated ledger with the highest sequence number (the most recent)
validated_ledger.base_fee	Unsigned Integer	Base fee, in drops of XRP, for propagating a transaction to the network.
validated_ledger.close_time	Number	Time this ledger was closed, in seconds since the Ripple Epoch
validated_ledger.hash	String	Unique hash of this ledger version, as hex
validated_ledger.reserve_base	Unsigned Integer	Minimum amount, in drops of XRP, necessary for every account to keep in reserve
validated_ledger.reserve_inc	Unsigned Integer	Amount, in drops of XRP, that is added to the account reserve for each item the account owns in the ledger.
validated_ledger.seq	Unsigned Integer	Unique sequence number of this ledger
validation_quorum	Number	Minimum number of trusted validations required in order to validate a ledger version. Some circumstances may cause the server to require more validations.

Possible Errors

• Any of the universal error types.

can_delete

[Source]

With online_delete and advisory_delete configuration options enabled, the can_delete method informs the rippled server of the latest ledger which may be deleted.

The can_delete method is an admin command that cannot be run by unpriviledged users.

Request Format

An example of the request format:

The request includes the following optional parameter:

Field	Type	Description
can_delete	String or Integer	The maximum ledger to allow to be deleted. For ledger_index or ledger_hash, see Specifying a Ledger. never sets the value to 0, and effectively disables online deletion until another can_delete is appropriately called. always sets the value to the maximum possible ledger (4294967295), and online deletion will occur as of each configured online_delete interval. now triggers online deletion at the next validated ledger that meets or exceeds the configured online_delete interval, but no further.

If no parameter is specified, no change is made.

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
can_delete	Integer	The maximum ledger index that may be removed by the online deletion routine.

Use this command with no parameter to query the existing can_delete setting.

Possible Errors

• Any of the universal error types.
• notEnabled - Not enabled in configuration.
• notReady - Not ready to handle this request.
• lgrNotFound - Ledger not found.
• invalidParams - Invalid parameters.

consensus_info

[Source]

The consensus_info command provides information about the consensus process for debugging purposes.

The consensus_info method is an admin command that cannot be run by unpriviledged users.

Request Format

An example of the request format:

The request has no parameters.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
info	Object	Information that may be useful for debugging consensus. This output is subject to change without notice.

The following is an incomplete summary of fields that may be contained in the info object:

Field	Type	Description
ledger_seq	Number	The sequence number of the ledger currently in the consensus process
our_position	Object	This server's expectation for the ledger in the consensus process.
peer_positions	Object	Map of peers and their proposed versions of the ledger in the consensus process.
proposers	Number	The number of trusted validators participating in this consensus process. Which validators are trusted depends on this server's configuration.
synched	Boolean	Whether this server considers itself in sync with the network.
state	String	What portion of the consensus process is currently in progress: open, consensus, finished, or accepted.

It is also normal to get a minimal result where the only field in info is "consensus": "none". This indicates that the server is in between consensus rounds.

The results of the consensus_info command can vary dramatically if you run it several times, even in short succession.

Possible Errors

• Any of the universal error types.

fetch_info

[Source]

The fetch_info command returns information about objects that this server is currently fetching from the network, and how many peers have that information. It can also be used to reset current fetches.

The fetch_info method is an admin command that cannot be run by unpriviledged users.

Request Format

An example of the request format:

The request includes the following parameters:

Field	Type	Description
clear	Boolean	If true, reset current fetches. Otherwise, only get status of fetches in progress.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
info	Object	Map of objects being fetched and the status of that object being fetched. A ledger being fetched may be identified by its sequence number; ledgers and other objects being fetched may also be identified by their hashes.

The fields describing a fetch in progress are subject to change without notice. The following fields may be included:

Field	Type	Description
hash	String	The hash of the object being fetched.
have_header	Boolean	For a ledger, whether this server has already obtained the ledger's header section.
have_transactions	Boolean	For a ledger, whether this server has already obtained the transaction section of that ledger.
needed_state_hashes	Array of (Hash) Strings	The hash values of state nodes still needed from this object. If more than 16 are needed, the response contains only the first 16.
peers	Number	The number of peers who have this object available.
timeouts	Number	The number of times that fetching this object has resulted in a timeout (2.5 seconds).

Possible Errors

• Any of the universal error types.

get_counts

[Source]

The get_counts command provides various stats about the health of the server, mostly the number of objects of different types that it currently holds in memory.

The get_counts method is an admin command that cannot be run by unpriviledged users.

Request Format

An example of the request format:

The request includes the following parameters:

Field	Type	Description
min_count	Number (Unsigned Integer)	Only return fields with a value at least this high.

Response Format

An example of a successful response:

The response follows the standard format. The list of fields contained in the result is subject to change without notice, but it may contain any of the following (among others):

Field	Type	Description
Transaction	Number	The number of Transaction objects in memory
Ledger	Number	The number of ledgers in memory
uptime	String	The amount of time this server has been running uninterrupted.

For most other entries, the value indicates the number of objects of that type currently in memory.

Possible Errors

• Any of the universal error types.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.

ledger_cleaner

[Source]

The ledger_cleaner command controls the Ledger Cleaner, an asynchronous maintenance process that can find and repair corruption in rippled's database of ledgers.

The ledger_cleaner method is an admin command that cannot be run by unpriviledged users.

Request Format

An example of the request format:

The request includes the following parameters:

Field	Type	Description
ledger	Number (Ledger Sequence Number)	(Optional) If provided, check and correct this specific ledger only.
max_ledger	Number (Ledger Sequence Number)	(Optional) Configure the ledger cleaner to check ledgers with sequence numbers equal or lower than this.
min_ledger	Number (Ledger Sequence Number)	(Optional) Configure the ledger cleaner to check ledgers with sequence numbers equal or higher than this.
full	Boolean	(Optional) If true, fix ledger state nodes and transations in the specified ledger(s). Defaults to false. Automatically set to true if ledger is provided.
fix_txns	Boolean	(Optional) If true, correct transaction in the specified ledger(s). Overrides full if provided.
check_nodes	Boolean	(Optional) If true, correct ledger state nodes in the specified ledger(s). Overrides full if provided.
stop	Boolean	(Optional) If true, disable the ledger cleaner.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
message	String	Cleaner configured on success.

Possible Errors

• Any of the universal error types.
• internal if one the parameters was specified in a way that the server couldn't interpret. (This is a bug, and it should return invalidParams instead. See RPD-916 for status.)

log_level

[Source]

The log_level command changes the rippled server's logging verbosity, or returns the current logging level for each category (called a partition) of log messages.

The log_level method is an admin command that cannot be run by unpriviledged users.

Request Format

An example of the request format:

The request includes the following parameters:

Field	Type	Description
severity	String	(Optional) What level of verbosity to set logging at. Valid values are, in order from least to most verbose: fatal, error, warn, info, debug, and trace. If omitted, return current log verbosity for all categories.
partition	String	(Optional) Ignored unless severity is provided. Which logging category to modify. If omitted, or if provided with the value base, set logging level for all categories.

Response Format

Examples of successful responses:

The response follows the standard format. The response format depends on whether the request specified a severity. If it did, the log level is changed and a successful result contains no additional fields.

Otherwise, the request contains the following field:

Field	Type	Description
level	Object	The current log levels of each category. This list of categories is subject to change without notice in future releases. You can use the field names as values to partition in requests to this command.

Possible Errors

• Any of the universal error types.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.

logrotate

[Source]

The logrotate command closes and reopens the log file. This is intended to facilitate log rotation on Linux file systems.

The logrotate method is an admin command that cannot be run by unpriviledged users.

Request Format

An example of the request format:

The request includes no parameters.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
message	String	On success, contains the message The log file was closed and reopened.

Possible Errors

• Any of the universal error types.

validation_create

[Source]

Use the validation_create command to generate the keys for a rippled validating node. Similar to the wallet_propose command, this command makes no real changes, but only generates a set of keys in the proper format.

The validation_create method is an admin command that cannot be run by unpriviledged users.

Request Format

An example of the request format:

The request includes the following parameters:

Field	Type	Description
secret	String	(Optional) Use this value as a seed to generate the credentials. The same secret always generates the same credentials. You can provide the seed in RFC-1751 format or Ripple's base-58 format. If omitted, generate a random seed.

Note: The security of your validator depends on the entropy of your seed. Do not use a secret value that is not sufficiently randomized for real business purposes. We recommend omitting the secret when generating new credentials for the first time.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
validation_key	String	The secret key for these validation credentials, in RFC-1751 format.
validation_public_key	String	The public key for these validation credentials, in Ripple's base-58 encoded string format.
validation_seed	String	The secret key for these validation credentials, in Ripple's base-58 encoded string format.

Possible Errors

• Any of the universal error types.
• badSeed - The request provided an invalid seed value. This usually means that the seed value appears to be a valid string of a different format, such as an account address or validation public key.

validation_seed

[Source]

The validation_seed command temporarily sets the secret value that rippled uses to sign validations. This value resets based on the config file when you restart the server.

The validation_seed request is an admin command that cannot be run by unpriviledged users!

Request Format

An example of the request format:

The request includes the following parameters:

Field	Type	Description
secret	String	(Optional) If present, use this value as the secret value for the validating key pair. Valid formats include base-58, RFC-1751, or as a passphrase. If omitted, disables proposing validations to the network.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
validation_key	String	(Omitted if proposing disabled) The secret key for these validation credentials, in RFC-1751 format.
validation_public_key	String	(Omitted if proposing disabled) The public key for these validation credentials, in Ripple's base-58 encoded string format.
validation_seed	String	(Omitted if proposing disabled) The secret key for these validation credentials, in Ripple's base-58 encoded string format.

Possible Errors

• Any of the universal error types.
• badSeed - The request provided an invalid secret value. This usually means that the secret value appears to be a valid string of a different format, such as an account address or validation public key.

peers

[Source]

The peers command returns a list of all other rippled servers currently connected to this one, including information on their connection and sync status.

The peers request is an admin command that cannot be run by unpriviledged users!

Request Format

An example of the request format:

The request includes no additional parameters.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing a peers array. Each member of the peers array is a peer object with the following fields:

Field	Type	Description
address	String	The IP address and port where this peer is connected
cluster	Boolean	(May be omitted) If true, the current server and the peer server are part of the same rippled cluster.
name	String	(May be omitted) If the peer is part of the same cluster, this is the display name for that node as defined in the config file.
complete_ledgers	String	Range expression indicating the sequence numbers of the ledger versions the peer rippled has available
inbound	Boolean	(May be omitted) If true, the peer is connecting to the local server.
latency	Number	The network latency to the peer (in milliseconds)
ledger	String	The hash of the peer's most recently closed ledger
load	Number	A measure of the amount of load the peer server is putting on the local server. Larger numbers indicate more load. (The units by which load is measured are not formally defined.)
protocol	String	(May be omitted) The protocol version that the peer is using, if not the same as the local server.
public_key	String	(May be omitted) A public key that can be used to verify the integrity of the peer's messages. This is not the same key that is used for validations, but it follows the same format.
sanity	String	(May be omitted) Whether this peer is following the same rules and ledger sequence as the current server. A value of insane probably indicates that the peer is part of a parallel network. The value unknown indicates that the current server is unsure whether the peer is compatible.
status	String	(May be omitted) The most recent status message from the peer. Could be connecting, connected, monitoring, validating, or shutting.
version	string	(May be omitted) The rippled version number of the peer server

Possible Errors

• Any of the universal error types.

print

[Source]

The print command returns the current status of various internal subsystems, including peers, the ledger cleaner, and the resource manager.

The print request is an admin command that cannot be run by unpriviledged users!

Request Format

An example of the request format:

The request includes no parameters.

Response Format

An example of a successful response:

The response follows the standard format. Additional fields in the result depend on the internal state of the rippled server. The results of this command are subject to change without notice.

Possible Errors

• Any of the universal error types.

Convenience Functions

The rippled server also provides a few simple commands purely for convenience.

ping

[Source]

The ping command returns an acknowledgement, so that clients can test the connection status and latency.

Request Format

An example of the request format:

Try it! >

The request includes no parameters.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing no fields. The client can measure the round-trip time from request to response as latency.

Possible Errors

• Any of the universal error types.

random

[Source]

The random command provides a random number to be used as a source of entropy for random number generation by clients.

Request Format

An example of the request format:

The request includes no parameters.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following field:

Field	Type	Description
random	String	Random 256-bit hex value.

Possible Errors

• Any of the universal error types.
• internal - Some internal error occurred, possibly relating to the random number generator.

json

The json method is a proxy to running other commands, and accepts the parameters for the command as a JSON value. It is exclusive to the Commandline client, and intended for cases where the commandline syntax for specifying parameters is inadequate or undesirable.

Request Format

An example of the request format:

Response Format

An example of a successful response:

The response follows the standard format, with whichever fields are appropriate to the type of command made.

connect

[Source]

The connect command forces the rippled server to connect to a specific peer rippled server.

The connect request is an admin command that cannot be run by unpriviledged users!

Request Format

An example of the request format:

The request includes the following parameters:

Field	Type	Description
ip	String	IP address of the server to connect to
port	Number	(Optional) Port number to use when connecting. Defaults to 6561.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
message	String	The value connecting, if the command was successful.

Possible Errors

• Any of the universal error types.
• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
• Cannot connect in standalone mode - Network-related commands are disabled in stand-alone mode.

stop

[Source]

Gracefully shuts down the server.

The stop request is an admin command that cannot be run by unpriviledged users!

Request Format

An example of the request format:

The request includes no parameters.

Response Format

An example of a successful response:

The response follows the standard format, with a successful result containing the following fields:

Field	Type	Description
message	String	ripple server stopping on success.

Possible Errors

• Any of the universal error types.