For AI agents: an LLM-friendly Markdown version of every page is available by appending .md to its URL or by sending an Accept: text/markdown request header. The full documentation index is at https://www.ankr.com/docs/llms.txt
Skip to main content

XRP — Methods, submit, transaction, tx, amm, book

API reference for XRP. All methods ->

submit​

Sends a transaction to the network.

The submit method applies a transaction and sends it 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 part 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 method, 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 method 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​

Parameters​

A submit-only request includes the following parameters:

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON-RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • tx_blob (string; required): Hex representation of the signed transaction to submit. This can be a multi-signed transaction.
    • fail_hard (boolean; optional): If true, and the transaction fails locally, do not retry or relay the transaction to other servers. The default is false.

Returns​

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

  • engine_result (string): Text result code indicating the preliminary result of the transaction, for example tesSUCCESS.
  • engine_result_code (integer): Numeric version of the result code. Not recommended.
  • engine_result_message (string): Human-readable explanation of the transaction's preliminary result.
  • tx_blob (string): The complete transaction in hex string format.
  • tx_json (object): The complete transaction in JSON format.
  • accepted (boolean; omitted in sign-and-submit mode): The value true indicates that the transaction was applied, queued, broadcast, or kept for later. The value false indicates that none of those happened, so the transaction cannot possibly succeed as long as you do not submit it again and have not already submitted it another time.
  • account_sequence_available (number; omitted in sign-and-submit mode): The next Sequence Number available for the sending account after all pending and queued transactions.
  • account_sequence_next (number; omitted in sign-and-submit mode): The next Sequence Number for the sending account after all transactions that have been provisionally applied, but not transactions in the queue.
  • applied (boolean; omitted in sign-and-submit mode): The value true indicates that this transaction was applied to the open ledger. In this case, the transaction is likely, but not guaranteed, to be validated in the next ledger version.
  • broadcast (boolean; omitted in sign-and-submit mode): The value true indicates this transaction was broadcast to peer servers in the peer-to-peer XRP Ledger network. The value false indicates the transaction was not broadcast to any other servers.
  • kept (boolean; omitted in sign-and-submit mode): The value true indicates that the transaction was kept to be retried later.
  • queued (boolean; omitted in sign-and-submit mode): The value true indicates the transaction was put in the Transaction Queue, which means it is likely to be included in a future ledger version.
  • open_ledger_cost (string; omitted in sign-and-submit mode): The current open ledger cost before processing this transaction. Transactions with a lower cost are likely to be queued.
  • validated_ledger_index (integer; omitted in sign-and-submit mode): The ledger index of the newest validated ledger at the time of submission. This provides a lower bound on the ledger versions that the transaction can appear in as a result of this request.

Request example​

curl 'https://rpc.ankr.com/xrp_mainnet/YOUR_ANKR_API_KEY' \
-d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "submit",
      "params": [
          {
            "tx_blob": "1200002280000000240000000361D4838D7EA4C6800000000000000000000000000055534400000000004B4E9C06F24296074F7BC48F92A97916C6DC5EA968400000000000000A732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB74473045022100D184EB4AE5956FF600E7536EE459345C7BBCF097A84CC61A93B9AF7197EDB98702201CEA8009B7BEEBAA2AACC0359B41C427C1C5B550A4CA4B80CF2174AF2D6D5DCE81144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143E9D4A2B8AA0780F682D136F7A56D6724EF53754"
        }
      ]
  }'

Response example​

