JSON Messages

From Ripple Wiki
(Redirected from RPC API)
Jump to: navigation, search

Contents

WARNING

While Ripple is in BETA this API is subject to change without notice.

Follow changes to this page to possibly be informed of updates.

Overview

This page documents the commands made available by rippled via its JSON-RPC and websocket interfaces. Values are formatted as per the JSON_Data_Format.

This tool can be used to experiment with the API: https://ripple.com/tools/api/

Changing the ledger

This API is used to talk to rippled. Things like creating an account, sending a payment, or creating an offer required a signed transaction to be submitted to rippled. See the RPC sign command to learn about signing. See the Transaction Format page to learn about transactions.

Reliably submitting transactions is documented here: Robustly submitting a transaction

REST interface

This is a low level interface for streaming communications.

Many developers will prefer to use this simpler interface: https://github.com/ripple/ripple-rest

Specifying the ledger

Many command allow the specification of a ledger. The fields are interpreted as shown here.

JSON:

{
  ...
  "ledger_hash" : ledger_hash,         // optional
  "ledger_index" : ledger_index   // optional, defaults to 'current' and will soon default to 'validated'
  ...
}

ledger_hash

  • A 20 byte hex string.

ledger_index

  • Used if ledger_hash is not supplied. Normally, ledger_index is specified as a number. The following tokens are also allowed:
    • current - select the current ledger.
    • closed - select the last closed ledger.
    • validated - select the last validated ledger.

In almost all cases, API users will want either a specific ledger or the last validated ledger. The other current and the merely last closed ledgers will only be useful to the most sophisticated API users or those wanting to display provisional status. For efficiency reasons, accessing the current ledger should be avoided if possible.

See also:

Public Commands

account_info

Command line:

account_info account|nickname|seed|pass_phrase|key [ledger_index] [strict]

JSON:

{
  "account": string,
  "strict": bool,                 // optional, defaults to false.
  "index": unsigned integer       // optional
  "ledger_hash" : ledger_hash,         // optional
  "ledger_index" : ledger_index   // optional, defaults to current
}

Return information about the specified account.

strict
If true, only accepts public keys and account ids for account.

To verify if an address is well formed, specify strict as true. Malformed addresses are returned as actMalformed. Bitcoin addresses are returned as actBitcoin.

If an account does not exist, actNotFound is returned.

account_lines

Return information about the specified account's ripple credit lines.

Command line:

account_lines account [peer [ledger_index]]
account
Specify account|nickname|seed|pass_phrase|key
peer
Limits results to peer. Specify as account, but specify "" for no peer.

JSON:

{
  ...                               // Specify ledger.
  "account": account_id|account_public
  "account_index": number           // Optional, defaults to 0.
  "peer": account_id|account_public // Optional.
  "peer_index": number              // Optional, defaults to 0.
}
peer
If provided, limit results to lines with specified peer.

Result JSON:

{
  ...
  "account" : account,
  "lines" : [
    {
      "account" : account,
      "balance" : value,
      "currency" : currency,
      "limit" : value,
      "limit_peer" : value,
      "quality_in" : number,
      "quality_out" : number
    },
    ...
  ]
}

account_offers

Command line:

account_offers account|nickname|seed|pass_phrase|key [ledger_index]

JSON:

{
  "account": account_id|account_public
  "account_index": number        // optional, defaults to 0.
  "ledger_hash" : ledger_hash
  "ledger_index" : ledger_index
}

Return the specified account's outstanding offers.

See also: offer, offer_cancel

account_tx

Fetch a list of transactions that applied to this account.

Command line:

account_tx accountID [ledger_min [ledger_max [limit]]] [binary] [count] [descending]

JSON multiple ledgers, inclusive:

{
  account: account,
  ledger_index_min: ledger_index, // required, set to -1 for the first fully-validated ledger.
  ledger_index_max: ledger_index, // required, set to -1 for the last fully-validated ledger.
  binary: boolean,                // optional, defaults to false
  forward: boolean,               // optional, defaults to false
  limit: integer,                 // optional
  marker: opaque                  // optional
}

A ledger_index_min or ledger_index_max of -1 indicates the first and last fully-validated ledgers the server has available. This range may not be stable. If you've gotten a count this way and you wish to query the same set, make sure to use the returned ledger_index_min and ledger_index_max on future queries.

Notes:

  • Ledger 0 is not available on the live Ripple network. Although, it might appear. For more information see: Genesis ledger
  • There won't be transactions for an account in ledgers before the creation of the account.
  • There won't be transactions for an account in ledgers past the current last validated ledger.

Alternatively, a single ledger may be specified by hash or sequence number using the usual ledger semantics.

  • binary
    • True, to return transactions in hex rather than JSON.
  • forward
    • True, to sort in ascending ledger order.
  • limit
    • Maximum number of results to provide.
  • marker
    • The point to resume from.

If a limit is not specified, the limit determined by the server, currently 500 for binary requests and 200 for non-binary. The server is not required to honor the client's limit request.

JSON response:

{
  account: account,
  transactions: object,
  marker: opaque,
  ledger_index_min: integer,
  ledger_index_max: integer
}

The marker, if present, indicates that the result was truncated. The marker can be returned to the server in a follow up query to resume. All other parameters should remain the same. Clients should not make any assumptions about the content of the marker.

account_tx is not a subscribable ledger entry type.

book_offers

This command returns the offers for an order book as one or more pages.

Command line:

book_offers taker_pays taker_gets [taker [ledger [limit [proof [marker]]]]] [autobridge]
taker_pays
Specified in the following forms 'XRP' or 'USD/rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh'
taker_gets
Specified in the following forms 'XRP' or 'USD/rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh'
ledger (optional)
"current" (default). "closed", "validated", ledger_index, or ledger.
taker (optional)
The address of the taker. This affects the funding of offers by owners as they may need to pay transfer fees.
limit (optional)
An integer. Specify 0 for no limit.
proof (optional)
Specify 0 or 1. Defaults to 0.
marker (optional)
Specify the paging marker as JSON. Defaults to "".
autobridge (optional)
If present, specifies synthesize orders through XRP books.

