XRP — Methods, submit, transaction, tx, amm, book (1/3)

API reference for XRP. All methods ->

Part 1 of 3: 1 · 2 · 3

`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"
            }
          }
      ]
  }'

submit​

Submit-only mode​

Parameters​

Returns​

Request example​

Response example​

Sign-and-Submit mode​

Parameters​

Returns​

Request example​

submit_multisigned​

Parameters​

Returns​

Request example​

`submit`

Submit-only mode

Parameters

Returns

Request example

Response example

Sign-and-Submit mode

Parameters

Returns

Request example

`submit_multisigned`

Parameters

Returns

Request example