{
    "result": {
        "accepted": true,
        "account_sequence_available": 393,
        "account_sequence_next": 393,
        "applied": false,
        "broadcast": false,
        "engine_result": "tefPAST_SEQ",
        "engine_result_code": -190,
        "engine_result_message": "This sequence number has already passed.",
        "kept": true,
        "open_ledger_cost": "10",
        "queued": false,
        "status": "success",
        "tx_blob": "1200002280000000240000000361D4838D7EA4C6800000000000000000000000000055534400000000004B4E9C06F24296074F7BC48F92A97916C6DC5EA968400000000000000A732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB74473045022100D184EB4AE5956FF600E7536EE459345C7BBCF097A84CC61A93B9AF7197EDB98702201CEA8009B7BEEBAA2AACC0359B41C427C1C5B550A4CA4B80CF2174AF2D6D5DCE81144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143E9D4A2B8AA0780F682D136F7A56D6724EF53754",
        "tx_json": {
            "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
            "Amount": {
                "currency": "USD",
                "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
                "value": "1"
            },
            "Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
            "Fee": "10",
            "Flags": 2147483648,
            "Sequence": 3,
            "SigningPubKey": "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB",
            "TransactionType": "Payment",
            "TxnSignature": "3045022100D184EB4AE5956FF600E7536EE459345C7BBCF097A84CC61A93B9AF7197EDB98702201CEA8009B7BEEBAA2AACC0359B41C427C1C5B550A4CA4B80CF2174AF2D6D5DCE",
            "hash": "82230B9D489370504B39BC2CE46216176CAC9E752E5C1774A8CBEC9FBB819208"
        },
        "validated_ledger_index": 100512474
    }
}

Sign-and-Submit mode​

This mode signs a transaction and immediately submits it. This mode is intended to be used for testing. You cannot use this mode for multi-signed transactions.

By default, sign-and-submit mode is admin-only. It can be used as a public method if the server has enabled public signing.

You can provide the secret key used to sign the transaction in the following ways:

  • Provide a secret value and omit the key_type field. This value can be formatted as an XRP Ledger base58 seed, RFC-1751, hexadecimal, or as a string passphrase. (secp256k1 keys only)
  • Provide a key_type value and exactly one of seed, seed_hex, or passphrase. Omit the secret field. (Not supported by the commandline syntax.)

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON-RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • tx_json (object): Transaction definition in JSON format, optionally omitting any auto-fillable fields.
    • secret (string; optional): 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. Cannot be used with key_type, seed, seed_hex, or passphrase.
    • seed (string; optional): Secret key of the account supplying the transaction, used to sign it. Must be in the XRP Ledger's base58 format. If provided, you must also specify the key_type. Cannot be used with secret, seed_hex, or passphrase.
    • seed_hex (string; optional): Secret key of the account supplying the transaction, used to sign it. Must be in hexadecimal format. If provided, you must also specify the key_type. Cannot be used with secret, seed, or passphrase.
    • passphrase (string; optional): Secret key of the account supplying the transaction, used to sign it, as a string passphrase. If provided, you must also specify the key_type. Cannot be used with secret, seed, or seed_hex.
    • key_type (string; optional): Type of cryptographic key provided in this request. Valid types are secp256k1 or ed25519. Defaults to secp256k1. Cannot be used with secret. Caution: Ed25519 support is experimental.
    • fail_hard (boolean; optional): If true, and the transaction fails locally, do not retry or relay the transaction to other servers. The default is false.
    • offline (boolean; optional): If true, when constructing the transaction, do not try to automatically fill in or validate values. The default is false.
    • build_path (boolean; optional): If this field is provided, the server auto-fills the Paths field of a Payment transaction before signing. You must omit this field if the transaction is a direct XRP payment or if it is not a Payment-type transaction. Caution: The server looks for the presence or absence of this field, not its value. This behavior may change.
    • fee_mult_max (integer; optional): Sign-and-submit fails with the error rpcHIGH_FEE if the auto-filled Fee value would be greater than the reference transaction cost × fee_mult_max ÷ fee_div_max. This field has no effect if you explicitly specify the Fee field of the transaction. The default is 10.
    • fee_div_max (integer; optional): Sign-and-submit fails with the error rpcHIGH_FEE if the auto-filled Fee value would be greater than the reference transaction cost × fee_mult_max ÷ fee_div_max. This field has no effect if you explicitly specify the Fee field of the transaction. The default is 1.