JSON:

{
  "ledger_hash" : ledger,             // Optional
  "ledger_index" : ledger_index,      // Optional
  "taker_gets" : { "currency": currency, "issuer" : address },
  "taker_pays" : { "currency": currency, "issuer" : address },
  "taker" : address,                // Optional.
  "limit" : integer,                  // Optional.
  "autobridge" : boolean              // Defaults to true.
  "proof" : boolean                   // Defaults to false.
  "marker" : element,                 // Optional.
  ...
}
taker_gets
The currency and issuer the taker gets. Do not specify an issuing account if the currency is XRP.
taker_pays
The currency and issuer the taker pays. Do not specify an issuing account if the currency is XRP.
taker
The address of the taker. This affects the funding of offers by owners as they may need to pay transfer fees. For a neutral point of view specify ADDRESS_ONE (rrrrrrrrrrrrrrrrrrrrBZbvji).
marker
Token indicating start of page, it is returned from a previous invocation.
autobridge
True to synthesize orders through XRP books.
limit - Not implemented
Maximum number of elements to return.
proof - Not implemented
True to return proof. When proof is true the data is returned in such a way as to provide the client with the information necessary to iteratively query the ledger database and verify its entries. When proof is false, it means to trust the server to perform this operation on the client's behalf and return formatted data in a lump.

Response:

{
  ...
  "marker" : element,           // Optional.
  "offers" : array_of_offers,   // Optional, if proof was false.
  "nodes" : array_of_nodes      // Optional, if proof was true.
}
marker
If present indicates more entries are available.
offers
Returned if proof is false. The offers in JSON format. Only funded offers and offers owned by the taker are provided. Offers are sorted from best to worst, from the taker's point of view. Orders of the same quality are sorted "first came, first served". This is the same order in which offers are taken.
nodes
Returned if proof is true. This allows client to fetch the relevant nodes, which they haven't already cached. Offers are sorted from best to worst, from the taker's point of view. Orders of the same quality are sorted "first came, first served". This is the same order in which offers are taken.

Offers:

{
  ...
  "taker_gets_funded" : amount, // Optional
  "taker_pays_funded" : amount, // Optional
  "quality" : value
}
taker_gets_funded
The actual amount the offer is funded to pay out. Only provided if the offer is not fully funded.
taker_pays_funded
The actual amount the offer is funded to receive. Only provided if the offer is not fully funded.
quality
This is the price of the base currency: quality = taker_pays / taker_gets (XRP prices are multiplied by million).

See also:

data_sign

Signs data with the private key of an address.

Not Implemented Yet

Command line:

data_sign secret address [text|hex|json] data

JSON:

{
  ...
  "account" : address,
  "data" : data,
  "format": "text" | "hex" | "json",
  "master" : bool,     // Optional, defaults false.
  "secret" : string,
}
address
The address to verify public_key is associated with in the specified ledger.
secret
The secret of address.
data
The data to verify.
format
The format of the data.

JSON values are converted to Canonical JSON representation and then signed as text entries.

Returns:

{
  ...
  "public_key" : string,
  "signature" : string
}
public_key
The public key as hex.
signature
The signature, in hex, to verify the data with.

See also: RPC data_verify

data_verify

Verifies if data is signed by a signature.

Not Implemented Yet

NOTE: As of 20131108 this command returns an unknownCmd error (code 26).

Command line:

data_verify address signature [text|hex|json] data

JSON:

{
  ...
  "account" : address,
  "data" : data,
  "format": "text" | "hex" | "json",
  "public_key" : string,
  "signature" : string,
}

account

  • The address the public_key is associated with in the public ledger.

data

  • The data blob to verify.

format

  • The format of the supplied data (text, hex, json).

public_key

  • The public key as a string of hexadecimal digits.

signature

  • The cryptographic signature of the data to verify. Supplied as a string of hexadecimal digits.

Returns:

{
  ...
  "verified" : bool
}

See also: RPC data_sign

json

Sends a JSON-RPC request to the server.

Command line:

json [method] [JSON stanza]

Example:

# rippled -q json ledger_closed '{}'
{
   "result" : {
      "ledger_hash" : "8047C3ECF1FA66326C1E57694F6814A1C32867C04D3D68A851367EE2F89BBEF3",
      "ledger_index" : 390308,
      "status" : "success"
   }
}

ledger

This API call returns information about the public ledger, or parts thereof.

RPC interaction

ledger ledger_selector [full]

Possible values for ledger_selector

  • current
  • closed
  • validated
  • a ledger hash
  • a ledger sequence number

Websockets interaction

