diff --git a/rippled-apis.html b/rippled-apis.html index 83b3f0670b..54ce9dcea7 100644 --- a/rippled-apis.html +++ b/rippled-apis.html @@ -127,16 +127,19 @@ mixpanel.init("132d42885e094171f34467fc54da6fab");
- - + + +
- -

WebSocket and JSON-RPC APIs

If you want to communicate directly with the rippled server, you have three fairly similar options for how to do that. All of these 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 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:

+

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:

@@ -1003,7 +1006,7 @@ rippled -- account_info r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 true -

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
+

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:

@@ -1180,7 +1183,7 @@ Response: } } -

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

Field
+

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

@@ -1227,12 +1230,12 @@ Response: - + - +
Field
taker_gets String or ObjectThe amount the account accepting the offer receives, as a String representing an amount in XRP, or a currency specification object. (See Specifying Currency Amounts)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 ObjectThe amount the account accepting the offer provides, as a String representing an amount in XRP, or a currency specification object. (See Specifying Currency Amounts)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)

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:

@@ -1796,7 +1799,7 @@ There is also a deprecated legacy variation of the standard format, with a successful result containing the following fields:

+

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

@@ -1930,7 +1933,7 @@ rippled -- wallet_propose test "status" : "success" } } -

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

Field
+

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

@@ -2077,7 +2080,7 @@ rippled -- ledger current false "status": "success" } } -

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

Field
+

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

@@ -2186,7 +2189,7 @@ rippled -- ledger_closed "status": "success" } } -

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

Field
+

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

@@ -2243,7 +2246,7 @@ rippled -- ledger_current "status": "success" } } -

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

Field
+

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

@@ -2482,7 +2485,7 @@ rippled -- ledger_current "status": "success" } } -

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

Field
+

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

@@ -2565,7 +2568,7 @@ rippled -- ledger_current }

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. -
  2. account_root - Retrieve an account node, similar to the account_info command
    3. +
  3. account_root - Retrieve an account node, similar to the account_info command
  4. directory - Retrieve a directory node, which contains a list of IDs linking things
  5. offer - Retrieve an offer node, which defines an offer to exchange currency
  6. ripple_state - Retrieve a RippleState node, which a trust line along which non-XRP balances are held
    7. @@ -2698,7 +2701,7 @@ rippled -- ledger_current "validated": true } } -

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

Field
+

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

@@ -2894,7 +2897,7 @@ tx E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7 false "status": "success", "type": "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
+

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

@@ -2934,7 +2937,7 @@ tx E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7 false -
Field Other fields from the Transaction object

Note: If the transaction was not found, it means that the rippled server could not find it from the ledger versions on hand. However, that does not mean that the transaction does not exist; it may simply have been included in an older ledger version that the rippled does not have on hand anymore.

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:

+

Note: If the transaction was not found, it means that the rippled server could not find it from the ledger versions on hand. However, that does not mean that the transaction does not exist; it may simply have been included in an older ledger version that the rippled does not have on hand anymore.

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:

{
   "id": 4,
@@ -3107,7 +3110,7 @@ rippled -- transaction_entry E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1B
     "status": "success",
     "type": "response"
 }
-

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

+

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

@@ -3991,7 +3994,7 @@ rippled -- tx_history 0 ] } } -

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

Field
+

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

@@ -4056,7 +4059,7 @@ rippled -- tx_history 0 - + @@ -4428,7 +4431,7 @@ rippled -- tx_history 0 "source_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59" } } -

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

Field
destination_amount String (XRP)
Object (Otherwise)		The amount of currency that needs to arrive at the destination. (See Specifying Currency Amounts. Set the issuer to the destination account’s address to use any issuer the destination accepts.)The amount of currency that needs to arrive at the destination. (See Specifying Currency Amounts. Set the issuer to the destination account’s address to use any issuer the destination accepts.)
paths
+

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

@@ -4450,7 +4453,7 @@ rippled -- tx_history 0 - + @@ -4480,7 +4483,7 @@ rippled -- tx_history 0 - +
Field
destination_amount String or ObjectCurrency amount that the destination would receive in a transactionCurrency amount that the destination would receive in a transaction
id
source_amount String or ObjectCurrency amount that the source would have to send along this path in order for the destination to receive the desired amountCurrency amount that the source would have to send along this path in order for the destination to receive the desired amount

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.

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