Returns​

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

  • engine_result (string): Text result code indicating the preliminary result of the transaction, for example tesSUCCESS.
  • engine_result_code (integer): Numeric version of the result code. Not recommended.
  • engine_result_message (string): Human-readable explanation of the transaction's preliminary result.
  • tx_blob (string): The complete transaction in hex string format.
  • tx_json (object): The complete transaction in JSON format.
  • accepted (boolean; omitted in sign-and-submit mode): The value true indicates that the transaction was applied, queued, broadcast, or kept for later. The value false indicates that none of those happened, so the transaction cannot possibly succeed as long as you do not submit it again and have not already submitted it another time.
  • account_sequence_available (number; omitted in sign-and-submit mode): The next Sequence Number available for the sending account after all pending and queued transactions.
  • account_sequence_next (number; omitted in sign-and-submit mode): The next Sequence Number for the sending account after all transactions that have been provisionally applied, but not transactions in the queue.
  • applied (boolean; omitted in sign-and-submit mode): The value true indicates that this transaction was applied to the open ledger. In this case, the transaction is likely, but not guaranteed, to be validated in the next ledger version.
  • broadcast (boolean; omitted in sign-and-submit mode): The value true indicates this transaction was broadcast to peer servers in the peer-to-peer XRP Ledger network. The value false indicates the transaction was not broadcast to any other servers.
  • kept (boolean; omitted in sign-and-submit mode): The value true indicates that the transaction was kept to be retried later.
  • queued (boolean; omitted in sign-and-submit mode): The value true indicates the transaction was put in the Transaction Queue, which means it is likely to be included in a future ledger version.
  • open_ledger_cost (string; omitted in sign-and-submit mode): The current open ledger cost before processing this transaction. Transactions with a lower cost are likely to be queued.
  • validated_ledger_index (integer; omitted in sign-and-submit mode): The ledger index of the newest validated ledger at the time of submission. This provides a lower bound on the ledger versions that the transaction can appear in as a result of this request.

Request example​

curl 'https://rpc.ankr.com/xrp_mainnet/YOUR_ANKR_API_KEY' \
-d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "submit",
      "params": [
          {
            "offline": false,
            "api_version": 2,
            "secret": "s████████████████████████████",
            "tx_json": {
                "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
                "DeliverMax": {
                    "currency": "USD",
                    "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
                    "value": "1"
                },
                "Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
                "TransactionType": "Payment"
            },
            "fee_mult_max": 1000
        }
      ]
  }'

submit_multisigned​

Sends a multi-signed transaction to the network.

The submit_multisigned command applies a multi-signed transaction and sends it to the network to be included in future ledgers.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON-RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • tx_json (object; required): Transaction in JSON format with an array of Signers. To be successful, the weights of the signatures must be equal or higher than the quorum of the SignerList.
    • fail_hard (boolean; optional): If true, and the transaction fails locally, do not retry or relay the transaction to other servers. The default is false.

Returns​

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

  • engine_result (string): Code indicating the preliminary result of the transaction, for example tesSUCCESS.
  • engine_result_code (integer): Numeric code indicating the preliminary result of the transaction, directly correlated to engine_result.
  • engine_result_message (string): Human-readable explanation of the preliminary transaction result.
  • tx_blob (string): The complete transaction in hex string format.
  • tx_json (object): The complete transaction in JSON format.

Request example​