{
  "command": "ledger"
  ("full" : bool,                // optional, defaults to false.)
  ("accounts" : bool,            // optional, defaults to false.)
  ("transactions" : bool,        // optional, defaults to false.)
  ("expand" : bool,              // optional, defaults to false.)
}

full

If set to true, sets the boolean flags accounts, transactions, and expand are set to true.

accounts

If set to true, it will return the accounts tree for that public ledger block.

transactions

If true, return the transactions for the ledger.

expand

If set to true, returns the ledger and transaction entries in JSON format. Otherwise, returns their identifying hashes.

Interacting with RPC through CURL

# curl -X POST -d '{ "method" : "ledger", "params" : [ { "ledger_index" : "verified" } ] }' http://s1.ripple.com:51234

See also: Specifying the ledger

ledger_closed

This command returns the index number and hash of the most recently closed ledger block. If a validation list has been provided, then validations should be available.

An example of a valid response:

{
  "ledger_hash" : "EDC29CDE8DC6CCB498FF2218425EEAE3CB5E6925B853DEDDD9B59D7CEB7491E7", // Type: uint256
  "ledger_index" : 3235354
}

Future: Might include validations.

When running this command on a local rippled you may get a noCurrent error response.

ledger_current

This command returns the current ledger index.

Proof is not possible for the current ledger. This command is primarily useful for testing.

The ledger hash changes as transactions are applied to the ledger. Due to the current ledgers' ledger hash transient nature, it is of limited use and not provided.

RPC interaction

./rippled ledger_current

Websockets interaction

{"command": "ledger_current"}

Response:

{
   "result": {
       "ledger_current_index": 3235386
   },
   "status": "success",
   "type": "response"
}

ledger_data

This command returns leaf nodes from the state tree of a ledger. It can be called repeatedly to extract all the leaf nodes from a ledger.

While a ledger can be specified by any of the normal methods, it is recommended that a ledger be specified by hash to ensure that the same ledger is queried each time.

Input fields:

{
   binary: boolean,         // optional, defaults to false
   limit: integer,          // optional
   marker: opaque           // optional (from previous reply)
}

Output fields:

{
   ledger_hash: String    // The hash of the ledger
   ledger_index: String   // The sequence number of the ledger
   marker: opaque         // optional
   state: Array           // Entries from the ledger
}

If no marker is provided in the output, this completes the ledger. If a marker is provided, it can be passed in a subsequent query for entries from the same ledger until the entire ledger is retrieved.

The ledger header and transaction tree can be returned from the ledger command. At the same time, you can determine the ledger hash for a given sequence number, with a query similar to the following:

curl -X POST -d ' { "method" : "ledger", "params" : [ { "ledger_index" : 5200000, "expand" : true, "transactions" : true } ] } ' https://s1.ripple.com:51234

ledger_entry

This command returns a ledger entry.

For untrusted servers, the index option provides raw access to ledger entries and proof.

For trusted servers, all commands except index return the JSON for the object.

{
  "command" : "ledger_entry",
  ("ledger_hash" : uint256,)
  ("ledger_index" : ledger, ))
  ( { "type": "index", "index": uint256 }, )
  ( { "type": "account_root", "account_root": "account_id" }, )
  ( { "type": "directory", "directory": "index"}, )
  ( { "type": "directory",
      "directory": {
          "dir_root": index,
          ( "sub_index": sub_index ) } }, )
  ( { "type": "directory",
      "directory": {
          "owner": account_id,
          ( "sub_index": sub_index ) } }, )
  ( { "type": "generator", "generator": index } )
  ( { "type": "generator", "generator": {
        "regular_seed": regular_seed } }, )
  ( { "type": "offer", "offer": index }, )
  ( { "type": "offer", "offer": {
        "account": account_id,
        "seq": sequence } }, )
  ( { "type": "ripple_state", "ripple_state": {
        "accounts": [ account_id, account_id, account_id... ],
        "currency": "currency_id" } } )
}

ledger_hash is the cryptographic hash of a ledger block, as a string of hexadecimal digits. If supplied, overrides ledger_index.

ledger_index is an index into the public ledger.

index returns the object as binary with proof. Note that proof is not implemented at this time.

account_root returns the root node of the account given.

directory returns a directory node. Please note that several different forms of this options are documented. Only one is needed.

generator returns the generator map node. Please note that several different forms of this options are documented. Only one is needed. (MOOF MOOF MOOF: That construction doesn't look right...)

offer returns an offer node. Please note that several different forms of this options are documented. Only one is needed.

ripple_state returns a ripple state node. The value of the currency field is the three letter code for the currency or currency_id.

If the request was successful, the response will look something like this:

{
  'ledger_closed' : uint256,        // Only provided if ledger is closed.
  'ledger_closed_index' : index,    // Only provided if ledger is closed.
  'ledger_current_index' : index,   // Only provided if ledger is not closed.
  'node' : node,                    // Only provided for non-binary responses.
  'node_binary' : node_as_binary,   // Only provided for binary responses.
  ... option response fields ...
}

If the request was not successful, the response will look something like this:

{
  'error' : 'nodeNotFound'
}

path_find

This command is only available via the Websocket API.

All client queries will get a response from the server. The server will also send unsolicited progress reports and updates to the client if it has an open pathfinding request.

A connection may only have one open pathfinding request.

Client queries must always have their "command" field set to "path_find". Server responses to client queries will have their "type" field set to "response". Unsolicited server responses will always have their "type" field set to "path_find".

Create

This message is sent by the client to create a pathfinding request.

JSON:

{
  "command": "ripple_path_find",
  "source_account": "sender's Ripple address",
  "destination_account": "receiver's Ripple address",
  "destination_amount": ["currency": "international currency code",
                         "issuer": "receiver's Ripple address",
                         "value": "amount of transaction"],
  "source_currencies": ["currency": "international currency code",
                        "issuer": "sender's Ripple address"],
  ("paths": [ [] ], // One or more paths through the Ripple network.  Optional)
  ("bridges": [ [] ] // Addresses of one or more Ripple bridges in the network.  Optional.)
}

Each entry in the source currencies array must contain a "currency" entry and may contain an "issuer" entry.

destination_account

  • If the server is trusted, this could be a federation style address.

destination_amount

  • Specify the issuer as the destination account, if the issuer does not matter.

bridges

  • If the server is trusted, this could be a list of supported bridges.

Use with an untrusted server:

  • Do not use for bitcoin or federation style addresses.
  • Use the outbound bitcoin bridge protocol directly to obtain a destination_account for use with the command.
  • Use the federation protocol directly to obtain a destination_account for use with the command.

Close

This message is sent by the client to remove its pathfinding request.

JSON:

{
  "command": "path_find",
  "subcommand": "close"
}

Status

This message is sent by the client to obtain the current status of a pathfinding request and any paths that have been found.

JSON:

{
  "command": "path_find",
  "subcommand": "status"
}

Result:

{
  "status": string,
  "bridge_type": string,           // optional
  "source_account": string,
  "destination_account": string,
  "destination_currency": string,
  "destination_currencies": array, // optional
  "destination_amount": string,
  "destination_tag": boolean,
  "alternatives":
  [
    {
      "paths" : array,
      "source_amount" :
      {
        "currency" : string,
        "value": string
      }
    }
  ],
  "id": object,                     // optional
}
alternatives
Each entry will correspond to one possible source currency.
paths
The entries will have no redundant fields. For account nodes, they will have only an "account" field. The currency out must be the same as the currency in. The issuer out must be the account holder.
destination_currencies
If present, indicates the list of currencies that can be sent to the destination account.
destination_tag
If true, then the destination tag requires a destination tag be set on all payments to it.
status
Overall status of the response.
bridge_type
The bridge type recognized.
id
The request id, if provided in the original request.

For order book nodes, they will have a "currency" field, indicating the currency out and, if not XRP out, an "issuer" field for the issuer out. The currency in must be the currency out from the previous node (or the source currency if this is the first path element). The issuer in, if not XRP, must be the preceding account node (or the sender if this is the first path element).

Statuses:

dstMalformed
Unrecognized address. Address must currently be Ripple, Bitcoin, or e-mail style addresses.
noBridge
No bridge was provided for the recognized type. The type is specified in bridge_type.
noNetwork
Unable to compute a path.
success
Latest result provided.

Bridge types:

email
The destination address is in email format.
bitcoin
The destination address is a bitcoin address.
other
Future types may be recognized at anytime.

Unsolicited Updates

This message is sent by the server to the client to alert it to a significant change in the results of its open pathfinding request.

The format is the same as the response to a status subcommand except the "type" field is set to "path_find".

Issues

Can this work over RPC? If so, how will callbacks work?

The client would like paths it can easily show and easily convert into a transaction.

ping

Comand line:

ping

Result:

{
  ...
}

This command is used to check connectivity for clients. Websocket clients can use this to determine turn around time and actively discover loss of connectivity to a server.

random

Comand line:

random

Result:

{
  ...
  'random': uint256
}

This command returns a 256 bit random number. This command is to provide a source of randomness for clients.

ripple_path_find

Find a path and estimated costs.

For non-interactive use, such as automated payment sending from business integrations, ripple_path_find gives you single response that you can use immediately. However, for uses that need updated paths as new ledgers close, repeated calls becomes expensive. In those cases, when possible, use the RPC path_find in place of this API.

Command line:

ripple_path_find json_as_below ledger

Note: JSON encoded strings must be in double quotes.

JSON:

{
  "source_account" : account_id,
  "destination_account" : account_id,
  "destination_amount" : amount,
  "source_currencies" : [              //optional
     {
       "currency" : currency,
       "issuer" : issuer     // optional
     },
     ...
  ],
  "ledger_hash" : ledger,         // optional
  "ledger_index" : ledger_index   // optional, defaults 'current'
}
destination_amount
To effectively omit an issuer, specify the destination account as the issuer.
source_currencies
List of currencies to try to spend as payment. Defaults to all available: XRP, IOUs on hand, and trust available.
issuer
Defaults to the sender.

Successful, response:

{
  ...
  "alternatives" : [
    {
      "source_amount" : amount,
      "paths_canonical" : paths,
      "paths_computed" : paths,
      "paths_expanded" : paths,
      "paths_proof" : TBD,        // Future
    },
    ...
  ],
  "destination_account": account_id,
  "destination_currencies" : array of currency // Optional.
}
alternatives
If empty, there is insufficient liquidity. Causes may be no credit lines.
source_amount
The cost as of the server's version of the ledger. The amount may omit an issuer. The intent is for the source amount plus a safety margin to be used for send_max.
paths_canonical
For inclusion in a payment transaction. If a value for paths_canonical is returned it should be used in preference to to paths_computed.
paths_computed
If paths_canonical is empty, paths_computed should be included in the payment transaction.
paths_expanded
For informational use.
destination_currencies
List of currencies the destination accepts.

Error, response:

{
  ...
  "destination_account": account_id,
  "destination_currencies" : array of currency // Optional.
}

sign

This command signs a transaction.

Command line:

sign secret tx_json [offline]

JSON:

{
  "tx_json"   : tx_json,
  "secret"    : secret of sender,
  "offline"   : bool, // Optional
  "fail_hard" : bool, // Optional, only valid for submit.
}

When given on the command line, JSON encoded strings must be in double quotes.

tx_json
This is the JSON representation of the transaction for server to sign with the private key of the secret.
secret
The signer's secret. Do not provide this field to untrusted servers. Required to sign tx_json submissions.
offline
True, to not attempt to verify the account or lookup the sequence number.
fail_hard
True, to avoid relaying or retrying the transaction if it fails locally.

Example tx_json:

{
  "TransactionType" : transaction_type,
  "Account" : account_id,
  "Fee" : integer,              // optional
  "Sequence" : integer,         // optional
  ... as per Transaction Format ...
}

This command will also automatically attempt to fill in some missing fields:

Sequence
The sequence number will be determined from the sender's account root entry in the current proposed ledger. Warning: the sequence number will not be updated till the transaction is applied to current proposed ledger. Using this automatic fill should only be used sequentially. That is after the previous transaction has been applied. In offline mode, this field must be provided.
Fee
The transaction fee in XRP. In offline mode, this field must be provided. Perhaps this should only do default fees, not urgent fees.

Response:

{
  ...
  "transaction" : {
    ... fields ...
    "hash" : transaction_id,
  },
  "tx_blob"   : serialized transaction signed by the sender
}
hash
The hash of the transaction. Use this to identify this particular transaction.
tx_blob
A hex representation of the signed transaction. This varies for each invocation, even if supplied the same parameters. To have the network apply this transaction, use the RPC submit.

Command line example:

# rippled -q sign snoPBrXtMeMyMHUVTgbuqAfg1SUTb '{"TransactionType":"Payment", "Account":"rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
  "Amount":"200000000","Destination":"r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV" }'
{
   "result" : {
      "status" : "success",
      "tx_blob" : "1200002200000000240000005061400000000BEBC20068400...",
      "tx_json" : {
         "Account" : "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
         "Amount" : "200000000",
         "Destination" : "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV",
         "Fee" : "10",
         "Flags" : 0,
         "Sequence" : 80,
         "SigningPubKey" : "0330E7FC9D56BB25D6893BA3F317AE5BCF33B3291BD63DB32654A313222F7FD020",
         "TransactionType" : "Payment",
         "TxnSignature" : "3046022100BDC21319D49511C2A1B6B5DA0D526A4D7CC...",
         "hash" : "C3106502AEFC9B2A7F378CE9F600953A0C9AC56EB7737E3A2952EEF1DBFAAE2D",
      }
   }
}

See also:

submit

This command submits a transaction to the network.

Command line and JSON arguments are as per RPC sign.

Alternative command line:

submit tx_blob

Alternative JSON for submitting previously signed transactions:

{
  "tx_blob"   : serialized transaction signed by the sender
}
tx_blob
A hex string of the transaction. This can be obtained with RPC sign. Mutually exclusive with providing tx_json and secret.

If issued over web socket and all goes well the caller will receive two messages back from the server. The first as the transaction is put in the server"s open ledger. The second when the transaction is included in a closed Ledger.

Response:

{
  ...
  "engine_result" : token,
  "engine_result_code" : integer,
  "engine_result_message" : string,
}
engine_result
For machine processing.
engine_result_code
For class detection.
engine_result_message
For programmers.

Engine results may not always be available. This command only provided preliminary results. The final disposition of a transaction may not be know till the current or next ledger closes.

If you don't control the server, the server can always lie. The server can tell you it failed when it succeeded and it succeeded when it failed.

The server has its own proposed view of the next ledger which you are submitting against. If the server is honest, it is reporting trying to apply your transaction against this ledger. If the transaction can't be applied, then its view of the sequence number will not be incremented.

See also:

subscribe

Start receiving selected streams from the server.

JSON:

{
  "id"           : user_created_id,   // Optional.
  "streams"      : [ streams+ ],      // Optional.
  "accounts"     : [ account_ids+ ],  // Optional.
  "accounts_proposed"  : [ account_ids+ ],  // Optional.
  "books"        : [ {
     "snapshot": boolean,                   // Optional, default false.
     "both": boolean,                       // Optional, default false.
     "taker_gets" : { "currency": currency, "issuer" : address },
     "taker_pays" : { "currency": currency, "issuer" : address },
     "taker" : address,                     // Optional, default false
     "proof" : boolean                      // Optional, default false.
  }, ... ], // optional
  "ledger_index" : ledger_index,      // Optional
  "url"          : url,               // Optional
  "url_username" : string,            // Optional
  "url_password" : string,            // Optional
}
streams
An array of these tokens: server, ledger, transactions
* server
** Sends a message anytime the server status changes such as network connectivity.
* ledger
** Sends a message at every ledger close.
* transactions
** Sends a message for every transaction that makes it into a ledger. Note, ledgerClosed messages are published prior to transaction messages.
transactions_proposed
Sends a message for every transaction that this server sees and also when the transaction finally makes it into the ledger. This only needed for applications which want to show might bes.
accounts
A list of account or contract ids that you want to monitor. Sends a message for all transactions that make it into the ledger that effect these accounts.
accounts_proposed
Like "accounts" field except you will get transactions from the server as they are proposed. It is possible these transactions will fail. This will also send closed transactions. Sends a message for every transaction that this server sees and also when the transaction finally makes it into the ledger that effect these accounts. This only needed for applications which want to show might bes.
books
Sends a message anytime one of these orderbooks changes. If you set snapshot to 1 it will send you the current state of the orderbook before it starts streaming it to you.
both
True, to return the other side of the order book. Defaults to false.
ledger_index - Not implemented
For accounts and accounts_proposed start publishing with the specified ledger.
url
Required for non-websocket requests. Specifies to the URL to post messages via JSON-RPC. Each message will come with a sequentially increasing seq starting with 1. A gap in seqs indicates lost messages. A new subscription for the same url, replaces the old username and password. There is no flow of control. To avoid gaps use websocket. Currently, only http is supported and hosts must be specified by IP address.
url_username
The user name for JSON-RPC basic authentication, if required.
url_password
The password for JSON-RPC basic authentication, if required.

Response:

{
   'type'   : 'response',
   'result' : 'success',
   'id'     : user_created_id,    // only if provided in request
   'seq'    : integer,            // only for url responses
   ...
}

Response for a subscribe server:

{
  ...
  'random' : uint256,
  'stand_alone' : bool,            // optional, defaults to 0.
  'testnet' : bool,                // optional, defaults to 0.
}
stand_alone
1, if server is operating in stand alone mode.
testnet
1, if server is operating in testnet mode.

Response for a subscribe ledger includes the information that would be published by a regular stream message.

Rationale: Remove a round trip, decrease start up complexity, avoid a race condition, and avoid duplicate messages.

Testing URL subscriptions

Launch a server JSON-RPC server to receive and report messages:

# jsonrpc_server.js 127.0.0.1 8000

Send a request to subscribe to the ledger stream:

# jsonrpc_request.js http://127.0.0.1:5010 subscribe '[ {"streams":["ledger"], "url":"http://127.0.0.1:8000/foo"} ]'

The above request could have been done with rippled. But, this allows an independent way to check the functionality and perhaps has lighter weight dependencies.

server stream messages

{
   "type" : "serverStatus", // Needs to be renamed
   "server_status" : string,
   "load_base" : integer,
   "load_factor" : integer
}
server_status
The server's operating mode.
load_base
See load_base.
load_factor
See load_factor.

ledger stream messages

This message is issued once per ledger close, when the ledger is validated. This message appears before transactions are published.

{
  "type": "ledgerClosed",
  "validated_ledgers": "32570-330980",
  "fee_base": 10,
  "fee_ref": 10,
  "ledger_hash": "FC1811059863C86902359C2CDDDF07AE5C36FC0105866C44591D3FB9CDEDADD5",
  "ledger_index": 330932,
  "ledger_time": 416110050,
  "reserve_base": 200000000,
  "reserve_inc": 50000000,
  "txn_count": Number,    // Only streamed, not in the subscribe result.
}

All fields are optional except for type.

If ledger_index is present, these fields are also present: fee_base, fee_ref, ledger_hash, ledger_time, reserve_base, reserve_inc, and txn_count.

type
A value of 'ledgerClosed' identifies the message as belonging to the stream.
txn_count
The number of transactions in the ledger.
validated_ledgers - Optional
The range of validated ledgers available. Possibly discontiguous.

transactions stream messages

{
  "type": "transaction",
  "transaction": Transaction Format,
  "engine_result": string,
  "engine_result_code": integer,
  "engine_result_message": string,
  "ledger_hash": ledger_hash,
  "ledger_index": ledger_index,
  "meta": meta_data,                // optional
  "status": string, // ignore
  "validated": bool
}
engine_result
See: engine_result
engine_result_code
See: engine_result_code
engine_result_message
See: engine_result_message
meta
Information about the transactions disposition.
validated
True, if the transaction has been validated by the server's UNL list.

Transactions are presented in hash order (this behavior should not be relied upon).

Note: misprogrammed and malicous servers may provide duplicate messages, malformed messages, and erroneous messages.

transaction_entry

transaction_entry transaction_hash [ledger_hash]

This command requests a completed transaction from the network.

transaction hash
The transaction you want the details of.
ledger hash
The ledger to look for the transaction in. The server will look for the transaction only in this ledger.

Errors:

ledgerNotFound
The ledger was not found as specified.
transactionNotFound
The transaction was not found as specified.

Response, if found:

{
  ...
  'transaction' : as per account_transaction_subscribe
  'meta' : as per account_transaction_subscribe
}

tx

Return information about a transaction.

Command line:

tx transaction_id
tx transaction_id binary

JSON:

{
  "transaction": transaction_id
  "binary": bool                  // optional, defaults to false.
}

Note, servers may not have full information for all transactions. Some servers may only have recent information.

tx_history

Command line:

tx_history startIndex

JSON:

{
  start: index
}

Returns the last N transactions starting from startIndex ordered by ledger sequence number descending. Server sets N.

unsubscribe

Stop receiving selected streams from the server.

{
  'command'     : 'unsubscribe',
  'id'          : user_created_id   // optional
  'streams'     : [ streams+ ]      // optional
  'accounts'    : [ account_ids+ ]  // optional
  'rt_accounts' : [ account_ids+ ]  // optional
  'url'         : string            // optional
}

Will unsubscribe the websocket connection or the specified JSON-RPC url from the streams and accounts subscribed too.

wallet_accounts

THIS COMMAND WILL BE MADE ADMIN ONLY.

Command line:

wallet_accounts <regular_seed>

JSON:

{
  seed: string
}

Returns: a list of accounts for wallet.

Admin Commands

These commands are only available to administrators.

connect

connect host [port]

Establish a connection to the specified host and port.

data_delete

data_delete key

Delete data stored by a data_store.

See also: data_fetch, data_store

data_fetch

data_delete key

Fetch data stored by a data_store.

See also: data_delete, data_store

data_store

data_store key data

Store data locally by a key. This function is for the convenience of application writers.

See also: data_delete, data_fetch

ledger_accept

To support software testing, in stand alone mode, this command closes the current ledger and return the new current ledger index. This command is only available with admin access.

Method:

ledger_accept

Response:

{
  ...
  'ledger_current_index' : index
}

log_level

Command line:

log_level

Shows the current partitions and log levels.

Command line:

log_level level

Sets the minimum log severity level for logging. Sets all partitions.

Command line:

log_level partition level

Sets the specified partition to the specified severity.

Partition levels control what logs messages are generated and logged to the log file (if a log file is specified). The special partition "base" determines the minimum log level for printing.

JSON:

{
  "severity" : string, // optional
  "partition" : string, // optional, defaults to "base"
}
severity
If not provided, returns severity levels.
partition
Only used if severity is provided. Set the partition's severity level.

JSON result of severity levels:

{
  ...
  "levels" : {
    "base" : severity,
    partition : severity,
    ...
  }
}

logrotate

logrotate

Rotate the log file. This closes and re-opens the file. Typically this is used with a cron job or a manual command line process to first move the existing log file before calling logrotate so that the new log file starts out empty again.

Typical steps for rotating the log may include:

  • Rename the log file:
    • rm -f /var/log/rippled/debug.log.old
    • mv -f /var/log/rippled/debug.log /var/log/rippled/debug.log.old
  • Give rippled the log rotate command: rippled logrotate
  • Delete the log file, possibly using the command : ionice -c 3 rm <file>

peers

peers

Returns an array of peers to which the server is connected. For each peer it returns the ip address, port, and the hanko.

Example:

[
   {
      "hanko" : "0000000000000000000000000000000000000000",
      "ip" : "127.0.0.1",
      "port" : 51235
   }
]

proof_create

Generate a proof-of-work token.

Command line:

proof_create [difficulty] [secret]

JSON:

{
  "difficulty" : 1,         // optional, valid range 1-30
  "secret" : secret,        // optional, 256-bit hex
}
difficulty - Optional
Sets the difficulty of the custom proof-of-work generator.
secret - Optional
Sets the secret of the custom proof-of-work generator.

If no parameters are provided, the proof-of-work is generated by the built-in generator according to its current difficulty setting.

Successful, response:

{
  "secret" : "22F0EB6AF63A04481BE43D5A60380803C4B0C88760DA89FD0D6C73E129F514BA",
  "status" : "success",
  "token" : "121F6995D7FCCF3B45A1C8A3B49B752F08F7FE31B88F9AE6744CB87121B91F5B-
             0CFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF-
             98304-342108224-44BA4EF9F70A2CC78D298D0853378B72490F3B660ECD191E721E8BB1A1AA1689"
}
token
This is a proof-of-work token generated according to the given parameters.
secret - Optional
For a custom generator this is the secret that it was using.

See: Proof of Work

proof_solve

Solve a proof-of-work token.

Command line:

proof_solve token

JSON:

{
  "token" : token,
}
token
Proof-of-work token. For example obtained via proof_create

Successful, response:

{
  "solution" : "C48B221A448812D344B9BE310689A1679D3EE1E2DE4803BFAD4DFE9FB300E45B",
  "status" : "success"
}
solution
Solution to the proof-of-work problem. If no solution was found, will return uint256(0).

See: Proof of Work

proof_verify

Verify a solution for a proof-of-work token.

Command line:

proof_verify token solution [difficulty] [secret]

JSON:

{
  "token" : token
  "solution" : solution
  "difficulty" : 1,         // optional, valid range 1-30
  "secret" : secret,        // optional, 256-bit hex
}
token
Proof-of-work token. For example obtained via proof_create
solution
Solution to the proof-of-work problem.
difficulty - Optional
Sets the difficulty of the custom proof-of-work generator.
secret - Optional
Sets the secret of the custom proof-of-work generator.

Successful, response:

{
  "proof_result" : "powOK",
  "proof_result_code" : 0,
  "proof_result_message" : "Valid proof-of-work.",
  "secret" : "22F0EB6AF63A04481BE43D5A60380803C4B0C88760DA89FD0D6C73E129F514BA",
  "status" : "success"
}
proof_result
Status code for proof-of-work verification result.
proof_result_code
Numeric status code for proof-of-work verification result.
proof_result_message
Human readable status message.
secret - Optional
For a custom generator this is the secret that it was using.

See: Proof of Work

server_info

Returns information about the state of the server for human consumption. Results are subject to change without notice.

RPC example

./rippled server_info

Websockets example

{"command": "server_info"}

JSON response

{
   "result" : {
      "info" : {
         "build_version" : "0.16.0",
         "complete_ledgers" : "3175520-3176530",
         "hostid" : "platypus.testbed.ripple.com",
         "last_close" : {
            "converge_time_s" : 2.001,
            "proposers" : 4
         },
         "load" : {
            "job_types" : [
               {
                  "job_type" : "untrustedProposal",
                  "per_second" : 1
               },
               {
                  "avg_time" : 1,
                  "job_type" : "transaction",
                  "peak_time" : 2
               },
               {
                  "job_type" : "writeObjects",
                  "peak_time" : 2,
                  "per_second" : 1
               },
               {
                  "job_type" : "peerCommand",
                  "per_second" : 110
               }
            ],
            "threads" : 6
         },
         "load_factor" : 1,
         "peers" : 31,
         "pubkey_node" : "uuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuu",
         "pubkey_validator" : "none",
         "server_state" : "full",
         "validated_ledger" : {
            "age" : 8,
            "base_fee_xrp" : 1e-04,
            "hash" : "jjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjjj",
            "reserve_base_xrp" : 50,
            "reserve_inc_xrp" : 12.5,
            "seq" : 3176530
         },
         "validation_quorum" : 2
      },
      "status" : "success"
   }
}
hostid
A string that uniquely identifies the machine running the server. For administrative connections this will be the host name. Otherwise, it will be a unique four letter word.
build_version
The version number, expressed as <major>.<minor>-<suffix>.
load_base
See: Transaction Fee#Communicating Fees to Clients
load_fee
See: Transaction Fee#Communicating Fees to Clients
reserve_base
Provided, if the last closed ledger is known. See: Transaction Fee#Communicating Fees to Clients
reserve_inc
Provided, if the last closed ledger is known. See: Transaction Fee#Communicating Fees to Clients
testnet (optional)
defaults to 0. 1 if server is running in testnet mode.

server_state

Returns information about the state of the server for use by other software. Please note that the fields returned differ in some respects from those returned by server_info

Command line:

./rippled server_state

JSON:

{
   "result" : {
      "state" : {
         "build_version" : "0.16.0",
         "complete_ledgers" : "3175520-3176615",
         "last_close" : {
            "converge_time" : 2001,
            "proposers" : 3
         },
         "load" : {
            "job_types" : [
               {
                  "job_type" : "untrustedValidation",
                  "per_second" : 1
               },
               {
                  "job_type" : "ledgerData",
                  "peak_time" : 6,
                  "per_second" : 2
               },
               {
                  "job_type" : "writeObjects",
                  "peak_time" : 5,
                  "per_second" : 5
               },
               {
                  "job_type" : "peerCommand",
                  "per_second" : 95
               },
               {
                  "job_type" : "diskAccess",
                  "peak_time" : 2
               }
            ],
            "threads" : 6
         },
         "load_base" : 256,
         "load_factor" : 256,
         "peers" : 30,
         "pubkey_node" : "ffffffffffffffffffffffffffffffffffffffffffffffffffff",
         "pubkey_validator" : "none",
         "server_state" : "syncing",
         "validated_ledger" : {
            "base_fee" : 10,
            "close_time" : 436988770,
            "hash" : "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
            "reserve_base" : 50000000,
            "reserve_inc" : 12500000,
            "seq" : 3176615
         },
         "validation_quorum" : 2
      },
      "status" : "success"
   }
}

sms

Sends a nexmo style SMS request.

Command line:

sms text

JSON:

{
  "text" : string
}

You must configure the following fields in rippled.cfg as appropriate:

  • [sms_from]
  • [sms_key]
  • [sms_secret]
  • [sms_to]
  • [sms_url]

stop

Stop the rippled server.

Command line:

./rippled stop

unl_add

Hot add a node to the node's UNL. May also cache connectivity information.

RPC:

./rippled unl_add domain.name.com|validation_public_key (text comment)

JSON response:

{
   "result" : {
      "message" : "adding node by public key",
      "status" : "success"
      }
}

Warning: Editing your UNL with unl_add and unl_delete< is discouraged. These commands exist for debugging and troubleshooting.

unl_delete

Hot delete a node from your UNL.

RPC:

./rippled unl_delete domain.name.com|public key

JSON response:

{
   "result" : {
      "message" : "removing node by public key",
      "status" : "success"
      }
}

Again, we do not recommend that you manage your UNL manually.

unl_list

Print the UNL list configured for this node. Outputs a block of JSON.

RPC:

./rippled unl_list

JSON:

{
  "result" : {
     "status" : "success",
     "unl" : [
        {
           "comment" : "",
           "publicKey" : "n9KPnVLn7ewVzHvn218DcEYsnWLzKerTDwhpofhk4Ym1RUq4TeGw"
        },
        {
           "comment" : "",
           "publicKey" : "n9LFzWuhKNvXStHAuemfRKFVECLApowncMAM5chSCL9R5ECHGN4V"
        },
        {
           "comment" : "",
           "publicKey" : "n94rSdgTyBNGvYg8pZXGuNt59Y5bGAZGxbxyvjDaqD9ceRAgD85P"
        },
        {
           "comment" : "",
           "publicKey" : "n9LeQeDcLDMZKjx1TZtrXoLBLo5q1bR1sUQrWG7tEADFU6R27UBp"
        },
        {
           "comment" : "",
           "publicKey" : "n94n485za69fjxo5VGUp5p2krzvcF7WeA5opDP9ZtikFE1MP7zC8"
        }
     ]
  }
}

unl_load

unl_load

Use the local validators.txt as specified in rippled.cfg.

Use validators.txt to populate the UNL list. Does not clear any existing entries.

Overview: rippled needs a UNL list, containing a list of nodes unlikely to collude, to interpret the network. This list is initially empty. The user can use unl_default to specify a local list or use unl_default network to get the default list from newcoin.org.

unl_network

unl_network

As unl_local, but attempt to obtain validators.txt from: http://newcoin.org/validators.txt

Note: File is currently publicly available at: https://redstem.com/validators.txt

unl_reset

unl_reset

Remove all entries from the UNL.

validation_create

validation_create [seed|validation_key|pass_phrase]

With no arguments, a random validation seed is created.

If a family seed is recognized, the provided seed is used to construct the output.

If a validation key is recognized, it is used to provide a seed to construct the output.

Otherwise, the argument is used as a pass phrase to provide a seed to construct the output.

Returns:

  • validation_public_key
    • The public key to advertise in ripple.txt. when validating. Ripple peers use this to identify your validations.
    • Example: n9J2gtVcyni8XkRPVZgpbPfszyvrqxWsfPYkpoUPG4DppzCcAYca
  • validation_seed
    • The validation seed from which public and private are generated for validation.
    • The recommend representation for transmission, has a very good checksum.
    • Example: spFyFA2g3jrWTCx2dTZKM5BAT6zgH
  • validation_key
    • An easily transcribable and verbally transmitted form of the seed in RFC 1751 format, has poor parity.
    • Example: TROD MUTE TAIL WARM CHAR KONG HAAG CITY BORE O TEAL AWL

validation_seed

validation_seed seed|validation_key|pass_phrase

Specify the seed to allow rippled to validate. If the seed is not specified, the current seed is unset.

This is an alternative to putting the seed in rippled.cfg.

Warning: passing the validation seed on the command line may be insecure.

wallet_propose

Command line:

wallet_propose [pass_phrase]

JSON:

{
  passphrase: string
}

A person wanting a wallet obtains an account_id which can be used to create the account and a master seed which can be used to claim the created wallet.

A person who does not have funds to create a wallet themselves, can provide the id to someone who can create the wallet for them.

Warning: Never reveal your master seed. The master seed can be used to change your regular password.

pass_phrase
This option is merely for testing convenience. Master pass phrases should always be randomly generated.

Returns: a master_seed and a account_id.

wallet_seed

Command line:

wallet_seed [<passphrase>|<passkey>]

JSON:

{
  seed: string
}

Returns: a regular seed for use re-passwording a wallet. If a passphrase is not provided, a random seed is returned.

Possible Future Commands

book_directories

NOT_IMPLEMENTED.

This command returns the index of directories for an order book.

Request:

{
  'command' : 'book_directories',
  'ledger' : uint256,       // Optional, overrides ledger_index.
  'ledger_index' : ledger,  // Optional, defaults to 0 if ledger is not present
  'currencies' : [ currency_in, currency_out ]
  'start' : integer,        // Optional, defaults to 0.
  'count' : integer         // Optional.
  ...
}
currency_in
The currency the taker pays.
currency_out
The currency the taker gets.
start
The index of the first element in the array of directories to return.
count
Maximum number of elements to return.

Response:

{
  ...
  'base' : integer,
  'count : integer,
  'directories' : array of indexes to order directories,
}
base
Index of the first directory returned.
count
Number of directories available.

ledger_validations

This command specifies requests the validations for the specified ledger for the validators specified by the previous validators command. This command is only for untrusted nodes.

{
  'command' : 'ledger_validations',
  'ledger' : index
}

Response:

{
  ...
  'validatations' : array of validations in hex
}

nickname_info

nickname_info <nickname>

Returns the account id associated with a nickname and the minimum offer price.

validators

This command specifies the list of nodes whose validations should be provided for proof by ledger_validations and ledger_subscribe.

{
  'command' : 'validators',
  'validators': array of validator ids
}
Personal tools
Namespaces

Variants
Actions
Navigation
Tools