@@ -5437,12 +5440,12 @@ rippled -- ripple_path_find '{"source_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnf destination_amount String or Object -Currency amount that the destination account would receive in a transaction +Currency amount that the destination account would receive in a transaction 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. +(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 @@ -5666,7 +5669,7 @@ rippled -- ripple_path_find '{"source_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnf "status": "success" } }
-

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

+

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

@@ -5708,7 +5711,7 @@ rippled -- ripple_path_find '{"source_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnf - +
Field
source_amount String or ObjectCurrency amount that the source would have to send along this path in order for the destination to receive the desired amountCurrency 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.

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 and secret key.

Note: It is possible and preferable to sign a transaction without connecting to a server instead of using this command. For example, ripple-lib’s rsign.js demonstrates offline signing of a transaction. You should prefer to do offline signing of a transaction, especially when 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:

@@ -5766,7 +5769,7 @@ rippled -- sign sssssssssssssssssssssssssssss '{"TransactionType": "Payment", "A tx_json Object -Transaction definition in JSON format +Transaction definition in JSON format secret @@ -5833,7 +5836,7 @@ rippled -- sign sssssssssssssssssssssssssssss '{"TransactionType": "Payment", "A } } }
-

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

+

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

@@ -5923,7 +5926,7 @@ submit sssssssssssssssssssssssssssss '{"TransactionType":"Payment", "Account":"r -
Field(Optional, defaults to false) If true, when constructing the transaction, do not attempt to automatically fill in or validate values. (No effect when specifying the transaction as tx_blob.)

The JSON format for tx_json varies depending on the type of transaction. In the case of sending non-XRP currency (IOUs), you can obtain appropriate values for the Paths field by doing a find_path or ripple_find_path command first. The Paths field is not required for sending XRP. The provided path or paths are used as options for the path the payment takes; the server selects one or more of them to use according to its own criteria. You can omit the Paths field, but that leaves it up to the server to choose a path on the fly. Since the total cost of making the payment, including transit fees, is automatically deducted from the sending account, you should find paths ahead of time to avoid getting surprised.

By default, rippled tries to compute the cheapest combination of paths, but it may not have the resources to find the best option. A payment may even be broken up into multiple parts that take different paths if that is the cheapest way. An untrustworthy server could be modified to choose paths maliciously.

If offline is not set to true, then the server tries to automatically fill the Sequence and Fee parameters appropriately.

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.

You should provide a LastLedgerSequence field in your transaction to make sure that it expires quickly in the case that it does not succeed. Otherwise, a transaction may end up in limbo, neither failing nor confirming, for a long time.

Response Format

An example of a successful response:

+

The JSON format for tx_json varies depending on the type of transaction. In the case of sending non-XRP currency (IOUs), you can obtain appropriate values for the Paths field by doing a find_path or ripple_find_path command first. The Paths field is not required for sending XRP. The provided path or paths are used as options for the path the payment takes; the server selects one or more of them to use according to its own criteria. You can omit the Paths field, but that leaves it up to the server to choose a path on the fly. Since the total cost of making the payment, including transit fees, is automatically deducted from the sending account, you should find paths ahead of time to avoid getting surprised.

By default, rippled tries to compute the cheapest combination of paths, but it may not have the resources to find the best option. A payment may even be broken up into multiple parts that take different paths if that is the cheapest way. An untrustworthy server could be modified to choose paths maliciously.

If offline is not set to true, then the server tries to automatically fill the Sequence and Fee parameters appropriately.

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.

You should provide a LastLedgerSequence field in your transaction to make sure that it expires quickly in the case that it does not succeed. Otherwise, a transaction may end up in limbo, neither failing nor confirming, for a long time.

Response Format

An example of a successful response:

{
   "id": 2,
@@ -5979,7 +5982,7 @@ submit sssssssssssssssssssssssssssss '{"TransactionType":"Payment", "Account":"r
         }
     }
 }
-

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

+

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

@@ -6077,12 +6080,12 @@ rippled -- book_offers 'USD/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B' 'EUR/rvYAfWj5gh67 - + - +
Field
taker_gets ObjectSpecification 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.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 ObjectSpecification 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.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, limit, proof, and autobridge — are not yet fully implemented. (See RIPD-295).

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:

@@ -6154,7 +6157,7 @@ rippled -- book_offers 'USD/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B' 'EUR/rvYAfWj5gh67 "validated": false } }
-

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

+

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

@@ -6325,7 +6328,7 @@ rippled -- book_offers 'USD/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B' 'EUR/rvYAfWj5gh67 "type": "response", "result": {} } -

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

- + - + @@ -6646,7 +6649,7 @@ rippled -- book_offers 'USD/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B' 'EUR/rvYAfWj5gh67 "status": "success", "type": "response" } -

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

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:

+

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

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:

{
   "id": 11,
@@ -6723,7 +6726,7 @@ rippled -- book_offers 'USD/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B' 'EUR/rvYAfWj5gh67
         "status": "success"
     }
 }
-

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
taker_gets ObjectSpecification 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.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 ObjectSpecification 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.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
+

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:

@@ -6795,7 +6798,7 @@ rippled -- book_offers 'USD/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B' 'EUR/rvYAfWj5gh67 - + @@ -6917,7 +6920,7 @@ rippled -- book_offers 'USD/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B' 'EUR/rvYAfWj5gh67 } } -

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
server_state StringA string indicating to what extent the server is participating in the network. See Possible Server States for more details.A string indicating to what extent the server is participating in the network. See Possible Server States for more details.
validated_ledger
+

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:

@@ -6984,7 +6987,7 @@ rippled -- book_offers 'USD/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B' 'EUR/rvYAfWj5gh67 - + @@ -7061,7 +7064,7 @@ rippled -- ping "status": "success" } } -

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.

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 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.

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:

{
     "id": 1,
@@ -7098,7 +7101,7 @@ rippled -- random
"status": "success" } }
-

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

Field
server_state StringA string indicating to what extent the server is participating in the network. See Possible Server States for more details.A string indicating to what extent the server is participating in the network. See Possible Server States for more details.
validated_ledger
+

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

@@ -7126,8 +7129,9 @@ rippled -q -- json ledger_closed '{}' "status" : "success" } } -

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

- +

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

+ + diff --git a/websocket_api.md b/websocket_api.md index 052b2e10ae..53ffe21061 100644 --- a/websocket_api.md +++ b/websocket_api.md @@ -5356,7 +5356,7 @@ The request includes the following parameters: | Field | Type | Description | |-------|------|-------------| -| tx_json | Object | [Transaction definition](https://ripple.com/wiki/Transaction_Format) in JSON format | +| tx_json | Object | [Transaction definition](transactions.html) 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. |
Field