curl 'https://rpc.ankr.com/xrp_mainnet/YOUR_ANKR_API_KEY' \
-d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "submit_multisigned",
      "params": [
          {
            "tx_json": {
                "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
                "Fee": "30000",
                "Flags": 262144,
                "LimitAmount": {
                    "currency": "USD",
                    "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
                    "value": "0"
                },
                "Sequence": 4,
                "Signers": [
                    {
                        "Signer": {
                            "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
                            "SigningPubKey": "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
                            "TxnSignature": "3045022100CC9C56DF51251CB04BB047E5F3B5EF01A0F4A8A549D7A20A7402BF54BA744064022061EF8EF1BCCBF144F480B32508B1D10FD4271831D5303F920DE41C64671CB5B7"
                        }
                    },
                    {
                        "Signer": {
                            "Account": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
                            "SigningPubKey": "03398A4EDAE8EE009A5879113EAA5BA15C7BB0F612A87F4103E793AC919BD1E3C1",
                            "TxnSignature": "3045022100FEE8D8FA2D06CE49E9124567DCA265A21A9F5465F4A9279F075E4CE27E4430DE022042D5305777DA1A7801446780308897699412E4EDF0E1AEFDF3C8A0532BDE4D08"
                        }
                    }
                ],
                "SigningPubKey": "",
                "TransactionType": "TrustSet",
                "hash": "81A477E2A362D171BB16BE17B4120D9F809A327FA00242ABCA867283BEA2F4F8"
            }
          }
      ]
  }'

transaction_entry​

Retrieves info on the transaction from a particular ledger version.

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

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON-RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • ledger_hash (string; optional): The unique hash of the ledger version to use. (See Specifying Ledgers.)
    • ledger_index (string or unsigned integer; optional): The ledger index of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying Ledgers.)
    • tx_hash (string; required): Unique hash of the transaction you are looking up.

Returns (API v2)​

  • close_time_iso (string): The ledger close time represented in ISO 8601 time format.
  • hash (string): The unique hash identifier of the transaction.
  • ledger_index (number — ledger index): The ledger index of the ledger version the transaction was found in; this is the same as the one from the request.
  • ledger_hash (string — hash; optional): The identifying hash of the ledger version the transaction was found in; this is the same as the one from the request.
  • meta (object): The transaction metadata, which shows the exact results of the transaction in detail.
  • tx_json (object): JSON representation of the Transaction object.

Returns (API v1)​

  • ledger_index (number — ledger index): The ledger index of the ledger version the transaction was found in; this is the same as the one from the request.
  • ledger_hash (string — hash; optional): The identifying hash of the ledger version the transaction was found in; this is the same as the one from the request.
  • metadata (object): The transaction metadata which shows the exact results of the transaction in detail.
  • tx_json (object): JSON representation of the Transaction object.

Request example​

curl 'https://rpc.ankr.com/xrp_mainnet/YOUR_ANKR_API_KEY' \
-d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "transaction_entry",
      "params": [
          {
            "tx_hash": "C53ECF838647FA5A4C780377025FEC7999AB4182590510CA461444B207AB74A9",
            "ledger_index": 56865245
          }
      ]
  }'

tx​

Retrieves info on the transaction from all the ledgers at hand.

The tx method retrieves information on a single transaction, by its identifying hash or its CTID.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON-RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • ctid (string; optional): The compact transaction identifier of the transaction to look up. Must use uppercase hexadecimal only. (Not supported in Clio v2.0 and earlier).
    • transaction (string; optional): The 256-bit hash of the transaction to look up, as hexadecimal.
    • binary (boolean; optional): If true, return transaction data and metadata as binary serialized to hexadecimal strings. If false, return transaction data and metadata as JSON. The default is false.
    • min_ledger (number; optional): Use this with max_ledger to specify a range of up to 1000 ledger indexes, starting with this ledger (inclusive). If the server cannot find the transaction, it confirms whether it was able to search all the ledgers in this range.
    • max_ledger (number; optional): Use this with min_ledger to specify a range of up to 1000 ledger indexes, ending with this ledger (inclusive). If the server cannot find the transaction, it confirms whether it was able to search all the ledgers in the requested range.

Returns (API v2)​

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

  • ctid (string): The transaction's compact transaction identifier. (Not supported in Clio v2.0 and earlier.)
  • date (number): The close time of the ledger in which the transaction was applied, in seconds since the Ripple Epoch.
  • hash (string): The unique identifying hash of the transaction.
  • inLedger (number; deprecated): Alias for ledger_index.
  • ledger_index (number): The ledger index of the ledger that includes this transaction.
  • meta (object — JSON mode): Transaction metadata, which describes the results of the transaction.
  • meta_blob (string — binary mode): Transaction metadata, which describes the results of the transaction, represented as a hex string.
  • tx_blob (string — binary mode): The transaction data represented as a hex string.
  • tx_json (object — JSON mode): The transaction data represented in JSON.
  • validated (boolean): If true, this data comes from a validated ledger version; if omitted or set to false, this data is not final.

Returns (API v1)​

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

  • ctid (string): The transaction's compact transaction identifier. (Not supported in Clio v2.0 and earlier.)
  • date (number): The close time of the ledger in which the transaction was applied, in seconds since the Ripple Epoch.
  • hash (string): The unique identifying hash of the transaction.
  • inLedger (number; deprecated): Alias for ledger_index.
  • ledger_index (number): The ledger index of the ledger that includes this transaction.
  • meta (object (JSON) or string (binary)): Transaction metadata, which describes the results of the transaction.
  • tx (string — binary mode): The transaction data represented as a hex string.
  • validated (boolean): If true, this data comes from a validated ledger version; if omitted or set to false, this data is not final.
  • (various) (various): Other fields from the Transaction object.

Request example (CTID)​

curl 'https://rpc.ankr.com/xrp_mainnet/YOUR_ANKR_API_KEY' \
-d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "tx",
      "params": [
           {
                "ctid": "C005523E00000000",
                "binary": false,
                "api_version": 2
           }
      ]
  }'

Request example (Hash)​

curl 'https://rpc.ankr.com/xrp_mainnet/YOUR_ANKR_API_KEY' \
-d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "tx",
      "params": [
           {
                "transaction": "C53ECF838647FA5A4C780377025FEC7999AB4182590510CA461444B207AB74A9",
                "binary": false,
                "api_version": 2
           }
      ]
  }'

tx_history​

Retrieves info on all recent transactions.

The tx_history method retrieves some of the most recent transactions made.

Caution: This method is removed in API v2.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON-RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • start (unsigned integer; required): Number of transactions to skip over.

Returns​

  • txs (array): Array of transaction objects.

Request example​

curl 'https://rpc.ankr.com/xrp_mainnet/YOUR_ANKR_API_KEY' \
-d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "tx_history",
      "params": [
           {
                "start": 0
           }
      ]
  }'

Response example​

{
    "result": {
        "index": 0,
        "status": "success",
        "txs": [
            {
                "Account": "rUPWQfH9SoNnbYDMjq6cMoawQ4x2or6nGA",
                "Amount": "100000000000000",
                "DeliverMax": "100000000000000",
                "Destination": "rUPWQfH9SoNnbYDMjq6cMoawQ4x2or6nGA",
                "Fee": "10",
                "Flags": 131072,
                "LastLedgerSequence": 100581760,
                "SendMax": {
                    "currency": "USD",
                    "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
                    "value": "1000000000000000"
                },
                "Sequence": 0,
                "SigningPubKey": "EDE91272F3124216316CC04C798E7AE3A7395924FAF50533B01BCC0CE5CE71B122",
                "TicketSequence": 100371575,
                "TransactionType": "Payment",
                "TxnSignature": "A338BAEE8DCFA84DC5F6F8ABD81BC1F9D406F24C248A19465A83E7C9564894538A9F83C654DEFD748F7507FF8E134AC0F108A430BD2E21C1CF45F030C9678705",
                "hash": "45A8E1470A18F55FF9559700ABA643FE25E7E957CDB2D35F84B6B746A22C96FF",
                "inLedger": 100581753,
                "ledger_index": 100581753
            }
        ]
    }
}

Path and Order Book Methods:

Paths define a way for payments to flow through intermediary steps on their way from sender to receiver. Paths enable cross-currency payments by connecting sender and receiver through order books. Use these methods to work with paths and other books.

amm_info​

Retrieves info on the Automated Market Maker (AMM) instance.

The amm_info method gets information about an Automated Market Maker (AMM) instance.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON-RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • account (string — address; optional): Show only LP Tokens held by this liquidity provider.
    • amm_account (string — address; optional): The address of the AMM's special AccountRoot. (This is the issuer of the AMM's LP Tokens.)
    • asset (object; optional): One of the assets of the AMM to look up, as an object with currency and issuer fields (omit issuer for XRP), like currency amounts.
    • asset2 (object; optional): The other of the assets of the AMM, as an object with currency and issuer fields (omit issuer for XRP), like currency amounts.

Note: You must specify either amm_account or both asset and asset2.

Returns​

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

  • amm (object): An AMM Description Object for the requested asset pair.
  • ledger_current_index (ledger index; optional): Omitted if ledger_index is provided instead. The ledger index of the current in-progress ledger, which was used when retrieving this information.
  • ledger_hash (hash; optional): Omitted if ledger_current_index is provided instead. The identifying hash of the ledger version that was used when retrieving this data.
  • ledger_index (ledger index; optional): Omitted if ledger_current_index is provided instead. The ledger index of the ledger version used when retrieving this information.
  • validated (boolean): If true, the ledger used for this request is validated and these results are final; if omitted or set to false, the data is pending and may change.

AMM Description Object​

The amm field is an object describing the current status of an Automated Market Maker (AMM) in the ledger, and contains the following fields:

  • account (string): The Address of the AMM Account.
  • amount (currency amount): The total amount of one asset in the AMM's pool. (Note: This could be asset or asset2 from the request.)
  • amount2 (currency amount): The total amount of the other asset in the AMM's pool. (Note: This could be asset or asset2 from the request.)
  • asset_frozen (boolean; omitted for XRP): If true, the amount currency is currently frozen.
  • asset2_frozen (boolean; omitted for XRP): If true, the amount2 currency is currently frozen.
  • auction_slot (object; optional): An Auction Slot Object describing the current auction slot holder, if there is one.
  • lp_token (currency amount): The total amount of this AMM's LP Tokens outstanding. If the request specified a liquidity provider in the account field, instead, this is the amount of this AMM's LP Tokens held by that liquidity provider.
  • trading_fee (number): The AMM's current trading fee, in units of 1/100,000; a value of 1 is equivalent to a 0.001% fee.
  • vote_slots (array; optional): The current votes for the AMM's trading fee, as Vote Slot Objects.

Auction Slot Object​

The auction_slot field of the amm object describes the current auction slot holder of the AMM, and contains the following fields:

  • account (string): The Address of the account that owns the auction slot.
  • auth_accounts (array): A list of additional accounts that the auction slot holder has designated as being eligible of the discounted trading fee. Each member of this array is an object with one field, account, containing the address of the designated account.
  • discounted_fee (number): The discounted trading fee that applies to the auction slot holder, and any eligible accounts, when trading against this AMM. This is 1/10 of the AMM's normal trading fee.
  • expiration (string): The ISO 8601 UTC timestamp after which this auction slot expires. After expired, the auction slot does not apply (but the data can remain in the ledger until another transaction replaces it or cleans it up).
  • price (currency amount): The amount, in LP Tokens, that the auction slot holder paid to win the auction slot. This affects the price to outbid the current slot holder.
  • time_interval (number): The current 72-minute time interval this auction slot is in, from 0 to 19. The auction slot expires after 24 hours (20 intervals of 72 minutes) and affects the cost to outbid the current holder and how much the current holder is refunded if someone outbids them.

Vote Slot Objects​

Each entry in the vote_slots array represents one liquidity provider's vote to set the trading fee, and contains the following fields:

  • account (string): The Address of this liquidity provider.
  • trading_fee (number): The trading fee this liquidity provider voted for, in units of 1/100,000.
  • vote_weight (number): How much this liquidity provider's vote counts towards the final trading fee. This is proportional to how much of the AMM's LP Tokens this liquidity provider holds. The value is equal to 100,000 times the number of this LP Tokens this liquidity provider holds, divided by the total number of LP Tokens outstanding. For example, a value of 1000 means that the liquidity provider holds 1% of this AMM's LP Tokens.

Request example​

curl 'https://rpc.ankr.com/xrp_mainnet/YOUR_ANKR_API_KEY' \
-d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "amm_info",
      "params": [
           {
              "asset": {
                "currency": "XRP"
              },
              "asset2": {
                "currency": "TST",
                "issuer": "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd"
              }
           }
      ]
  }'

Response example​

{
  "result": {
    "amm": {
      "account": "rp9E3FN3gNmvePGhYnf414T2TkUuoxu8vM",
      "amount": "296890496",
      "amount2": {
        "currency": "TST",
        "issuer": "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd",
        "value": "25.81656470648473"
      },
      "asset2_frozen": false,
      "auction_slot": {
        "account": "rJVUeRqDFNs2xqA7ncVE6ZoAhPUoaJJSQm",
        "auth_accounts": [
          {
            "account": "r3f2WpQMsAd8k4Zoijv2PZ78EYFJ2EdvgV"
          },
          {
            "account": "rnW8FAPgpQgA6VoESnVrUVJHBdq9QAtRZs"
          }
        ],
        "discounted_fee": 0,
        "expiration": "2023-Jan-26 00:28:40.000000000 UTC",
        "price": {
          "currency": "039C99CD9AB0B70B32ECDA51EAAE471625608EA2",
          "issuer": "rp9E3FN3gNmvePGhYnf414T2TkUuoxu8vM",
          "value": "0"
        },
        "time_interval": 0
      },
      "lp_token": {
        "currency": "039C99CD9AB0B70B32ECDA51EAAE471625608EA2",
        "issuer": "rp9E3FN3gNmvePGhYnf414T2TkUuoxu8vM",
        "value": "87533.41976112682"
      },
      "trading_fee": 600,
      "vote_slots": [
        {
          "account": "rJVUeRqDFNs2xqA7ncVE6ZoAhPUoaJJSQm",
          "trading_fee": 600,
          "vote_weight": 9684
        }
      ]
    },
    "ledger_current_index": 316745,
    "status": "success",
    "validated": false
  }
}

book_changes​

Retrieves information on order book changes.

The book_changes method reports information about changes to the order books in the decentralized exchange (DEX) compared with the previous ledger version. This may be useful for building "candlestick" charts.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON-RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

Returns​

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

  • changes (array): List of Book Update Objects, containing one entry for each order book that was updated in this ledger version. The array is empty if no order books were updated.
  • ledger_hash (hash): The identifying hash of the ledger version that was used when retrieving this data.
  • ledger_index (ledger index): The ledger index of the ledger version that was used when retrieving this data.
  • ledger_time (number): The official close time of the ledger that was used when retrieving this data, in seconds since the Ripple Epoch.
  • type (string): The string bookChanges, which indicates that this is an order book update message.
  • validated (boolean; optional): If true, the information comes from a validated ledger version.

Book Update Objects​

A Book Update Object represents the changes to a single order book in a single ledger version, and contains the following fields:

  • currency_a (string): An identifier for the first of the two currencies in the order book. For XRP, this is the string XRP_drops. For tokens, this is formatted as the address of the issuer in base58, followed by a forward-slash (/), followed by the Currency Code for the token, which can be a 3-character standard code or a 20-character hexadecimal code.
  • currency_b (string): An identifier for the second of two currencies in the order book. This is in the same format as currency_a, except currency_b can never be XRP.
  • volume_a (string — number): The total amount, or volume, of the first currency (that is, currency_a) that moved as a result of trades through this order book in this ledger.
  • volume_b (string — number): The volume of the second currency (that is, currency_b) that moved as a result of trades through this order book in this ledger.
  • high (string — number): The highest exchange rate among all offers matched in this ledger, as a ratio of the first currency to the second currency. (In other words, currency_a : currency_b.)
  • low (string — number): The lowest exchange rate among all offers matched in this ledger, as a ratio of the first currency to the second currency.
  • open (string — number): The exchange rate at the top of this order book before processing the transactions in this ledger, as a ratio of the first currency to the second currency.
  • close (string — number): The exchange rate at the top of this order book after processing the transactions in this ledger, as a ratio of the first currency to the second currency.

For XRP-token order books, XRP is always currency_a. For token-token order books, the currencies are sorted alphabetically by the issuer and then currency code.

Exchange rates involving XRP are always calculated using drops of XRP. For example, if the rate from XRP to FOO is 1.0 XRP to 1 FOO, the rate reported by the API is 1000000 (1 million drops of XRP per 1 FOO).

Request example​

curl 'https://rpc.ankr.com/xrp_mainnet/YOUR_ANKR_API_KEY' \
-d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "book_changes",
      "params": [
           {
              "ledger_index": 88530953
           }
      ]
  }'

Response example​

{
    "result" : {
       "changes" : [
          {
             "close" : "277777.7777777778",
             "currency_a" : "XRP_drops",
             "currency_b" : "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/CNY",
             "high" : "277777.7777777778",
             "low" : "277777.7777777778",
             "open" : "277777.7777777778",
             "volume_a" : "44082741",
             "volume_b" : "158.6978676"
          },
          {
             "close" : "202999.9948135647",
             "currency_a" : "XRP_drops",
             "currency_b" : "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/XLM",
             "high" : "202999.9948135647",
             "low" : "202999.9948135647",
             "open" : "202999.9948135647",
             "volume_a" : "44191586",
             "volume_b" : "217.6925474337355"
          },
          {
             "close" : "80475.34586323083",
             "currency_a" : "XRP_drops",
             "currency_b" : "rf5YPb9y9P3fTjhxNaZqmrwaj5ar8PG1gM/47414C4100000000000000000000000000000000",
             "high" : "80475.34586323083",
             "low" : "80475.34586323083",
             "open" : "80475.34586323083",
             "volume_a" : "100000000",
             "volume_b" : "1242.61659179386"
          },
          {
             "close" : "231974.7481608686",
             "currency_a" : "XRP_drops",
             "currency_b" : "rsoLo2S1kiGeCcn6hCUXVrCpGMWLrRrLZz/534F4C4F00000000000000000000000000000000",
             "high" : "231974.7481608686",
             "low" : "231974.7481608686",
             "open" : "231974.7481608686",
             "volume_a" : "33734",
             "volume_b" : "0.1454210006367"
          },
          {
             "close" : "7.290000000001503",
             "currency_a" : "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/CNY",
             "currency_b" : "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/USD",
             "high" : "7.290000000001503",
             "low" : "7.290000000001503",
             "open" : "7.290000000001503",
             "volume_a" : "158.6978670792",
             "volume_b" : "21.76925474337"
          },
          {
             "close" : "0.1",
             "currency_a" : "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/USD",
             "currency_b" : "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/XLM",
             "high" : "0.1",
             "low" : "0.1",
             "open" : "0.1",
             "volume_a" : "21.76925474337355",
             "volume_b" : "217.6925474337355"
          }
       ],
       "ledger_hash" : "7AB08A2415C10E07201521F3260F77ADFF4902A528EA66378E259A07767A24B9",
       "ledger_index" : 88530953,
       "ledger_time" : 771100891,
       "status" : "success",
       "type" : "bookChanges"
    }
}