From 65d0020ed4e91922ef3f6a712449ad27a697a356 Mon Sep 17 00:00:00 2001 From: Rome Reginelli Date: Tue, 5 Sep 2017 17:43:03 -0700 Subject: [PATCH] Reorg: remove generated HTML files, move dactyl-config to op level (#270) * Reorg: remove generated HTML files, move dactyl-config to op level * Update CI for reorg --- .gitignore | 1 + circle.yml | 4 +- concept-accounts.html | 331 - concept-amendments.html | 687 - concept-consensus.html | 300 - concept-fee-voting.html | 221 - concept-fees.html | 197 - concept-freeze.html | 884 - ...ept-issuing-and-operational-addresses.html | 213 - concept-noripple.html | 215 - concept-partial-payments.html | 293 - concept-paths.html | 304 - concept-reaching-consensus.html | 247 - concept-reserves.html | 211 - concept-stand-alone-mode.html | 249 - concept-transaction-cost.html | 363 - concept-transfer-fees.html | 210 - tool/dactyl-config.yml => dactyl-config.yml | 14 +- data-api-v2-tool.html | 184 - gb-2015-05.html | 197 - gb-2015-06.html | 182 - index.html | 224 - reference-data-api.html | 8471 ---------- reference-ledger-format.html | 1454 -- reference-rippleapi.html | 6134 ------- reference-rippled.html | 13826 ---------------- reference-transaction-format.html | 2673 --- ripple-api-tool.html | 211 - tool-jsonrpc.html | 184 - tutorial-escrow.html | 972 -- tutorial-gateway-guide.html | 927 -- tutorial-listing-xrp.html | 776 - tutorial-multisign.html | 727 - tutorial-paychan.html | 750 - tutorial-reliable-transaction-submission.html | 582 - tutorial-rippleapi-beginners-guide.html | 526 - tutorial-rippled-setup.html | 498 - 37 files changed, 9 insertions(+), 44433 deletions(-) delete mode 100644 concept-accounts.html delete mode 100644 concept-amendments.html delete mode 100644 concept-consensus.html delete mode 100644 concept-fee-voting.html delete mode 100644 concept-fees.html delete mode 100644 concept-freeze.html delete mode 100644 concept-issuing-and-operational-addresses.html delete mode 100644 concept-noripple.html delete mode 100644 concept-partial-payments.html delete mode 100644 concept-paths.html delete mode 100644 concept-reaching-consensus.html delete mode 100644 concept-reserves.html delete mode 100644 concept-stand-alone-mode.html delete mode 100644 concept-transaction-cost.html delete mode 100644 concept-transfer-fees.html rename tool/dactyl-config.yml => dactyl-config.yml (98%) delete mode 100644 data-api-v2-tool.html delete mode 100644 gb-2015-05.html delete mode 100644 gb-2015-06.html delete mode 100644 index.html delete mode 100644 reference-data-api.html delete mode 100644 reference-ledger-format.html delete mode 100644 reference-rippleapi.html delete mode 100644 reference-rippled.html delete mode 100644 reference-transaction-format.html delete mode 100644 ripple-api-tool.html delete mode 100644 tool-jsonrpc.html delete mode 100644 tutorial-escrow.html delete mode 100644 tutorial-gateway-guide.html delete mode 100644 tutorial-listing-xrp.html delete mode 100644 tutorial-multisign.html delete mode 100644 tutorial-paychan.html delete mode 100644 tutorial-reliable-transaction-submission.html delete mode 100644 tutorial-rippleapi-beginners-guide.html delete mode 100644 tutorial-rippled-setup.html diff --git a/.gitignore b/.gitignore index 12736e11ab..cd1690cd66 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ .DS_Store content/code_samples/*/node_modules/ __pycache__ +out/ diff --git a/circle.yml b/circle.yml index b4798dacbd..c6cfd4a3e4 100644 --- a/circle.yml +++ b/circle.yml @@ -1,5 +1,5 @@ general: - build_dir: tool/ + build_dir: ./ dependencies: pre: - pyenv global 3.4.0 @@ -7,5 +7,5 @@ dependencies: - pip3 install dactyl test: override: - - dactyl_build + - dactyl_build -s - dactyl_link_checker diff --git a/concept-accounts.html b/concept-accounts.html deleted file mode 100644 index 9395fd5338..0000000000 --- a/concept-accounts.html +++ /dev/null @@ -1,331 +0,0 @@ - - - - - - - - Accounts - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

XRP Ledger Accounts

-

An "Account" in the XRP Ledger represents a holder of XRP and a sender of transactions. The core elements of an account are:

-
    -
  • An identifying address, such as rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn
    • -
  • An XRP balance. Some of this XRP is set aside for the Reserve.
    • -
  • A sequence number, starting at 1 and increasing with each transaction sent from this account. No transaction can be included in a ledger unless the transaction's sequence number matches its sender's next sequence number.
    • -
  • A history of transactions that affected this account and its balances.
    • -
  • One or more ways to authorize transactions, possibly including:
      -
    • A master key pair intrinsic to the account. (This can be disabled but not changed.)
      • -
    • A "regular" key pair that can be rotated.
      • -
    • A signer list for multi-signing. (Stored separately from the account's core data.)
      • -
    -
    • -
-

In the ledger's data tree, an account's core data is stored in the AccountRoot ledger node type. An account can also be the owner (or partial owner) of several other types of data.

-

Tip: An "Account" in the XRP Ledger is somewhere between the financial usage (like "bank account") and the computing usage (like "UNIX account"). Non-XRP currencies and assets aren't stored in an XRP Ledger Account itself; each such asset is stored in an accounting relationship called a "Trust Line" that connects two parties.

-

Addresses

-

Accounts in the XRP Ledger are identified by a base58 XRP Ledger Address. The address is derived from the account's master public key, which is in turn derived from a secret key. An address is represented as a string in JSON and has the following characteristics:

-
    -
  • Between 25 and 35 characters in length
    • -
  • Starts with the character r
    • -
  • Uses alphanumeric characters, excluding the number "0" capital letter "O", capital letter "I", and lowercase letter "l"
    • -
  • Case-sensitive
    • -
  • Includes a 4-byte checksum so that the probability of generating a valid address from random characters is approximately 1 in 2^32
    • -
-

Any valid address can become an account in the XRP Ledger by receiving a Payment of XRP, as long as the amount of XRP delivered is greater than or equal to the account reserve. This is called funding the account. You can also use an address that has not been funded to represent a regular key or a member of a signer list. Only a funded account can be the sender of a transaction.

-

Creating a valid address is a strictly mathematical task starting with a key pair. You can generate a key pair and calculate its address entirely offline without communicating to the XRP Ledger or any other party. The conversion from a public key to an address involves a one-way hash function, so it is possible to confirm that a public key matches an address but it is impossible to derive the public key from the address alone. (This is part of the reason why signed transactions include the public key and the address of the sender.)

-

For more technical details of how to calculate an XRP Ledger address, see Address Encoding.

-

Special Addresses

-

Some addresses have special meaning, or historical uses, in the XRP Ledger. In many cases, these are "black hole" addresses, meaning the address is not derived from a known secret key. Since it is effectively impossible to guess a secret key from only an address, any XRP possessed by black hole addresses is lost forever.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
AddressNameMeaningBlack Hole?
rrrrrrrrrrrrrrrrrrrrrhoLvTpACCOUNT_ZEROAn address that is the base58 encoding of the value 0. In peer-to-peer communications, rippled uses this address as the issuer for XRP.Yes
rrrrrrrrrrrrrrrrrrrrBZbvjiACCOUNT_ONEAn address that is the base58 encoding of the value 1. In the ledger, RippleState entries use this address as a placeholder for the issuer of a trust line balance.Yes
rHb9CJAWyB4rj91VRWn96DkukG4bwdtyThThe genesis accountWhen rippled starts a new genesis ledger from scratch (for example, in stand-alone mode), this account holds all the XRP. This address is generated from the seed value "masterpassphrase" which is hard-coded.No
rrrrrrrrrrrrrrrrrNAMEtxvNvQRipple Name reservation black-holeIn the past, Ripple asked users to send XRP to this account to reserve Ripple Names.Yes
rrrrrrrrrrrrrrrrrrrn5RM1rHdNaN AddressPrevious versions of ripple-lib generated this address when base58 encoding the value NaN.Yes
-

Permanence of Accounts

-

Once created, an account exists in the XRP Ledger's data tree forever. This is because the current sequence number for a transaction must be tracked forever, so that old transactions cannot be processed a second time.

-

Unlike Bitcoin and many other crypto-currencies, each new version of the XRP Ledger's public ledger chain contains the full state of the ledger, which increases in size with each new account. For that reason, Ripple discourages creating new accounts unless entirely necessary. Institutions who send and receive value on behalf of many users can use Source Tags and Destination Tags to distinguish payments from and to their customers while only using one (or a handful) of accounts in the XRP Ledger.

-

Transaction History

-

In the XRP Ledger, transaction history is tracked by a "thread" of transactions linked by a transaction's identifying hash and the ledger index. The AccountRoot ledger node has the identifying hash and ledger of the transaction that most recently modified it; the metadata of that transaction includes the previous state of the AccountRoot node, so it is possible to iterate through the history of a single account this way. This transaction history includes any transactions that modify the AccountRoot node directly, including:

-
    -
  • Transactions sent by the account, because they modify the account's Sequence number. These transactions also modify the account's XRP balance because of the transaction cost.
    • -
  • Transactions that modified the account's XRP balance, including incoming Payment transactions and other types of transactions such as PaymentChannelClaim and EscrowFinish.
    • -
-

The conceptual transaction history of an account also includes transactions that modified the account's owned objects and non-XRP balances. These objects are separate ledger nodes, each with their own thread of transactions that affected them. If you have an account's full ledger history, you can follow it forward to find the ledger node objects created or modified by it. A "complete" transaction history includes the history of objects owned by a transaction, such as:

-
    -
  • RippleState objects (Trust Lines) connected to the account.
    • -
  • DirectoryNode objects, especially the owner directory tracking the account's owned objects.
    • -
  • Offer objects, representing the account's outstanding currency-exchange orders in the decentralized exchange
    • -
  • PayChannel objects, representing asynchronous payment channels to and from the account
    • -
  • Escrow objects, representing held payments to or from the account that are locked by time or a crypto-condition.
    • -
  • SignerList objects, representing lists of addresses that can authorize transactions for the account by multi-signing.
    • -
-

For more information on each of these objects, see the Ledger Format Reference.

-

Address Encoding

-

Tip: These technical details are only relevant for people building low-level library software for XRP Ledger compatibility!

-

[Source]

-

XRP Ledger addresses are encoded using base58 with the Ripple dictionary: rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz. Since the XRP Ledger encodes several types of keys with base58, it prefixes the encoded data with a one-byte "type prefix" (also called a "version prefix") to distinguish them. The type prefix causes addresses to usually start with different letters in base58 format.

-

The following diagram shows the relationship between keys and addresses:

-

Passphrase → Secret Key → Public Key + Type Prefix → Account ID + Checksum → Address

-

The formula for calculating an XRP Ledger address is as follows. For the complete example code, see encode_address.js.

-
    -
  1. -

    Import required algorithms: SHA-256, RIPEMD160, and base58. Set the dictionary for base58.

    -
    'use strict';
-const assert = require('assert');
-const crypto = require('crypto');
-const R_B58_DICT = 'rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz';
-const base58 = require('base-x')(R_B58_DICT);
-
-assert(crypto.getHashes().includes('sha256'));
-assert(crypto.getHashes().includes('ripemd160'));
-
    -
    2. -
  2. -

    Start with a 33-byte ECDSA secp256k1 public key, or a 32-byte Ed25119 public key. For Ed25519 keys, prefix the key with the byte 0xED.

    -
    const pubkey_hex =
-  'ED9434799226374926EDA3B54B1B461B4ABF7237962EAE18528FEA67595397FA32';
-const pubkey = Buffer.from(pubkey_hex, 'hex');
-assert(pubkey.length == 33);
-
    -
    3. -
  3. -

    Calculate the RIPEMD160 hash of the SHA-256 hash of the public key. This value is the "Account ID".

    -
    const pubkey_inner_hash = crypto.createHash('sha256').update(pubkey);
-const pubkey_outer_hash = crypto.createHash('ripemd160');
-pubkey_outer_hash.update(pubkey_inner_hash.digest());
-const account_id = pubkey_outer_hash.digest();
-
    -
    4. -
  4. -

    Calculate the SHA-256 hash of the SHA-256 hash of the Account ID; take the first 4 bytes. This value is the "checksum".

    -
    const address_type_prefix = Buffer.from([0x00]);
-const payload = Buffer.concat([address_type_prefix, account_id]);
-const chksum_hash1 = crypto.createHash('sha256').update(payload).digest();
-const chksum_hash2 = crypto.createHash('sha256').update(chksum_hash1).digest();
-const checksum =  chksum_hash2.slice(0,4);
-
    -
    5. -
  5. -

    Concatenate the payload and the checksum. Calculate the base58 value of the concatenated buffer. The result is the address.

    -
    const dataToEncode = Buffer.concat([payload, checksum]);
-const address = base58.encode(dataToEncode);
-console.log(address);
-// rDTXLQ7ZKZVKz33zJbHjgVShjsBnqMBhmN
-
    -
    6. -
- -
-
-
- - - - \ No newline at end of file diff --git a/concept-amendments.html b/concept-amendments.html deleted file mode 100644 index 6e49e05d40..0000000000 --- a/concept-amendments.html +++ /dev/null @@ -1,687 +0,0 @@ - - - - - - - - Amendments - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

Amendments

-

Introduced in: rippled 0.31.0

-

The Amendments system provides a means of introducing new features to the decentralized XRP Ledger network without causing disruptions. The amendments system works by utilizing the core consensus process of the network to approve any changes by showing continuous support before those changes go into effect. An amendment normally requires 80% support for two weeks before it can apply.

-

When an Amendment has been enabled, it applies permanently to all ledger versions after the one that included it. You cannot disable an Amendment, unless you introduce a new Amendment to do so.

-

Background

-

Any changes to transaction processing could cause servers to build a different ledger with the same set of transactions. If some validators (rippled servers participating in consensus) have upgraded to a new version of the software while other validators use the old version, this could cause anything from minor inconveniences to full outages. In the minor case, a minority of servers spend more time and bandwidth fetching the actual consensus ledger because they cannot build it using the transaction processing rules they already know. In the worst case, the consensus process might be unable to validate new ledger versions because servers with different rules could not reach a consensus on the exact ledger to build.

-

Amendments solve this problem, so that new features can be enabled only when enough validators support those features.

-

Users and businesses who rely on the XRP Ledger can also use Amendments to provide advance notice of changes in transaction processing that might affect their business. However, API changes that do not impact transaction processing or the consensus process do not need Amendments.

-

About Amendments

-

An amendment is a fully-functional feature or change, waiting to be enabled by the peer-to-peer network as a part of the consensus process. A rippled server that wants to use an amendment has code for two modes: without the amendment (old behavior) and with the amendment (new behavior).

-

Every amendment has a unique identifying hex value and a short name. The short name is for human use, and is not used in the amendment process. Two servers can support the same amendment ID while using different names to describe it. An amendment's name is not guaranteed to be unique.

-

By convention, Ripple's developers use the SHA-512Half hash of the amendment name as the amendment ID.

-

See also: Known Amendments

-

Amendment Process

-

Every 256th ledger is called a "flag" ledger. The process of approving an amendment starts in the ledger version immediately before the flag ledger. When rippled validator servers send validation messages for that ledger, those servers also submit votes in favor of specific amendments. If a validator does not vote in favor of an amendment, that is the same as voting against the amendment. (Fee Voting also occurs around flag ledgers.)

-

The flag ledger itself has no special contents. However, during that time, the servers look at the votes of the validators they trust, and decide whether to insert an EnableAmendment pseudo-transaction into the following ledger. The flags of an EnableAmendment pseudo-transaction show what the server thinks happened:

-
    -
  • The tfGotMajority flag means that support for the amendment has increased to at least 80% of trusted validators.
    • -
  • The tfLostMajority flag means that support for the amendment has decreased to less than 80% of trusted validators.
    • -
  • An EnableAmendment pseudo-transaction with no flags means that support for the amendment has been enabled. (The change in transaction processing applies to every ledger after this one.)
    • -
-

A server only inserts the pseudo-transaction to enable an amendment if all of the following conditions are met:

-
    -
  • The amendment has not already been enabled.
    • -
  • A previous ledger includes an EnableAmendment pseudo-transaction for this amendment with the tfGotMajority flag enabled.
    • -
  • The previous ledger in question is an ancestor of the current ledger.
    • -
  • The previous ledger in question has a close time that is at least two weeks before the close time of the latest flag ledger.
    • -
  • There are no EnableAmendment pseudo-transactions for this amendment with the tfLostMajority flag enabled in the consensus ledgers between the tfGotMajority pseudo-transaction and the current ledger.
    • -
-

Theoretically, a tfLostMajority EnableAmendment pseudo-transaction could be included in the same ledger as the pseudo-transaction to enable an amendment. In this case, the pseudo-transaction with the tfLostMajority pseudo-transaction has no effect.

-

Amendment Voting

-

Each version of rippled is compiled with a list of known amendments and the code to implement those amendments. By default, rippled supports known amendments and opposes unknown amendments. Operators of rippled validators can configure their servers to explicitly support or oppose certain amendments, even if those amendments are not known to their rippled versions.

-

To become enabled, an amendment must be supported by at least 80% of trusted validators continuously for two weeks. If support for an amendment goes below 80% of trusted validators, the amendment is temporarily rejected. The two week period starts over if the amendment regains support of at least 80% of trusted validators. (This can occur if validators vote differently, or if there is a change in which validators are trusted.) An amendment can gain and lose a majority an unlimited number of times before it becomes permanently enabled. An amendment cannot be permanently rejected, but it becomes very unlikely for an amendment to become enabled if new versions of rippled do not have the amendment in their known amendments list.

-

As with all aspects of the consensus process, amendment votes are only taken into account by servers that trust the validators sending those votes. At this time, Ripple (the company) recommends only trusting the 5 default validators that Ripple operates. For now, trusting only those validators is enough to coordinate with Ripple on releasing new features.

-

Configuring Amendment Voting

-

You can temporarily configure an amendment using the feature command. To make a persistent change to your server's support for an amendment, change your server's rippled.cfg file.

-

Use the [veto_amendments] stanza to list amendments you do not want the server to vote for. Each line should contain one amendment's unique ID, optionally followed by the short name for the amendment. For example:

-
[veto_amendments]
-C1B8D934087225F509BEB5A8EC24447854713EE447D277F69545ABFA0E0FD490 Tickets
-DA1BD556B42D85EA9C84066D028D355B52416734D3283F85E216EA5DA6DB7E13 SusPay
-
-

Use the [amendments] stanza to list amendments you want to vote for. (Even if you do not list them here, by default a server votes for all the amendments it knows how to apply.) Each line should contain one amendment's unique ID, optionally followed by the short name for the amendment. For example:

-
[amendments]
-4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373 MultiSign
-42426C4D4F1009EE67080A9B7965B44656D7714D104A72F9B4369F97ABF044EE FeeEscalation
-
-

Amendment Blocked

-

When an amendment gets enabled for the network after the voting process, servers running earlier versions of rippled that do not know about the amendment become "amendment blocked" because they no longer understand the rules of the network. Servers that are amendment blocked:

-
    -
  • Cannot determine the validity of a ledger
    • -
  • Cannot submit or process transactions
    • -
  • Do not participate in the consensus process
    • -
  • Do not vote on future amendments
    • -
-

Becoming amendment blocked is a security feature to protect backend applications. Rather than guessing and maybe misinterpreting a ledger after new rules have applied, rippled reports that it does not know the state of the ledger because it does not know how the amendment works.

-

The amendments that a rippled server is configured to vote for or against have no impact on whether the server becomes amendment blocked. A rippled server always follows the set of amendments enabled by the rest of the network, to the extent possible. A server only becomes amendment blocked if the enabled amendment is not included in the amendment definitions compiled into the server's source code -- in other words, if the amendment is newer than the server.

-

If your server is amendment blocked, you must upgrade to a new version to sync with the network.

-

Testing Amendments

-

If you want to see how rippled behaves with an amendment enabled, before that amendment gets enabled on the production network, you can run use rippled's configuration file to forcibly enable a feature. This is intended for development purposes only.

-

Because other members of the consensus network probably do not have the feature enabled, you should not use this feature while connecting to the production network. While testing with features forcibly enabled, you should run rippled in Stand-Alone Mode.

-

To forcibly enable a feature, add a [features] stanza to your rippled.cfg file. In this stanza, add the short names of the features to enable, one per line. For example:

-
[features]
-MultiSign
-TrustSetAuth
-
-

Known Amendments

-

[Source]

-

The following is a comprehensive list of all known amendments and their status on the production XRP Ledger:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameIntroducedStatus
FlowCrossv0.70.0Planned: TBD
SHAMapV2v0.33.0Planned: TBD
OwnerPaysFeev0.33.0Planned: TBD
TicketsN/APlanned: TBD
EnforceInvariantsv0.70.0Enabled: 2017-07-07
fix1373v0.70.0Enabled: 2017-07-07
fix1368v0.60.0Enabled: 2017-03-31
PayChanv0.33.0Enabled: 2017-03-31
Escrowv0.60.0Enabled: 2017-03-31
TickSizev0.50.0Enabled: 2017-02-21
SusPayv0.31.0Vetoed: Removed in v0.60.0
CryptoConditionsv0.50.0Enabled: 2017-01-03
Flowv0.33.0Enabled: 2016-10-21
FlowV2v0.32.1Vetoed: Removed in v0.33.0
TrustSetAuthv0.30.0Enabled: 2016-07-19
MultiSignv0.31.0Enabled: 2016-06-27
FeeEscalationv0.31.0Enabled: 2016-05-19
-

Note: In many cases, an incomplete version of the code for an amendment is present in previous versions of the software. The "Introduced" version in the table above is the first stable version.

-

CryptoConditions

- - - - - - - - - - - - - -
Amendment IDStatus
1562511F573A19AE9BD103B5D6B9E01B3B46805AEC5D3C4805C902B514399146Enabled
-

Although this amendment is enabled, it has no effect unless the SusPay amendment is also enabled. Ripple does not expect SusPay to become enabled. Instead, Ripple plans to incorporate crypto-conditions in the Escrow amendment.

-

EnforceInvariants

- - - - - - - - - - - - - -
Amendment IDStatus
DC9CA96AEA1DCF83E527D1AFC916EFAF5D27388ECA4060A88817C1238CAEE0BFEnabled
-

Adds sanity checks to transaction processing to ensure that certain conditions are always met. This provides an extra, independent layer of protection against bugs in transaction processing that could otherwise cause exploits and vulnerabilities in the XRP Ledger. Ripple expects to add more invariant checks in future versions of rippled without additional amendments.

-

Introduces two new transaction error codes, tecINVARIANT_FAILED and tefINVARIANT_FAILED. Changes transaction processing to add the new checks.

-

Examples of invariant checks:

- -

Escrow

- - - - - - - - - - - - - -
Amendment IDStatus
07D43DCE529B15A10827E5E04943B496762F9A88E3268269D69C44BE49E21104Enabled
-

Replaces the SusPay and CryptoConditions amendments.

-

Provides "suspended payments" for XRP for escrow within the XRP Ledger, including support for Interledger Protocol Crypto-Conditions. Creates a new ledger node type for suspended payments and new transaction types to create, execute, and cancel suspended payments.

-

FeeEscalation

- - - - - - - - - - - - - -
Amendment IDStatus
42426C4D4F1009EE67080A9B7965B44656D7714D104A72F9B4369F97ABF044EEEnabled
-

Changes the way the transaction cost applies to proposed transactions. Modifies the consensus process to prioritize transactions that pay a higher transaction cost.

-

This amendment introduces a fixed-size transaction queue for transactions that were not able to be included in the previous consensus round. If the rippled servers in the consensus network are under heavy load, they queue the transactions with the lowest transaction cost for later ledgers. Each consensus round prioritizes transactions from the queue with the largest transaction cost (Fee value), and includes as many transactions as the consensus network can process. If the transaction queue is full, transactions drop from the queue entirely, starting with the ones that have the lowest transaction cost.

-

While the consensus network is under heavy load, legitimate users can pay a higher transaction cost to make sure their transactions get processed. The situation persists until the entire backlog of cheap transactions is processed or discarded.

-

A transaction remains in the queue until one of the following happens:

-
    -
  • It gets applied to a validated ledger (regardless of success or failure)
    • -
  • It becomes invalid (for example, the LastLedgerSequence causes it to expire)
    • -
  • It gets dropped because there are too many transactions in the queue with a higher transaction cost.
    • -
-

fix1368

- - - - - - - - - - - - - -
Amendment IDStatus
E2E6F2866106419B88C50045ACE96368558C345566AC8F2BDF5A5B5587F0E6FAEnabled
-

Fixes a minor bug in transaction processing that causes some payments to fail when they should be valid. Specifically, during payment processing, some payment steps that are expected to produce a certain amount of currency may produce a microscopically different amount, due to a loss of precision related to floating-point number representation. When this occurs, those payments fail because they cannot deliver the exact amount intended. The fix1368 amendment corrects transaction processing so payments can no longer fail in this manner.

-

fix1373

- - - - - - - - - - - - - -
Amendment IDStatus
42EEA5E28A97824821D4EF97081FE36A54E9593C6E4F20CBAE098C69D2E072DCEnabled
-

Fixes a minor bug in transaction processing that causes failures when trying to prepare certain payment paths for processing. As a result, payments could not use certain paths that should have been valid but were invalidly prepared. Without this amendment, those payments are forced to use less-preferable paths or may even fail.

-

The fix1373 amendment corrects the issue so that the paths are properly prepared and payments can use them. It also disables some inappropriate paths that are currently allowed, including paths whose steps include conflicting fields and paths that loop through the same object more than once.

-

Flow

- - - - - - - - - - - - - -
Amendment IDStatus
740352F2412A9909880C23A559FCECEDA3BE2126FED62FC7660D628A06927F11Enabled
-

Replaces the payment processing engine with a more robust and efficient rewrite called the Flow engine. The new version of the payment processing engine is intended to follow the same rules as the old one, but occasionally produces different results due to floating point rounding. This Amendment supersedes the FlowV2 amendment.

-

The Flow Engine also makes it easier to improve and expand the payment engine with further Amendments.

-

FlowCross

- - - - - - - - - - - - - -
Amendment IDStatus
3012E8230864E95A58C60FD61430D7E1B4D3353195F2981DC12B0C7C0950FFACReleased but not enabled
-

Streamlines the offer crossing logic in the XRP Ledger's decentralized exchange. Uses the updated code from the Flow amendment to power offer crossing, so OfferCreate transactions and Payment transactions share more code. This has subtle differences in how offers are processed:

-
    -
  • Rounding is slightly different in some cases.
    • -
  • Due to differences in rounding, some combinations of offers may be ranked higher or lower than by the old logic, and taken preferentially.
    • -
  • The new logic may delete more or fewer offers than the old logic. (This includes cases caused by differences in rounding and offers that were incorrectly removed as unfunded by the old logic.)
    • -
-

FlowV2

- - - - - - - - - - - - - -
Amendment IDStatus
5CC22CFF2864B020BD79E0E1F048F63EF3594F95E650E43B3F837EF1DF5F4B26Withdrawn
-

This is a previous version of the Flow amendment. It was rejected due to a bug and removed in version 0.33.0.

-

MultiSign

- - - - - - - - - - - - - -
Amendment IDStatus
4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373Enabled
-

Introduces multi-signing as a way to authorize transactions. Creates the SignerList ledger node type and the SignerListSet transaction type. Adds the optional Signers field to all transaction types. Modifies some transaction result codes.

-

This amendment allows addresses to have a list of signers who can authorize transactions from that address in a multi-signature. The list has a quorum and 1 to 8 weighted signers. This allows various configurations, such as "any 3-of-5" or "signature from A plus any other two signatures."

-

Signers can be funded or unfunded addresses. Funded addresses in a signer list can sign using a regular key (if defined) or master key (unless disabled). Unfunded addresses can sign with a master key. Multi-signed transactions have the same permissions as transactions signed with a regular key.

-

An address with a SignerList can disable the master key even if a regular key is not defined. An address with a SignerList can also remove a regular key even if the master key is disabled. The tecMASTER_DISABLED transaction result code is renamed tecNO_ALTERNATIVE_KEY. The tecNO_REGULAR_KEY transaction result is retired and replaced with tecNO_ALTERNATIVE_KEY. Additionally, this amendment adds the following new transaction result codes:

-
    -
  • temBAD_SIGNER
    • -
  • temBAD_QUORUM
    • -
  • temBAD_WEIGHT
    • -
  • tefBAD_SIGNATURE
    • -
  • tefBAD_QUORUM
    • -
  • tefNOT_MULTI_SIGNING
    • -
  • tefBAD_AUTH_MASTER
    • -
-

OwnerPaysFee

- - - - - - - - - - - - - -
Amendment IDStatus
9178256A980A86CF3D70D0260A7DA6402AAFE43632FDBCB88037978404188871Released but not enabled
-

Fixes an inconsistency in the way transfer fees are calculated between OfferCreate and Payment transaction types. Without this amendment, the holder of the issuances pays the transfer fee if an offer is executed in offer placement, but the initial sender of a transaction pays the transfer fees for offers that are executed as part of payment processing. With this amendment, the holder of the issuances always pays the transfer fee, regardless of whether the offer is executed as part of a Payment or an OfferCreate transaction. Offer processing outside of payments is unaffected.

-

This Amendment requires the Flow Amendment to be enabled.

-

PayChan

- - - - - - - - - - - - - -
Amendment IDStatus
08DE7D96082187F6E6578530258C77FAABABE4C20474BDB82F04B021F1A68647Enabled
-

Creates "Payment Channels" for XRP. Payment channels are a tool for facilitating repeated, unidirectional payments or temporary credit between two parties. Ripple expects this feature to be useful for the Interledger Protocol. One party creates a Payment Channel and sets aside some XRP in that channel for a predetermined expiration. Then, through off-ledger secure communications, the sender can send "Claim" messages to the receiver. The receiver can redeem the Claim messages before the expiration, or choose not to in case the payment is not needed. The receiver can verify Claims individually without actually distributing them to the network and waiting for the consensus process to redeem them, then redeem the batched content of many small Claims later, as long as it is within the expiration.

-

Creates three new transaction types:PaymentChannelCreate, PaymentChannelClaim, and PaymentChannelFund. Creates a new ledger node type, PayChannel. Defines an off-ledger data structure called a Claim, used in the ChannelClaim transaction. Creates new rippled API methods: channel_authorize (creates a signed Claim), channel_verify (verifies a signed Claim), and account_channels (lists Channels associated with an account).

-

For more information, see the Payment Channels Tutorial.

-

SHAMapV2

- - - - - - - - - - - - - -
Amendment IDStatus
C6970A8B603D8778783B61C0D445C23D1633CCFAEF0D43E7DBCD1521D34BD7C3Released but not enabled
-

Changes the hash tree structure that rippled uses to represent a ledger. The new structure is more compact and efficient than the previous version. This affects how ledger hashes are calculated, but has no other user-facing consequences.

-

When this amendment is activated, the XRP Ledger will undergo a brief scheduled unavailability while the network calculates the changes to the hash tree structure.

-

SusPay

- - - - - - - - - - - - - -
Amendment IDStatus
DA1BD556B42D85EA9C84066D028D355B52416734D3283F85E216EA5DA6DB7E13Enabled on TestNet; not intended for production.
-

This amendment is currently enabled on the Ripple Test Net. In production, Ripple expects to enable similar functionality with the Escrow amendment instead.

-

TrustSetAuth

- - - - - - - - - - - - - -
Amendment IDStatus
6781F8368C4771B83E8B821D88F580202BCB4228075297B19E4FDC5233F1EFDCEnabled
-

Allows pre-authorization of accounting relationships (zero-balance trust lines) when using Authorized Accounts.

-

With this amendment enabled, a TrustSet transaction with tfSetfAuth enabled can create a new RippleState ledger node even if it keeps all the other values of the RippleState node in their default state. The new RippleState node has the lsfLowAuth or lsfHighAuth flag enabled, depending on whether the sender of the transaction is considered the low node or the high node. The sender of the transaction must have already enabled lsfRequireAuth by sending an AccountSet transaction with the asfRequireAuth flag enabled.

-

TickSize

- - - - - - - - - - - - - -
Amendment IDStatus
532651B4FD58DF8922A49BA101AB3E996E5BFBF95A913B3E392504863E63B164Enabled
-

Changes the way Offers are ranked in order books, so that currency issuers can configure how many significant digits are taken into account when ranking Offers by exchange rate. With this amendment, the exchange rates of Offers are rounded to the configured number of significant digits, so that more Offers have the same exact exchange rate. The intent of this change is to require a meaningful improvement in price to outrank a previous Offer. If used by major issuers, this should reduce the incentive to spam the ledger with Offers that are only a tiny fraction of a percentage point better than existing offers. It may also increase the efficiency of order book storage in the ledger, because Offers can be grouped into fewer exchange rates.

-

Introduces a TickSize field to accounts, which can be set with the AccountSet transaction type. If a currency issuer sets the TickSize field, the XRP Ledger truncates the exchange rate (ratio of funds in to funds out) of Offers to trade the issuer's currency, and adjusts the amounts of the Offer to match the truncated exchange rate. If only one currency in the trade has a TickSize set, that number of significant digits applies. When trading two currencies that have different TickSize values, whichever TickSize indicates the fewest significant digits applies. XRP does not have a TickSize.

-

Tickets

- - - - - - - - - - - - - -
Amendment IDStatus
C1B8D934087225F509BEB5A8EC24447854713EE447D277F69545ABFA0E0FD490In development
-

Introduces Tickets as a way to reserve a transaction sequence number for later execution. Creates the Ticket ledger node type and the transaction types TicketCreate and TicketCancel.

-

Caution: This amendment is still in development.

- -
-
-
- - - - \ No newline at end of file diff --git a/concept-consensus.html b/concept-consensus.html deleted file mode 100644 index bc42a213fa..0000000000 --- a/concept-consensus.html +++ /dev/null @@ -1,300 +0,0 @@ - - - - - - - - Consensus Process - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

The XRP Ledger Consensus Process

-

Written by Dave Cohen, David Schwartz, and Arthur Britto.

-

This article provides a high level overview of the XRP Ledger, the information it stores, and how transactions result in changes to the ledger.

-

When building applications on the XRP Ledger, it is important to understand this process, so as not to be surprised by the behavior of XRP Ledger APIs and their effects.

-

Caution: Transactions are not applied to the XRP Ledger instantaneously; it takes some time for the effects of transactions to be applied. During this process, rippled APIs may return provisional results that should not be mistaken for the final, immutable results of a transaction. Immutable results can only be determined by looking at validated ledgers.

-

Introduction

-

The peer-to-peer XRP Ledger network provides a worldwide, shared ledger, which gives applications authoritative information about the state of its contents. This state information includes:

-
    -
  • settings for each account
    • -
  • balances between accounts (trust lines)
    • -
  • offers in the distributed exchange
    • -
  • network settings, such as transaction costs and reserve amounts
    • -
  • a time stamp
    • -
-

For a full, technical description of which data is included in a ledger version, see the Ledger Format Reference.

-

Figure 1: XRP Ledger Elements

-

Figure 1: XRP Ledger Elements

-

The XRP Ledger has a new ledger version every several seconds. The ledger versions that preceded it comprise the ledger history. Even the most recent validated ledger is part of history, as it represents the state of the network as of a short time ago. In the present, the network is evaluating transactions which may be applied and finalized in the next ledger version.

-

Figure 2: XRP Ledger Sequence and History

-

Figure 2: XRP Ledger Sequence and History

-

A ledger instance is identified by its sequence number 1, also called a ledger index. Ledgers are numbered incrementally. If the last validated ledger is N, the previous was N-1 and the next will be N+1. The N+1 ledger is produced by applying a set of transactions to ledger N.

-

User level changes to the ledger are the results of transactions. Examples of transactions include payments, changes to account settings or trust lines, and offers to trade. Each transaction authorizes changes to the ledger and is cryptographically signed by an account owner. Transactions are the only way to authorize changes to an account.

-

A ledger instance also contains a set of transactions and metadata about those transactions. The transactions are those that have been applied to the prior ledger in order to create the new instance. The metadata records precisely the effects of the transaction on the ledger.

-

Figure 3: Transactions Applied to Ledger Version

-

Figure 3: Transactions Applied to Ledger Version

-

The set of transactions included in a ledger instance are recorded in that ledger and allow auditability of the XRP Ledger history. If an account balance is different in ledger N+1 than it was in ledger N, then ledger N+1 contains the transaction(s) responsible for the change.

-

Transactions that appear in a validated ledger may have succeeded in changing the ledger, or may have been processed without doing the requested action. Successful transactions will have the tesSUCCESS result code which indicates the requested changes are applied to the ledger and a fee was claimed. Other transactions in the ledger have tec class result codes, which indicate transactions that only claim a fee and perform no other changes 2.

-

Transactions of the tec class are included with the ledger because they change an account balance when claiming a fee.

-

In addition to the tes and tec class result codes, there are ter, tef and tem class codes. The latter three indicate provisional failures returned by API calls. Only tes and tec codes appear in ledgers.

-

When working with rippled APIs, applications must distinguish between candidate transactions proposed for inclusion in a ledger versus validated transactions which are included in a validated ledger. Only transaction results found in a validated ledger are immutable. A candidate transaction may or may not ever be included in a validated ledger.

-

Important: Some rippled APIs provide provisional results, based on candidate transactions 3. Applications should never rely on provisional results to determine the final outcome of a transaction. The only way to know with certainty that a transaction finally succeeded is to check the status of the transaction until it is both in a validated ledger and has result code tesSUCCESS. If the transaction is in a validated ledger with any other result code, it has failed. If the ledger specified in a transaction’s LastLedgerSequence has been validated, yet the transaction does not appear in that ledger or any before it, then that transaction has failed and will never appear in any ledger. An outcome is final only for transactions that appear in a validated ledger or can never appear because of LastLedgerSequence restrictions as explained later in this document.

-

The XRP Ledger Protocol – Consensus and Validation

-

The peer-to-peer XRP Ledger network consists of many distributed servers, called nodes, that accept and process transactions. Client applications sign and send transactions to nodes, which relay these candidate transactions throughout the network for processing. Examples of client applications include mobile and web wallets, gateways to financial institutions, and electronic trading platforms.

-

Figure 4: Participants in the XRP Ledger Protocol

-

Figure 4: Participants in the XRP Ledger Protocol

-

The nodes that receive, relay and process transactions may be either tracking nodes or validating nodes. Tracking nodes’ primary functions include distributing transactions from clients and responding to queries about the ledger. Validating nodes perform the same functions as tracking nodes and additionally contribute to advancing the ledger sequence 4.

-

While accepting transactions submitted by client applications, each tracking node uses the last validated ledger as a starting point. The accepted transactions are candidates. The nodes relay their candidate transactions to their peers, allowing the candidate transactions to propagate throughout the network. Ideally, each candidate transaction would be known to all nodes, allowing each to consider an identical set of transactions to apply to the last validated ledger. As transactions take time to propagate however, the nodes do not work with an identical set of candidate transactions at all times. To account for this, the XRP Ledger uses a process called consensus to ensure that identical transactions are processed and validated ledgers are consistent across the peer-to-peer XRP Ledger network.

-

Consensus

-

The nodes on the network share information about candidate transactions. Through the consensus process, validating nodes agree on a specific subset of the candidate transactions to be considered for the next ledger. Consensus is an iterative process in which nodes relay proposals, or sets of candidate transactions. Nodes communicate and update proposals until a supermajority 5 of peers agree on the same set of candidate transactions.

-

During consensus, each node evaluates proposals from a specific set of peers, called chosen validators 6. Chosen validators represent a subset of the network which, when taken collectively, is "trusted" not to collude in an attempt to defraud the node evaluating the proposals. This definition of "trust" does not require that each individual chosen validator is trusted. Rather, validators are chosen based on the expectation they will not collude in a coordinated effort to falsify data relayed to the network 7.

-

Figure 5: Validators Propose Transaction Sets

-

Figure 5: Validators Propose Transaction Sets — At the start of consensus, nodes work with different sets of transactions. Rounds of proposals determine which transactions will be applied to the ledger, and which must wait for a subsequent round of consensus.

-

Candidate transactions which fail to be included in the agreed-upon proposal remain candidate transactions. They may be considered again in the next round of consensus.

-

Figure 6: Through Consensus, Nodes Agree on Transaction Set

-

Figure 6: Through Consensus, Nodes Agree On Transaction Set — Nodes will apply the agreed-upon set of transactions (shown in green) to the last validated ledger. Transactions not in the set (in red) may be agreed upon in the next round.

-

Typically, a transaction which does not pass one round of consensus will succeed in the following round. However, in some circumstances, a transaction could fail to pass consensus indefinitely. One such circumstance is if the network increases the base fee to a value higher than the transaction provides. The transaction could potentially succeed if the fees are lowered at some point in the future.

-

The LastLedgerSequence transaction field is a mechanism to prevent such a transaction from being viable indefinitely and ensure transaction processing occurs in a timely fashion. Applications should include a LastLedgerSequence parameter with each transaction. This ensures a transaction will either succeed or fail on or before the specified ledger sequence number, thus limiting the amount of time an application must wait before obtaining a definitive transaction result. For more information, see Reliable Transaction Submission.

-

Validation

-

When a round of consensus completes, each node computes a new ledger by applying the candidate transactions in the consensus transaction set to the last validated ledger.

-

Figure 7: A Network Node Calculates a Ledger Validation

-

Figure 7: A Network Node Calculates a Ledger Validation — Each tracking node applies agreed-upon transactions to the last validated ledger. Validating nodes will transmit their results to the entire network.

-

The validating nodes calculate a new version of the ledger and relay their results to the network, each transmitting a signed hash of the ledger it calculated based on the candidate transactions proposed during consensus. These signed hashes, called validations, allow each node to compare the ledger it computed with those of its peers.

-

Figure 8: Ledger is Validated When Supermajority of Peers Calculate an Identical Result

-

Figure 8: Ledger is Validated When Supermajority of Peers Calculate an Identical Result — Nodes compare their calculated ledger with the hashes received from chosen validators. If not in agreement, the node must re-calculate or retrieve the correct ledger.

-

Nodes of the network recognize a ledger instance as validated when a supermajority of the peers have signed and broadcast an identical validation hash 8. Going forward, transactions will be applied to this updated and now validated ledger with sequence number N+1.

-

In cases where a node is in the minority, having computed a ledger that differs from its peers, the node will disregard the ledger it computed 9. It will recompute the correct ledger, or retrieve the correct ledger as needed.

-

If the network fails to achieve supermajority agreement on validations, this implies that transaction volume was too high or network latency too great for the consensus process to produce consistent proposals. In this case, the nodes repeat the consensus process. As time passes since consensus began, it becomes increasingly likely that a majority of the nodes have received the same set of candidate transactions, as each consensus round reduces disagreement. The XRP Ledger dynamically adjusts transaction costs and the time to wait for consensus in response to these conditions.

-

Figure 9: Network Recognizes a New Validated Ledger Version

-

Figure 9: Network Recognises the New Validated Ledger Version — At the end of a round of the consensus process, nodes have an updated validated ledger.

-

Once they reach supermajority agreement on validations, the nodes work with the new validated ledger, sequence number N+1. The consensus and validation process repeats 10, considering candidate transactions that were not included in the last round along with new transactions submitted in the meantime.

-

Key Takeaways

-

Transactions submitted to the XRP Ledger are not processed instantaneously. For a period of time, each transaction remains a candidate.

-

The lifecycle of a single transaction is as follows:

-
    -
  • A transaction is created and signed by an account owner.
    • -
  • The transaction is submitted to the network.
      -
    • Badly formed transactions may be rejected immediately.
      • -
    • Well formed transactions may provisionally succeed, then later fail.
      • -
    • Well formed transactions may provisionally fail, then later succeed.
      • -
    -
    • -
  • During consensus, the transaction is included in the ledger.
      -
    • The result of a successful consensus round is a validated ledger.
      • -
    • If a consensus round fails, the consensus process repeats until it succeeds.
      • -
    -
    • -
  • The validated ledger includes the transaction and its effects on the ledger state.
    • -
-

Applications should only rely on information in validated ledgers, not on the provisional results of candidate transactions. Some rippled APIs initially return provisional results for transactions. The results of a transaction become immutable only when that transaction is included in a validated ledger, or the transaction includes LastLedgerSequence and does not appear in any validated ledger with that sequence number or lower.

-

Best practices for applications submitting transactions include:

-
    -
  • Use the LastLedgerSequence parameter to ensure that transactions validate or fail in a deterministic and timely fashion.
    • -
  • Check the results of transactions in validated ledgers.
      -
    • Until a ledger containing the transaction is validated, or LastLedgerSequence has passed, results are provisional.
      • -
    • Transactions with result code tesSUCCESS and "validated": true have immutably succeeded.
      • -
    • Transactions with other result codes and "validated": true have immutably failed.
      • -
    • Transactions that fail to appear in any validated ledger up to and including the validated ledger identified by the transaction’s LastLedgerSequence have immutably failed.
        -
      • Take care to use a node with a continuous ledger history to detect this case 11.
        • -
      -
      • -
    • It may be necessary to check the status of a transaction repeatedly until the ledger identified by LastLedgerSequence is validated.
      • -
    -
    • -
-

Further Resources

- -

End Notes

-

1 – A ledger instance can also be uniquely identified by its hash, which is a digital fingerprint of its contents.

-

2 – Transactions with tec result codes are included in ledgers and not do the requested action. The rationale for this is that multiple transactions may be submitted in sequence, with the order of processing determined by a sequence number associated with an account (not to be confused with the ledger sequence number). To prevent a hold on account sequence numbers which would block subsequent transactions, the transaction is processed to consume the sequence number. Additionally, transactions which are distributed to the network must claim a fee to prevent network abuse.

-

3 – For example, consider a scenario where Alice has $100, and sends all of it to Bob. If an application first submits that payment transaction, then immediately after checks Alice’s balance, the API will return $0. This value is based on the provisional result of a candidate transaction. There are circumstances in which the payment will fail and Alice’s balance will remain $100 (or, due to other transactions, become some other amount). The only way to know with certainty that Alice’s payment to Bob succeeded is to check the status of the transaction until it is both in a validated ledger and has result code tesSUCCESS. If the transaction is in a validated ledger with any other result code, the payment has failed.

-

4 – Strictly speaking, validating nodes are a subset of tracking nodes. They provide the same features and additionally create "validations." Tracking nodes may be further categorized by whether they maintain full vs. partial ledger history.

-

5 – Transactions fail to pass a round of consensus when the percentage of peers recognizing the transaction falls below a threshold. Each round is an iterative process. At the start of the first round, at least 50% of peers must agree. The final threshold for a consensus round is 80% agreement. These specific values are subject to change

-

6 – Sometimes referred to as a Unique Node List (UNL).

-

7 – If proposals from all validators were evaluated, instead of exclusively from the validators chosen not to collude, a malicious attacker could spin up enough validating nodes to comprise a colluding supermajority to introduce invalid transactions or omit valid transactions from proposals. The chosen validator list defends against Sybil attacks.

-

8 – The supermajority threshold, as of November 2014, requires that at least 80% of peers must agree for a ledger to be validated. This happens to be the same percentage required by a round of consensus. Both thresholds are subject to change and need not be equal.

-

9 – In practice, the node detects that it is in the minority before receiving validations from all peers. It knows when it receives non-matching validations from over 20% of peers that its validation will not meet the 80% threshold. At that point, it can begin to recalculate a ledger.

-

10 – In practice, the XRP Ledger runs more efficiently by starting a new round of consensus concurrently, before validation has completed.

-

11 – A rippled server can respond to API requests even without a complete ledger history. Interruptions in service or network connectivity can lead to missing ledgers, or gaps, in the node’s ledger history. Over time, if configured to, rippled will fill in gaps in its history. When testing for missing transactions, it is important to verify against a node with continuous complete ledgers from the time the transaction was submitted until its LastLedgerSequence. Use the RPC server_state to determine which complete_ledgers are available to a particular node.

-
-
-
- - - - \ No newline at end of file diff --git a/concept-fee-voting.html b/concept-fee-voting.html deleted file mode 100644 index 7825dad903..0000000000 --- a/concept-fee-voting.html +++ /dev/null @@ -1,221 +0,0 @@ - - - - - - - - Fee Voting - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

Fee Voting

-

Validators can vote for changes to basic transaction cost as well as reserve requirements. If the preferences in a validator's configuration are different than the network's current settings, the validator expresses its preferences to the network periodically. If a quorum of validators agrees on a change, they can apply a change that takes effect thereafter. Validators may do this for various reasons, especially to adjust to long-term changes in the value of XRP.

-

Operators of rippled validators can set their preferences for the transaction cost and reserve requirements in the [voting] stanza of the rippled.cfg file. Caution: insufficient requirements could expose the XRP Ledger peer-to-peer network to denial-of-service attacks. The parameters you can set are as follows:

- - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterDescriptionRecommended Value
reference_feeAmount of XRP, in drops, that must be destroyed to send the reference transaction, the cheapest possible transaction. (1 XRP = 1 million drops.) The actual transaction cost is a multiple of this value, scaled dynamically based on the load of individual servers.10 (0.00001 XRP)
account_reserveMinimum amount of XRP, in drops, that an account must have on reserve. This is the smallest amount that can be sent to fund a new account in the ledger.20000000 (20 XRP)
owner_reserveHow much more XRP, in drops, that an address must hold for each object it owns in the ledger.5000000 (5 XRP)
-

Voting Process

-

Every 256th ledger is called a "flag" ledger. (A flag ledger is defined such that the ledger_index modulo 256 is equal to 0.) In the ledger immediately before the flag ledger, each validator whose account reserve or transaction cost preferences are different than the current network setting distributes a "vote" message alongside its ledger validation, indicating the values that validator prefers.

-

In the flag ledger itself, nothing happens, but validators receive and take note of the votes from other validators they trust.

-

After counting the votes of other validators, each validator attempts to compromise between its own preferences and the preferences of a majority of validators it trusts. (For example, if one validator wants to raise the minimum transaction cost from 10 to 100, but most validators only want to raise it from 10 to 20, the one validator settles on the change to raise the cost to 20. However, the one validator never settles on a value lower than 10 or higher than 100.) If a compromise is possible, the validator inserts a SetFee pseudo-transaction into its proposal for the ledger following the flag ledger. Other validators who want the same change insert the same SetFee pseudo-transaction into their proposals for the same ledger. (Validators whose preferences match the existing network settings do nothing.) If a SetFee psuedo-transaction survives the consensus process to be included in a validated ledger, then the new transaction cost and reserve settings denoted by the SetFee pseudo-transaction take effect starting with the following ledger.

-

In short:

-
    -
  • Flag ledger -1: Validators submit votes.
    • -
  • Flag ledger: Validators tally votes and decide what SetFee to include, if any.
    • -
  • Flag ledger +1: Validators insert SetFee pseudo-transaction into their proposed ledgers.
    • -
  • Flag ledger +2: New settings take effect, if a SetFee psuedotransaction achieved consensus.
    • -
-
-
-
- - - - \ No newline at end of file diff --git a/concept-fees.html b/concept-fees.html deleted file mode 100644 index cd380563d8..0000000000 --- a/concept-fees.html +++ /dev/null @@ -1,197 +0,0 @@ - - - - - - - - Fees (Disambiguation) - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

Fees (Disambiguation)

-

The XRP Ledger is a decentralized ledger, secured by cryptography and operated by a distributed peer-to-peer network of servers. This means that no one party, not even Ripple, can require a fee for access to the network.

-

However, the rules of the XRP Ledger include several types of fees, including neutral fees which protect the ledger against abuse. These neutral fees are not paid to anyone. There are also several optional ways that users can collect fees from each other, both inside and outside the XRP Ledger.

-

In the Ledger

-

Neutral Fees

-

The transaction cost (sometimes called the transaction fee) is a miniscule amount of XRP destroyed to send a transaction. This cost scales with the load of the network, which protects the peer-to-peer network from spam. See Transaction Cost for more information.

-

The reserve requirement is a minimum amount of XRP that an account must hold. It increases with the number of objects the account owns in the ledger. This disincentivizes users from increasing the size of the ledger carelessly or maliciously. See Reserves for more information.

-

Optional Fees

-

Transfer fees are optional percentage fees that issuers can charge to transfer the currencies they issue to other addresses within the XRP Ledger. See Transfer Fees for more information.

-

Trust line quality is a setting that allows an account to value balances on a trust line at higher or lower than face value. This can lead to situations that are like charging a fee. Trust line quality does not apply to XRP, which is not tied to a trust line.

-

Outside the Ledger

-

Although the fees described above are the only fees built into the XRP Ledger, people can still invent ways to charge fees associated with the ledger. For example, financial institutions commonly charge their customers to send money into and out of the XRP Ledger.

-

Many other fees are also possible. Businesses might charge for access to a client application, maintenance of non-XRP Ledger accounts, exchange services (especially when buying XRP on a private market instead of within the XRP Ledger's decentralized exchange) and any number of other services. Always be aware of the fee schedule before doing business with any financial institution.

-
-
-
- - - - \ No newline at end of file diff --git a/concept-freeze.html b/concept-freeze.html deleted file mode 100644 index 45c0bce015..0000000000 --- a/concept-freeze.html +++ /dev/null @@ -1,884 +0,0 @@ - - - - - - - - Freeze - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

Freeze Features

-

The XRP Ledger gives addresses the ability to freeze non-XRP balances, which can be useful to meet regulatory requirements, or while investigating suspicious activity. There are three settings related to freezes:

-
    -
  • Individual Freeze - Freeze one counterparty.
    • -
  • Global Freeze - Freeze all counterparties.
    • -
  • No Freeze - Permanently give up the ability to freeze individual counterparties, as well as the ability to end a global freeze.
    • -
-

Because no party has a privileged place in the XRP Ledger, the freeze feature cannot prevent a counterparty from conducting transactions in XRP or funds issued by other counterparties. No one can freeze XRP.

-

All freeze settings can be enacted regardless of whether the balance(s) to be frozen are positive or negative. Either the currency issuer or the currency holder can freeze a trust line; however, the effect of a currency holder freezing an issuer is minimal.

-

Individual Freeze

-

The Individual Freeze feature is a setting on a trust line. When an issuing address enables the Individual Freeze setting, the following rules apply:

-
    -
  • Payments can still occur directly between the two parties of the frozen trust line.
    • -
  • The counterparty of that trust line can no longer decrease its balance on the frozen trust line, except in direct payments to the issuer. The counterparty can only send the frozen issuances directly to the issuer.
    • -
  • The counterparty can still receive payments from others on the frozen trust line.
    • -
  • The counterparty's offers to sell the currency issued on the frozen trust line are considered unfunded.
    • -
-

A financial institution can freeze the trust line linking it to a counterparty if that counterparty shows suspicious activity or violates the financial institution's terms of use. The financial institution should also freeze the counterparty in any other systems the financial institution operates that are connected to the XRP Ledger. (Otherwise, an address might still be able to engage in undesired activity by sending payments through the financial institution.)

-

An individual address can freeze its trust line to a financial institution. This has no effect on transactions between the institution and other users. It does, however, prevent other addresses, including operational addresses, from sending that financial institution's issuances to the individual address. This type of individual freeze has no effect on offers.

-

The Individual Freeze applies to a single currency only. To freeze multiple currencies with a particular counterparty, the address must enable Individual Freeze on the trust lines for each currency individually.

-

An address cannot enable the Individual Freeze setting if it has enabled the No Freeze setting.

-

Global Freeze

-

The Global Freeze feature is a setting on an address. When an issuing address enables the Global Freeze feature, the following rules apply:

-
    -
  • All counterparties of the frozen issuing address can no longer decrease the balances in their trust lines to the frozen address, except in direct payments to the issuer. (This also affects any operational addresses.)
    • -
  • Counterparties of the frozen issuing address can still send and receive payments directly to and from the issuing address.
    • -
  • All offers to sell currencies issued by the frozen address are considered unfunded.
    • -
-

It can be useful to enable Global Freeze on a financial institution's issuing address if the secret key to an operational address is compromised, even after regaining control of a such an address. This stops the flow of funds, preventing attackers from getting away with any more money or at least making it easier to track what happened. Besides enacting a Global Freeze in the XRP Ledger, a financial institution should also suspend activities in its connectors to outside systems.

-

It can also be useful to enable Global Freeze if a financial institution intends to migrate to a new issuing address, or if the financial institution intends to cease doing business. This locks the funds at a specific point in time, so users cannot trade them away for other currencies.

-

Global Freeze applies to all currencies issued and held by the address. You cannot enable Global Freeze for only one currency. If you want to have the ability to freeze some currencies and not others, you should use different addresses for each currency.

-

An address can always enable the Global Freeze setting. However, if the address has enabled the No Freeze setting, it can never disable Global Freeze.

-

No Freeze

-

The No Freeze feature is a setting on an address that permanently gives up the ability to freeze counterparties. A business can use this feature to treat its issued funds as "more like physical money" in the sense that the business cannot interfere with customers trading it among themselves. The NoFreeze setting has two effects:

-
    -
  • The issuing address can no longer enable Individual Freeze on trust lines to any counterparty.
    • -
  • The issuing address can still enable Global Freeze to enact a global freeze, but the address cannot disable Global Freeze.
    • -
-

The XRP Ledger cannot force a financial institution to honor the obligations that its issued funds represent, so giving up the ability to enable a Global Freeze cannot protect customers. However, giving up the ability to disable a Global Freeze ensures that the Global Freeze feature is not used unfairly against some customers.

-

The No Freeze setting applies to all currencies issued to and from an address. If you want to be able to freeze some currencies but not others, you should use different addresses for each currency.

-

You can only enable the No Freeze setting with a transaction signed by your address's master key secret. You cannot use a Regular Key or a multi-signed transaction to enable No Freeze.

-

Technical Details

-

Enabling or Disabling Individual Freeze

-

Using rippled

-

To enable or disable Individual Freeze on a specific trust line, send a TrustSet transaction. Use the tfSetFreeze flag to enable a freeze, and the tfClearFreeze flag to disable it. The fields of the transaction should be as follows:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
AccountStringThe XRP Ledger address to enable or disable the freeze.
TransactionTypeStringTrustSet
LimitAmountObjectObject defining the trust line to freeze.
LimitAmount.currencyStringCurrency of the trust line
LimitAmount.issuerStringThe XRP Ledger address of the counterparty to freeze
LimitAmount.valueStringThe amount of currency you trust this counterparty to issue to you, as a quoted number. From the perspective of a financial institution, this is typically "0".
FlagsNumberTo enable a freeze, use a value with the bit 0x00100000 (tfSetFreeze) enabled. To disable a freeze, use a value with the bit 0x00200000 (tfClearFreeze) enabled instead.
-

Set the Fee, Sequence, and LastLedgerSequence parameters in the typical way.

-

Example of submitting a TrustSet transaction to enable an individual freeze using the WebSocket API:

-
{
-  "id": 12,
-  "command": "submit",
-  "tx_json": {
-    "TransactionType": "TrustSet",
-    "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-    "Fee": "12000",
-    "Flags": 1048576,
-    "LastLedgerSequence": 18103014,
-    "LimitAmount": {
-      "currency": "USD",
-      "issuer": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-      "value": "110"
-    },
-    "Sequence": 340
-  },
-  "secret": "s████████████████████████████",
-  "offline": false,
-  "fee_mult_max": 1000
-}
-
-

Caution: Never send your secret key to an untrusted server or over an insecure channel.

-

Using RippleAPI

-

To enable or disable Individual Freeze on a specific trust line, prepare a Trustline transaction using the prepareTrustline method. The fields of the trustline parameter should be set as follows:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
currencyStringThe currency of the trust line to freeze
counterpartyStringThe XRP Ledger address of the counterparty
limitStringThe amount of currency you trust this counterparty to issue to you, as a quoted number. From the perspective of a financial institution, this is typically "0".
frozenBooleantrue to enable Individual Freeze on this trust line. false to disable Individual Freeze.
-

The rest of the transaction flow is the same as any other transaction.

-

Example JavaScript (ECMAScript 6) code to enable Individual Freeze on a trust line:

-
const {RippleAPI} = require('ripple-lib');
-
-const api = new RippleAPI({
-  server: 'wss://s1.ripple.com' // Public rippled server
-});
-api.on('error', (errorCode, errorMessage) => {
-  console.log(errorCode + ': ' + errorMessage);
-});
-
-const issuing_address = 'rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn';
-const issuing_secret = 's████████████████████████████';
-    // Best practice: get your secret from an encrypted
-    //  config file instead
-const address_to_freeze = 'rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v';
-const currency_to_freeze = 'USD';
-
-api.connect().then(() => {
-
-  // Look up current state of trust line
-  const options = {counterparty: address_to_freeze,
-                 currency: currency_to_freeze};
-  console.log('looking up', currency_to_freeze, 'trust line from',
-              issuing_address, 'to', address_to_freeze);
-  return api.getTrustlines(issuing_address, options);
-
-}).then(data => {
-
-  // Prepare a trustline transaction to enable freeze
-  let trustline = {};
-  if (data.length !== 1) {
-    console.log('trustline not found, making a default one');
-    trustline = {
-      currency: currency_to_freeze,
-      counterparty: address_to_freeze,
-      limit: 0
-    };
-  } else {
-    trustline = data[0].specification;
-    console.log('trustline found. previous state:', trustline);
-  }
-
-  trustline.frozen = true;
-
-  console.log('preparing trustline transaction for line:', trustline);
-  return api.prepareTrustline(issuing_address, trustline);
-
-}).then(prepared_tx => {
-
-  // Sign and submit the trustline transaction
-  console.log('signing tx:', prepared_tx.txJSON);
-  const signed1 = api.sign(prepared_tx.txJSON, issuing_secret);
-  console.log('submitting tx:', signed1.id);
-
-  return api.submit(signed1.signedTransaction);
-}).then(() => {
-  return api.disconnect();
-}).catch(console.error);
-
-

Enabling or Disabling Global Freeze

-

Using rippled

-

To enable Global Freeze on an address, send an AccountSet transaction with the asfGlobalFreeze flag value in the SetFlag field. To disable Global Freeze, put the asfGlobalFreeze flag value in the ClearFlag field instead.

-

Example of submitting an AccountSet transaction to enable Global Freeze using the WebSocket API:

-
{
-  "id": 12,
-  "command": "submit",
-  "tx_json": {
-    "TransactionType": "AccountSet",
-    "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-    "Fee": "12000",
-    "Flags": 0,
-    "SetFlag": 7,
-    "LastLedgerSequence": 18122753,
-    "Sequence": 349
-  },
-  "secret": "s████████████████████████████",
-  "offline": false,
-  "fee_mult_max": 1000
-}
-
-

Caution: Never send your secret key to an untrusted server or over an insecure channel.

-

Using RippleAPI

-

To enable or disable Global Freeze on an address, prepare a Settings transaction using the prepareSettings method. The settings parameter should be an object set as follows:

- - - - - - - - - - - - - - - -
FieldValueDescription
globalFreezeBooleantrue to enable a Global Freeze on this address. false to disable Global Freeze.
-

The rest of the transaction flow is the same as any other transaction.

-

Example JavaScript (ECMAScript 6) code to enable Global Freeze on an address:

-
const {RippleAPI} = require('ripple-lib');
-
-const api = new RippleAPI({
-  server: 'wss://s1.ripple.com' // Public rippled server
-});
-api.on('error', (errorCode, errorMessage) => {
-  console.log(errorCode + ': ' + errorMessage);
-});
-
-const issuing_address = 'rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn';
-const issuing_secret = 's████████████████████████████';
-    // Best practice: get your secret from an encrypted
-    //  config file instead
-
-api.connect().then(() => {
-
-  // Prepare a settings transaction to enable global freeze
-  const settings = {
-    'globalFreeze': true
-  };
-
-  console.log('preparing settings transaction for account:',
-              issuing_address);
-  return api.prepareSettings(issuing_address, settings);
-
-}).then(prepared_tx => {
-
-  // Sign and submit the settings transaction
-  console.log('signing tx:', prepared_tx.txJSON);
-  const signed1 = api.sign(prepared_tx.txJSON, issuing_secret);
-  console.log('submitting tx:', signed1.id);
-
-  return api.submit(signed1.signedTransaction);
-
-}).then(() => {
-  return api.disconnect();
-}).catch(console.error);
-
-

Enabling No Freeze

-

Using rippled

-

To enable No Freeze on an address, send an AccountSet transaction with the asfNoFreeze flag value in the SetFlag field. You must sign this transaction using the master key. Once enabled, you cannot disable No Freeze.

-

Example of submitting an AccountSet transaction to enable No Freeze using the WebSocket API:

-

WebSocket request:

-
{
-  "id": 12,
-  "command": "submit",
-  "tx_json": {
-    "TransactionType": "AccountSet",
-    "Account": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
-    "Fee": "12000",
-    "Flags": 0,
-    "SetFlag": 6,
-    "LastLedgerSequence": 18124917,
-    "Sequence": 4
-  },
-  "secret": "s████████████████████████████",
-  "offline": false,
-  "fee_mult_max": 1000
-}
-
-

Caution: Never send your secret key to an untrusted server or over an insecure channel.

-

Using RippleAPI

-

To enable No Freeze on an address, prepare a Settings transaction using the prepareSettings method. Once enabled, you cannot disable No Freeze. The settings parameter should be an object set as follows:

- - - - - - - - - - - - - - - -
FieldValueDescription
noFreezeBooleantrue
-

You must sign this transaction using the master key. The rest of the transaction flow is the same as any other transaction.

-

Example JavaScript (ECMAScript 6) code to enable No Freeze on an address:

-
const {RippleAPI} = require('ripple-lib');
-
-const api = new RippleAPI({
-  server: 'wss://s1.ripple.com' // Public rippled server
-});
-api.on('error', (errorCode, errorMessage) => {
-  console.log(errorCode + ': ' + errorMessage);
-});
-
-const issuing_address = 'rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v';
-const issuing_secret = 'snnDVkSW3aV6jvMJTPdCiE2Qxv1RW';
-    // Best practice: get your secret from an encrypted
-    //  config file instead
-
-api.connect().then(() => {
-
-  // Prepare a settings transaction to enable no freeze
-  const settings = {
-    'noFreeze': true
-  };
-
-  console.log('preparing settings transaction for account:',
-              issuing_address);
-  return api.prepareSettings(issuing_address, settings);
-
-}).then(prepared_tx => {
-
-  // Sign and submit the settings transaction
-  console.log('signing tx:', prepared_tx.txJSON);
-  const signed1 = api.sign(prepared_tx.txJSON, issuing_secret);
-  console.log('submitting tx:', signed1.id);
-
-  return api.submit(signed1.signedTransaction);
-}).then(() => {
-  return api.disconnect();
-}).catch(console.error);
-
-

Checking for Individual Freeze

-

Using rippled

-

To see if a trust line has an Individual Freeze enabled, use the account_lines method with the following parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
accountStringThe XRP Ledger address of the issuer
peerStringThe XRP Ledger address of the counterparty
ledger_indexStringUse validated to get the most recently validated information.
-

The response contains an array of trust lines, for each currency in which the issuing address and the counterparty are linked. Look for the following fields in each trust line object:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
freezeBoolean(May be omitted) true if the issuing address has frozen this trust line. If omitted, that is the same as false.
freeze_peerBoolean(May be omitted) true if the counterparty has frozen this trust line. If omitted, that is the same as false.
-

Example WebSocket request to check for individual freeze:

-
{
-  "id": 15,
-  "command": "account_lines",
-  "account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-  "ledger": "validated",
-  "peer": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW"
-}
-
-

Example WebSocket response:

-
{
-  "id": 15,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-    "lines": [
-      {
-        "account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-        "balance": "10",
-        "currency": "USD",
-        "freeze": true,
-        "limit": "110",
-        "limit_peer": "0",
-        "peer_authorized": true,
-        "quality_in": 0,
-        "quality_out": 0
-      }
-    ]
-  }
-}
-
-

The field "freeze": true indicates that rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn has enabled Individual Freeze on the USD trust line to rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW. The lack of a field "freeze_peer": true indicates that the counterparty has not frozen the trust line.

-

Using RippleAPI

-

To see if a trust line has an Individual Freeze enabled, use the getTrustlines method with the following parameters:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
addressStringThe XRP Ledger address of the issuer
options.counterpartyStringThe XRP Ledger address of the counterparty
-

The response contains an array of trust lines, for each currency in which the issuing address and the counterparty are linked. Look for the following fields in each trust line object:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
specification.frozenBoolean(May be omitted) true if the issuing address has frozen the trust line.
counterparty.frozenBoolean(May be omitted) true if the counterparty has frozen the trust line.
-

Example JavaScript (ECMAScript 6) code to check whether a trust line is frozen:

-
const {RippleAPI} = require('ripple-lib');
-
-const api = new RippleAPI({
-  server: 'wss://s1.ripple.com' // Public rippled server
-});
-api.on('error', (errorCode, errorMessage) => {
-  console.log(errorCode + ': ' + errorMessage);
-});
-
-const my_address = 'rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn';
-const counterparty_address = 'rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v';
-const frozen_currency = 'USD';
-
-api.connect().then(() => {
-
-  // Look up current state of trust line
-  const options = {counterparty: counterparty_address,
-                   currency: frozen_currency};
-  console.log('looking up', frozen_currency, 'trust line from',
-              my_address, 'to', counterparty_address);
-  return api.getTrustlines(my_address, options);
-
-}).then(data => {
-
-  if (data.length !== 1) {
-    throw 'should only be 1 trust line per counterparty+currency pair';
-  }
-
-  const trustline = data[0];
-  console.log('Trust line frozen from our side?',
-              trustline.specification.frozen === true);
-  console.log('Trust line frozen from counterparty\'s side?',
-              trustline.counterparty.frozen === true);
-
-}).then(() => {
-  return api.disconnect();
-}).catch(console.error);
-
-

Checking for Global Freeze and No Freeze

-

Using rippled

-

To see if an address has enabled Global Freeze, No Freeze, or both, use the account_info method with the following parameters:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
accountStringThe XRP Ledger address of the issuing address
ledger_indexStringUse validated to get the most recently validated information.
-

Check the value of the account_data.Flags field of the response using the bitwise-AND operator:

-
    -
  • If Flags AND 0x00400000 (lsfGlobalFreeze) is nonzero: Global Freeze is enabled.
    • -
  • If Flags AND 0x00200000 (lsfNoFreeze) is nonzero: No Freeze is enabled.
    • -
-

Example WebSocket request:

-
{
-  "id": 1,
-  "command": "account_info",
-  "account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-  "ledger_index": "validated"
-}
-
-

WebSocket response:

-
{
-  "id": 4,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "account_data": {
-      "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-      "AccountTxnID": "41320138CA9837B34E82B3B3D6FB1E581D5DE2F0A67B3D62B5B8A8C9C8D970D0",
-      "Balance": "100258663",
-      "Domain": "6D64756F31332E636F6D",
-      "EmailHash": "98B4375E1D753E5B91627516F6D70977",
-      "Flags": 12582912,
-      "LedgerEntryType": "AccountRoot",
-      "MessageKey": "0000000000000000000000070000000300",
-      "OwnerCount": 4,
-      "PreviousTxnID": "41320138CA9837B34E82B3B3D6FB1E581D5DE2F0A67B3D62B5B8A8C9C8D970D0",
-      "PreviousTxnLgrSeq": 18123095,
-      "Sequence": 352,
-      "TransferRate": 1004999999,
-      "index": "13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8",
-      "urlgravatar": "http://www.gravatar.com/avatar/98b4375e1d753e5b91627516f6d70977"
-    },
-    "ledger_hash": "A777B05A293A73E511669B8A4A45A298FF89AD9C9394430023008DB4A6E7FDD5",
-    "ledger_index": 18123249,
-    "validated": true
-  }
-}
-
-

In the above example, the Flags value is 12582912. This indicates that has the following flags enabled: lsfGlobalFreeze, lsfDefaultRipple, as demonstrated by the following JavaScript code:

-
var lsfGlobalFreeze = 0x00400000;
-var lsfNoFreeze = 0x00200000;
-
-var currentFlags = 12582912;
-
-console.log(currentFlags & lsfGlobalFreeze); //4194304
-//therefore, Global Freeze is enabled
-
-console.log(currentFlags & lsfNoFreeze); //0
-//therefore, No Freeze is not enabled
-
-

Using RippleAPI

-

To see if an address has enabled Global Freeze, No Freeze, or both, use the getSettings method with the following parameters:

- - - - - - - - - - - - - - - -
FieldValueDescription
addressStringThe XRP Ledger address of the issuing address
-

Look for the following values in the response object:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
noFreezeBoolean(May be omitted) true if No Freeze is enabled.
globalFreezeBoolean(May be omitted) true if Global Freeze is enabled.
-

Example JavaScript (ECMAScript 6) code to check whether an address has Global Freeze or No Freeze enabled:

-
const {RippleAPI} = require('ripple-lib');
-
-const api = new RippleAPI({
-  server: 'wss://s1.ripple.com' // Public rippled server
-});
-api.on('error', (errorCode, errorMessage) => {
-  console.log(errorCode + ': ' + errorMessage);
-});
-
-const my_address = 'rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn';
-
-api.connect().then(() => {
-  // Look up settings object
-  return api.getSettings(my_address);
-}).then(settings => {
-  console.log('Got settings for address', my_address);
-  console.log('Global Freeze enabled?',
-              (settings.globalFreeze === true));
-  console.log('No Freeze enabled?', (settings.noFreeze === true));
-
-}).then(() => {
-  return api.disconnect();
-}).catch(console.error);
-
-

See Also

- -
-
-
- - - - \ No newline at end of file diff --git a/concept-issuing-and-operational-addresses.html b/concept-issuing-and-operational-addresses.html deleted file mode 100644 index ce642e045b..0000000000 --- a/concept-issuing-and-operational-addresses.html +++ /dev/null @@ -1,213 +0,0 @@ - - - - - - - - Issuing and Operational Addresses - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

Issuing and Operational Addresses

-

In the XRP Ledger, financial institutions typically use multiple XRP Ledger addresses to minimize the risk associated with a compromised secret key. Ripple strongly recommends the following separation of roles:

-
    -
  • One issuing address, also known as a "cold wallet." This address is the hub of the financial institution's accounting relationships in the ledger, but sends as few transactions as possible.
    • -
  • One or more operational addresses, also known as "hot wallets." Automated, internet-connected systems use the secret keys to these addresses to conduct day-to-day business like transfers to customers and partners.
    • -
  • Optional standby addresses, also known as "warm wallets." Trusted human operators use these addresses to transfer money to the operational addresses.
    • -
-

Funds Lifecycle

-

All non-XRP currency balances (issuances) in the XRP Ledger are tied to accounting relationships between two XRP Ledger addresses. When a financial institution uses Ripple's recommended separation of roles, funds relating to that institution tend to flow in a cycle.

-

Diagram: Funds flow from the issuing address to standby addresses, to operational addresses, to customer and partner addresses, and finally back to the issuing address.

-

When the issuing address sends payments, it creates balances in the accounting relationships in the XRP Ledger. Within the XRP Ledger, users can exchange balances across different accounting relationships, so we use the term issuances to describe any non-XRP balance. Issuances have negative value from the perspective of the issuing address, since they represent obligations. The same issuances have positive value from the perspective of the issuing address's counterparties. When the issuing address receives a payment, this reduces its obligations, erasing the issuances that were sent.

-

The issuing address sends issuances to a standby address, or directly to an operational address. The standby addresses send those issuances to operational addresses. Operational addresses send payments to other counterparties, such as liquidity providers, partners, and other customers. Because all issuances are tied to accounting relationships with the issuing address, payments and exchanges of issuances "ripple through" the issuing address. The payment debits the sender's balance in its accounting relationship with the issuing address and credits the recipient's balance in the recipient's accounting relationship with the issuing address. The XRP Ledger also supports more complicated paths that connect multiple issuers through order books and liquidity providers who allow their funds to ripple.

-

Issuing Address

-

The issuing address is like a vault. Partners, customers, and operational addresses create accounting relationships (trust lines) to the issuing address, but this address sends as few transactions as possible. Periodically, a human operator creates and signs a transaction from the issuing address to refill the balances of a standby or operational address. Ideally, the secret key used to sign these transactions should never be accessible from any internet-connected computer.

-

Unlike a vault, the issuing address can receive payments directly from customers and partners. Since all transactions in the XRP Ledger are public, automated systems can monitor for payments to the issuing address without needing a secret key.

-

Issuing Address Compromise

-

If a malicious actor learns the secret key behind a institution's issuing address, that actor can create new issuances without limit and trade them in the decentralized exchange. This would make it difficult for the financial institution to distinguish legitimately-obtained issuances and redeem them fairly. If a financial institution loses control of its issuing address, the institution must create a new issuing address, and all users who have accounting relationships with the old issuing address must create new accounting relationships with the new address.

-

Multiple Issuing Addresses

-

A financial institution can issue more than one currency in the XRP Ledger from a single issuing address. However, there are some settings that apply equally to all currencies issued from an address, including the percentage for transfer fees and the global freeze status. If the financial institution wants the flexibility to manage settings differently for each currency, the institution must use a different issuing address for each currency.

-

Operational Addresses

-

An operational address is like a cash register. It makes payments on behalf of the institution by transferring issuances to customers and partners. To sign transactions automatically, the secret key for an operational address must be stored on a server that is connected to the internet. (The secret key can be stored encrypted, but the server must decrypt it to sign transactions.) Customers and partners do not, and should not, create accounting relationships with an operational address.

-

Each operational address has a limited balance of issuances. When the balance of an operational address gets low, the financial institution refills it by sending a payment from the issuing address or a standby address.

-

Operational Address Compromise

-

If a malicious actor learns the secret key behind an operational address, the financial institution can only lose as much currency as that operational address holds. The institution can switch to a new operational address with no action from customers and partners.

-

Standby Addresses

-

Another optional step that an institution can take to balance risk and convenience is to use "standby addresses" as an intermediate step between the issuing address and operational addresses. The institution can fund additional XRP Ledger addresses as standby addresses, whose keys are not stored online, but are entrusted to different trusted users.

-

When an operational address is running low on funds, a trusted user can use a standby address to refill the operational address's balance. When a standby addresses run low on funds, the institution can use the issuing address to send more currency to a standby address in a single transaction, and the standby addresses can distribute that currency among themselves if necessary. This improves security of the issuing address, allowing it to make fewer total transactions, without leaving too much money in the control of a single automated system.

-

As with operational addresses, a standby address must have an accounting relationship with the issuing address, and not with customers or partners. All precautions that apply to operational addresses also apply to standby addresses.

-

Standby Address Compromise

-

If a standby address is compromised, the consequences are like an operational address being compromised. A malicious actor can steal any balances possessed by the standby address, and the financial institution can change to a new standby address with no action from customers and partners.

-
-
-
- - - - \ No newline at end of file diff --git a/concept-noripple.html b/concept-noripple.html deleted file mode 100644 index 0ffe48788c..0000000000 --- a/concept-noripple.html +++ /dev/null @@ -1,215 +0,0 @@ - - - - - - - - Understanding the NoRipple flag - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

Understanding the NoRipple Flag

-

In the XRP Ledger, the "NoRipple" flag is a setting on a trust line. When an address enables the NoRipple flag on two trust lines, payments from third parties cannot "ripple" through that address on those trust lines. This protects liquidity providers from having balances shift unexpectedly between different issuers of the same currency.

-

Background

-

"Rippling" occurs when more than one trust line is adjusted to make a payment. For example, if Alice owes Charlie money, and Alice also owes Bob money, then you could represent that in the XRP Ledger with trust lines like so:

-

Charlie --($10)-- Alice -- ($20) -- Bob

-

If Bob wants to pay $3 to Charlie, then he could say, "Alice, take $3 of the money you owe me, and pay it to Charlie." Alice transfers some of the debt from Bob to Charlie. In the end, the trust lines work out like so:

-

Charlie --($13)-- Alice --($17)-- Bob

-

We call this process, where two addresses pay each other by adjusting the balances of trust lines in between them, "rippling". This is a useful and important feature of the XRP Ledger. Rippling occurs when addresses are linked by trust lines that use the same currency code. The issuer does not need to be the same: in fact, larger chains always involve changing issuers.

-

Justification

-

Sometimes you do not want your balances to ripple. For example, imagine Emily has money issued by two different financial institutions, like so

-

Charlie --($10)-- Institution A --($1)-- Emily --($100)-- Institution B --($2)-- Daniel

-

Now Charlie can pay Daniel by rippling through Emily's address. For example, if Charlie pays Daniel $10:

-

Charlie --($0)-- Institution A --($11)-- Emily --($90)-- Institution B --($12)-- Daniel

-

This may surprise Emily, who does not know Charlie or Daniel. Even worse, if Institution A charges her higher fees to withdraw her money than Institution B, this could cost Emily money. The NoRipple flag exists to avoid this scenario. If Emily sets it on both trust lines, then payments cannot ripple through her address using those two trust lines.

-

For example:

-

Charlie --($10)-- Institution A --($1, NoRipple)-- Emily --($100,NoRipple)-- Institution B --($2)-- Daniel

-

Now the above scenario, where Charlie pays Daniel while rippling through Emily's address, is no longer possible.

-

Specifics

-

The NoRipple flag makes certain paths invalid, so that they cannot be used to make payments. A path is considered invalid if and only if it enters and exits an address node through trust lines where NoRipple has been enabled for that address.

-

Diagram demonstrating that NoRipple has to be set on both trust lines by the same address to do anything

-

Technical Details

-

Enabling / Disabling NoRipple

-

The NoRipple flag can only be enabled on a trust line if the address has a positive or zero balance on that trust line. This is so that the feature cannot be abused to default on the obligation the trust line balance represents. (Of course, you can still default by abandoning the address.)

-

In the rippled APIs, you can enable the NoRipple flag by sending a TrustSet Transaction with the tfSetNoRipple flag. You can disable NoRipple (enable rippling) with the tfClearNoRipple flag.

-

In RippleAPI, you can enable the NoRipple flag by sending a Trustline transaction transaction with the ripplingDisabled field of the trust line set to true.

-

Looking Up NoRipple Status

-

In the case of two accounts that mutually trust each other, the NoRipple flag is tracked separately for each account.

-

In the rippled APIs, you can use the account_lines method to look up the trust lines associated with an address. For each trust line, the no_ripple field shows whether the current address has enabled the NoRipple flag on that trust line, and the no_ripple_peer field shows whether the counterparty has enabled the NoRipple flag.

-

In RippleAPI, you can use the getTrustlines method to look up the trust lines associated with an address. For each trust line, the ripplingDisabled field shows whether the current address has enabled the NoRipple flag on that trust line, and the counterparty.ripplingDisabled field shows whether the counterparty has enabled the NoRipple flag.

-
-
-
- - - - \ No newline at end of file diff --git a/concept-partial-payments.html b/concept-partial-payments.html deleted file mode 100644 index 155f0ac7b2..0000000000 --- a/concept-partial-payments.html +++ /dev/null @@ -1,293 +0,0 @@ - - - - - - - - Partial Payments - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

Partial Payments

-

In the default case, the Amount field of a Payment transaction in the XRP Ledger specifies the exact amount to deliver, after charging for exchange rates and transfer fees. The "Partial Payment" flag (tfPartialPayment) allows a payment to succeed by reducing the amount received instead of increasing the amount sent. Partial payments are useful for returning payments without incurring additional costs to oneself.

-

The amount of XRP used for the transaction cost is always deducted from the sender’s account, regardless of the type of transaction.

-

Partial payments can be used to exploit naive integrations with the XRP Ledger to steal money from exchanges and gateways. The Partial Payments Exploit section of this document describes how this exploit works and how you can avoid it.

-

Semantics

-

Without Partial Payments

-

When sending a Payment that does not use the Partial Payment flag, the Amount field of the transaction specifies the exact amount to deliver, and the SendMax field specifies the maximum amount and currency to send. If a payment cannot deliver the full Amount without exceeding the SendMax parameter, or the full amount cannot be delivered for any other reason, the transaction fails. If the SendMax field is omitted from the transaction instructions, it is considered to be equal to the Amount. In this case, the payment can only succeed if the total amount of fees is 0.

-

In other words:

-
Amount + (fees) = (sent amount) ≤ SendMax
-
-

In this formula, "fees" refers to transfer fees and currency exchange rates. The "sent amount" and the delivered amount (Amount) may be denominated in different currencies and converted by consuming Offers in the XRP Ledger's decentralized exchange.

-

Note: The Fee field of the transaction refers to the XRP transaction cost, which is destroyed to relay the transaction to the network. The exact transaction cost specified is always debited from the sender and is completely separate from the fee calculations for any type of payment.

-

With Partial Payments

-

When sending a Payment that has the Partial Payment flag enabled, the Amount field of the transaction specifies a maximum amount to deliver. Partial payments can succeed at sending some of the intended value despite limitations including fees, lack of liquidity, insufficient space in the receiving account's trust lines, or other reasons.

-

The optional DeliverMin field specifies a minimum amount to deliver. The SendMax field functions the same as with non-partial payments. The partial payment transaction is successful if it delivers any amount equal or greater than the DeliverMin field without exceeding the SendMax amount. If the DeliverMin field is not specified, a partial payment can succeed by delivering any positive amount.

-

In other words:

-
Amount ≥ (Delivered Amount) = SendMax - (Fees) ≥ DeliverMin > 0
-
-

Partial Payment Limitations

-

Partial Payments have the following limitations:

-
    -
  • A partial payment cannot provide the XRP to fund an address; this case returns the result code telNO_DST_PARTIAL.
    • -
  • Direct XRP-to-XRP payments cannot be partial payments; this case returns the result code temBAD_SEND_XRP_PARTIAL.
      -
    • However, issuance-to-XRP payments or XRP-to-issuance payments can be partial payments.
      • -
    -
    • -
-

The delivered_amount Field

-

To help understand how much a partial payment actually delivered, the metadata of a successful Payment transaction includes a delivered_amount field. This field describes the amount actually delivered, in the same format as the Amount field.

-

For non-partial payments, the delivered_amount field of the transaction metadata is equal to the Amount field of the transaction. When a payment delivers an issued currency, the delivered_amount may be slightly different than the Amount field due to rounding.

-

The delivered amount is not available for transactions that meet both of the following criteria:

-
    -
  • Is a partial payment
    • -
  • Is included in a validated ledger before 2014-01-20
    • -
-

If both conditions are true, then delivered_amount contains the string value unavailable instead of an actual amount. If this happens, you can only determine the actual delivered amount by reading the AffectedNodes in the transaction's metadata. If the transaction delivered an issued currency and the issuer of the Amount is the same account as the Destination address, the delivered amount may be divided among multiple AffectedNodes members representing trust lines to different counterparties.

-

You can find the delivered_amount field in the following places:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
APIMethodField
JSON-RPC / WebSocketaccount_tx commandresult.transactions array members' meta.delivered_amount
JSON-RPC / WebSockettx commandresult.meta.delivered_amount
JSON-RPC / WebSockettransaction_entry commandresult.metadata.delivered_amount
RippleAPIgetTransaction methodoutcome.deliveredAmount
RippleAPIgetTransactions methodarray members' outcome.deliveredAmount
-

Partial Payments Exploit

-

If a financial institution's integration with the XRP Ledger assumes that the Amount field of a Payment is always the full amount delivered, malicious actors may be able to exploit that assumption to steal money from the institution. This exploit can be used against gateways, exchanges, or merchants as long as those institutions' software does not process partial payments correctly.

-

The correct way to process incoming Payment transactions is to use the delivered_amount metadata field, not the Amount field. This way, an institution is never mistaken about how much it actually received.

-

Exploit Scenario Steps

-

To exploit a vulnerable financial institution, a malicious actor does something like this:

-
    -
  1. The malicious actor sends a Payment transaction to the institution. This transaction has a large Amount field and has the tfPartialPayment flag enabled.
    2. -
  2. The partial payment succeeds (result code tesSUCCESS) but actually delivers a very small amount of the currency specified.
    3. -
  3. The vulnerable institution reads the transaction's Amount field without looking at the Flags field or delivered_amount metadata field.
    4. -
  4. The vulnerable institution credits the malicious actor in an external system, such as the institution's own ledger, for the full Amount, despite only receiving a much smaller delivered_amount in the XRP Ledger.
    5. -
  5. The malicious actor withdraws as much of the balance as possible to another system before the vulnerable institution notices the discrepancy.
      -
    • Malicious actors usually prefer to convert the balance to another crypto-currency such as Bitcoin, because blockchain transactions are usually irreversible. With a withdrawal to a fiat currency system, the financial institution may be able to reverse or cancel the transaction several days after it initially executes.
      • -
    • In the case of an exchange, the malicious actor can also withdraw an XRP balance directly back into the XRP Ledger.
      • -
    -
    6. -
-

In the case of a merchant, the order of operations is slightly different, but the concept is the same:

-
    -
  1. The malicious actor requests to buy a large amount of goods or services.
    2. -
  2. The vulnerable merchant invoices the malicious actor for the price of those goods and services.
    3. -
  3. The malicious actor sends a Payment transaction to the merchant. This transaction has a large Amount field and has the tfPartialPayment flag enabled.
    4. -
  4. The partial payment succeeds (result code tesSUCCESS) but delivers only a very small amount of the currency specified.
    5. -
  5. The vulnerable merchant reads the transaction's Amount field without looking at the Flags field or delivered_amount metadata field.
    6. -
  6. The vulnerable merchant treats the invoice as paid and provides the goods or services to the malicious actor, despite only receiving a much smaller delivered_amount in the XRP Ledger.
    7. -
  7. The malicious actor uses, resells, or absconds with the goods and services before the merchant notices the discrepancy.
    8. -
-

Further Mitigations

-

Using the delivered_amount field when processing incoming transactions is sufficient to avoid this exploit. Still, additional proactive business practices can also avoid or mitigate the likelihood of this and similar exploits. For example:

-
    -
  • Add additional sanity checks to your business logic for processing withdrawals. Never process a withdrawal if the total balance you hold in the XRP Ledger does not match your expected assets and obligations.
    • -
  • Follow "Know Your Customer" guidelines and strictly verify your customers' identities. You may be able to recognize and block malicious users in advance, or pursue legal action against a malicious actor who exploits your system.
    • -
-
-
-
- - - - \ No newline at end of file diff --git a/concept-paths.html b/concept-paths.html deleted file mode 100644 index 66bfdceebb..0000000000 --- a/concept-paths.html +++ /dev/null @@ -1,304 +0,0 @@ - - - - - - - - Paths - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

Paths

-

In the XRP Ledger, 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. Paths also enable complex settlement of offsetting debts.

-

A single Payment transaction in the XRP Ledger can use multiple paths, combining liquidity from different sources to deliver the desired amount. Thus, a transaction includes a path set, which is a collection of possible paths to take. The paths in a path set must start and end with the same currency.

-

Since XRP can be sent directly to any address, an XRP-to-XRP transaction does not use any paths.

-

Path Steps

-

A path is made of steps that connect the sender to the receiver of the payment. Every step is either:

-
    -
  • Rippling through another address with the same currency
    • -
  • Exchanging currency at an order book
    • -
-

Rippling through another address is the process of moving debt around. In the typical case, this involves reducing an issuer's obligation to one party and increasing the obligation to another party. Rippling can occur between any addresses that are connected by trust lines. See Understanding the NoRipple Flag for more examples of rippling.

-

In the case of a currency exchange step, the path step specifies which currency to change to, but does not record the state of the Offers in the order book. The canonical order of transactions is not final until a ledger is validated, so you cannot know for certain which Offers a transaction will take, until after the transaction has been validated. (You can make an educated guess, since each transaction takes the best available Offers at the time it executes in the final ledger.)

-

In both types of steps, each intermediate address gains and loses approximately equal value: either a balance ripples from a trust line to another trust line in the same currency, or they exchange currencies according to a previously-placed order. In some cases, the amounts gained and lost may not be exactly equivalent, due to transfer fees, trust line quality, or rounding.

-

Diagram of three example paths

-

Technical Details

-

Pathfinding

-

The rippled API has two methods that can be used for pathfinding. The ripple_path_find command does a one-time lookup of possible path sets. The path_find command (WebSocket only) expands on the search with follow-up responses whenever a ledger closes or the server finds a better path.

-

You can have rippled automatically fill in paths when you sign it, by including the build_path field in a request to the sign command or submit command (sign-and-submit mode). However, we recommend pathfinding separately and confirming the results before signing, to avoid surprises.

-

Caution: Although rippled is designed to search for the cheapest paths possible, it may not always find them. Untrustworthy rippled instances could also be modified to change this behavior for profit. The actual cost to execute a payment along a path can change between submission and transaction execution.

-

Finding paths is a very challenging problem that changes slightly every few seconds as new ledgers are validated, so rippled is not designed to find the absolute best path. Still, you can find several possible paths and estimate the cost of delivering a particular amount.

-

Implied Steps

-

By convention, several steps of a path are implied by the fields of the Payment transaction: specifically, the Account (sender), Destination (receiver), Amount (currency and amount to be delivered) and SendMax (currency and amount to be sent, if specified). The implied steps are as follows:

-
    -
  • The first step of a path is always implied to be the sender of the transaction, as defined by the transaction's Account field.
    • -
  • If the transaction includes a SendMax field with an issuer that is not the sender of the transaction, that issuer is implied to be the second step of the path.
      -
    • If issuer of the SendMax is the sending address, then the path starts at the sending address, and may use any of that address's trust lines in the given currency. See special values for SendMax and Amount for details.
      • -
    -
    • -
  • If the Amount field of the transaction includes an issuer that is not the same as the Destination of the transaction, that issuer is implied to be the second-to-last step of the path.
    • -
  • Finally, last step of a path is always implied to be the receiver of a transaction, as defined by the transaction's Destination field.
    • -
-

Default Paths

-

In addition to explicitly specified paths, a transaction can execute along the default path. The default path is the simplest possible way to connect the implied steps of the transaction.

-

The default path could be any of the following:

-
    -
  • If the transaction is uses only one currency (regardless of issuer), then the default path assumes the payment should ripple through the addresses involved. This path only works if those addresses are connected by trust lines.
      -
    • If SendMax is omitted, or the issuer of the SendMax is the sender, the default path needs a trust line from the sending Account to the issuer of the destination Amount to work.
      • -
    • If the SendMax and Amount have different issuer values, and neither are the sender or receiver, the default path is probably not useful because it would need to ripple across a trust line between the two issuers. Ripple (the company) typically discourages issuers from trusting one another directly.
      • -
    -
    • -
  • For cross-currency transactions, the default path uses the order book between the source currency (as specified in the SendMax field) and the destination currency (as specified in the Amount field).
    • -
-

The following diagram enumerates all possible default paths: -Diagram of default paths

-

You can use the tfNoDirectRipple flag to disable the default path. In this case, the transaction can only execute using the paths explicitly included in the transaction. Traders can use this option to take arbitrage opportunities.

-

Path Specifications

-

A path set is an array. Each member of the path set is another array that represents an individual path. Each member of a path is an object that specifies the step. A step has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
accountString - Address(Optional) If present, this path step represents rippling through the specified address. MUST NOT be provided if this step specifies the currency or issuer fields.
currencyString - Currency Code(Optional) If present, this path step represents changing currencies through an order book. The currency specified indicates the new currency. MUST NOT be provided if this step specifies the account field.
issuerString - Address(Optional) If present, this path step represents changing currencies and this address defines the issuer of the new currency. If omitted in a step with a non-XRP currency, a previous step of the path defines the issuer. If present when currency is omitted, indicates a path step that uses an order book between same-named currencies with different issuers. MUST be omitted if the currency is XRP. MUST NOT be provided if this step specifies the account field.
typeIntegerDEPRECATED (Optional) An indicator of which other fields are present.
type_hexStringDEPRECATED: (Optional) A hexadecimal representation of the type field.
-

In summary, the following combination of fields are valid, optionally with type, type_hex, or both:

-
    -
  • account by itself
    • -
  • currency by itself
    • -
  • currency and issuer as long as the currency is not XRP
    • -
  • issuer by itself
    • -
-

Any other use of account, currency, and issuer fields in a path step is invalid.

-

The type field, used for the binary serialization of a path set, is actually constructed through bitwise operations on a single integer. The bits are defined as follows:

- - - - - - - - - - - - - - - - - - - - - - - - - -
Value (Hex)Value (Decimal)Description
0x011A change of address (rippling): the account field is present.
0x1016A change of currency: the currency field is present.
0x2032A change of issuer: the issuer field is present.
-
-
-
- - - - \ No newline at end of file diff --git a/concept-reaching-consensus.html b/concept-reaching-consensus.html deleted file mode 100644 index 6a3432e871..0000000000 --- a/concept-reaching-consensus.html +++ /dev/null @@ -1,247 +0,0 @@ - - - - - - - - Reaching Consensus in the XRP Ledger - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

Reaching Consensus in the XRP Ledger

-

The XRP Ledger is a universal payment system enabling users to transfer funds (including fiat currencies, digital currencies and other forms of value) across national boundaries as seamlessly as sending an email. Like other digital currencies such as Bitcoin, the XRP Ledger enables peer-to-peer transaction settlement across a decentralized network of computers. Unlike other digital currency protocols,the XRP Ledger also allows users to transact in currencies other than the ledger's native currency, XRP. In addition, the technology enables near real-time settlement (three to six seconds) and is built to route each international transaction to the cheapest FX bid/ask spread available in the network.

-

Background

-

Mechanics

-

At the core, the XRP Ledger is a shared database that records information such as accounts, balances, and offers to trade assets. Operations such as creating accounts, making payments, and converting assets are performed through signed instructions called “transactions.”

-

As a cryptographic system, the owners of XRP Ledger accounts are identified by cryptographic identities. Transactions are authorized by cryptographic signatures matching these identities. Every server processes every transaction according to the same deterministic, known rules. Ultimately, the goal is for every server in the network to have an identical, complete copy of the ledger state, without needing a single central authority to arbitrate transactions.

-

The Double Spend Problem

-

The "double spend" problem is a fundamental challenge to operating any sort of payment system. The problem comes from the requirement that when money is spent in one place, it can't also be spent in another place. More generally, the problem occurs when you have any two transactions such that either one is valid but not both together.

-

Suppose Alice, Bob, and Charlie are using a payment system, and Alice has a balance of $10. For the payment system to be useful, Alice must be able to send her $10 to Bob, or to Charlie. However, if Alice tries to send $10 to Bob and also send $10 to Charlie at the same time, that's where the double spend problem comes in.

-

If Alice can send the "same" $10 to both Charlie and Bob, the payment system ceases to be useful. The payment system needs a way to choose which transaction should succeed and which should fail, in such a way that all participants agree on which transaction has happened. Either of those two transactions is equally valid on its own. However, different participants in the payment system may have a different view of which transaction came first.

-

Conventionally, payment systems solve the double spend problem by having a central authority track and approve transactions. For example, a bank decides to clear a deck based on the issuer's available balance, of which the bank is the sole custodian. In such a system, all participants follow the central authority's decisions.

-

Distributed ledger technologies, like the XRP Ledger, have no central authority. They must solve the double spend problem in some other way.

-

How Consensus Works

-

Simplfying the Problem

-

Much of the double spend problem can be solved by well-known rules such as prohibiting an account from spending funds it does not have. In fact, the double spend problem can be reduced to putting transactions in order.

-

Consider the example of Alice trying to send the same $10 to both Bob and Charlie. If the payment to Bob is known to be first, then everyone can agree that she has the funds to pay Bob. If the payment to Charlie is known to be second, then everyone can agree that she cannot send those funds to Charlie because the money has already been sent to Bob.

-

We can also order transactions by deterministic rules. Because transactions are collections of digital information, it's trivial for a computer to sort them.

-

This would be sufficient to solve the double spend problem without a central authority, but it would require us to have every transaction that would ever occur (so that we could sort them) before we could be certain of the results of any transaction. Obviously, this is impractical.

-

However, if we could collect transactions into groups and agree on those groupings, we could sort the transactions within that group. That is, so long as every participant agrees on which transactions are to be processed as a unit, they can use deterministic rules to solve the double spend problem without any need for a central authority. The participants simply each sort the transactions and apply them in a deterministic way following the known rules. The XRP Ledger solves the double-spend problem in exactly this way.

-

The XRP Ledger allows multiple conflicting transactions to be in the agreed group. The group of transactions is executed according to deterministic rules, so whichever transaction comes first according to the sorting rules succeeds and whichever conflicting transaction comes second fails.

-

Consensus Rules

-

The primary role of consensus is for participants in the process to agree on which transactions are to be processed as a group to resolve the double spend problem. There are four reasons this agreement is easier to achieve than might be expected:

-
    -
  1. If there is no reason a transaction should not be included in such a group of transactions, all honest participants will agree to include it. If all participants already agree, consensus has no work to do.
    2. -
  2. If there is any reason at all a transaction should not be included in such a group of transactions, all honest participants are willing to exclude it. If the transaction is still valid, there is no reason not to include it in the next round, and they should all agree to include it then.
    3. -
  3. It is extremely rare for a participant to particularly care how the transactions were grouped. Agreement is easiest when everyone’s priority is reaching agreement and only challenging when there are diverging interests.
    4. -
  4. Deterministic rules can be used even to form the groupings, leading to disagreement only in edge cases. For example, if there are two conflicting transactions in a round, deterministic rules can be used to determine which is included in the next round.
    5. -
-

Every participant’s top priority is correctness. They must first enforce the rules to be sure nothing violates the integrity of the shared ledger. For example, a transaction that is not properly signed must never be processed (even if other participants want to be processed). However, every honest participant’s second priority is agreement. A network with possible double spends has no utility at all. Agreement is facilitated by the fact that every honest participant values it above everything but correctness.

-

Consensus Rounds

-

A consensus round is an attempt to agree on a group of transactions so they can be processed. A consensus round starts with each participant who wishes to do so taking an initial position. This is the set of valid transactions they have witnessed.

-

Participants then “avalanche” to consensus: If a particular transaction does not have majority support, participants agree to defer that transaction. If a particular transaction does have majority support, participants agree to include the transaction. Thus slight majorities rapidly become full support and slight minorities rapidly become universal rejection from the current round.

-

To prevent consensus from stalling near 50% and to reduce the overlap required for reliable convergence, the required threshold to include a transaction increases over time. Initially, participants continue to agree to include a transaction if 50% or more of other participants agree. If participants disagree, they increase this threshold, first to 60% and then even higher, until all disputed transactions are removed from the current set. Any transactions removed this way are deferred to the next ledger version.

-

When a participant sees a supermajority that agrees on the set of transactions to next be processed, it declares a consensus to have been reached.

-

Consensus Can Fail

-

It is not practical to develop a consensus algorithm that never fails to achieve perfect consensus. To understand why, consider how the consensus process terminates. At some point, each participant must declare that a consensus has been reached and that some set of transactions is known to be the result of the process. This declaration commits that participant irrevocably to some particular set of transactions as the result of the consensus process.

-

Clearly, some participant must do this first or no participant will ever do it, and they will never reach a consensus. Now, consider the participant that does this first. When this participant decides that consensus is finished, other participants have not yet made that decision. If they were incapable of changing the agreed set from their point of view, they would have already decided consensus was finished. So they must be still capable of changing their agreed set.

-

In other words, for the consensus process to ever terminate, some participant must declare that consensus has been reached on a set of transactions even though every other participant is theoretically still capable of changing the agreed upon set of transactions.

-

Imagine a group of people in a room trying to agree which door they should use to exit. No matter how much the participants discuss, at some point, someone has to be the first one to walk out of a door, even though the people behind that person could still change their minds and leave through the other door.

-

The probability of this kind of failure can be made very low, but it cannot be reduced to zero. The engineering tradeoffs are such that driving this probability down below about one in a thousand makes consensus significantly slower, and less able to tolerate network and endpoint failures.

-

How the XRP Ledger Handles Consensus Failure

-

After a consensus round completes, each participant applies the set of transactions that they believe were agreed to. This results in constructing what they believe the next state of the ledger should be.

-

Participants that are also validators then publish a cryptographic fingerprint of this next ledger. We call this fingerprint a “validation vote”. If the consensus round succeeded, the vast majority of honest validators should be publishing the same fingerprint.

-

Participants then collect these validation votes. From the validation votes, they can determine whether the previous consensus round resulted in a supermajority of participants agreeing on a set of transactions or not.

-

Participants then find themselves in one of three cases, in order of probability:

-
    -
  1. They built the same ledger a supermajority agreed to. In this case, they can consider that ledger fully validated and rely on its contents.
    2. -
  2. They built a different ledger than a supermajority agreed on. In this case, they must build and accept the supermajority ledger. This typically indicates that they declared a consensus early and many other participants changed after that. They must “jump” to the super-majority ledger to resume operation.
    3. -
  3. No supermajority is clear from the received validations. In this case, the previous consensus round was wasted and a new round must occur before any ledger can be validated.
    4. -
-

Of course, case 1 is the most common. Case 2 does no harm to the network whatsoever. A small percentage of the participants could even fall into case 2 every round, and the network would operate with no issues. Even those participants can recognize that they did not build the same ledger as the supermajority, so they know not to report their results as final until they are in agreement with the supermajority.

-

Case 3 results in the network losing a few seconds in which it could have made forward progress, but is extremely rare. In this case, the subsequent consensus round is much less likely to fail because disagreements are resolved in the consensus process and only remaining disagreements can cause a failure.

-

On rare occasions, the network as a whole fails to make forward progress for a few seconds. In exchange, average transaction confirmation times are low.

-

Philosophy

-

One form of reliability is the ability of a system to provide results even under conditions where some components have failed, some participants are malicious, and so on. While this is important, there is another form of reliability that is much more important in cryptographic payment systems — the ability of a system to produce results that can be relied upon. That is, when a system reports a result to us as reliable, we should be able to rely on that result.

-

Real-world systems, however, face operational conditions in which both kinds of reliability can be compromised. These include hardware failures, communication failures, and even dishonest participants. Part of the XRP Ledger's design philosophy is to detect conditions where the reliability of results are impaired and report them, rather than providing results that must not be relied on.

-

The XRP Ledger's consensus algorithm provides a robust alternative to proof of work systems, without consuming computational resources needlessly. Byzantine failures are possible, and do happen, but the consequence is only minor delays. In all cases, the XRP Ledger's consensus algorithm reports results as reliable only when they in fact are.

-
-
-
- - - - \ No newline at end of file diff --git a/concept-reserves.html b/concept-reserves.html deleted file mode 100644 index 9d7acc914f..0000000000 --- a/concept-reserves.html +++ /dev/null @@ -1,211 +0,0 @@ - - - - - - - - Reserves - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

Reserves

-

The XRP Ledger applies reserve requirements, in XRP, to protect the shared global ledger from growing excessively large as the result of spam or malicious usage. The goal is to constrain the growth of the ledger to match improvements in technology so that a current commodity-level machine can always fit the current ledger in RAM and the full ledger history on disk.

-

To submit transactions, an address must hold a minimum amount of XRP in the shared global ledger. You cannot send this XRP to other addresses. To fund a new address, you must send enough XRP to meet the reserve requirement.

-

The current minimum reserve requirement is 20 XRP. (This is the cost of an address that owns no other objects in the ledger.)

-

Base Reserve and Owner Reserve

-

The reserve requirement is divided into two parts:

-
    -
  • The Base Reserve is a minimum amount of XRP that is required for every address in the ledger. Currently, this is 20 XRP (20000000 drops).
    • -
  • The Owner Reserve is an increase to the reserve requirement for each object that the address owns in the ledger. Currently, this is 5 XRP (5000000 drops) per item.
    • -
-

Owner Reserves

-

Many objects in the ledger are owned by a particular address, and count toward the reserve requirement of that address. When objects are removed from the ledger, they no longer count against their owner's reserve requirement.

-
    -
  • Offers are owned by the address that placed them. Transaction processing automatically removes Offers that are fully consumed or found to be unfunded. Alternatively, the owner can cancel an Offer by sending an OfferCancel transaction, or by sending an OfferCreate transaction that contains an OfferSequence parameter.
    • -
  • Trust lines are shared between two addresses. The owner reserve can apply to one or both of the addresses, depending on whether the fields that address controls are in their default state. See Contributing to the Owner Reserve for details.
    • -
  • A single SignerList counts as 3 to 10 objects for purposes of the owner reserve, depending on how many members it has. See also: SignerLists and Reserves.
    • -
  • Held Payments (Escrow) are owned by the address that placed them.
    • -
  • Owner directories list all the ledger nodes that contribute to an address's owner reserve. However, the owner directory itself does not count towards the reserve.
    • -
-

Owner Reserve Edge Cases

-

The XRP Ledger considers an OfferCreate transaction to be an explicit statement of willingness to hold an asset. Consuming the offer automatically creates a trust line (with limit 0, and a balance above that limit) for the taker_pays currency if such a trust line does not exist. However, if the offer's owner does not hold enough XRP to also meet the owner reserve requirement of the new trust line, the offer is considered unfunded. See also: Lifecycle of an Offer.

-

Going Below the Reserve Requirement

-

During transaction processing, the transaction cost destroys some of the sending address's XRP balance. This can cause an address's XRP to go below the reserve requirement.

-

When an address holds less XRP than its current reserve requirement, it cannot send new transactions that would transfer XRP to others, or increase its own reserve. Even so, the address continues to exist in the ledger and can send other transactions as long as it has enough XRP to pay the transaction cost. The address can become able to send all types of transactions again if it receives enough XRP to meet its reserve requirement again, or if the reserve requirement decreases to less than the address's XRP holdings.

-

Tip: When an address is below the reserve requirement, it can send new OfferCreate transactions to acquire more XRP, or other currencies on its existing trust lines. These transactions cannot create new trust lines, or Offer nodes in the ledger, so they can only execute trades that consume Offers that are already in the order books.

-

Changing the Reserve Requirements

-

The XRP Ledger has a mechanism to adjust the reserve requirements for long-term changes in the value of XRP. Any changes have to be approved by the consensus process. See Fee Voting for more information.

-
-
-
- - - - \ No newline at end of file diff --git a/concept-stand-alone-mode.html b/concept-stand-alone-mode.html deleted file mode 100644 index 87d121b6ed..0000000000 --- a/concept-stand-alone-mode.html +++ /dev/null @@ -1,249 +0,0 @@ - - - - - - - - Stand-Alone Mode - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

Stand-Alone Mode

-

You can run rippled in stand-alone mode without a consensus of trusted servers. In stand-alone mode, rippled does not communicate with any other servers in the XRP Ledger peer-to-peer network, but you can do most of the same actions on your local server only. Stand-alone provides a method for testing rippled behavior without being tied to the live network. For example, you can test the effects of Amendments before those Amendments have gone into effect across the decentralized network.

-

When you run rippled in stand-alone mode, you have to tell it what ledger version to start from:

- -

Caution: In stand-alone mode, you must manually advance the ledger.

-

New Genesis Ledger

-

In stand-alone mode, you can have rippled create a new genesis ledger. This provides a known state, with none of the ledger history from the production XRP Ledger. (This is very useful for unit tests, among other things.)

-
    -
  • To start rippled in stand-alone mode with a new genesis ledger, use the -a and --start options:
    • -
-
rippled -a --start --conf=/path/to/rippled.cfg
-
-

In a genesis ledger, the genesis address holds all 100 billion XRP. The keys of the genesis address are hardcoded as follows:

-

Address: rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh

-

Secret: snoPBrXtMeMyMHUVTgbuqAfg1SUTb ("masterpassphrase")

-

Caution: If you create a new genesis ledger, the hard-coded default Reserve is 200 XRP minimum for funding a new address, with an increment of 50 XRP per object in the ledger. These values are higher than the current reserve requirements of the production network. (See also: Fee Voting)

-

New in: rippled 0.50.0 If you start a new genesis ledger with --start, all The genesis ledger contains an EnableAmendment pseudo-transaction to turn on all Amendments natively supported by the rippled server, except for amendments that you explicitly disable in the configuration file. The effects of those amendments are available starting from the very next ledger version.

-

Load Saved Ledger

-

You can start with a ledger version that was saved to disk if your rippled server was previously synced with the XRP Ledger peer-to-peer network (either the production network or the Test Net).

-

1. Start rippled normally.

-

To load an existing ledger, you must first retrieve that ledger from the network. Start rippled in online mode as normal:

-
rippled --conf=/path/to/rippled.cfg
-
-

2. Wait until rippled is synced.

-

Use the server_info command to check the state of your server relative to the network. Your server is synced when the server_state value shows any of the following values:

-
    -
  • full
    • -
  • proposing
    • -
  • validating
    • -
-

For more information, see Possible Server States.

-

3. (Optional) Retrieve specific ledger versions.

-

If you only want the most recent ledger, you can skip this step.

-

If you want to load a specific historical ledger version, use the ledger_request command to make rippled fetch it. If rippled does not already have the ledger version, you may have to run the ledger_request command multiple times until it has finished retrieving the ledger.

-

If you want to replay a specific historical ledger version, you must fetch both the ledger version to replay and the ledger version before it. (The previous ledger version sets up the initial state upon which you apply the changes described by the ledger version you replay.)

-

4. Shut down rippled.

-

Use the stop command:

-
rippled stop --conf=/path/to/rippled.cfg
-
-

5. Start rippled in stand-alone mode.

-

To load the most recent ledger version, you can use the -a and --load options when starting the server:

-
rippled -a --load --conf=/path/to/rippled.cfg
-
-

To instead load a specific historical ledger, use the --load parameter along with the --ledger parameter, providing the ledger index or identifying hash of the ledger version to load:

-
rippled -a --load --ledger 19860944 --conf=/path/to/rippled.cfg
-
-

6. Manually advance the ledger.

-

When you load a ledger with --ledger in stand-alone mode, it goes to the current open ledger, so you must manually advance the ledger:

-
rippled ledger_accept --conf=/path/to/rippled.cfg
-
-

Advancing Ledgers in Stand-Alone Mode

-

In stand-alone mode, rippled does not communicate to other members of the peer-to-peer network or participate in a consensus process. Instead, you must manually advance the ledger index using the ledger_accept command:

-
rippled ledger_accept --conf=/path/to/rippled.cfg
-
-

In stand-alone mode, rippled makes no distinction between a "closed" ledger version and a "validated" ledger version. (For more information about the difference, see The XRP Ledger Consensus Process.)

-

Whenever rippled closes a ledger, it reorders the transactions according to a deterministic but hard-to-game algorithm. (This is an important part of consensus, since transactions may arrive at different parts of the network in different order.) When using rippled in stand-alone mode, you should manually advance the ledger before submitting a transaction that depends on the result of a transaction from a different address. Otherwise, the two transactions might be executed in reverse order when the ledger is closed. Note: You can safely submit multiple transactions from a single address to a single ledger, because rippled sorts transactions from the same address in ascending order by Sequence number.

- -
-
-
- - - - \ No newline at end of file diff --git a/concept-transaction-cost.html b/concept-transaction-cost.html deleted file mode 100644 index 9f5ab2791f..0000000000 --- a/concept-transaction-cost.html +++ /dev/null @@ -1,363 +0,0 @@ - - - - - - - - Transaction Cost - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

Transaction Cost

-

To protect the XRP Ledger from being disrupted by spam and denial-of-service attacks, each transaction must destroy a small amount of XRP. This transaction cost is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network.

-

Every transaction must specify how much XRP to destroy to pay the transaction cost.

-

Current Transaction Cost

-

The current minimum transaction cost required by the network for a standard transaction is 0.00001 XRP (10 drops). It sometimes increases due to higher than usual load.

-

You can also query rippled for the current transaction cost.

-

Special Transaction Costs

-

Some transactions have different transaction costs:

- - - - - - - - - - - - - - - - - - - - - - - - - -
TransactionCost Before Load Scaling
Reference Transaction (Most transactions)10 drops
Key Reset Transaction0
Multi-signed Transaction10 drops × (1 + Number of Signatures Provided)
EscrowFinish Transaction with Fulfillment10 drops × (33 + (Fulfillment size in bytes ÷ 16))
-

Beneficiaries of the Transaction Cost

-

The transaction cost is not paid to any party: the XRP is irrevocably destroyed. Since no new XRP can ever be created, this makes XRP more scarce and benefits all holders of XRP by making XRP more valuable.

-

Load Cost and Open Ledger Cost

-

When the FeeEscalation amendment is enabled, there are two thresholds for the transaction cost:

-
    -
  • If the transaction cost does not meet a rippled server's load-based transaction cost threshold, the server ignores the transaction completely. (This logic is essentially unchanged with or without the amendment.)
    • -
  • If the transaction cost does not meet a rippled server's open ledger cost threshold, the server queues the transaction for a later ledger.
    • -
-

This divides transactions into roughly three categories:

-
    -
  • Transactions that specify a transaction cost so low that they get rejected by the load-based transaction cost.
    • -
  • Transactions that specify a transaction cost high enough to be included in the current open ledger.
    • -
  • Transactions in between, which get queued for a later ledger version.
    • -
-

Local Load Cost

-

Each rippled server maintains a cost threshold based on its current load. If you submit a transaction with a Fee value that is lower than current load-based transaction cost of the rippled server, that server neither applies nor relays the transaction. (Note: If you submit a transaction through an admin connection, the server applies and relays the transaction as long as the transaction meets the un-scaled minimum transaction cost.) A transaction is very unlikely to survive the consensus process unless its Fee value meets the requirements of a majority of servers.

-

Open Ledger Cost

-

The rippled server has a second mechanism for enforcing the transaction cost, called the open ledger cost. A transaction can only be included in the open ledger if it meets the open ledger cost requirement in XRP. Transactions that do not meet the open ledger cost may be queued for a following ledger instead.

-

For each new ledger version, the server picks a soft limit on the number of transactions to be included in the open ledger, based on the number of transactions in the previous ledger. The open ledger cost is equal to the minimum un-scaled transaction cost until the number of transactions in the open ledger is equal to the soft limit. After that, the open ledger cost increases exponentially for each transaction included in the open ledger. For the next ledger, the server increases the soft limit if the current ledger contained more transactions than the soft limit, and decreases the soft limit if the consensus process takes more than 5 seconds.

-

The open ledger cost requirement is proportional to the normal cost of the transaction, not the absolute transaction cost. Transaction types that have a higher-than-normal requirement, such as multi-signed transactions must pay more to meet the open ledger cost than transactions which have minimum transaction cost requirements.

-

See also: Fee Escalation explanation in rippled repository.

-

Queued Transactions

-

When rippled receives a transaction that meet the server's local load cost but not the open ledger cost, the server estimates whether the transaction is "likely to be included" in a later ledger. If so, the server adds the transaction to the transaction queue and relays the transaction to other members of the network. Otherwise, the server discards the transaction. The server tries to minimize the amount of network load caused by transactions that would not pay a transaction cost, since the transaction cost only applies when a transaction is included in a validated ledger.

-

When the current open ledger closes and the server starts a new open ledger, the server starts taking transactions from the queue to include in the new open ledger. The transaction queue is sorted with the transactions that would pay the highest transaction cost first, proportional to the reference cost of those transactions. Transactions that pay the same transaction cost are queued in the order the server receives them.

-

Note: When rippled queues a transaction, the provisional transaction response code is terQUEUED. This means that the transaction is likely to succeed in a future ledger version. As with all provisional response codes, the outcome of the transaction is not final until the transaction is either included in a validated ledger, or rendered permanently invalid.

-

Queuing Restrictions

-

The rippled server uses a variety of heuristics to estimate which transactions are "likely to be included in a ledger." The current implementation uses the following rules to decide which transactions to queue:

-
    -
  • Transactions must be properly-formed and authorized with valid signatures.
    • -
  • Transactions with an AccountTxnID field cannot be queued.
    • -
  • A single sending address can have at most 10 transactions queued at the same time. In order for a transaction to be queued, the sender must have enough XRP to pay all the XRP costs of all the sender's queued transactions including both the Fee fields and the sum of the XRP that each transaction could send. New in: rippled 0.32.0
    • -
  • If a transaction affects how the sending address authorizes transactions, no other transactions from the same address can be queued behind it. New in: rippled 0.32.0
    • -
  • If the transaction includes a LastLedgerSequence field, the value of that field must be at least the current ledger index + 2.
    • -
-

Fee Averaging

-

New in: rippled 0.33.0

-

If a sending address has one or more transactions queued, that sender can "push" the existing queued transactions into the open ledger by submitting a new transaction with a high enough transaction cost to pay for all of them. Specifically, the new transaction must increase the total transaction cost of the queued transactions from the same sending address, including the new transaction, to cover the open ledger cost of each transaction as it gets added to the ledger. The total must include the increased open ledger cost for each new transaction. The transactions must still follow the other queuing restrictions and the sending address must have enough XRP to pay the transaction costs of all the queued transactions.

-

This feature helps you work around a particular situation. If you submitted one or more transactions with a low cost, which got queued, you cannot send new transactions from the same address unless you do one of the following:

-
    -
  • Wait for the queued transactions to be included in a validated ledger, or
    • -
  • Wait for the queued transactions to be permanently invalidated if the transactions have the LastLedgerSequence field set, or
    • -
  • Cancel the queued transactions by submitting a new transaction with the same sequence number.
    • -
-

If none of the above occur, transactions can stay in the queue for a theoretically unlimited amount of time, while other senders can "cut in line" by submitting transactions with higher transaction costs. Since signed transactions are immutable, you cannot increase the transaction cost of the queued transactions to increase their priority. If you do not want to invalidate the previously submitted transactions, fee averaging provides a workaround. If you increase the transaction cost of your new transaction to compensate, you can ensure the queued transactions are included in an open ledger right away.

-

Reference Transaction Cost

-

The "Reference Transaction" is the cheapest (non-free) transaction, in terms of the necessary transaction cost before load scaling. Most transactions have the same cost as the reference transaction. Some transactions, such as multi-signed transactions, require a multiple of this cost instead. When the open ledger cost escalates, the requirement is proportional to the basic cost of the transaction.

-

Fee Levels

-

Fee levels represent the proportional difference between the minimum cost and the actual cost of a transaction. The Open Ledger Cost is measured in fee levels instead of absolute cost. See the following table for a comparison:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TransactionMinimum cost in dropsMinimum cost in Fee levelsDouble cost in dropsDouble cost in fee levels
Reference transaction (most transactions)1025620512
Multi-signed transaction with 4 signatures50256100512
Key reset transaction0(Effectively infinite)N/A(Effectively infinite)
EscrowFinish transaction with 32-byte preimage.350256700512
-

Querying the Transaction Cost

-

The rippled APIs have two ways to query the local load-based transaction cost: the server_info command (intended for humans) and the server_state command (intended for machines).

-

If the FeeEscalation amendment is enabled, you can use the fee command to check the open ledger cost.

-

server_info

-

The server_info command reports the unscaled minimum XRP cost, as of the previous ledger, as validated_ledger.base_fee_xrp, in the form of decimal XRP. The actual cost necessary to relay a transaction is scaled by multiplying that base_fee_xrp value by the load_factor parameter in the same response, which represents the server's current load level. In other words:

-

Current Transaction Cost in XRP = base_fee_xrp × load_factor

-

server_state

-

The server_state command returns a direct representation of rippled's internal load calculations. In this case, the effective load rate is the ratio of the current load_factor to the load_base. The validated_ledger.base_fee parameter reports the minimum transaction cost in drops of XRP. This design enables rippled to calculate the transaction cost using only integer math, while still allowing a reasonable amount of fine-tuning for server load. The actual calculation of the transaction cost is as follows:

-

Current Transaction Cost in Drops = (base_fee × load_factor) ÷ load_base

-

Specifying the Transaction Cost

-

Every signed transaction must include the transaction cost in the Fee field. Like all fields of a signed transaction, this field cannot be changed without invalidating the signature.

-

As a rule, the XRP Ledger executes transactions exactly as they are signed. (To do anything else would be difficult to coordinate across a decentralized consensus network, at the least.) As a consequence of this, every transaction destroys the exact amount of XRP specified by the Fee field, even if the specified amount is much more than the current minimum transaction cost for any part of the network. The transaction cost can even destroy XRP that would otherwise be set aside for an account's reserve requirement.

-

Before signing a transaction, we recommend looking up the current load-based transaction cost. If the transaction cost is high due to load scaling, you may want to wait for it to decrease. If you do not plan on submitting the transaction immediately, we recommend specifying a slightly higher transaction cost to account for future load-based fluctuations in the transaction cost.

-

Automatically Specifying the Transaction Cost

-

When you sign a transaction online, you can omit the Fee field. In this case, rippled or RippleAPI checks the state of the peer-to-peer network for the current requirement and adds a Fee value before signing the transaction. However, there are several drawbacks and limitations to automatically filling in the transaction cost in this manner:

-
    -
  • If the network's transaction cost goes up between signing and distributing the transaction, the transaction may not be confirmed.
      -
    • In the worst case, the transaction may be stuck in a state of being neither definitively confirmed or rejected, unless it included a LastLedgerSequence parameter or until you cancel it with a new transaction that uses the same Sequence number. See reliable transaction submission for best practices.
      • -
    -
    • -
  • You do not know in advance exactly what value you are signing for the Fee field.
      -
    • If you are using rippled, you can also use the fee_mult_max and fee_div_max parameters of the sign command to set a limit to the load scaling you are willing to sign.
      • -
    -
    • -
  • You cannot look up the current transaction cost from an offline machine.
    • -
  • You cannot automatically specify the transaction cost when multi-signing.
    • -
-

Transaction Costs and Failed Transactions

-

Since the purpose of the transaction cost is to protect the XRP Ledger peer-to-peer network from excessive load, it should apply to any transaction that gets distributed to the network, regardless of whether or not that transaction succeeds. However, to affect the shared global ledger, a transaction must be included in a validated ledger. Thus, rippled servers try to include failed transactions in ledgers, with tec status codes ("tec" stands for "Transaction Engine - Claimed fee only").

-

The transaction cost is only debited from the sender's XRP balance when the transaction actually becomes included in a validated ledger. This is true whether the transaction is considered successful or fails with a tec code.

-

If a transaction's failure is final, the rippled server does not relay it to the network. The transaction does not get included in a validated ledger, so it cannot have any effect on anyone's XRP balance.

-

Insufficient XRP

-

When a rippled server initially evaluates a transaction, it rejects the transaction with the error code terINSUF_FEE_B if the sending account does not have a high enough XRP balance to pay the XRP transaction cost. Since this is a ter (Retry) code, the rippled server retries the transaction without relaying it to the network, until the transaction's outcome is final.

-

When a transaction has already been distributed to the network, but the account does not have enough XRP to pay the transaction cost, the result code tecINSUFF_FEE occurs instead. In this case, the account pays all the XRP it can, ending with 0 XRP. This can occur because rippled decides whether to relay the transaction to the network based on its in-progress ledger, but transactions may be dropped or reordered when building the consensus ledger.

-

Key Reset Transaction

-

As a special case, an account can send a SetRegularKey transaction with a transaction cost of 0, as long as the account's lsfPasswordSpent flag is disabled. This transaction must be signed by the account's master key pair. Sending this transaction enables the lsfPasswordSpent flag.

-

This feature is designed to allow you to recover an account if the regular key is compromised, without worrying about whether the compromised account has any XRP available. This way, you can regain control of the account before you send more XRP to it.

-

The lsfPasswordSpent flag starts out disabled. It gets enabled when you send a SetRegularKey transaction signed by the master key pair. It gets disabled again when the account receives a Payment of XRP.

-

When the FeeEscalation amendment is enabled, rippled prioritizes key reset transactions above other transactions even though the nominal transaction cost of a key reset transaction is zero.

-

Changing the Transaction Cost

-

The XRP Ledger has a mechanism for changing the minimum transaction cost to account for long-term changes in the value of XRP. Any changes have to be approved by the consensus process. See Fee Voting for more information.

- -
-
-
- - - - \ No newline at end of file diff --git a/concept-transfer-fees.html b/concept-transfer-fees.html deleted file mode 100644 index 80bac8ffe6..0000000000 --- a/concept-transfer-fees.html +++ /dev/null @@ -1,210 +0,0 @@ - - - - - - - - Transfer Fees - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

Transfer Fees

-

The TransferRate setting in the XRP Ledger allows financial institutions that issue currency in the XRP Ledger to charge users a transfer fee for sending the currencies issued by that financial institution. The sender of the transfer is debited an extra percentage based on the transfer fee, while the recipient of the transfer is credited the intended amount. The difference is the transfer fee, which becomes the property of the issuing address, and is no longer tracked in the XRP Ledger. The transfer fee does not apply when sending or receiving directly to and from the issuing account, but it does apply when transferring from an operational address to another user.

-

XRP never has a transfer fee, because it never has an issuer.

-

For example, ACME Bank might set the transfer fee to 0.5% for ACME issuances. For the recipient of a payment to get 2 EUR.ACME, the sender must send 2.01 EUR.ACME. After the transaction, ACME's outstanding obligations in the XRP Ledger have decreased by 0.01€, which means that ACME no longer needs to hold that amount in the account backing its XRP Ledger issuances.

-

The following diagram shows an XRP Ledger payment of 2 EUR.ACME from Alice to Charlie with a transfer fee of 1%:

-

Alice sends 2,02€, Charlie receives 2,00€, and ACME owes 0,02€ less in the XRP Ledger

-

Transfer Fees in Payment Paths

- -

A transfer fee applies whenever an individual transfer would shift issuances from one party to another through the issuing account. In more complex transactions, this can occur multiple times. Transfer fees apply starting from the end and working backwards, so that ultimately the sender of a payment must send enough to account for all fees. For example:

-

Diagram of cross-currency payment with transfer fees

-

In this scenario, Salazar (the sender) holds EUR issued by ACME, and wants to deliver 100 USD issued by WayGate to Rosa (the recipient). FXMaker is a currency trader with the best offer in the order book, at a rate of 1 USD.WayGate for every 0.9 EUR.ACME. If there were no transfer fees, Salazar could deliver 100 USD to Rosa by sending 90 EUR. However, ACME has a transfer fee of 1% and WayGate has a transfer fee of 0.2%. This means:

-
    -
  • FXMaker must send 100.20 USD.WayGate for Rosa to receive 100 USD.WayGate.
    • -
  • FXMaker's current ask is 90.18 EUR.ACME to send 100.20 USD.WayGate.
    • -
  • For FXMaker to receive 90.18 EUR.ACME, Salazar must send 91.0818 EUR.ACME.
    • -
-

Technical Details

-

The transfer fee is represented by a setting on the issuing address. The transfer fee has a maximum precision of 9 digits, and cannot be less than 0%. The TransferRate setting applies to all currencies issued by the same account. If you want to have different transfer fee percentages for different currencies, use different issuing addresses for each currency.

-

RippleAPI

-

In RippleAPI, the transfer fee is specified in the transferRate field, as a decimal which represents the amount you must send for the recipient to get 1 unit of the same currency. A transferRate of 1.005 is equivalent to a transfer fee of 0.5%. By default, the transferRate is set to no fee. The value of transferRate cannot be less than 1.0 or more than 4.294967295. The value null is a special case for no fee, equivalent to 1000000000.

-

A financial institution can send a Settings transaction from its issuing address to change the transferRate for its issuances.

-

You can check an account's transferRate with the getSettings method.

-

rippled

-

In rippled's JSON-RPC and WebSocket APIs, the transfer fee is specified in the TransferRate field, as an integer which represents the amount you must send for the recipient to get 1 billion units of the same currency. A TransferRate of 1005000000 is equivalent to a transfer fee of 0.5%. By default, the TransferRate is set to no fee. The value of TransferRate cannot be less than 1000000000 or more than 4294967295 (the maximum value of a 32-bit unsigned integer). The value 0 is special case for no fee, equivalent to 1000000000.

-

A financial institution can submit an AccountSet transaction from its issuing address to change the TransferRate for its issuances.

-

You can check an account's TransferRate with the account_info command. If the TransferRate is omitted, then that indicates no fee.

-
-
-
- - - - \ No newline at end of file diff --git a/tool/dactyl-config.yml b/dactyl-config.yml similarity index 98% rename from tool/dactyl-config.yml rename to dactyl-config.yml index f991f51dd3..9bc4fe1b19 100644 --- a/tool/dactyl-config.yml +++ b/dactyl-config.yml @@ -1,27 +1,25 @@ # Relative paths work OK as long as you start the tool from its local dir -template_path: . +template_path: tool # This folder gets copied into the output directory -template_static_path: ../assets +template_static_path: assets # Templates should have filenames starting in template- default_template: template-doc.html -pdf_template: template-forpdf.html +default_pdf_template: template-forpdf.html # HTML, PDF, GFM all get output here -out_path: .. +out_path: out # MD files should be here (and in subdirs) -content_path: ../content +content_path: content # This folder gets copied into the output directory -content_static_path: ../img +content_static_path: img # PDF creation needs a dir for temporary files temporary_files_path: /tmp/ -prince_executable: prince - default_filters: - multicode_tabs - standardize_header_ids diff --git a/data-api-v2-tool.html b/data-api-v2-tool.html deleted file mode 100644 index d75f35a95d..0000000000 --- a/data-api-v2-tool.html +++ /dev/null @@ -1,184 +0,0 @@ - - - - - - - - Data API v2 Tool - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-
-
-
-
-
-

REST Request

- -
-

-

-
Invalid JSON
-
-

https://data.ripple.com

-
-
- -
-
-

Response

-
- - -
-
-
-
-
-
-
-
- -
-
- - - - - - - - - - - - - - \ No newline at end of file diff --git a/gb-2015-05.html b/gb-2015-05.html deleted file mode 100644 index 1c01297547..0000000000 --- a/gb-2015-05.html +++ /dev/null @@ -1,197 +0,0 @@ - - - - - - - - GB-2015-05: Historical Ledger Query Migration - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

GB-2015-05: Historical Ledger Query Migration

-

In the past, Ripple Labs has supplied the rippled cluster, -s1.ripple.com, with full historical ledgers and transactions for public -access. Moving forward, we would like to inform our partners and -community to migrate to the Historical Database. Instructions for -migration are linked below. s1.ripple.com will no longer store full -history and provide the ability to query for historical ledgers and -transactions. In order to continue providing interested parties with -historical data, Ripple Labs will be offering a REST based service that -will provide the ability to query against all historical transactions -based upon a specific Ripple address. This however will not address the -ability to retrieve historical ledger states or historical order books. -Action Required For Historical Ledger Queries Starting on May 1, -2015, the public rippled cluster s1.ripple.com will store 1 month of -ledger history. Please consider one of the options below if historical -data is needed:

-
    -
  • To access historical transactions per account (account_tx and tx calls) : -
    • -
  • To access historical ledgers and order books
      -
    • Configure and start your own full history rippled server
      • -
    • Use s2.ripple.com public cluster.
      • -
    -
    • -
-
-
-
- - - - \ No newline at end of file diff --git a/gb-2015-06.html b/gb-2015-06.html deleted file mode 100644 index 3f7bb80f1f..0000000000 --- a/gb-2015-06.html +++ /dev/null @@ -1,182 +0,0 @@ - - - - - - - - GB-2015-06: Corrections to Autobridging - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

GB-2015-06: Corrections to Autobridging

-

Overview

-

Ripple Labs recently deployed a new feature to the Ripple network called autobridging. An error in the autobridging implementation caused some gateways to erroneously hold small balances. This error has been corrected. The total value miscredited across the Ripple network as a result of this error was less than $10.

-

Ripple Labs recommends gateways forgive these small errors. A gateway can forgive these errors by auditing their cold wallet balances for unwanted positive values and then using a payment transaction to zero those positive balances. This has the benefit of (1) the gateway not holding unwanted 3rd party balances in their cold wallet and (2) simplifying future audits by eliminating unnecessary balances.

-

The fix is currently deployed and may cause rippled servers not running the latest release to reacquire sync slightly more often than normal. Optionally, to avoid unnecessary resyncs, rippled servers can be upgraded to the latest release:

-

0.28.1-rc2

-

The latest release of rippled can be found on Github.

-

Additional Resources

- -
-
-
- - - - \ No newline at end of file diff --git a/index.html b/index.html deleted file mode 100644 index ae7ff7f259..0000000000 --- a/index.html +++ /dev/null @@ -1,224 +0,0 @@ - - - - - - - - Overview - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-
- - - -
-
-
-
-
- -
-
-

Welcome to the Developer Center

-

-Ripple’s distributed settlement network is built on open-source technology that anyone can use. Here are the tools developers can use to build solutions around the open-source platform.

-
-
-
-
-
- - - -
-
-
- -
-
- -
-
- -
-
- -
-
- -
-
-
- -
-
- - - - \ No newline at end of file diff --git a/reference-data-api.html b/reference-data-api.html deleted file mode 100644 index c74bac2d30..0000000000 --- a/reference-data-api.html +++ /dev/null @@ -1,8471 +0,0 @@ - - - - - - - - Ripple Data API v2 - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

Ripple Data API v2

-

The Ripple Data API v2 provides access to information about changes in the XRP Ledger, including transaction history and processed analytical data. This information is stored in a dedicated database, which frees rippled servers to keep fewer historical ledger versions. The Data API v2 also acts as data source for applications such as XRP Charts and ripple.com.

-

Ripple provides a live instance of the Data API with as complete a transaction record as possible at the following address:

-

https://data.ripple.com

-

More Information

-

The Ripple Data API v2 replaces the Historical Database v1 and the Charts API.

- -

API Method Reference

-

The Data API v2 provides a REST API with the following methods:

-

Ledger Contents Methods:

- -

Account Methods:

- -

External Information Methods:

- -

Validation Network Methods:

- -

Health Checks:

- -

Get Ledger

-

[Source]

-

Retrieve a specific Ledger by hash, index, date, or latest validated.

-

Request Format

-
- -
GET /v2/ledgers/{:identifier}
-
-
-

Try it!

-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - -
FieldValueDescription
ledger_identifierLedger Hash, Ledger Index, or Timestamp(Optional) An identifier for the ledger to retrieve: either the full hash in hex, an integer sequence number, or a date-time. If a date-time is provided, retrieve the ledger that was most recently closed at that time. If omitted, retrieve the latest validated ledger.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
transactionsBooleanIf true, include the identifying hashes of all transactions that are part of this ledger.
binaryBooleanIf true, include all transactions from this ledger as hex-formatted binary data. (If provided, overrides transactions.)
expandBooleanIf true, include all transactions from this ledger as nested JSON objects. (If provided, overrides binary and transactions.)
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
ledgerLedger objectThe requested ledger.
-

Example

-

Request:

-
GET /v2/ledgers/3170DA37CE2B7F045F889594CBC323D88686D2E90E8FFD2BBCD9BAD12E416DB5
-
-

Response:

-
200 OK
-{
-    "result": "success",
-    "ledger": {
-        "ledger_hash": "3170da37ce2b7f045f889594cbc323d88686d2e90e8ffd2bbcd9bad12e416db5",
-        "ledger_index": 8317037,
-        "parent_hash": "aff6e04f07f441abc6b4133f8c50c65935b817a85b895f06dba098b3fbc1be90",
-        "total_coins": 99999980165594400,
-        "close_time_res": 10,
-        "accounts_hash": "8ad73e49a34d8b9c31bc13b8a97c56981e45ee70225ef4892e8b198fec5a1f7d",
-        "transactions_hash": "33e0b9c5fd7766343e67854aed4222f5ed9c9507e0ec0d7ae7d54d0f17adb98e",
-        "close_time": 1408047740,
-        "close_time_human": "2014-08-14T20:22:20+00:00"
-    }
-}
-
-

Get Ledger Validations

-

[Source]

-

Retrieve a any validations recorded for a specific ledger hash. This dataset includes ledger versions that are outside the validated ledger chain. (New in v2.2.0)

-

Note: The Data API does not have a comprehensive record of all validations. The response only includes data that the Data API has recorded. Some ledger versions, especially older ledgers, may have no validations even if they were validated by consensus.

-

Request Format

-
- -
GET /v2/ledgers/{:ledger_hash}/validations
-
-
-

Try it!

-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - -
FieldValueDescription
ledger_hashHashLedger hash to retrieve validations for.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
limitIntegerMaximum results per page. Defaults to 200. Cannot be more than 1000.
markerStringPagination key from previously returned response.
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultString - successIndicates that the body represents a successful response.
ledger_hashString - HashThe identifying hash of the ledger version requested.
countIntegerNumber of validations returned.
markerString(May be omitted) Pagination marker.
validationsArray of Validation ObjectsAll known validation votes for the ledger version.
-

Example

-

Request:

-
GET /v2/ledgers/A10E9E338BA365D2B768814EC8B0A9A2D8322C0040735E20624AF711C5A593E7/validations?limit=2
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "ledger_hash": "A10E9E338BA365D2B768814EC8B0A9A2D8322C0040735E20624AF711C5A593E7",
-  "count": 2,
-  "marker": "A10E9E338BA365D2B768814EC8B0A9A2D8322C0040735E20624AF711C5A593E7|n9KDJnMxfjH5Ez8DeWzWoE9ath3PnsmkUy3GAHiVjE7tn7Q7KhQ2|20160608001732",
-  "validations": [
-    {
-      "count": 27,
-      "first_datetime": "2016-06-08T00:17:32.352Z",
-      "last_datetime": "2016-06-08T00:17:32.463Z",
-      "ledger_hash": "A10E9E338BA365D2B768814EC8B0A9A2D8322C0040735E20624AF711C5A593E7",
-      "reporter_public_key": "n9KJb7NMxGySRcjCqh69xEPMUhwJx22qntYYXsnUqYgjsJhNoW7g",
-      "signature": "304402204C751D0033070EBC008786F0ECCA8E29195FD7DD8D22498EB6E4E732905FC7090220091F458976904E7AE4633A1EC405175E6A126798E4896DD452853B887B1E6359",
-      "validation_public_key": "n949f75evCHwgyP4fPVgaHqNHxUVN15PsJEZ3B3HnXPcPjcZAoy7"
-    },
-    {
-      "count": 3,
-      "first_datetime": "2016-06-08T00:17:32.653Z",
-      "last_datetime": "2016-06-08T00:17:32.673Z",
-      "ledger_hash": "A10E9E338BA365D2B768814EC8B0A9A2D8322C0040735E20624AF711C5A593E7",
-      "reporter_public_key": "n9JCK5AML7Ejv3TcJmnvJk5qeYhf7Q9YwScjz5PhtUbtWCKH3NAm",
-      "signature": "3045022100A48E5AF6EA9D0ACA6FDE18536081A7D2182535579EA580C3D0B0F18C2556C5D30220521615A3D677376069F8F3E608B59F14482DDE4CD2A304DE578B6CCE2F5E8D54",
-      "validation_public_key": "n9K6YbD1y9dWSAG2tbdFwVCtcuvUeNkBwoy9Z6BmeMra9ZxsMTuo"
-    }
-  ]
-}
-
-

Get Ledger Validation

-

[Source]

-

Retrieve a validation vote recorded for a specific ledger hash by a specific validator. This dataset includes ledger versions that are outside the validated ledger chain. (New in v2.2.0)

-

Note: The Data API does not have a comprehensive record of all validations. The response only includes data that the Data API has recorded. Some ledger versions, especially older ledgers, may have no validations even if they were validated by consensus.

-

Request Format

-
- -
GET /v2/ledgers/{:ledger_hash}/validations/{:pubkey}
-
-
-

Try it!

-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
ledger_hashHashLedger hash to retrieve validations for.
pubkeyString - Base-58 Public KeyValidator public key.
-

This request takes no query parameters.

-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body containing a Validation Object with the following additional field:

- - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
-

Example

-

Request:

-
GET /v2/ledgers/A10E9E338BA365D2B768814EC8B0A9A2D8322C0040735E20624AF711C5A593E7/validations/n949f75evCHwgyP4fPVgaHqNHxUVN15PsJEZ3B3HnXPcPjcZAoy7
-
-

Response:

-
200 OK
-{
-  "count": 27,
-  "first_datetime": "2016-06-08T00:17:32.352Z",
-  "last_datetime": "2016-06-08T00:17:32.463Z",
-  "ledger_hash": "A10E9E338BA365D2B768814EC8B0A9A2D8322C0040735E20624AF711C5A593E7",
-  "reporter_public_key": "n9KJb7NMxGySRcjCqh69xEPMUhwJx22qntYYXsnUqYgjsJhNoW7g",
-  "signature": "304402204C751D0033070EBC008786F0ECCA8E29195FD7DD8D22498EB6E4E732905FC7090220091F458976904E7AE4633A1EC405175E6A126798E4896DD452853B887B1E6359",
-  "validation_public_key": "n949f75evCHwgyP4fPVgaHqNHxUVN15PsJEZ3B3HnXPcPjcZAoy7",
-  "result": "success"
-}
-
-

Get Transaction

-

[Source]

-

Retrieve a specific transaction by its identifying hash.

-

Request Format

-
- -
GET /v2/transactions/{:hash}
-
-
-

Try it!

-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - -
FieldValueDescription
hashString - HashThe identifying hash of the transaction.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - -
FieldValueDescription
binaryBooleanIf true, return transaction data in binary format, as a hex string. Otherwise, return transaction data as nested JSON. Defaults to false.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
transactionTransaction objectThe requested transaction.
-

Example

-

Request:

-
GET /v2/transactions/03EDF724397D2DEE70E49D512AECD619E9EA536BE6CFD48ED167AE2596055C9A
-
-

Response (trimmed for size):

-
200 OK
-{
-    "result": "success",
-    "transaction": {
-        "ledger_index": 8317037,
-        "date": "2014-08-14T20:22:20+00:00",
-        "hash": "03EDF724397D2DEE70E49D512AECD619E9EA536BE6CFD48ED167AE2596055C9A",
-        "tx": {
-            "TransactionType": "OfferCreate",
-            "Flags": 131072,
-            "Sequence": 159244,
-            "TakerPays": {
-                "value": "0.001567373",
-                "currency": "BTC",
-                "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-            },
-            "TakerGets": "146348921",
-            "Fee": "64",
-            "SigningPubKey": "02279DDA900BC53575FC5DFA217113A5B21C1ACB2BB2AEFDD60EA478A074E9E264",
-            "TxnSignature": "3045022100D81FFECC36A3DEF0922EB5D16F1AA5AA0804C30A18ED3B512093A75E87C81AD602206B221E22A4E3158785C109E7508624AD3DE5C0E06108D34FA709FCC9575C9441",
-            "Account": "r2d2iZiCcJmNL6vhUGFjs8U8BuUq6BnmT"
-        },
-        "meta": {
-            "TransactionIndex": 0,
-            "AffectedNodes": [
-                {
-                    "ModifiedNode": {
-                        "LedgerEntryType": "AccountRoot",
-                        "PreviousTxnLgrSeq": 8317036,
-                        "PreviousTxnID": "A56793D47925BED682BFF754806121E3C0281E63C24B62ADF7078EF86CC2AA53",
-                        "LedgerIndex": "2880A9B4FB90A306B576C2D532BFE390AB3904642647DCF739492AA244EF46D1",
-                        "PreviousFields": {
-                            "Balance": "275716601760"
-                        },
-                        "FinalFields": {
-                            "Flags": 0,
-                            "Sequence": 326323,
-                            "OwnerCount": 27,
-                            "Balance": "275862935331",
-                            "Account": "rfCFLzNJYvvnoGHWQYACmJpTgkLUaugLEw",
-                            "RegularKey": "rfYqosNivHQFJ6KpArouxoci3QE3huKNYe"
-                        }
-                    }
-                },
-
-                ...
-            ],
-            "TransactionResult": "tesSUCCESS"
-        }
-    }
-}
-
-

Get Transactions

-

[Source]

-

Retrieve transactions by time

-

Request Format

-
- -
GET /v2/transactions/
-
-
-

Try it!

-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
startString - TimestampFilter results to this time and later.
endString - TimestampFilter results to this time and earlier.
descendingBooleanIf true, return results in reverse chronological order. Defaults to false.
typeStringFilter transactions to a specific transaction type.
resultStringFilter transactions for a specific transaction result.
binaryBooleanIf true, return transactions in binary form. Defaults to false.
limitIntegerMaximum results per page. Defaults to 20. Cannot be more than 100.
markerStringPagination marker from a previous response.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
countIntegerNumber of Transactions returned.
markerString(May be omitted) Pagination marker.
transactionsArray of Transaction objectThe requested transactions.
-

Example

-

Request:

-
GET /v2/transactions/?result=tecPATH_DRY&limit=2&type=Payment
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "count": 2,
-  "marker": "20130106022000|000000053869|00000",
-  "transactions": [
-    {
-      "hash": "B8E4335A94438EC8209135A4E861A4C88F988C651B819DDAF2E8C55F9B41E589",
-      "date": "2013-01-02T20:13:40+00:00",
-      "ledger_index": 40752,
-      "ledger_hash": "55A900C2BA9483DC83F8FC065DE7789570662365BDE98EB75C5F4CE4F9B43214",
-      "tx": {
-        "TransactionType": "Payment",
-        "Flags": 0,
-        "Sequence": 61,
-        "Amount": {
-          "value": "96",
-          "currency": "USD",
-          "issuer": "rJ6VE6L87yaVmdyxa9jZFXSAdEFSoTGPbE"
-        },
-        "Fee": "10",
-        "SigningPubKey": "02082622E4DA1DC6EA6B38A48956D816881E000ACF0C5F5B52863B9F698799D474",
-        "TxnSignature": "304402200A0746192EBC7BC3C1B9D657F42B6345A49D75FE23EF340CB6F0427254C139D00220446BF9169C94AEDC87F56D01DB011866E2A67E2AADDCC45C4D11422550D044CB",
-        "Account": "rB5TihdPbKgMrkFqrqUC3yLdE8hhv4BdeY",
-        "Destination": "rJ6VE6L87yaVmdyxa9jZFXSAdEFSoTGPbE"
-      },
-      "meta": {
-        "TransactionIndex": 0,
-        "AffectedNodes": [
-          {
-            "ModifiedNode": {
-              "LedgerEntryType": "AccountRoot",
-              "PreviousTxnLgrSeq": 40212,
-              "PreviousTxnID": "F491DC8B5E51045D4420297293199039D5AE1EA0C6D62CAD9A973E3C89E40CD6",
-              "LedgerIndex": "9B242A0D59328CE964FFFBFF7D3BBF8B024F9CB1A212923727B42F24ADC93930",
-              "PreviousFields": {
-                "Sequence": 61,
-                "Balance": "8178999999999400"
-              },
-              "FinalFields": {
-                "Flags": 0,
-                "Sequence": 62,
-                "OwnerCount": 6,
-                "Balance": "8178999999999390",
-                "Account": "rB5TihdPbKgMrkFqrqUC3yLdE8hhv4BdeY"
-              }
-            }
-          }
-        ],
-        "TransactionResult": "tecPATH_DRY"
-      }
-    },
-    {
-      "hash": "1E1C14BF5E61682F3DC9D035D9908816497B8E8843E05C0EE98E06DFDDDAE920",
-      "date": "2013-01-05T08:43:10+00:00",
-      "ledger_index": 51819,
-      "ledger_hash": "88ED10E4E31FC7580285CF173B264690B0E8688A3FC9F5F9C62F1A295B96269D",
-      "tx": {
-        "TransactionType": "Payment",
-        "Flags": 0,
-        "Sequence": 10,
-        "Amount": {
-          "value": "2",
-          "currency": "EUR",
-          "issuer": "rfitr7nL7MX85LLKJce7E3ATQjSiyUPDfj"
-        },
-        "Fee": "10",
-        "SigningPubKey": "03FDDCD97668B686100E60653FD1E5210A8310616669AACB3A1FCC6D2C090CCB32",
-        "TxnSignature": "304402204F9BB7E37C14A3A3762E2A7DADB9A28D1AFFB3797521229B6FB98BA666B5491B02204F69AAEAFAC8FA473E52042FF06035AB3618A54E0B76C9852766D55184E98598",
-        "Account": "rhdAw3LiEfWWmSrbnZG3udsN7PoWKT56Qo",
-        "Destination": "rfitr7nL7MX85LLKJce7E3ATQjSiyUPDfj"
-      },
-      "meta": {
-        "TransactionIndex": 0,
-        "AffectedNodes": [
-          {
-            "ModifiedNode": {
-              "LedgerEntryType": "AccountRoot",
-              "PreviousTxnLgrSeq": 51814,
-              "PreviousTxnID": "5EC1C179996BD87E2EB11FE60A37ADD0FB2229ADC7D13B204FAB04FABED8A38D",
-              "LedgerIndex": "AC1B67084F84839A3158A4E38618218BF9016047B1EE435AECD4B02226AB2105",
-              "PreviousFields": {
-                "Sequence": 10,
-                "Balance": "10000999910"
-              },
-              "FinalFields": {
-                "Flags": 0,
-                "Sequence": 11,
-                "OwnerCount": 2,
-                "Balance": "10000999900",
-                "Account": "rhdAw3LiEfWWmSrbnZG3udsN7PoWKT56Qo"
-              }
-            }
-          }
-        ],
-        "TransactionResult": "tecPATH_DRY"
-      }
-    }
-  ]
-}
-
-

Get Payments

-

[Source]

-

Retrieve Payments over time, where Payments are defined as Payment type transactions where the sender of the transaction is not also the destination. (New in v2.0.4)

-

Results can be returned as individual payments, or aggregated to a specific list of intervals if currency and issuer are provided.

-

Request Format

-
- -
GET /v2/payments/
-
- -
GET /v2/payments/{:currency}
-
-
-

Try it!

-

This method uses the following URL parameters:

- - - - - - - - - - - - - - - -
FieldValueDescription
:currencyString(Optional) Currency code, followed by + and a counterparty address. (Or XRP with no counterparty.) If omitted, return payments for all currencies.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
startString - TimestampFilter results to this time and later.
endString - TimestampFilter results to this time and earlier.
intervalStringIf provided and currency is also specified, return results aggregated into intervals of the specified length instead of individual payments. Valid intervals are day, week, or month.
descendingBooleanIf true, return results in reverse chronological order. Defaults to false.
limitIntegerMaximum results per page. Defaults to 200. Cannot be more than 1000.
markerStringPagination key from previously returned response.
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
countIntegerNumber of payments returned.
markerString(May be omitted) Pagination marker.
paymentsArray of Payment Objects, or array of aggregate objects.The requested payments.
-
Aggregate Results
-

If the request specifies a currency and an interval, the result includes objects summarizing activity over a specific time period instead of listing individual payments. Each interval summary object has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
countNumberThe number of payments that occurred during this interval.
currencyString - Currency CodeThis summary describes payments that delivered the specified currency.
issuerString - Address(Omitted for XRP) This summary describes payments that delivered the currency issued by this address.
startString - TimestampThe start time of this interval.
total_amountNumberThe amount of the currency delivered during this interval.
average_amountNumberThe average amount of currency delivered by a single payment during this interval.
-

Example

-

Request:

-
GET /v2/payments/BTC+rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q?limit=2
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "count": 2,
-  "marker": "20131124004240|000003504935|00002",
-  "payments": [
-    {
-      "amount": "100.0",
-      "delivered_amount": "100.0",
-      "destination_balance_changes": [
-        {
-          "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-          "currency": "BTC",
-          "value": "100"
-        }
-      ],
-      "transaction_cost": "1.0E-5",
-      "source_balance_changes": [
-        {
-          "counterparty": "rwm98fCBS8tV1YB8CGho8zUPW5J7N41th2",
-          "currency": "BTC",
-          "value": "-100"
-        }
-      ],
-      "tx_index": 3,
-      "currency": "BTC",
-      "destination": "rwm98fCBS8tV1YB8CGho8zUPW5J7N41th2",
-      "executed_time": "2013-09-27T04:03:00Z",
-      "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-      "ledger_index": 2424349,
-      "source": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-      "source_currency": "BTC",
-      "tx_hash": "EDDE2601C38F886E1183B5E7E1BFD936105C76E3648E3FAD2A6C55E90BABDB47"
-    },
-    {
-      "amount": "0.2",
-      "delivered_amount": "0.2",
-      "destination_balance_changes": [
-        {
-          "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-          "currency": "BTC",
-          "value": "0.2"
-        }
-      ],
-      "transaction_cost": "1.5E-5",
-      "max_amount": "0.202",
-      "source_balance_changes": [
-        {
-          "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-          "currency": "BTC",
-          "value": "-0.2"
-        }
-      ],
-      "tx_index": 1,
-      "currency": "BTC",
-      "destination": "rHfcNvcg8pBqBxtSvD9Ma8gF17uxauB31o",
-      "executed_time": "2013-11-20T23:52:30Z",
-      "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-      "ledger_index": 3445885,
-      "source": "rwm98fCBS8tV1YB8CGho8zUPW5J7N41th2",
-      "source_currency": "BTC",
-      "tx_hash": "F30D6CED4B0C37660F6DD741C9CA49F0BCB2D2648CDB8FC8AD6CFD86A86384E2"
-    }
-  ]
-}
-
-

Get Exchanges

-

[Source]

-

Retrieve Exchanges for a given currency pair over time. Results can be returned as individual exchanges or aggregated to a specific list of intervals

-

Request Format

-
- -
GET /v2/exchanges/{:base}/{:counter}
-
-
-

Try it!

-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
baseStringBase currency of the pair, as a Currency Code, followed by + and the issuer Address unless it's XRP.
counterStringCounter currency of the pair, as a Currency Code, followed by + and the issuer Address unless it's XRP.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
startString - TimestampFilter results to this time and later.
endString - TimestampFilter results to this time and earlier.
intervalStringAggregation interval: 1minute, 5minute, 15minute, 30minute, 1hour, 2hour, 4hour, 1day, 3day, 7day, or 1month. Defaults to non-aggregated results.
descendingBooleanIf true, return results in reverse chronological order.
reduceBooleanAggregate all individual results. Defaults to false.
limitIntegerMaximum results per page. Defaults to 200. Cannot be more than 20,000 if reduce is true. Otherwise cannot be more than 1,000.
markerStringPagination key from previously returned response.
autobridgedBooleanIf true, filter results to autobridged exchanges only.
formatStringFormat of returned results: csv or json. Defaults to json
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
countIntegerNumber of Transactions returned.
markerString(May be omitted) Pagination marker.
exchangesArray of Exchange ObjectsThe requested exchanges.
-

Example

-

Request:

-
GET /v2/exchanges/USD+rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q/XRP?descending=true&limit=3&result=tesSUCCESS&type=OfferCreate
-
-

Response:

-
200 OK
-{
-    "result": "success",
-    "count": 3,
-    "marker": "USD|rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q|XRP||20151021222220|000016612683|00017|00000",
-    "exchanges": [
-        {
-            "base_amount": 4.98954834453577,
-            "counter_amount": 1047.806201,
-            "node_index": 9,
-            "rate": 210.00021000021,
-            "tx_index": 0,
-            "buyer": "rpP2JgiMyTF5jR5hLG3xHCPi1knBb1v9cM",
-            "executed_time": "2015-10-21T23:09:50",
-            "ledger_index": 16613308,
-            "offer_sequence": 1010056,
-            "provider": "rpP2JgiMyTF5jR5hLG3xHCPi1knBb1v9cM",
-            "seller": "rK2o63evRPdRoMT2ZaW72wsHsFzcjnRLLq",
-            "taker": "rK2o63evRPdRoMT2ZaW72wsHsFzcjnRLLq",
-            "tx_hash": "25600A10E5395D45A9D514E1EC3D98C341C5451FD21C48FA9D104C310EC29D6B",
-            "tx_type": "Payment",
-            "base_currency": "USD",
-            "base_issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-            "counter_currency": "XRP"
-        },
-        {
-            "base_amount": 0.0004716155440678037,
-            "counter_amount": 0.1,
-            "node_index": 3,
-            "rate": 212.03711637126,
-            "tx_index": 0,
-            "buyer": "rfh3pFHkCXv3TgzsEJgyCzF1CduZHCLi9o",
-            "executed_time": "2015-10-21T23:09:50",
-            "ledger_index": 16613308,
-            "offer_sequence": 158081,
-            "provider": "rfh3pFHkCXv3TgzsEJgyCzF1CduZHCLi9o",
-            "seller": "rK2o63evRPdRoMT2ZaW72wsHsFzcjnRLLq",
-            "taker": "rK2o63evRPdRoMT2ZaW72wsHsFzcjnRLLq",
-            "tx_hash": "25600A10E5395D45A9D514E1EC3D98C341C5451FD21C48FA9D104C310EC29D6B",
-            "tx_type": "Payment",
-            "base_currency": "USD",
-            "base_issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-            "counter_currency": "XRP"
-        },
-        {
-            "base_amount": 0.0004714169229390923,
-            "counter_amount": 0.1,
-            "node_index": 3,
-            "rate": 212.1264535361624,
-            "tx_index": 17,
-            "autobridged_currency": "USD",
-            "autobridged_issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-            "buyer": "rfh3pFHkCXv3TgzsEJgyCzF1CduZHCLi9o",
-            "executed_time": "2015-10-21T22:22:20",
-            "ledger_index": 16612683,
-            "offer_sequence": 158059,
-            "provider": "rfh3pFHkCXv3TgzsEJgyCzF1CduZHCLi9o",
-            "seller": "rpP2JgiMyTF5jR5hLG3xHCPi1knBb1v9cM",
-            "taker": "rpP2JgiMyTF5jR5hLG3xHCPi1knBb1v9cM",
-            "tx_hash": "F05F670B06D641D7F6FE18E450DDB2C7A4DDF76D580C34C820939DC22AD9F582",
-            "tx_type": "OfferCreate",
-            "base_currency": "USD",
-            "base_issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-            "counter_currency": "XRP"
-        }
-    ]
-}
-
-

Get Exchange Rates

-

[Source]

-

Retrieve an exchange rate for a given currency pair at a specific time.

-

Request Format

-
- -
GET /v2/exchange_rates/{:base}/{:counter}
-
-
-

Try it!

-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
baseStringBase currency of the pair, as a Currency Code, followed by + and the issuer Address. Omit the + and the issuer for XRP.
counterStringCounter currency of the pair, as a Currency Code, followed by + and the issuer Address. Omit the + and the issuer for XRP.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
dateString - TimestampReturn an exchange rate for the specified time. Defaults to the current time.
strictBooleanIf false, allow rates derived from less than 10 exchanges. Defaults to true.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
rateNumberThe requested exchange rate, or 0 if the exchange rate could not be determined.
-

All exchange rates are calcuated by converting the base currency and counter currency to XRP.

-

The rate is derived from the volume weighted average over the calendar day specified, averaged with the volume weighted average of the last 50 trades within the last 14 days.

-

Example

-

Request:

-
GET /v2/exchange_rates/USD+rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q/XRP?date=2015-11-13T00:00:00Z
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "rate": "224.65709"
-}
-
-

Normalize

-

[Source]

-

Convert an amount from one currency and issuer to another, using the network exchange rates.

-

Request Format

-
- -
GET /v2/normalize
-
-
-

Try it!

-

You must provide at least some of the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
amountNumber(Required) Amount of currency to normalize.
currencyString - Currency CodeThe currency code of the amount to convert from. Defaults to XRP.
issuerString - AddressThe issuer of the currency to convert from. (Required if currency is not XRP.)
exchange_currencyString - Currency CodeThe currency to convert to. Defaults to XRP.
exchange_issuerString - AddressThe issuer of the currency to convert to. (Required if exchange_currency is not XRP.)
dateString - TimestampConvert according to the exchange rate at this time. Defaults to the current time.
strictBooleanIf true, do not use exchange rates that are determined by less than 10 exchanges. Defaults to true.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
amountNumberPre-conversion amount specified in the request.
convertedNumberPost-conversion amount of the exchange_currency, or 0 if the exchange rate could not be determined.
rateNumberExchange rate used to calculate the conversion, or 0 if the exchange rate could not be determined.
-

All exchange rates are calculating by converting both currencies to XRP.

-

Example

-

Request:

-
GET /v2/normalize?amount=100&currency=XRP&exchange_currency=USD&exchange_issuer=rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "amount": "100",
-  "converted": "0.4267798022744489",
-  "rate": "0.0042677980"
-}
-
-

Get Daily Reports

-

[Source]

-

Retrieve per account per day aggregated payment summaries

-

Request Format

-
- -
GET /v2/reports/{:date}
-
-
-

Try it!

-

This method uses the following URL parameter:

- - - - - - - - - - - - - - - -
FieldValueDescription
dateString(Optional) UTC query date. If omitted, use the current day.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
accountsBooleanIf true, include lists of counterparty accounts. Defaults to false.
paymentsBooleanIf true, include lists of individual payments. Defaults to false.
formatStringFormat of returned results: csv or json. Defaults to json.
limitIntegerMaximum results per page. Defaults to 200. Cannot be more than 1000.
markerStringPagination key from previously returned response.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
dateString - TimestampThe date for which this report applies.
countIntegerNumber of reports returned.
markerString(May be omitted) Pagination marker.
reportsArray of Reports ObjectsThe requested reports. Each report pertains to a single account.
-

Caution: This method may return a very large amount of data (more than 1 megabyte), which may cause poor performance in your client application.

-

Example

-

Request:

-
GET /v2/reports/2015-08-19T00:00:00Z?accounts=true&payments=true
-
-

Response (trimmed for size):

-
{
-    "result": "success",
-    "date": "2015-08-19T00:00:00Z",
-    "count": 2,
-    "marker": "20150819000000|r2nt4zXDP6Be5FNrLsiuuTEBETbGR9RFw",
-    "reports": [
-        {
-            "account": "r2LXq2rZWSgQ1thhKiEytzi1smg6oEn8A",
-            "date": "2015-08-19T00:00:00Z",
-            "high_value_received": "7000",
-            "high_value_sent": "3400",
-            "payments": [
-                {
-                    "tx_hash": "A032EFBB219B1102BBD9BCCB91EDC6EAA8185509574FA476A2D3FE6BA79B04EF",
-                    "amount": "1700",
-                    "type": "received"
-                },
-                {
-                    "tx_hash": "8B059360DC83777CDCABA84824C169651AFD6A7AB44E8742A3B8C6BC2AAF7384",
-                    "amount": "40",
-                    "type": "received"
-                },
-
-                ...(additional results trimmed)...
-
-                {
-                    "tx_hash": "76041BD6546389B5EC2CDBAA543200CF7B8D300F34F908BA5CA8523B0CA158C8",
-                    "amount": "1400",
-                    "type": "sent"
-                }
-            ],
-            "payments_received": 155,
-            "payments_sent": 49,
-            "receiving_counterparties": [
-                "rDMFJrKg2jyoNG6WDWJknXDEKZ6ywNFGwD",
-                "r4XXHxraHLuCiLmLMw96FTPXXywZSnWSyR",
-
-                ...(additional results trimmed)...
-
-
-                "rp1C4Ld6uGjurFpempUJ8q5hPSWhak5EQf"
-            ],
-            "sending_counterparties": [
-                "rwxcJVWZSEgN2DmLZYYjyagHjMx5jQ7BAa",
-
-                ...(additional results trimmed)...
-
-
-                "rBK1rLjbWsSU9EuST1cAz9RsiYdJPVGXXA"
-            ],
-            "total_value": "210940",
-            "total_value_received": "100540",
-            "total_value_sent": "110400"
-        },
-        {
-            "account": "r2adXWaWFJt9mHeoWN77iHJozDz2FDAPA",
-            "date": "2015-08-19T00:00:00Z",
-            "high_value_received": "7400",
-            "high_value_sent": "15900",
-            "payments": [
-                {
-                    "tx_hash": "9C7EA76D467AE58E6AEFAAC7994D42FB4E7FA72BFA22F90260937386D76BDB64",
-                    "amount": "900",
-                    "type": "sent"
-                },
-
-                ...(additional results trimmed)...
-
-
-                {
-                    "tx_hash": "EC25427964419394BB5D06343BC74235C33655C1F70523C688F9A201957D65BA",
-                    "amount": "100",
-                    "type": "sent"
-                }
-            ],
-            "payments_received": 43,
-            "payments_sent": 62,
-            "receiving_counterparties": [
-                "rB4cyZxrBrTmJcWZSBc8YoW2t3bafiKRp",
-
-                ...(additional results trimmed)...
-
-
-                "rKybkw3Pu74VfJfrWr7QJbVPJNarnKP2EJ"
-            ],
-            "sending_counterparties": [
-                "rNRCXw8PQRjvTwMDDLZVvuLHSKqqXUXQHv",
-                "r7CLMVEuNvK2yXTPLPnkWMqzkkXuopWeL",
-
-                ...(additional results trimmed)...
-
-
-                "ranyeoYRhvwiFABzDvxSVyqQKp1bMkFsaX"
-            ],
-            "total_value": "117600",
-            "total_value_received": "54700",
-            "total_value_sent": "62900"
-        }
-    ]
-}
-
-

Get Stats

-

[Source]

-

Retrieve statistics about transaction activity in the XRP Ledger, divided into intervals of time.

-

Request Format

-
- -
GET /v2/stats
-
-
-

Try it!

-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
familyStringIf provided, filter results to a single family of stats: type, result, or metric. By default, provides all stats from all families.
metricsStringFilter results to one or more metrics (in a comma-separated list). Requires the family of the metrics to be specified. By default, provides all metrics in the family.
startString - TimestampFilter results to this time and later.
endString - TimestampFilter results to this time and earlier.
intervalStringAggregation interval (hour,day,week, defaults to day)
limitIntegerMaximum results per page. Defaults to 200. Cannot be more than 1000.
markerStringPagination key from previously returned response.
descendingBooleanIf true, return results in reverse chronological order. Defaults to false.
formatStringFormat of returned results: csv or json. Defaults to json.
-
Families and Metrics
-

The family and metrics query parameters provide a way to filter results to a specific subset of all metrics available for transactions in any given interval. Each metric is tied to a specific family, as follows:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FamilyIncluded MetricsMeaning
typeAll XRP Ledger transaction types, including Payment, AccountSet, OfferCreate, and others.Number of transactions of the given type that occurred during the interval.
resultAll transaction result codes (string codes, not the numeric codes), including tesSUCCESS, tecPATH_DRY, and many others.Number of transactions that resulted in the given code during the interval.
metricData-API defined Special Transaction Metrics.(Varies)
-
Special Transaction Metrics
-

The Data API derives the following values for every interval. These metrics are part of the metric family.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
accounts_createdNumberThe number of new accounts funded during this interval.
exchanges_countNumberThe number of currency exchanges that occurred during this interval.
ledger_countNumberThe number of ledgers closed during this interval.
ledger_intervalNumberThe average number of seconds between ledgers closing during this interval.
payments_countNumberThe number of payments from one account to another during this interval.
tx_per_ledgerNumberThe average number of transactions per ledger in this interval.
-

If any of the metrics have a value of 0, they are omitted from the results.

-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
countIntegerNumber of reports returned.
markerString(May be omitted) Pagination marker.
statsArray of stats objectsThe requested stats. Omits metrics with a value of 0, and intervals that have no nonzero metrics.
-

Example

-

Request:

-
GET /v2/stats/?start=2015-08-30&end=2015-08-31&interval=day&family=metric&metrics=accounts_created,exchanges_count,ledger_count,payments_count
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "count": 2,
-  "stats": [
-    {
-      "accounts_created": 15,
-      "exchanges_count": 19368,
-      "ledger_count": 20307,
-      "payments_count": 24763,
-      "date": "2015-08-30T00:00:00Z"
-    },
-    {
-      "accounts_created": 18,
-      "exchanges_count": 17192,
-      "ledger_count": 19971,
-      "payments_count": 30894,
-      "date": "2015-08-31T00:00:00Z"
-    }
-  ]
-}
-
-

Get Capitalization

-

[Source]

-

Get the total amount of a single currency issued by a single issuer, also known as the market capitalization. (New in v2.0.4)

-

Request Format

-
- -
GET /v2/capitaliztion/{:currency}
-
-
-

Try it!

-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - -
FieldValueDescription
:currencyStringCurrency to look up, in the form of currency+issuer. XRP is disallowed.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
startString - TimestampStart time of query range. Defaults to 2013-01-01T00:00:00Z.
endString - TimestampEnd time of query range. Defaults to the current time.
intervalStringAggregation interval - day, week, or month. Defaults to day.
limitIntegerMaximum results per page. Defaults to 200. Cannot be more than 1000.
markerStringPagination key from previously returned response.
descendingBooleanIf true, return results in reverse chronological order. Defaults to false.
adjustedBooleanIf true, do not count known issuer-owned addresses towards market capitalization. Defaults to true.
formatStringFormat of returned results: csv or json. Defaults to json.
-

If the request omits both start and end, the API returns only the most recent sample.

-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
countIntegerNumber of reports returned.
currencyStringCurrency requested.
issuerStringIssuer requested.
markerString(May be omitted) Pagination marker.
rowsArray of issuer capitalization objectsThe requested capitalization data.
-

Each issuer capitalization object has the following fields:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
dateString - TimestampThe start time of the interval this object represents.
amountString - NumberThe total amount of currency issued by the issuer as of the start of this interval.
-

Example

-

Request:

-
GET /v2/capitalization/USD+rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q?start=2015-01-01T00:00:00Z&end=2015-10-31&interval=month
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "currency": "USD",
-  "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-  "count": 10,
-  "rows": [
-    {
-      "date": "2015-01-01T00:00:00Z",
-      "amount": "4212940.254176095"
-    },
-    {
-      "date": "2015-02-01T00:00:00Z",
-      "amount": "5102817.663782776"
-    },
-    {
-      "date": "2015-03-01T00:00:00Z",
-      "amount": "4179270.8503426993"
-    },
-    {
-      "date": "2015-04-01T00:00:00Z",
-      "amount": "2609239.954946732"
-    },
-    {
-      "date": "2015-05-01T00:00:00Z",
-      "amount": "2262976.3681027396"
-    },
-    {
-      "date": "2015-06-01T00:00:00Z",
-      "amount": "2401904.277326213"
-    },
-    {
-      "date": "2015-07-01T00:00:00Z",
-      "amount": "2007614.760195671"
-    },
-    {
-      "date": "2015-08-01T00:00:00Z",
-      "amount": "2286058.6013003727"
-    },
-    {
-      "date": "2015-09-01T00:00:00Z",
-      "amount": "2070512.4729615194"
-    },
-    {
-      "date": "2015-10-01T00:00:00Z",
-      "amount": "2140238.7719266433"
-    }
-  ]
-}
-
-

Get Active Accounts

-

[Source]

-

Get information on which accounts are actively trading in a specific currency pair. (New in v2.0.4)

-

Request Format

-
- -
GET /v2/active_accounts/{:base}/{:counter}
-
-
-

Try it!

-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
:baseStringBase currency of the pair, as a Currency Code, followed by + and the issuer Address unless it's XRP.
:counterStringCounter currency of the pair, as a Currency Code, followed by + and the issuer Address unless it's XRP.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
periodStringGet results for trading activity during a chosen time period. Valid periods are 1day, 3day, or 7day. Defaults to 1day.
dateStringGet results for the period starting at this time. Defaults to the most recent period available.
include_exchangesBooleanInclude individual exchanges for each account in the results.
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
countIntegerNumber of accounts returned.
exchanges_countIntegerTotal number of exchanges in the period.
accountsArray of active Account Trading ObjectsActive trading accounts for the period.
-

Each "Account Trading Object" describes the activity of a single account during this time period, and has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
buyObjectSummary of currency exchanges buying the base currency
buy.base_volumeNumberAmount of base currency the account bought in this period.
buy.counter_volumeNumberAmount of counter currency the account sold in this period.
buy.countNumberNumber of trades that bought the base currency in this period.
sellObjectSummary of currency changes selling the base currency.
sell.base_volumeNumberAmount of the base currency the account sold this period.
sell.counter_volumeNumberAmount of the counter currency the account bought this period.
sell.countNumberNumber of trades that sold the base currency.
accountString - AddressThe address whose activity this object describes.
base_volumeNumberThe total volume of the base currency the account bought and sold in this period.
counter_volumeNumberThe total volume of the counter currency the account bought and sold in this period.
countNumberThe total number of exchanges the account made during this period.
-

Example

-

Request:

-
GET /v2/active_accounts/XRP/USD+rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q
-
-

Response:

-
200 OK
-{
-    "result": "success",
-    "count": 12,
-    "exchanges_count": 11,
-    "accounts": [
-        {
-            "buy": {
-                "base_volume": 0,
-                "counter_volume": 0,
-                "count": 0
-            },
-            "sell": {
-                "base_volume": 13084.822874,
-                "counter_volume": 54.499328645454604,
-                "count": 4
-            },
-            "account": "rGBQhB8EH5DmqMmfKPLchpqr3MR19pv6zN",
-            "base_volume": 13084.822874,
-            "counter_volume": 54.499328645454604,
-            "count": 4
-        },
-        {
-            "buy": {
-                "base_volume": 12597.822874,
-                "counter_volume": 52.4909286454546,
-                "count": 1
-            },
-            "sell": {
-                "base_volume": 0,
-                "counter_volume": 0,
-                "count": 0
-            },
-            "account": "rQE5Z3FgVnRMbVfS6xiVQFgB4J3X162FVD",
-            "base_volume": 12597.822874,
-            "counter_volume": 52.4909286454546,
-            "count": 1
-        },
-
-        ... (additional results trimmed)...
-
-        {
-            "buy": {
-                "base_volume": 1.996007,
-                "counter_volume": 0.008782427920595,
-                "count": 1
-            },
-            "sell": {
-                "base_volume": 0,
-                "counter_volume": 0,
-                "count": 0
-            },
-            "account": "rD8LigXE7165r3VWhSQ4FwzJy7PNrTMwUq",
-            "base_volume": 1.996007,
-            "counter_volume": 0.008782427920595,
-            "count": 1
-        },
-        {
-            "buy": {
-                "base_volume": 0,
-                "counter_volume": 0,
-                "count": 0
-            },
-            "sell": {
-                "base_volume": 0.1,
-                "counter_volume": 0.0004821658905462904,
-                "count": 1
-            },
-            "account": "rfh3pFHkCXv3TgzsEJgyCzF1CduZHCLi9o",
-            "base_volume": 0.1,
-            "counter_volume": 0.0004821658905462904,
-            "count": 1
-        }
-    ]
-}
-
-

Get Exchange Volume

-

[Source]

-

Get aggregated exchange volume for a given time period. (New in v2.0.4)

-

The API returns results in units of a single display currency rather than many different currencies. The conversion uses standard rates to and from XRP.

-

Request Format

-
- -
GET /v2/network/exchange_volume
-
-
-

Try it!

-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
startString - TimestampStart time of query range. Defaults to the start of the most recent interval.
endString - TimestampEnd time of query range. Defaults to the end of the most recent interval.
intervalStringAggregation interval - valid intervals are day, week, or month. Defaults to day.
liveStringReturn a live rolling window of this length of time. Valid values are day, hour, or minute. Ignored if interval is provided. (New in v2.3.0)
exchange_currencyString - Currency CodeNormalize all amounts to use this as a display currency. If not XRP, exchange_issuer is also required. Defaults to XRP.
exchange_issuerString - AddressNormalize results to the specified currency issued by this issuer.
limitIntegerMaximum results per page. Defaults to 200. Cannot be more than 1000.
markerStringPagination key from previously returned response.
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
countIntegerNumber of results returned.
rowsArray of exchange Volume ObjectsExchange volumes for each interval in the requested time period. (By default, this array contains only the most recent complete interval. If live is specified and interval isn't, this array contains the specified rolling window instead.)
-

Each object in the components array of the Volume Objects represent the volume of exchanges in a market between two currencies, and has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
countNumberThe number of exchanges in this market during this interval.
rateNumberThe exchange rate from the base currency to the display currency.
amountNumberThe amount of volume in the market, in units of the base currency.
baseObjectThe currency and issuer of the base currency of this market. There is no issuer for XRP.
counterObjectThe currency and issuer of the counter currency of this market. There is no issuer for XRP.
converted_amountNumberThe total amount of volume in the market, converted to the display currency. (Before v2.1.0, this was convertedAmount.)
-

Example

-

Request:

-
GET /v2/network/exchange_volume?exchange_currency=USD&exchange_issuer=rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B
-
-

Response:

-
200 OK
-{
-    "result": "success",
-    "count": 1,
-    "rows": [
-        {
-            "components": [
-                {
-                    "count": 1711,
-                    "rate": 5.514373809662552e-8,
-                    "amount": 333.7038784107369,
-                    "base": {
-                        "currency": "BTC",
-                        "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-                    },
-                    "counter": {
-                        "currency": "XRP"
-                    },
-                    "converted_amount": 117720.99268355068
-                },
-                {
-                    "count": 1977,
-                    "rate": 0.000019601413454357618,
-                    "amount": 74567.72531650064,
-                    "base": {
-                        "currency": "USD",
-                        "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-                    },
-                    "counter": {
-                        "currency": "XRP"
-                    },
-                    "converted_amount": 74003.51871932109
-                },
-
-                ... (additional results trimmed) ...
-
-                {
-                    "count": 3,
-                    "rate": 0.022999083584408355,
-                    "amount": 85.40728674708998,
-                    "base": {
-                        "currency": "CNY",
-                        "issuer": "razqQKzJRdB4UxFPWf5NEpEG3WMkmwgcXA"
-                    },
-                    "counter": {
-                        "currency": "USD",
-                        "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-                    },
-                    "converted_amount": 12.72863756671683
-                },
-                {
-                    "count": 3,
-                    "rate": 1.7749889023209692e-7,
-                    "amount": 570.687912196755,
-                    "base": {
-                        "currency": "JPY",
-                        "issuer": "r94s8px6kSw1uZ1MV98dhSRTvc6VMPoPcN"
-                    },
-                    "counter": {
-                        "currency": "BTC",
-                        "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q"
-                    },
-                    "converted_amount": 4.4137945368632545
-                }
-            ],
-            "count": 11105,
-            "endTime": "2015-09-11T19:58:58+00:00",
-            "exchange": {
-                "currency": "USD",
-                "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-            },
-            "exchangeRate": 0.004410567085248279,
-            "startTime": "2015-11-10T00:06:04+00:00",
-            "total": 442442.5974313684
-        }
-    ]
-}
-
-

Get Payment Volume

-

[Source]

-

Get aggregated payment volume for a given time period. (New in v2.0.4)

-

The API returns results in units of a single display currency rather than many different currencies. The conversion uses standard rates to and from XRP.

-

Request Format

-
- -
GET /v2/network/payment_volume
-
-
-

Try it!

-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
startString - TimestampStart time of query range. Defaults to the start of the most recent interval.
endString - TimestampEnd time of query range. Defaults to the end of the most recent interval.
intervalStringAggregation interval - valid intervals are day, week, or month. Defaults to day.
liveStringReturn a live rolling window of this length of time. Valid values are day, hour, or minute. Ignored if interval is provided. (New in v2.3.0)
exchange_currencyString - Currency CodeNormalize all amounts to use this as a display currency. If not XRP, exchange_issuer is also required. Defaults to XRP.
exchange_issuerString - AddressNormalize results to the specified currency issued by this issuer.
limitIntegerMaximum results per page. Defaults to 200. Cannot be more than 1000.
markerStringPagination key from previously returned response.
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
countIntegerNumber of results returned.
rowsArray of payment Volume ObjectsPayment volumes for each interval in the requested time period. (By default, this array contains only the most recent interval. If live is specified and interval isn't, this array contains the specified rolling window instead.)
-

Each object in the components array of the Volume Objects represent the volume of payments for one currencies and issuer, and has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
currencyString - Currency CodeThe currency of this payment volume object.
issuerString - Address(Omitted for XRP) The issuer of this payment volume object.
amountNumberTotal payment volume for this currency during the interval, in units of the currency itself.
countNumberThe total number of payments in this currency.
rateNumberThe exchange rate between this currency and the display currency.
converted_amountNumberTotal payment volume for this currency, converted to the display currency. (Before v2.1.0, this was convertedAmount.)
-

Example

-

Request:

-
GET /v2/network/payment_volume
-
-

Response:

-
200 OK
-{
-    "result": "success",
-    "count": 1,
-    "rows": [
-        {
-            "components": [
-                {
-                    "currency": "USD",
-                    "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-                    "amount": 87279.59029136538,
-                    "count": 331,
-                    "rate": 0.004412045860957953,
-                    "converted_amount": 19782113.1153009
-                },
-                {
-                    "currency": "USD",
-                    "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-                    "amount": 0,
-                    "count": 0,
-                    "rate": 0.00451165816091143,
-                    "converted_amount": 0
-                },
-                {
-                    "currency": "BTC",
-                    "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-                    "amount": 279.03077460240354,
-                    "count": 107,
-                    "rate": 0.000013312520335244644,
-                    "converted_amount": 20960026.169024874
-                },
-
-                ... (additional results trimmed) ...
-
-                {
-                    "currency": "MXN",
-                    "issuer": "rG6FZ31hDHN1K5Dkbma3PSB5uVCuVVRzfn",
-                    "amount": 49263.13280138676,
-                    "count": 19,
-                    "rate": 0.07640584677247926,
-                    "converted_amount": 644756.0609868265
-                },
-                {
-                    "currency": "XRP",
-                    "amount": 296246369.30089426,
-                    "count": 8691,
-                    "rate": 1,
-                    "converted_amount": 296246369.30089426
-                }
-            ],
-            "count": 9388,
-            "endTime": "2015-09-11T19:58:59+00:00",
-            "exchange": {
-                "currency": "XRP"
-            },
-            "exchangeRate": 1,
-            "startTime": "2015-11-10T00:19:04+00:00",
-            "total": 390754174.7837752
-        }
-    ]
-}
-
-

Get Issued Value

-

[Source]

-

Get the total value of all currencies issued by major gateways over time. By default, returns only the most recent measurement. (New in v2.0.4)

-

The API returns results in units of a single display currency rather than many different currencies. The conversion uses standard rates to and from XRP.

-

Request Format

-
- -
GET /v2/network/issued_value
-
-
-

Try it!

-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
startString - TimestampStart time of query range. Defaults to the start of the most recent interval.
endString - TimestampEnd time of query range. Defaults to the end of the most recent interval.
exchange_currencyString - Currency CodeNormalize all amounts to use this as a display currency. If not XRP, exchange_issuer is also required. Defaults to XRP.
exchange_issuerString - AddressNormalize results to the specified currency issued by this issuer.
limitIntegerMaximum results per page. Defaults to 200. Cannot be more than 1000.
markerStringPagination key from previously returned response.
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
countIntegerNumber of results returned.
rowsArray of Issued Value ObjectsAggregated capitalization at the requested point(s) in time.
-

Each Issued Value Object represents the total value issued at one point in time, and has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
componentsArray of ObjectsThe data on individual issuers that was used to assemble this total.
exchangeObjectIndicates the display currency used, as with fields currency and (except for XRP) issuer. All amounts are normalized by first converting to XRP, and then to the display currency specified in the request.
exchangeRateNumberThe exchange rate to the displayed currency from XRP.
timeString - TimestampWhen this data was measured.
totalNumberTotal value of all issued assets at this time, in units of the display currency.
-

Example

-

Request:

-
GET /v2/network/issued_value?start=2015-10-01T00:00:00&end=2015-10-01T00:00:00&exchange_currency=USD&exchange_issuer=rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "count": 1,
-  "rows": [
-    {
-      "components": [
-        {
-          "currency": "USD",
-          "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-          "amount": "2177473.2843876695",
-          "rate": "0.000028818194",
-          "converted_amount": "2166521.1303508882"
-        },
-        {
-          "currency": "USD",
-          "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-          "amount": "1651297.315492664",
-          "rate": "0.000028888001",
-          "converted_amount": "1639021.4313562333"
-        },
-
-        ... (additional results trimmed for size) ...
-
-        {
-          "currency": "MXN",
-          "issuer": "rG6FZ31hDHN1K5Dkbma3PSB5uVCuVVRzfn",
-          "amount": "2288827.2376308907",
-          "rate": "0.00050850375",
-          "converted_amount": "129061.20018881827"
-        }
-      ],
-      "exchange": {
-        "currency": "USD",
-        "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q"
-      },
-      "total": "8338101.394233938",
-      "exchange_rate": "0.0053547404",
-      "date": "2015-10-01T00:00:00Z"
-    }
-  ]
-}
-
-

Get XRP Distribution

-

[Source]

-

Get information on the total amount of XRP in existence and in circulation, by weekly intervals. (New in v2.2.0)

-

Request Format

-
- -
GET /v2/network/xrp_distribution
-
-
-

Try it!

-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
startString - TimestampStart time of query range. Defaults to the start of the most recent interval.
endString - TimestampEnd time of query range. Defaults to the end of the most recent interval.
limitIntegerMaximum results per page. Defaults to 200. Cannot be more than 1000.
markerStringPagination key from previously returned response.
descendingBooleanIf true, return results in reverse chronological order. Defaults to false.
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that the body represents a successful response.
countIntegerNumber of rows returned.
rowsArray of Distribution ObjectsWeekly snapshots of the XRP distribution.
-

Each Distribution Object has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
dateString - TimestampThe time of this snapshot.
totalStringTotal XRP in existence.
undistributedStringAggregate amount of XRP held by Ripple (the company).
distributedStringAggregate amount of XRP held by others.
-

Example

-

Request:

-
GET /v2/network/xrp_distribution
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "count": 171,
-  "rows": [
-    {
-      "date": "2016-04-10T00:00:00Z",
-      "distributed": "34918644255.77274",
-      "total": "99997725821.25714",
-      "undistributed": "65079081565.4844"
-    },
-    ...
-  ]
-}
-
-

Get Top Currencies

-

[Source]

-

Returns the top currencies on the XRP Ledger, ordered from highest rank to lowest. The ranking is determined by the volume and count of transactions and the number of unique counterparties. By default, returns results for the 30-day rolling window ending on the current date. You can specify a date to get results for the 30-day window ending on that date. (New in v2.1.0)

-

Request Format

-
- -
GET /v2/network/top_currencies
-
- -
GET /v2/network/top_currencies/{:date}
-
-
-

Try it!

-

This method uses the following URL parameter:

- - - - - - - - - - - - - - - -
FieldValueDescription
dateString - ISO 8601 Date(Optional) Historical date to query. If omitted, use the most recent date available.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
limitIntegerMaximum results per page. Defaults to 1000. Cannot be more than 1000.
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
dateString - TimestampWhen this data was measured.
countIntegerNumber of objects in the currencies field.
currenciesArray of Top Currency ObjectsThe top currencies for this data sample. Each member represents one currency, by currency code and issuer.
-

Each Top Currency Object has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
currencyString - Currency CodeThe currency this object describes.
issuerString - AddressThe XRP Ledger address that issues this currency.
avg_exchange_countString - NumberDaily average number of exchanges
avg_exchange_volumeString - NumberDaily average volume of exchanges, normalized to XRP
avg_payment_countString - NumberDaily average number of payments
avg_payment_volumeString - NumberDaily average volume of payments, normalized to XRP
issued_valueString - NumberTotal amount of this currency issued by this issuer, normalized to XRP
-

Example

-

Request:

-
GET /v2/network/top_currencies/2016-04-14?limit=2
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "date": "2016-04-14T00:00:00Z",
-  "count": 2,
-  "currencies": [
-    {
-      "avg_exchange_count": "8099.967741935484",
-      "avg_exchange_volume": "3.5952068085531615E7",
-      "avg_payment_count": "624.28125",
-      "avg_payment_volume": "3910190.139488101",
-      "issued_value": "1.5276205395328993E8",
-      "currency": "CNY",
-      "issuer": "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y"
-    },
-    {
-      "avg_exchange_count": "3003.2258064516127",
-      "avg_exchange_volume": "3.430482029838605E7",
-      "avg_payment_count": "257.4375",
-      "avg_payment_volume": "501442.0789529095",
-      "issued_value": "2.6289124450524995E8",
-      "currency": "USD",
-      "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-    }
-  ]
-}
-
-

Get Top Markets

-

[Source]

-

Returns the top exchange markets on the XRP Ledger, ordered from highest rank to lowest. The rank is determined by the number and volume of exchanges and the number of counterparties participating. By default, returns top markets for the 30-day rolling window ending on the current date. You can specify a date to get results for the 30-day window ending on that date. (New in v2.1.0)

-

Request Format

-
- -
GET /v2/network/top_markets
-
- -
GET /v2/network/top_markets/{:date}
-
-
-

Try it!

-

This method uses the following URL parameter:

- - - - - - - - - - - - - - - -
FieldValueDescription
dateString - ISO 8601 Date(Optional) Historical date to query. If omitted, use the most recent date available.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
limitIntegerMaximum results per page. Defaults to 1000. Cannot be more than 1000.
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
dateString - TimestampThe end of the rolling window over which this data was calculated.
countIntegerNumber of results in the markets field.
marketsArray of Top Market ObjectsThe top markets for this data sample. Each member represents a currency pair.
-

Each Top Market object has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
base_currencyString - Currency CodeThe base currency for this market.
base_issuerString - Address(Omitted if base_currency is XRP) The XRP Ledger address that issues the base currency.
counter_currencyString - Currency CodeThe counter currency for this market.
counter_issuerString - Address(Omitted if counter_currency is XRP) The XRP Ledger address that issues the counter currency.
avg_base_volumeStringDaily average volume in terms of the base currency.
avg_counter_volumeStringDaily average volume in terms of the counter currency.
avg_exchange_countStringDaily average number of exchanges
avg_volumeStringDaily average volume, normalized to XRP
-

Example

-

Request:

-
GET /v2/network/top_markets/2015-12-31
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "date": "2015-12-31T00:00:00Z",
-  "count": 58,
-  "markets": [
-    {
-      "avg_base_volume": "116180.98607935428",
-      "avg_counter_volume": "1.6657039295476614E7",
-      "avg_exchange_count": "1521.4603174603174",
-      "avg_volume": "1.6657039295476614E7",
-      "base_currency": "USD",
-      "base_issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-      "counter_currency": "XRP"
-    },
-    {
-      "avg_base_volume": "410510.0286920887",
-      "avg_counter_volume": "9117398.719214212",
-      "avg_exchange_count": "1902.1587301587301",
-      "avg_volume": "9117398.719214212",
-      "base_currency": "CNY",
-      "base_issuer": "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y",
-      "counter_currency": "XRP"
-    },
-    ...
-  ]
-}
-
-

Get Transaction Costs

-

[Source]

-

Returns transaction cost stats per ledger, hour, or day. The data shows the average, minimum, maximum, and total transaction costs paid for the given interval or ledger. (New in v2.2.0)

-

Request Format

-
- -
GET /v2/network/fees
-
-
-

Try it!

-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
startString - TimestampStart time of query range. Defaults to the earliest data available.
endString - TimestampEnd time of query range. Defaults to the latest data available.
intervalStringAggregation interval - valid intervals are ledger, hour, or day. Defaults to ledger.
descendingBooleanIf true, sort results with most recent first. By default, sort results with oldest first.
limitIntegerMaximum results per page. Defaults to 200. Cannot be more than 1000.
markerStringPagination key from previously returned response.
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
markerString(May be omitted) Pagination marker.
countIntegerNumber of results in the markets field.
rowsArray of Fee Summary ObjectsTransaction cost statistics for each interval.
-

Each Fee Summary object has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
avgNumberAverage transaction cost paid in this interval.
minNumberMinimum transaction cost paid in this interval.
maxNumberMaximum transaction cost paid in this interval.
totalNumberTotal XRP destroyed by transaction costs.
tx_countNumberNumber of transactions in this interval.
dateString - TimestampThe start time of this interval (time intervals), or the close time of this ledger (ledger interval).
ledger_indexInteger - Ledger Index(Only present in ledger interval) The ledger this object describes.
-

Example

-

Request:

-
GET /v2/network/fees?interval=day&limit=3&descending=true
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "marker": "day|20160603000000",
-  "count": 3,
-  "rows": [
-    {
-      "avg": 0.011829,
-      "max": 15,
-      "min": 0.01,
-      "total": 6682.15335,
-      "tx_count": 564918,
-      "date": "2016-06-06T00:00:00Z"
-    },
-    {
-      "avg": 0.011822,
-      "max": 4.963071,
-      "min": 0.01,
-      "total": 5350.832025,
-      "tx_count": 452609,
-      "date": "2016-06-05T00:00:00Z"
-    },
-    {
-      "avg": 0.012128,
-      "max": 15,
-      "min": 0.01,
-      "total": 5405.126404,
-      "tx_count": 445689,
-      "date": "2016-06-04T00:00:00Z"
-    }
-  ]
-}
-
-

Get Topology

-

[Source]

-

Get known rippled servers and peer-to-peer connections between them. (New in v2.2.0)

-

Request Format

-
- -
GET /v2/network/topology
-
-
-

Try it!

-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
dateString - TimestampDate and time for historical query. By default, uses the most recent data available.
verboseBooleanIf true, include additional details about each server where available. Defaults to false.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that the body represents a successful response.
dateString - TimestampThe time of this measurement.
node_countIntegerNumber of rippled servers in the topology.
link_countIntegerNumber of links in the topology.
nodesArray of Server ObjectsDetails of rippled servers in the peer-to-peer network.
linksArray of Link ObjectsNetwork connections between rippled servers in the peer-to-peer network.
-

Example

-

Request:

-
GET /v2/network/topology
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "date": "2016-06-06T23:51:04Z",
-  "node_count": 115,
-  "link_count": 1913,
-  "nodes": [
-    {
-      "node_public_key": "n94fDXS3ta92gRSi7DKngh47S7Rg4z1FuNsahvbiakFEg51dLeVa",
-      "version": "rippled-0.31.0-rc1",
-      "uptime": 266431,
-      "inbound_count": 24,
-      "last_updated": "2016-06-03T21:50:57Z"
-    },
-    {
-      "node_public_key": "n94h5KNspwUGLaGcdHGxruYNmExWHjPkLcMvwsNrivR9czRp6Lor",
-      "ip": "104.247.221.178",
-      "port": 51235,
-      "version": "rippled-0.31.0",
-      "uptime": 608382,
-      "inbound_count": 10,
-      "outbound_count": 11,
-      "city": "Atlanta",
-      "country": "United States",
-      "country_code": "US",
-      "isp": "QuickPacket, LLC",
-      "last_updated": "2016-05-28T06:29:43Z",
-      "lat": "-84.3846",
-      "long": "33.8379",
-      "postal_code": "30305",
-      "region": "Georgia",
-      "region_code": "GA",
-      "timezone": "America/New_York"
-    },
-
-    ...
-  ],
-  "links": [
-    {
-      "source": "n94Extku8HiQVY8fcgxeot4bY7JqK2pNYfmdnhgf6UbcmgucHFY8",
-      "target": "n9KcFAX2bCuwF4vGF8gZZcpQQ6nyqm44e5TUygb3zvdZEpiJE5As"
-    },
-    {
-      "source": "n94Extku8HiQVY8fcgxeot4bY7JqK2pNYfmdnhgf6UbcmgucHFY8",
-      "target": "n9LGAj7PjvfTmEGQ75JaRKba6GQmVwFCnJTSHgX2HDXzxm6d2JpM"
-    },
-
-    ...
-  ]
-}
-
-

Get Topology Nodes

-

[Source]

-

Get known rippled nodes. (This is a subset of the data returned by the Get Topology method.) (New in v2.2.0)

-

Request Format

-
- -
GET /v2/network/topology/nodes
-
-
-

Try it!

-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
dateString - TimestampDate and time for historical query. Defaults to most recent data.
verboseBooleanIf true, return full details for each server. Defaults to false.
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that the body represents a successful response.
dateString - TimestampWhen this the data was measured.
countIntegerNumber of rippled servers described.
nodesArray of Server ObjectsDetails of the rippled servers in the topology.
-

Example

-

Request:

-
GET /v2/network/topology/nodes
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "date": "2016-06-08T00:36:53Z",
-  "count": 116,
-  "nodes": [
-    {
-      "node_public_key": "n94BuARkPiYLrMuAVZqMQFhTAGpo12dqUPiH3yrzEnhaEcXfLAnV",
-      "version": "rippled-0.30.1",
-      "uptime": 122424,
-      "inbound_count": 10,
-      "last_updated": "2016-06-06T14:36:52Z"
-    },
-    {
-      "node_public_key": "n94h5KNspwUGLaGcdHGxruYNmExWHjPkLcMvwsNrivR9czRp6Lor",
-      "ip": "104.247.221.178",
-      "port": 51235,
-      "version": "rippled-0.31.2",
-      "uptime": 38649,
-      "inbound_count": 10,
-      "outbound_count": 11,
-      "city": "Atlanta",
-      "country": "United States",
-      "country_code": "US",
-      "isp": "QuickPacket, LLC",
-      "last_updated": "2016-06-07T13:53:12Z",
-      "lat": "-84.3846",
-      "long": "33.8379",
-      "postal_code": "30305",
-      "region": "Georgia",
-      "region_code": "GA",
-      "timezone": "America/New_York"
-    },
-
-    ...
-
-  ]
-}
-
-

Get Topology Node

-

[Source]

-

Get information about a single rippled server by its node public key (not validator public key). (New in v2.2.0)

-

Request Format

-
- -
GET /v2/network/topology/nodes/{:pubkey}
-
-
-

Try it!

-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - -
FieldValueDescription
pubkeyString - Base-58 Public KeyNode public key of the server to look up.
-

This method takes no query parameters.

-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with a Server Object in the response with the following additional field:

- - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
-

Example

-

Request:

-
GET /v2/network/topology/nodes/n94h5KNspwUGLaGcdHGxruYNmExWHjPkLcMvwsNrivR9czRp6Lor
-
-

Response:

-
200 OK
-{
-  "node_public_key": "n94h5KNspwUGLaGcdHGxruYNmExWHjPkLcMvwsNrivR9czRp6Lor",
-  "ip": "104.247.221.178",
-  "port": 51235,
-  "version": "rippled-0.31.2",
-  "uptime": 43342,
-  "inbound_count": 10,
-  "outbound_count": 11,
-  "city": "Atlanta",
-  "country": "United States",
-  "country_code": "US",
-  "isp": "QuickPacket, LLC",
-  "last_updated": "2016-06-07T13:53:12Z",
-  "lat": "-84.3846",
-  "long": "33.8379",
-  "postal_code": "30305",
-  "region": "Georgia",
-  "region_code": "GA",
-  "timezone": "America/New_York",
-  "result": "success"
-}
-
- -

[Source]

-

Get information on peer-to-peer connections between rippled servers. (This is a subset of the data returned by the Get Topology method.) (New in v2.2.0)

-

Request Format

-
- -
GET /v2/network/topology/links
-
-
-

Try it!

-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
dateString - TimestampDate and time for historical query. Defaults to most recent data available.
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that the body represents a successful response.
dateString - TimestampWhen this data was measured.
countIntegerNumber of links returned.
linksArray of Link ObjectsLinks between rippled servers.
-

Example

-

Request:

-
GET /v2/network/topology/links
-
-

Response:

-
200 OK
-{
-  result: "success",
-  date: "2016-03-21T16:38:52Z",
-  count: 1632,
-  links: [
-    {
-      source: "n94Extku8HiQVY8fcgxeot4bY7JqK2pNYfmdnhgf6UbcmgucHFY8",
-      target: "n9JccBLfrDJBLBF2X5N7bUW8251riCwSf9e3VQ3P5fK4gYr5LBu4"
-    },
-    ...
-  ]
-}
-
-

Get Validator

-

[Source]

-

Get details of a single validator in the consensus network. (New in v2.2.0)

-

Request Format

-
- -
GET /v2/network/validators/{:pubkey}
-
-
-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - -
FieldValueDescription
pubkeyString - Base-58 Public KeyValidator public key.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - -
FieldValueDescription
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that the body represents a successful response.
last_datetimeIntegerThe last reported validation vote signed by this validator.
validation_public_keyString - Base-58 Public KeyThis validator's validator public key.
domainString(May be omitted) The DNS domain associated with this validator.
domain_stateStringThe value verified indicates that this validator has a verified domain controlled by the same operator as the validator. The value AccountDomainNotFound indicates that the "Account Domain" part of Domain Verification is not set up properly. The value RippleTxtNotFound indicates that the ripple.txt step of Domain Verification is not set up properly.
-

Example

-

Request:

-
GET /v2/network/validators/n949f75evCHwgyP4fPVgaHqNHxUVN15PsJEZ3B3HnXPcPjcZAoy7
-
-

Response:

-
200 OK
-{
-  "domain": "ripple.com",
-  "domain_state": "verified",
-  "last_datetime": "2016-06-07T01:22:59.929Z",
-  "validation_public_key": "n949f75evCHwgyP4fPVgaHqNHxUVN15PsJEZ3B3HnXPcPjcZAoy7",
-  "result": "success"
-}
-
-

Get Validators

-

[Source]

-

Get a list of known validators. (New in v2.2.0)

-

Request Format

-
- -
GET /v2/network/validators
-
-
-

Try it!

-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - -
FieldValueDescription
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that the body represents a successful response.
last_datetimeIntegerNumber of links returned.
validation_public_keyString - Base-58 Public KeyValidator public key of this validator.
-

Example

-

Request:

-
GET /v2/network/validators/n949f75evCHwgyP4fPVgaHqNHxUVN15PsJEZ3B3HnXPcPjcZAoy7
-
-

Response:

-
200 OK
-{
-  result: "success",
-  last_datetime: "2016-02-11T23:20:41.319Z",
-  validation_public_key: "n949f75evCHwgyP4fPVgaHqNHxUVN15PsJEZ3B3HnXPcPjcZAoy7"
-}
-
-

Get Validator Validations

-

[Source]

-

Retrieve validation votes signed by a specified validator, including votes for ledger versions that are outside the main ledger chain. (New in v2.2.0)

-

Note: The Data API does not have a comprehensive record of all validations. The response only includes data that the Data API has recorded. Some ledger versions, especially older ledgers, may have no validations even if they were validated by consensus.

-

Request Format

-
- -
GET /v2/network/validators/{:pubkey}/validations
-
-
-

Try it!

-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - -
FieldValueDescription
pubkeyString - Base-58 Public KeyValidator public key.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
startString - TimestampFilter results to this time and later.
endString - TimestampFilter results to this time and earlier.
limitIntegerMaximum results per page. Defaults to 200. Cannot be more than 1000.
markerStringPagination key from previously returned response.
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that the body represents a successful response.
countIntegerNumber of validations returned.
markerString(May be omitted) Pagination marker.
validationsArray of Validation ObjectsThe requested validations.
-

Example

-

Request:

-
GET /v2/network/validator/n949f75evCHwgyP4fPVgaHqNHxUVN15PsJEZ3B3HnXPcPjcZAoy7/validations?limit=3&descending=true
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "count": 3,
-  "marker": "n949f75evCHwgyP4fPVgaHqNHxUVN15PsJEZ3B3HnXPcPjcZAoy7|20160608020910|4499E5D60FD4F3F239C5B274E65B9CAE033398BE976E4FB49E9B30508D95F5A5",
-  "validations": [
-    {
-      "count": 27,
-      "first_datetime": "2016-06-08T02:09:21.280Z",
-      "last_datetime": "2016-06-08T02:09:21.390Z",
-      "ledger_hash": "246C5142A108C7B64F5D700936D31360B7790FA6349A98A2A1F7A14671D70B48",
-      "reporter_public_key": "n9KKTtooV4h2UsmNEhBqPvMRNj6RAHLPS6Baktf4u1AhgKNbyJAF",
-      "signature": "304402204506DD69B831886C4738F97CEED43AAFDBA67254D3EAF4FB5B3BF167A15B1B690220147E366CA53A3EC8B513978F2BA3A0905DC412CCE553E8ECE544236B097F2C8A",
-      "validation_public_key": "n949f75evCHwgyP4fPVgaHqNHxUVN15PsJEZ3B3HnXPcPjcZAoy7"
-    },
-    {
-      "count": 27,
-      "first_datetime": "2016-06-08T02:09:17.275Z",
-      "last_datetime": "2016-06-08T02:09:17.383Z",
-      "ledger_hash": "1DC9245CDBFE2C640ACD766DB4AF1DE66F6E92A8EE78F628281A6568760DBAB2",
-      "reporter_public_key": "n9JySgyBVcQKvyDoeRKg7s2Mm6ZcFHk22vUZb3o1HSosWxcj9xPt",
-      "signature": "3045022100E07D8CB801EC7AC98DB1DED813D49AE1FFE3C4CB027314EB6ED1BA7796653DE902204E65E96B0961AC09D8D7542EC59B3CE2ECAE6BC02557A4D1C0385DED00445329",
-      "validation_public_key": "n949f75evCHwgyP4fPVgaHqNHxUVN15PsJEZ3B3HnXPcPjcZAoy7"
-    },
-    {
-      "count": 27,
-      "first_datetime": "2016-06-08T02:09:13.277Z",
-      "last_datetime": "2016-06-08T02:09:13.387Z",
-      "ledger_hash": "0E11FA2052E8D345069CF09F13D76A8EF618C32F2B25A948FF104D59F53371BE",
-      "reporter_public_key": "n9KKTtooV4h2UsmNEhBqPvMRNj6RAHLPS6Baktf4u1AhgKNbyJAF",
-      "signature": "3045022100C1252F3FE8D0683F7FE5261D36876650EE185EEFE558150DEEF67F86E928463F022017237E1D89D5DBD8C4C2CC041C2EA73D96260D44A283D6CFF95359E86008E765",
-      "validation_public_key": "n949f75evCHwgyP4fPVgaHqNHxUVN15PsJEZ3B3HnXPcPjcZAoy7"
-    }
-  ]
-}
-
-

Get Validations

-

[Source]

-

Retrieve validation votes, including votes for ledger versions that are outside the main ledger chain. (New in v2.2.0)

-

Note: The Data API does not have a comprehensive record of all validations. The response only includes data that the Data API has recorded. Some ledger versions, especially older ledgers, may have no validations even if they were validated by consensus.

-

Request Format

-
- -
GET /v2/network/validations
-
-
-

Try it!

-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
startString - TimestampFilter results to this time and later.
endString - TimestampFilter results to this time and earlier.
limitIntegerMaximum results per page. Defaults to 200. Cannot be more than 1000.
markerStringPagination key from previously returned response.
formatStringFormat of returned results: csv or json. Defaults to json.
descendingBooleanIf true, return results sorted with earliest first. Otherwise, return oldest results first. Defaults to false.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that the body represents a successful response.
countIntegerNumber of validation votes returned.
markerString(May be omitted) Pagination marker.
validationsArray of Validation ObjectsThe requested validation votes.
-

Example

-

Request:

-
GET /v2/network/validations?limit=3&descending=true
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "count": 3,
-  "marker": "20160608005421561|nHUBJUyiW7ePZdjoLYrRvLB6JEytaAiX2NFqcmgNqW3CCFgBV7LZ|ADB496DFDBF27382E4D49F79D7EC5DD15229AF21E664934217A82D404748C994",
-  "validations": [
-    {
-      "count": 7,
-      "first_datetime": "2016-06-08T00:54:21.583Z",
-      "last_datetime": "2016-06-08T00:54:21.583Z",
-      "ledger_hash": "ADB496DFDBF27382E4D49F79D7EC5DD15229AF21E664934217A82D404748C994",
-      "reporter_public_key": "n9MVezjxa3Wk1vsZ8omj7Hga3tEcFiNH3gjWwx2SsQxkiamBwFw5",
-      "signature": "3044022027DCB43438A27F4F51DFD436FC078933524C6D675DBD7E0033C5A33DA3683699022029A5143EE172CA94AAD706454192CC2EC3CC93182697F0B2C00818C1C43ECE27",
-      "validation_public_key": "n949f75evCHwgyP4fPVgaHqNHxUVN15PsJEZ3B3HnXPcPjcZAoy7"
-    },
-    {
-      "count": 1,
-      "first_datetime": "2016-06-08T00:54:21.574Z",
-      "last_datetime": "2016-06-08T00:54:21.574Z",
-      "ledger_hash": "ADB496DFDBF27382E4D49F79D7EC5DD15229AF21E664934217A82D404748C994",
-      "reporter_public_key": "n9MqZ95ENFuf9yCWjZFsvCuvjNv9K3NpYgE9NYLAgzmCkkFpNs9W",
-      "signature": "3044022054FC074D6AFA022316C24EAEAC70644F3646151C164B72FB3B5A509A692ECAA7022038C93B3E282B5475FC9DC962CA4AD15A28796A1C10A978F66B0C8BBFF42A5782",
-      "validation_public_key": "n9MM9o8j5HmjNF2YFcvNWdKxAsMsMf58Ke6WQvcnn7oHLsuvkAtf"
-    },
-    {
-      "count": 1,
-      "first_datetime": "2016-06-08T00:54:21.574Z",
-      "last_datetime": "2016-06-08T00:54:21.574Z",
-      "ledger_hash": "ADB496DFDBF27382E4D49F79D7EC5DD15229AF21E664934217A82D404748C994",
-      "reporter_public_key": "n9MexcuoJg7KsVnJkvyPuLCtJNx5DSWnZbuWpcdsZ2jeqbU1ghEA",
-      "signature": "3045022100B6CD4FAFF0B699689885D48AB4CA449FA9E4E51832737E36BE5AA6642F88C52C02202297D2F4EFE41F512A4985A571E4D64F8161651DF3FA94561B2F583769305E27",
-      "validation_public_key": "n9KeL6TaqiQoUGndmyYKFDE868bFSAQQJ6XT1LmsuCDCebBdF5BV"
-    }
-  ]
-}
-
-

Get Single Validator Reports

-

[Source]

-

Get a single validator's validation vote stats for 24-hour intervals.

-

Request Format

-
- -
GET /v2/network/validators/{:pubkey}/reports
-
-
-

Try it!

-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - -
FieldValueDescription
pubkeyStringValidator public key.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
startString - TimestampStart date and time for historical query. Defaults to 200 days before the current date.
endString - TimestampEnd date and time for historical query. Defaults to most recent data available.
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that the body represents a successful response.
countIntegerNumber of validators returned.
validatorsArray of Single Validator Report ObjectsDaily reports of this validator's validation votes.
-

Each member in the validators array is a Single Validator Report Object with data on that validator's performance on that day. Each has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
dateString - TimestampThe start time of the date this object describes.
total_ledgersIntegerNumber of ledger hashes for which this validator submitted validation votes. If this number is much lower than other validators in the same time period, that could mean the validator had downtime.
main_net_agreementString - NumberThe fraction of consensus-validated production network ledger versions for which this validator voted in this interval. "1.0" indicates 100% agreement.
main_net_ledgersIntegerNumber of consensus-validated production network ledger versions this validator voted for.
alt_net_agreementString - NumberThe fraction of the consensus-validated Test Network ledger versions this validator voted for. "1.0" indicates 100% agreement.
alt_net_ledgersIntegerNumber of consensus-validated Test Network ledger versions this validator voted for.
other_ledgersIntegerNumber of other ledger versions this validator voted for. If this number is high, that could indicate that this validator was running non-standard or out-of-date software.
-

Example

-

Request:

-
GET /v2/network/validators/n949f75evCHwgyP4fPVgaHqNHxUVN15PsJEZ3B3HnXPcPjcZAoy7/reports
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "count": 198,
-  "reports": [
-    {
-      "date": "2015-11-20T00:00:00Z",
-      "total_ledgers": 19601,
-      "main_net_agreement": "1.0",
-      "main_net_ledgers": 19601,
-      "alt_net_agreement": "0.0",
-      "alt_net_ledgers": 0,
-      "other_ledgers": 0
-    },
-    {
-      "date": "2015-11-21T00:00:00Z",
-      "total_ledgers": 19876,
-      "main_net_agreement": "1.0",
-      "main_net_ledgers": 19876,
-      "alt_net_agreement": "0.0",
-      "alt_net_ledgers": 0,
-      "other_ledgers": 0
-    },
-
-    ...
-  ]
-}
-
-

Get Daily Validator Reports

-

[Source]

-

Get a validation vote stats and validator information for all known validators in a 24-hour period.

-

Request Format

-
- -
GET /v2/network/validator_reports
-
-
-

Try it!

-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
dateString - TimestampDate and time to query. By default, uses the most recent data available.
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that the body represents a successful response.
countIntegerNumber of reports returned.
reportsArray of Daily Validator Report ObjectsSummaries of activity for each validator active during this time period.
-

Daily Validator Report Object fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
validation_public_keyString - Base-58 Public KeyThis validator's validator public key.
dateString - TimestampThe start time of the date this object describes.
total_ledgersIntegerNumber of ledger indexes for which this validator submitted validation votes. If this number is much lower than other validators in the same time period, that could mean the validator had downtime.
main_net_agreementString - NumberThe fraction of consensus-validated production network ledger versions for which this validator voted in this interval. "1.0" indicates 100% agreement.
main_net_ledgersIntegerNumber of consensus-validated production network ledger versions this validator voted for.
alt_net_agreementString - NumberThe fraction of the consensus-validated Test Network ledger versions this validator voted for. "1.0" indicates 100% agreement.
alt_net_ledgersIntegerNumber of consensus-validated Test Network ledger versions this validator voted for.
other_ledgersIntegerNumber of other ledger versions this validator voted for. If this number is high, that could indicate that this validator was running non-standard or out-of-date software.
last_datetimeIntegerThe last reported validation vote signed by this validator.
domainString(May be omitted) The DNS domain associated with this validator.
domain_stateStringThe value verified indicates that this validator has a verified domain controlled by the same operator as the validator. The value AccountDomainNotFound indicates that the "Account Domain" part of Domain Verification is not set up properly. The value RippleTxtNotFound indicates that the ripple.txt step of Domain Verification is not set up properly.
-

Example

-

Request:

-
GET /v2/network/validator_reports
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "count": 27,
-  "reports": [
-    {
-      "validation_public_key": "n9KvSsyJiheyFnivzFqChZ58pQgjwWWuc7Tp28WPzXbkdwqL6P5y",
-      "date": "2016-06-07T00:00:00Z",
-      "total_ledgers": 1289,
-      "main_net_agreement": "1.00000",
-      "main_net_ledgers": 1289,
-      "alt_net_agreement": "0.00000",
-      "alt_net_ledgers": 0,
-      "other_ledgers": 0,
-      "domain": "rippled.media.mit.edu",
-      "domain_state": "verified",
-      "last_datetime": "2016-06-07T01:20:20.753Z"
-    },
-    {
-      "validation_public_key": "n949f75evCHwgyP4fPVgaHqNHxUVN15PsJEZ3B3HnXPcPjcZAoy7",
-      "date": "2016-06-07T00:00:00Z",
-      "total_ledgers": 1289,
-      "main_net_agreement": "1.00000",
-      "main_net_ledgers": 1289,
-      "alt_net_agreement": "0.00000",
-      "alt_net_ledgers": 0,
-      "other_ledgers": 0,
-      "domain": "ripple.com",
-      "domain_state": "verified",
-      "last_datetime": "2016-06-07T01:20:20.717Z"
-    },
-
-    ...
-  ]
-}
-
-

Get rippled Versions

-

[Source]

-

Reports the latest versions of rippled available from the official Ripple Yum repositories. (New in v2.3.0.)

-

Request Format

-
- -
GET /v2/network/rippled_versions
-
-
-

Try it!

-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that the body represents a successful response.
countIntegerNumber of rows returned.
rowsArray of Version ObjectsDescription of the latest rippled version in each repository.
-

Each Version Object contains the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
dateString - TimestampThe date this rippled version was released.
repoStringThe Yum repository where this rippled is available. The stable repository has the latest production version. Other versions are for development and testing.
versionStringThe version string for this version of rippled.
-

Example

-

Request:

-
GET /v2/network/rippled_versions
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "count": 3,
-  "rows": [
-    {
-      "date": "2016-06-24T00:00:00Z",
-      "repo": "nightly",
-      "version": "0.32.0-rc2"
-    },
-    {
-      "date": "2016-06-24T00:00:00Z",
-      "repo": "stable",
-      "version": "0.32.0"
-    },
-    {
-      "date": "2016-06-24T00:00:00Z",
-      "repo": "unstable",
-      "version": "0.32.0-rc1"
-    }
-  ]
-}
-
-

Get All Gateways

-

[Source]

-

Get information about known gateways. (New in v2.0.4)

-

Request Format

-
- -
GET /v2/gateways/
-
-
-

Try it!

-

This method takes no query parameters.

-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body.

-

Each field in the top level JSON object is a Currency Code. The content of each field is an array of objects, representing gateways that issue that currency. Each object has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
nameStringA human-readable proper name for the gateway.
accountString - AddressThe issuing address of this currency.
featuredBooleanWhether this gateway is considered a "featured" issuer of the currency. Ripple decides which gateways to feature based on responsible business practices, volume, and other measures.
labelString(May be omitted) Only provided when the Currency Code is a 40-character hexadecimal value. This is an alternate human-readable name for the currency issued by this gateway.
assetsArray of StringsGraphics filenames available for this gateway, if any. (Mostly, these are logos used by XRP Charts.)
-

Example

-

Request:

-
GET /v2/gateways/
-
-

Response:

-
200 OK
-{
-    "AUD": [
-        {
-            "name": "Bitstamp",
-            "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-            "featured": false,
-            "assets": [
-                "logo.grayscale.svg",
-                "logo.svg"
-            ]
-        },
-        {
-            "name": "Coinex",
-            "account": "rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc",
-            "featured": false,
-            "assets": []
-        }
-    ],
-
-... (additional results trimmed) ...
-
-    "0158415500000000C1F76FF6ECB0BAC600000000": [
-        {
-            "name": "GBI",
-            "account": "rrh7rf1gV2pXAoqA8oYbpHd8TKv5ZQeo67",
-            "featured": false,
-            "label": "XAU (-0.5pa)",
-            "assets": []
-        }
-    ],
-    "KRW": [
-        {
-            "name": "EXRP",
-            "account": "rPxU6acYni7FcXzPCMeaPSwKcuS2GTtNVN",
-            "featured": true,
-            "assets": []
-        },
-        {
-            "name": "Pax Moneta",
-            "account": "rUkMKjQitpgAM5WTGk79xpjT38DEJY283d",
-            "featured": false,
-            "assets": []
-        }
-    ]
-}
-
-

Get Gateway

-

[Source]

- -

Get information about a specific gateway from the Data API's list of known gateways. (New in v2.0.4)

-

Request Format

-
- -
GET /v2/gateways/{:gateway}
-
-
-

Try it!

-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - -
FieldValueDescription
gatewayStringThe issuing Address, URL-encoded name, or normalized name of the gateway.
-

This method takes no query parameters.

-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
nameStringHuman-readable name of the gateway.
start_dateString - TimestampThe approximate date of the first time exchanges for this gateway's currencies appeared in the ledger.
accountsArrayA list of issuing addresses used by this gateway. (Gateways may use different issuing accounts for different currencies.)
hotwalletsArray of AddressesThis gateway's operational addresses.
domainStringThe domain name where this gateway does business. Typically the gateway hosts a ripple.txt there.
normalizedStringA normalized version of the name field suitable for including in URLs.
assetsArray of StringsGraphics filenames available for this gateway, if any. (Mostly, these are logos used by XRP Charts.)
-

Each object in the accounts field array has the following fields:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
addressStringThe issuing address used by this gateway.
currenciesObjectEach field in this object is a Currency Code corresponding to a currency issued from this address. Each value is an object with a featured boolean indicating whether that currency is featured. Ripple decides which currencies and gateways to feature based on responsible business practices, volume, and other measures.
-

Example

-

Request:

-
GET /v2/gateways/Gatehub
-
-

Response:

-
200 OK
-{
-    "name": "Gatehub",
-    "start_date": "2015-02-15T00:00:00Z",
-    "accounts": [
-        {
-            "address": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
-            "currencies": {
-                "EUR": {
-                    "featured": true
-                },
-                "USD": {
-                    "featured": true
-                }
-            }
-        }
-    ],
-    "hotwallets": [
-        "rhotcWYdfn6qxhVMbPKGDF3XCKqwXar5J4"
-    ],
-    "domain": "gatehub.net",
-    "normalized": "gatehub",
-    "assets": [
-        "logo.grayscale.svg",
-        "logo.svg"
-    ]
-}
-
-

Get Currency Image

-

[Source]

-

Retrieve vector icons for various currencies. (New in v2.0.4)

-

Request Format

-
- -
GET /v2/currencies/{:currencyimage}
-
-
-

This method requires the following URL parameter:

- - - - - - - - - - - - - - - -
FieldValueDescription
currencyimageStringAn image file for a currency, such as xrp.svg. See the source code for a list of available images.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a Content-Type header of image/svg+xml to indicate that the contents are XML representing a file in SVG format.

-

Example

-

Request:

-
GET /v2/currencies/mxn.svg
-
-

Response

-
200 OK
-Content-Type: image/svg+xml
-<?xml version="1.0" encoding="utf-8"?>
-<!-- Generator: Adobe Illustrator 18.1.1, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
-<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
-     width="200px" height="200px" viewBox="0 0 200 200" enable-background="new 0 0 200 200" xml:space="preserve">
-<g>
-    <path fill="#FC6E74" d="M105.1,181.5c-12.2,0-24-2.1-35.1-6.2c-11.1-4.1-21.6-10.5-31.1-19.1l-1.3-1.2l18.8-22.3l1.4,1.2
-        c7.4,6.4,14.9,11.3,22.4,14.7c7.4,3.4,16,5.1,25.5,5.1c8,0,14.4-1.7,19-5c4.5-3.2,6.7-7.3,6.7-12.7c0-3-0.4-5.2-1.3-7.1
-        c-0.8-1.8-2.4-3.6-4.8-5.4c-2.4-1.8-5.9-3.5-10.2-5.1c-4.5-1.6-10.3-3.2-17.5-4.8c-8.3-1.9-15.8-4.1-22.4-6.6
-        c-6.6-2.5-12.3-5.6-16.8-9.2C54,94.3,50.4,89.8,48,84.5c-2.4-5.2-3.6-11.6-3.6-18.9c0-7.4,1.4-13.8,4.1-19.5
-        c2.7-5.8,6.6-10.7,11.4-14.8c4.8-4.1,10.6-7.3,17.3-9.5c6.7-2.3,14-3.4,21.9-3.4c11.6,0,22.2,1.7,31.4,5.1
-        c9.3,3.4,18.1,8.4,26.2,14.8l1.4,1.1l-16.8,23.6l-1.5-1.1c-6.9-5-13.9-9-20.7-11.6c-6.7-2.6-13.6-4-20.4-4
-        c-7.5,0-13.4,1.6-17.5,4.9c-4,3.2-6,7-6,11.6c0,3.1,0.5,5.5,1.4,7.5c0.9,2,2.6,3.8,5,5.4c2.6,1.8,6.3,3.4,10.9,5
-        c4.8,1.6,10.9,3.3,18.2,5c8.3,2.1,15.7,4.4,22,7c6.5,2.6,12,5.8,16.3,9.5c4.3,3.8,7.7,8.3,9.9,13.3c2.2,5,3.4,10.9,3.4,17.5
-        c0,7.9-1.4,14.7-4.2,20.7c-2.8,6-6.8,11.1-11.9,15.3c-5,4.1-11.1,7.3-18.1,9.4C121.2,180.5,113.4,181.5,105.1,181.5z"/>
-    <rect x="86.7" y="0" fill="#FC6E74" width="26.5" height="40.1"/>
-    <rect x="86.5" y="159.2" fill="#FC6E74" width="27" height="40.8"/>
-</g>
-</svg>
-
-

Get Accounts

-

[Source]

-

Retrieve information about the creation of new accounts in the XRP Ledger.

-

Request Format

-
- -
GET /v2/accounts
-
-
-

Try it!

-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
startString - TimestampStart time of query range.
endString - TimestampEnd time of query range.
intervalStringAggregation interval (hour,day,week). If omitted, return individual accounts. Not compatible with the parent parameter.
limitIntegerMaximum results per page. Defaults to 200. Cannot be more than 1,000.
markerStringPagination key from previously returned response.
descendingBooleanIf true, return results in reverse chronological order. Defaults to false.
parentStringFilter results to children of the specified parent account. Not compatible with the interval parameter.
reduceBooleanReturn a count of results only.
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
countIntegerNumber of accounts returned.
markerString(May be omitted) Pagination marker.
accountsArrayIf the request used the interval query parameter, each member of the array is an interval object. Otherwise, this field is an array of account creation objects.
-
Interval Objects
-

If the request uses the interval query parameter, the response has an array of interval objects, each of which represents the number of accounts created during a single interval. Interval objects have the following fields:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
dateString - TimestampWhen this interval starts. (The length of the interval is determined by the request.)
countNumberHow many accounts were created in this interval.
-

Example

-

Request:

-
GET /v1/accounts?parent=rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "count": 3,
-  "accounts": [
-    {
-      "balance": "20.0",
-      "account": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
-      "executed_time": "2015-02-09T23:31:40+00:00",
-      "ledger_index": 11620700,
-      "parent": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-      "tx_hash": "1D381C0FCA00E8C34A6D4D3A91DAC9F3697B4E66BC49ED3D9B2D6F57D7F15E2E"
-    },
-    {
-      "balance": "30",
-      "account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
-      "executed_time": "2015-06-16T21:15:40+00:00",
-      "ledger_index": 14090928,
-      "parent": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-      "tx_hash": "60B614622FC67DFCA8D796D7F6AF0B7AEC5E59BB268EA032F810395407DDF8D5"
-    },
-    {
-      "balance": "50",
-      "account": "rLFd1FzHMScFhLsXeaxStzv3UC97QHGAbM",
-      "executed_time": "2015-09-23T23:05:20+00:00",
-      "ledger_index": 16061430,
-      "parent": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-      "tx_hash": "FAE331A6D5CB83BCE832E7EBEDBD807EDEFFAF39AB241683EE81A0326A1A6748"
-    }
-  ]
-}
-
-

Get Account

-

[Source]

-

Get creation info for a specific ripple account

-

Request Format

-
- -
GET /v2/accounts/{:address}
-
-
-

Try it!

-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - -
FieldValueDescription
addressStringXRP Ledger address to query.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
accountObject - Account CreationThe requested account.
-

Example

-

Request:

-
GET /v2/accounts/rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn
-
-

Response:

-
200 OK
-{
-    "result": "success",
-    "account": {
-        "address": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-        "parent": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-        "initial_balance": "100.0",
-        "inception": "2014-05-29T17:05:20+00:00",
-        "ledger_index": 6902264,
-        "tx_hash": "074415C5DC6DB0029E815EA6FC2629FBC29A2C9D479F5D040AFF94ED58ECC820"
-    }
-}
-
-

Get Account Balances

-

[Source]

-

Get all balances held or owed by a specific XRP Ledger account.

-
- -
GET /v2/accounts/{:address}/balances
-
-
-

Try it!

-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - -
FieldValueDescription
addressStringXRP Ledger address to query.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
ledger_indexIntegerIndex of ledger for historical balances.
ledger_hashStringLedger hash for historical balances.
dateStringUTC date for historical balances.
currencyStringRestrict results to specified currency.
counterpartyStringRestrict results to specified counterparty/issuer.
limitIntegerMaximum results per page. Defaults to 200. Cannot be greater than 400, but you can use the value all to return all results. (Caution: When using limit=all to retrieve very many results, the request may time out. For large issuers, there can be several tens of thousands of results.)
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
ledger_indexIntegerledger index for balances query.
close_timeStringclose time of the ledger.
limitStringnumber of results returned, if limit was exceeded.
markerString(May be omitted) Pagination marker.
balancesArray of Balance ObjectsThe requested balances.
-

Example

-

Request:

-
GET /v2/accounts/rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn/balances?currency=USD&date=2015-01-01T00:00:00Z&limit=3
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "ledger_index": 10852618,
-  "close_time": "2015-01-01T00:00:00Z",
-  "limit": 3,
-  "balances": [
-    {
-      "currency": "USD",
-      "counterparty": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-      "value": "-11.0301"
-    },
-    {
-      "currency": "USD",
-      "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-      "value": "0.0001"
-    },
-    {
-      "currency": "USD",
-      "counterparty": "rweYz56rfmQ98cAdRaeTxQS9wVMGnrdsFp",
-      "value": "0"
-    }
-  ]
-}
-
-

Get Account Orders

-

[Source]

-

Get orders in the order books, placed by a specific account. This does not return orders that have already been filled.

-

Request Format

-
- -
GET /v2/account/{:address}/orders
-
-
-

Try it!

-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - -
FieldValueDescription
addressString - AddressXRP Ledger address to query.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
ledger_indexIntegerGet orders as of this ledger. Not compatible with ledger_hash or date.
ledger_hashStringGet orders as of this ledger. Not compatible with ledger_index or date.
dateString - TimestampGet orders at this time. Not compatible with ledger_index or ledger_hash.
limitIntegerMaximum results per page. Defaults to 200. Cannot be greater than 400.
formatStringFormat of returned results: csv or json. Defaults to json.
-

If none of ledger_index, ledger_hash, or date are specified, the API uses the most current data available.

-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
ledger_indexIntegerledger_index of the ledger version used.
close_timeStringClose time of the ledger version used.
limitStringThe limit from the request.
ordersArray of order objectsThe requested orders.
-

Each order object has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
specificationObjectDetails of this order's current state.
specification.directionStringEither buy or sell.
specification.quantityBalance ObjectThe maximum amount of the base currency this order would buy or sell (depending on the direction). This value decreases as the order gets partially filled.
specification.totalPriceBalance ObjectThe maximum amount of the counter currency the order can spend or gain to buy or sell the base currency. This value decreases as the order gets partially filled.
propertiesObjectDetails of how the order was placed.
properties.makerString - AddressThe XRP Ledger account that placed the order.
properties.sequenceNumberThe sequence number of the transaction that placed this order.
properties.makerExchangeRateString - NumberThe exchange rate from the point of view of the account that submitted the order.
-

Example

-

Request:

-
GET /v2/accounts/rK5j9n8baXfL4gzUoZsfxBvvsv97P5swaV/orders?limit=2&date=2015-11-11T00:00:00Z
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "ledger_index": 17007855,
-  "close_time": "2015-11-11T00:00:00Z",
-  "limit": 2,
-  "orders": [
-    {
-      "specification": {
-        "direction": "buy",
-        "quantity": {
-          "currency": "JPY",
-          "value": "56798.00687665813",
-          "counterparty": "r94s8px6kSw1uZ1MV98dhSRTvc6VMPoPcN"
-        },
-        "totalPrice": {
-          "currency": "USD",
-          "value": "433.792841227449",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        }
-      },
-      "properties": {
-        "maker": "rK5j9n8baXfL4gzUoZsfxBvvsv97P5swaV",
-        "sequence": 7418286,
-        "makerExchangeRate": "130.9334813270407"
-      }
-    },
-    {
-      "specification": {
-        "direction": "buy",
-        "quantity": {
-          "currency": "JPY",
-          "value": "11557.02705273459",
-          "counterparty": "r94s8px6kSw1uZ1MV98dhSRTvc6VMPoPcN"
-        },
-        "totalPrice": {
-          "currency": "USD",
-          "value": "87.570156003591",
-          "counterparty": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq"
-        }
-      },
-      "properties": {
-        "maker": "rK5j9n8baXfL4gzUoZsfxBvvsv97P5swaV",
-        "sequence": 7418322,
-        "makerExchangeRate": "131.9744942815983"
-      }
-    }
-  ]
-}
-
-

Get Account Transaction History

-

[Source]

-

Retrieve a history of transactions that affected a specific account. This includes all transactions the account sent, payments the account received, and payments that rippled through the account.

-

Request Format

-
- -
GET /v2/accounts/{:address}/transactions
-
-
-

Try it!

-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - -
FieldValueDescription
:addressString - AddressXRP Ledger address to query.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
startString - TimestampStart time of query range. Defaults to the earliest date available.
endString - TimestampEnd time of query range. Defaults to the current date.
min_sequenceStringMinimum sequence number to query.
max_sequenceStringMax sequence number to query.
typeStringRestrict results to a specified transaction type
resultStringRestrict results to specified transaction result.
binaryBooleanReturn results in binary format.
descendingBooleanIf true, return results in reverse chronological order. Defaults to false.
limitIntegerMaximum results per page. Defaults to 20. Cannot be more than 1,000.
markerStringPagination key from previously returned response.
-

Note: This method cannot return CSV format; only JSON results are supported for raw XRP Ledger transactions.

-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
countIntegerThe number of objects contained in the transactions field.
markerString(May be omitted) Pagination marker.
transactionsArray of transaction objectsAll transactions matching the request.
-

Example

-

Request:

-
GET /v2/accounts/rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn/transactions?type=Payment&result=tesSUCCESS&limit=1
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "count": 1,
-  "marker": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn|20140602224750|000006979192|00001",
-  "transactions": [
-    {
-      "hash": "074415C5DC6DB0029E815EA6FC2629FBC29A2C9D479F5D040AFF94ED58ECC820",
-      "date": "2014-05-29T17:05:20+00:00",
-      "ledger_index": 6902264,
-      "tx": {
-        "TransactionType": "Payment",
-        "Flags": 0,
-        "Sequence": 1,
-        "LastLedgerSequence": 6902266,
-        "Amount": "100000000",
-        "Fee": "12",
-        "SigningPubKey": "032ECFCC409F02057D8556988B89E17D48ECFC8373965036C6BA294AA2B7972971",
-        "TxnSignature": "30450221008D8E251DA5EA17A29CC9192717860F3B4047E74DF005127A65D9140CAE870C0902201C8E4548D2D3BA11B3E13CE8A167EBC076920E2B1C38547275CAA75FEC436EB9",
-        "Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-        "Destination": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
-      },
-      "meta": {
-        "TransactionIndex": 1,
-        "AffectedNodes": [
-          {
-            "CreatedNode": {
-              "LedgerEntryType": "AccountRoot",
-              "LedgerIndex": "13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8",
-              "NewFields": {
-                "Sequence": 1,
-                "Balance": "100000000",
-                "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
-              }
-            }
-          },
-          {
-            "ModifiedNode": {
-              "LedgerEntryType": "AccountRoot",
-              "PreviousTxnLgrSeq": 6486567,
-              "PreviousTxnID": "FF9BFF3C200B475CA7EE54F9A98EAB7E92BBDBD2DBE95AC854405D8A85C9D535",
-              "LedgerIndex": "43EA78783A089B137D5E87610DF3BD4129F989EDD02EFAF6C265924D3A0EF8CE",
-              "PreviousFields": {
-                "Sequence": 1,
-                "Balance": "1000000000"
-              },
-              "FinalFields": {
-                "Flags": 0,
-                "Sequence": 2,
-                "OwnerCount": 0,
-                "Balance": "899999988",
-                "Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX"
-              }
-            }
-          }
-        ],
-        "TransactionResult": "tesSUCCESS"
-      }
-    }
-  ]
-}
-
-

Get Transaction By Account And Sequence

-

[Source]

-

Retrieve a specifc transaction originating from a specified account

-

Request Format

-
- -
GET /v2/accounts/{:address}/transactions/{:sequence}
-
-
-

Try it!

-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
addressStringXRP Ledger address to query.
sequenceIntegerTransaction sequence number.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - -
FieldValueDescription
binaryBooleanIf true, return transaction in binary format. Defaults to false.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
transactiontransaction objectThe requested transaction.
-

Example

-

Request:

-
GET /v2/accounts/rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn/transactions/10?binary=true
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "transaction": {
-    "hash": "4BFFBB86C12659B6C5BB88F0EB859356DE3433EBACBFD9F50F6E70B2C05CCFE0",
-    "date": "2014-09-15T19:59:10+00:00",
-    "ledger_index": 8889812,
-    "tx": "1200052200000000240000000A68400000000000000A732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB74473045022100AA4AF08726FCF0F28AA4A841C45F975C3BF1545648F6907DCB33F6E3DD7E85D6022037365B80AB1972BF8A4280009A0DBCF16A1D562ED0489B155750E48CC939039981144B4E9C06F24296074F7BC48F92A97916C6DC5EA9",
-    "meta": "201C00000003F8E5110061250087A5C555CBCA96F4C42E0EBC0E75C5AD84B3403FEDF824A7DAFA45ADCA6ECB66AA143C1B5613F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8E6240000000A62400000000DB5852F8814D3484B9ED2556DCE16A3B928B438BA6EE0FF0989E1E72200010000240000000B2D0000000062400000000DB5852572110000000000000000000000070000000300770A6D64756F31332E636F6D81144B4E9C06F24296074F7BC48F92A97916C6DC5EA9E1E1F1031000"
-  }
-}
-
-

Get Account Payments

-

[Source]

-

Retrieve a payments for a specified account

-

Request Format

-
- -
GET /v2/accounts/{:address}/payments
-
-
-

Try it!

-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - -
FieldValueDescription
addressStringXRP Ledger address to query.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
startString - TimestampFilter results to this time and later.
endString - TimestampFilter results to this time and earlier.
typeStringType of payment - sent or received.
currencyString - Currency CodeFilter results to specified currency.
issuerString - AddressFilter results to specified issuer.
source_tagIntegerFilter results to specified source tag.
destination_tagIntegerFilter results to specified destination tag.
descendingBooleanIf true, sort results with most recent first. Otherwise, return oldest results first. Defaults to false.
limitIntegerMaximum results per page. Defaults to 200. Cannot be more than 1,000.
markerStringPagination key from previously returned response.
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
countIntegerThe number of objects contained in the payments field.
markerString(May be omitted) Pagination marker.
paymentsArray of payment objectsAll payments matching the request.
-

Example

-

Request:

-
GET /v2/accounts/rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn/payments?currency=USD&limit=1
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "count": 1,
-  "marker": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn|20140604191650|000007013674|00000",
-  "payments": [
-    {
-      "amount": "1.0",
-      "delivered_amount": "1.0",
-      "destination_balance_changes": [
-        {
-          "counterparty": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-          "currency": "USD",
-          "value": "1"
-        }
-      ],
-      "source_balance_changes": [
-        {
-          "counterparty": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-          "currency": "USD",
-          "value": "-1"
-        }
-      ],
-      "tx_index": 1,
-      "currency": "USD",
-      "destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-      "executed_time": "2014-06-02T22:47:50Z",
-      "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-      "ledger_index": 6979192,
-      "source": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-      "source_currency": "USD",
-      "tx_hash": "7BF105CFE4EFE78ADB63FE4E03A851440551FE189FD4B51CAAD9279C9F534F0E",
-      "transaction_cost": "1.0E-5"
-    }
-  ]
-}
-
-

Get Account Exchanges

-

[Source]

-

Retrieve Exchanges for a given account over time.

-

Request Format

-

There are two variations on this method:

-
- -
GET /v2/accounts/{:address}/exchanges/
-
- -
GET /v2/accounts/{:address}/exchanges/{:base}/{:counter}
-
-
-

Try it!

-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
addressStringXRP Ledger address to query.
baseStringBase currency of the pair, as a Currency Code, followed by + and the issuer Address unless it's XRP.
counterStringCounter currency of the pair, as a Currency Code, followed by + and the issuer Address unless it's XRP.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
startString - TimestampFilter results to this time and later.
endString - TimestampFilter results to this time and earlier.
descendingBooleanIf true, return results in reverse chronological order. Defaults to false.
limitIntegerMaximum results per page. Defaults to 200. Cannot be more than 1000.
markerStringPagination key from previously returned response.
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
countIntegerNumber of exchanges returned.
markerString(May be omitted) Pagination marker.
exchangesArray of Exchange ObjectsThe requested exchanges.
-

Example

-

Request:

-
GET /v2/accounts/rsyDrDi9Emy6vPU78qdxovmNpmj5Qh4NKw/exchanges/KRW+rUkMKjQitpgAM5WTGk79xpjT38DEJY283d/XRP?start=2015-08-08T00:00:00Z&end=2015-08-31T00:00:00Z&limit=2
-
-
-

Response:

-
200 OK
-{
-    "result": "success",
-    "count": 2,
-    "marker": "rsyDrDi9Emy6vPU78qdxovmNpmj5Qh4NKw|20150810014200|000015162386|00013|00003",
-    "exchanges": [
-        {
-            "base_amount": 209.3501241148,
-            "counter_amount": 20.424402,
-            "rate": 0.097560973925,
-            "autobridged_currency": "USD",
-            "autobridged_issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-            "base_currency": "KRW",
-            "base_issuer": "rUkMKjQitpgAM5WTGk79xpjT38DEJY283d",
-            "buyer": "rnAqwsu2BEbCjacoZmsXrpViqd3miZhHbT",
-            "counter_currency": "XRP",
-            "executed_time": "2015-08-08T02:57:40",
-            "ledger_index": 15122851,
-            "offer_sequence": "1738",
-            "provider": "rsyDrDi9Emy6vPU78qdxovmNpmj5Qh4NKw",
-            "seller": "rsyDrDi9Emy6vPU78qdxovmNpmj5Qh4NKw",
-            "taker": "rnAqwsu2BEbCjacoZmsXrpViqd3miZhHbT",
-            "tx_hash": "506D109A609A5E0778276CCBB125A4AA7B78428059F069A2CB4F739B861C0C49",
-            "tx_type": "OfferCreate"
-        },
-        {
-            "base_amount": 86355.6498758851,
-            "counter_amount": 8424.941452,
-            "rate": 0.097560975618,
-            "base_currency": "KRW",
-            "base_issuer": "rUkMKjQitpgAM5WTGk79xpjT38DEJY283d",
-            "buyer": "r9xQi5YT8jqVM3wZhbiV94ZKKvGHaVeSDj",
-            "client": "rt1.1-26-gbeb68ab",
-            "counter_currency": "XRP",
-            "executed_time": "2015-08-08T07:15:00",
-            "ledger_index": 15126536,
-            "offer_sequence": "1738",
-            "provider": "rsyDrDi9Emy6vPU78qdxovmNpmj5Qh4NKw",
-            "seller": "rsyDrDi9Emy6vPU78qdxovmNpmj5Qh4NKw",
-            "taker": "r9xQi5YT8jqVM3wZhbiV94ZKKvGHaVeSDj",
-            "tx_hash": "C897A595DED16ADF5AD52E6FD9CE5DE65C78A93CCAA62A85248DC3015A78F5C4",
-            "tx_type": "Payment"
-        }
-    ]
-}
-
-

Get Account Balance Changes

-

[Source]

-

Retrieve Balance changes for a given account over time.

-

Request Format

-
- -
GET /v2/accounts/{:address}/balance_changes/
-
-
-

Try it!

-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - -
FieldValueDescription
addressStringXRP Ledger address to query.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
currencyStringRestrict results to specified currency.
counterpartyStringRestrict results to specified counterparty/issuer.
startString - TimestampStart time of query range.
endString - TimestampEnd time of query range.
descendingBooleanIf true, return results in reverse chronological order. Defaults to false.
limitIntegerMaximum results per page. Defaults to 200. Cannot be more than 1000.
markerStringPagination key from previously returned response.
formatStringFormat of returned results: csv orjson. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
countIntegerNumber of balance changes returned.
markerString(May be omitted) Pagination marker.
exchangesArray of balance change descriptorsThe requested balance changes.
-

Example

-

Request:

-
GET /v2/accounts/rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn/balance_changes?descending=true&limit=3
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "count": 3,
-  "marker": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn|20160122235211|000018425487|00010|00001",
-  "balance_changes": [
-    {
-      "amount_change": "-0.012",
-      "final_balance": "75.169663",
-      "tx_index": 7,
-      "change_type": "transaction_cost",
-      "currency": "XRP",
-      "executed_time": "2016-01-29T22:57:20Z",
-      "ledger_index": 18555460,
-      "tx_hash": "2B44EBE00728D04658E597A85EC4F71D20503B31ABBF556764AD8F7A80BA72F6"
-    },
-    {
-      "amount_change": "-25.0",
-      "final_balance": "75.181663",
-      "node_index": 1,
-      "tx_index": 4,
-      "change_type": "payment_source",
-      "currency": "XRP",
-      "executed_time": "2016-01-26T08:32:20Z",
-      "ledger_index": 18489336,
-      "tx_hash": "E5C6DD25B2DCF534056D98A2EFE3B7CFAE4EBC624854DE3FA436F733A56D8BD9"
-    },
-    {
-      "amount_change": "-0.01",
-      "final_balance": "100.181663",
-      "tx_index": 4,
-      "change_type": "transaction_cost",
-      "currency": "XRP",
-      "executed_time": "2016-01-26T08:32:20Z",
-      "ledger_index": 18489336,
-      "tx_hash": "E5C6DD25B2DCF534056D98A2EFE3B7CFAE4EBC624854DE3FA436F733A56D8BD9"
-    }
-  ]
-}
-
-

Get Account Reports

-

[Source]

-

Retrieve daily summaries of payment activity for an account.

-
- -
GET /v2/accounts/{:address}/reports/
-
- -
GET /v2/accounts/{:address}/reports/{:date}
-
-
-

Try it!

-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
addressStringXRP Ledger address to query.
dateString(Optional) UTC date for single report. If omitted, use the start and end query parameters.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
startString - TimestampStart time of query range. Defaults to start of current date. Ignored if date specified.
endString - TimestampEnd time of query range. Defaults to current date. Ignored if date specified.
accountsBooleanIf true, provide lists with addresses of all sending_counterparties and receiving_counterparties in results. Otherwise, return only the number of sending and receiving counterparties.
paymentsBooleanInclude Payment Summary Objects in the payments field for each interval, with the payments that occurred during that interval.
descendingBooleanIf true, sort results with most recent first. By default, sort results with oldest first.
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
countIntegerNumber of reports in the reports field.
reportsArray of Reports ObjectsDaily summaries of account activity for the given account and date range.
-

Example

-

Request:

-
GET /v2/accounts/rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q/reports?start=2015-08-28T00:00:00&end=2015-08-28T00:00:00&accounts=true&payments=true&descending=true
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "count": 1,
-  "reports": [
-    {
-      "account": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-      "date": "2015-08-28T00:00:00+00:00",
-      "high_value_received": 89500.74142547617,
-      "high_value_sent": 0,
-      "payments": [
-        {
-          "tx_hash": "F2323EE7494384E77ABB18F31981FEE8C31767BBD27515B55FC3BD6792C4E408",
-          "amount": 2.7,
-          "currency": "BTC",
-          "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-          "type": "received"
-        },
-        {
-          "tx_hash": "FEAD462738EE430E154FF3122D3EE2DD27DDD8BEFBA080A60FE91B78E8865365",
-          "amount": 3,
-          "currency": "BTC",
-          "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-          "type": "received"
-        },
-        {
-          "tx_hash": "383B1D1EABB646AB2EFBBF9E8967FE279BFE5EF86A3B6BCD5BDA287210053116",
-          "amount": 0.14,
-          "currency": "BTC",
-          "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-          "type": "received"
-        }
-      ],
-      "payments_received": 3,
-      "payments_sent": 0,
-      "receiving_counterparties": [],
-      "sending_counterparties": [
-        "rhi4zZdCeFdfTokzek8D7p9bUWmtEFCZAe",
-        "rP1hkW1LCiVos6FpzU7itmm9Tk29yqvyk5"
-      ],
-      "total_value": 174019.58324753598,
-      "total_value_received": 174019.58324753598,
-      "total_value_sent": 0
-    }
-  ]
-}
-
-

Get Account Transaction Stats

-

[Source]

-

Retrieve daily summaries of transaction activity for an account. (New in v2.1.0.)

-
- -
GET /v2/accounts/{:address}/stats/transactions
-
-
-

Try it!

-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - -
FieldValueDescription
addressStringXRP Ledger address to query.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
startString - TimestampStart time of query range. Defaults to the earliest date available.
endString - TimestampEnd time of query range. Defaults to the current date.
limitIntegerMaximum results per page. Defaults to 200. Cannot be more than 1000.
descendingBooleanIf true, sort results with most recent first. By default, sort results with oldest first.
markerStringPagination key from previously returned response.
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
countIntegerNumber of transaction stats objects in the rows field.
rowsArray of Transaction Stats ObjectsDaily summaries of account transaction activity for the given account.
-

Each Transaction Stats Object has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
dateString - TimestampThis object describes activity on this date.
transaction_countIntegerThe total number of transactions sent by the account on this date.
resultObjectMap of transaction result codes, indicating how many of each result code occurred in the transactions sent by this account on this date.
typeObjectMap of transaction types, indicating how many of each transaction type the account sent on this date.
-

Example

-

Request:

-
GET /v2/accounts/rGFuMiw48HdbnrUbkRYuitXTmfrDBNTCnX/stats/transactions?start=2015-01-01&limit=2
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "count": 2,
-  "marker": "rGFuMiw48HdbnrUbkRYuitXTmfrDBNTCnX|20150116000000",
-  "rows": [
-    {
-      "date": "2015-01-14T00:00:00Z",
-      "transaction_count": 44,
-      "result": {
-        "tecUNFUNDED_PAYMENT": 1,
-        "tesSUCCESS": 43
-      },
-      "type": {
-        "Payment": 42,
-        "TrustSet": 2
-      }
-    },
-    {
-      "date": "2015-01-15T00:00:00Z",
-      "transaction_count": 116,
-      "result": {
-        "tesSUCCESS": 116
-      },
-      "type": {
-        "Payment": 116
-      }
-    }
-  ]
-}
-
-

Get Account Value Stats

-

[Source]

-

Retrieve daily summaries of transaction activity for an account. (New in v2.1.0.)

-
- -
GET /v2/accounts/{:address}/stats/value
-
-
-

Try it!

-

This method requires the following URL parameters:

- - - - - - - - - - - - - - - -
FieldValueDescription
addressStringXRP Ledger address to query.
-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
startString - TimestampStart time of query range. Defaults to the start of the most recent interval.
endString - TimestampEnd time of query range. Defaults to the end of the most recent interval.
limitIntegerMaximum results per page. Defaults to 200. Cannot be more than 1000.
markerStringPagination key from previously returned response.
descendingBooleanIf true, sort results with most recent first. By default, sort results with oldest first.
formatStringFormat of returned results: csv or json. Defaults to json.
-

Response Format

-

A successful response uses the HTTP code 200 OK and has a JSON body with the following:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
resultStringThe value success indicates that this is a successful response.
countIntegerNumber of value stats objects in the rows field.
rowsArray of Value Stats ObjectsDaily summaries of account value for the given account.
-

Each Value Stats Object has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
dateString - TimestampThis object describes activity on this date.
valueString - NumberThe total of all currency held by this account, normalized to XRP.
balance_change_countNumberThe number of times the account's balance changed on this date.
-

Example

-

Request:

-
GET /v2/accounts/rGFuMiw48HdbnrUbkRYuitXTmfrDBNTCnX/stats/value?limit=2&descending=true
-
-

Response:

-
200 OK
-{
-  "result": "success",
-  "count": 2,
-  "marker": "rGFuMiw48HdbnrUbkRYuitXTmfrDBNTCnX|20160412000000",
-  "rows": [
-    {
-      "date": "2016-04-14T00:00:00Z",
-      "account_value": "7.666658705139822E7",
-      "balance_change_count": 58
-    },
-    {
-      "date": "2016-04-13T00:00:00Z",
-      "account_value": "1.0022208004947332E8",
-      "balance_change_count": 184
-    }
-  ]
-}
-
-

Health Check - API

-

[Source]

-

Check the health of the API service.

-
- -
GET /v2/health/api
-
-
-

Try it!

-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
thresholdIntegerConsider the API unhealthy if the database does not respond within this amount of time, in seconds. Defaults to 5 seconds.
verboseBooleanIf true, return a JSON response with data points. By default, return an integer value only.
-

Response Format

-

A successful response uses the HTTP code 200 OK. By default, the response body is an integer health value only.

-

The health value 0 always indicates a healthy status. Other health values are defined as follows:

- - - - - - - - - - - - - - - - - -
ValueMeaning
0API service is up, and response time to HBase is less than threshold value from request.
1API service is up, but response time to HBase is greater than threshold value from request.
-

If the request specifies verbose=true in the query parameters, the response body is a JSON object, with the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
score0-1Health value, as defined above.
response_timeString - Human-readable timeThe actual response time of the database.
response_time_thresholdString - Human-readable timeThe maximum response time to be considered healthy.
-

Example

-

Request:

-
GET /v2/health/api?verbose=true
-
-

Response:

-
200 OK
-{
-    "score": 0,
-    "response_time": "0.014s",
-    "response_time_threshold": "5s"
-}
-
-

Health Check - Ledger Importer

-

[Source]

-

Check the health of the Ledger Importer Service.

-
- -
GET /v2/health/importer
-
-
-

Try it!

-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
thresholdIntegerConsider the Importer unhealthy if more than this amount of time, in seconds, has elapsed since the latest validated ledger was imported. Defaults to 300 seconds.
threshold2IntegerConsider the Importer unhealthy if more than this amount of time, in seconds, has elapsed since the latest ledger of any kind was imported. Defaults to 60 seconds.
verboseBooleanIf true, return a JSON response with data points. By default, return an integer value only.
-

Response Format

-

A successful response uses the HTTP code 200 OK. By default, the response body is an integer health value only.

-

The health value 0 always indicates a healthy status. Other health values are defined as follows:

- - - - - - - - - - - - - - - - - - - - - -
ValueMeaning
0The most recent imported ledger was less than threshold2 (Default: 60) seconds ago, and most recent validated ledger was less than threshold seconds ago.
1The most recent imported ledger was less than threshold2 (Default: 60) seconds ago, but the most recent validated ledger is older than threshold seconds.
2The most recent imported ledger was more than threshold2 seconds ago.
-

If the request specifies verbose=true in the query parameters, the response body is a JSON object, with the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
score0-2Health value, as defined above.
response_timeStringThe actual response time of the database.
ledger_gapString - Human-readable timeDifference between the close time of the last saved ledger and the current time.
ledger_gap_thresholdString - Human-readable timeMaximum ledger gap to be considered healthy.
valildation_gapString - Human-readable timeDifference between the close time of the last imported validated ledger and the current time.
validation_gap_thresholdString - Human-readable timeMaximum validation gap to be considered healthy.
-

Example

-

Request:

-
GET /v2/health/importer?verbose=true
-
-

Response:

-
200 OK
-{
-    "score": 0,
-    "response_time": "0.081s",
-    "ledger_gap": "1.891s",
-    "ledger_gap_threshold": "5.00m",
-    "validation_gap": "29.894s",
-    "validation_gap_threshold": "15.00m"
-}
-
-

Health Check - Nodes ETL

-

[Source]

-

Check the health of the Topology Nodes Extract, Transform, Load (ETL) Service.

-
- -
GET /v2/health/nodes_etl
-
-
-

Try it!

-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
thresholdIntegerConsider the service unhealthy if more than this amount of time, in seconds, has elapsed since the latest data was imported. Defaults to 120 seconds.
verboseBooleanIf true, return a JSON response with data points. By default, return an integer value only.
-

Response Format

-

A successful response uses the HTTP code 200 OK. By default, the response body is an integer health value only.

-

The health value 0 always indicates a healthy status. Other health values are defined as follows:

- - - - - - - - - - - - - - - - - -
ValueMeaning
0The most recent imported topology data was less than threshold (Default: 120) seconds ago.
1The most recent imported topology data was more than threshold seconds ago.
-

If the request specifies verbose=true in the query parameters, the response body is a JSON object, with the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
score0-1Health value, as defined above.
gapString - Human-readable timeDifference between the latest imported data and the current time.
gap_thresholdString - Human-readable timeMaximum gap to be considered healthy.
messageStringDescription of the reason for a non-zero score, if applicable.
-

Example

-

Request:

-
GET /v2/health/nodes_etl?verbose=true
-
-

Response:

-
200 OK
-{
-  "score": 0,
-  "gap": "1.891s",
-  "gap_threshold": "2.00m",
-}
-
-

Health Check - Validations ETL

-

[Source]

-

Check the health of the Validations Extract, Transform, Load (ETL) Service.

-
- -
GET /v2/health/validations_etl
-
-
-

Try it!

-

Optionally, you can provide the following query parameters:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
thresholdIntegerConsider the service unhealthy if more than this amount of time, in seconds, has elapsed since the latest data was imported. Defaults to 120 seconds.
verboseBooleanIf true, return a JSON response with data points. By default, return an integer value only.
-

Response Format

-

A successful response uses the HTTP code 200 OK. By default, the response body is an integer health value only.

-

The health value 0 always indicates a healthy status. Other health values are defined as follows:

- - - - - - - - - - - - - - - - - -
ValueMeaning
0The most recent imported topology data was less than threshold (Default: 120) seconds ago.
1The most recent imported topology data was more than threshold seconds ago.
-

If the request specifies verbose=true in the query parameters, the response body is a JSON object, with the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
score0-1Health value, as defined above.
gapString - Human-readable timeDifference between the latest imported data and the current time.
gap_thresholdString - Human-readable timeMaximum gap to be considered healthy.
messageStringDescription of the reason for a non-zero score, if applicable.
-

Example

-

Request:

-
GET /v2/health/nodes_etl?verbose=true
-
-

Response:

-
200 OK
-{
-  "score": 0,
-  "gap": "1.891s",
-  "gap_threshold": "2.00m",
-}
-
-

API Conventions

-

Basic Types

-

As a REST API, the Data API v2 uses JSON's native datatypes to represent API fields, with some special cases.

-

Numbers and Precision

-

Currency amounts in the XRP Ledger require more precision than most native number types, so the Data API v2 uses the String type to represent some values.

-

Within the String value, the numbers are serialized in the same way as native JSON numbers:

-
    -
  • Base-10.
    • -
  • Non-zero-prefaced.
    • -
  • May contain . as a decimal point. For example, ½ is represented as 0.5. (American style, not European)
    • -
  • May contain E or e to indicate being raised to a power of 10. For example, 1.2E5 is equivalent to 120000.
    • -
  • No comma (,) characters are used.
    • -
-

The precision for amounts of non-XRP currency in the XRP Ledger is as follows:

-
    -
  • Minimum nonzero absolute value: 1000000000000000e-96
    • -
  • Maximum value: 9999999999999999e80
    • -
  • Minimum value: -9999999999999999e80
    • -
  • 15 decimal digits of precision
    • -
-

XRP has a different internal representation, and its precision is different:

-
    -
  • Minimum value: 0
    • -
  • Maximum value: 100000000000 (1e11)
    • -
  • Precise to the nearest 0.000001 (1e-6)
    • -
-

In other words, XRP has the same precision as a 64-bit unsigned integer where each unit is equivalent to 0.000001 XRP.

-

Addresses

-

Accounts in the XRP Ledger are identified by a base58 XRP Ledger Address. The address is derived from the account's master public key, which is in turn derived from a secret key. An address is represented as a string in JSON and has the following characteristics:

-
    -
  • Between 25 and 35 characters in length
    • -
  • Starts with the character r
    • -
  • Uses alphanumeric characters, excluding the number "0" capital letter "O", capital letter "I", and lowercase letter "l"
    • -
  • Case-sensitive
    • -
  • Includes a 4-byte checksum so that the probability of generating a valid address from random characters is approximately 1 in 2^32
    • -
-

For more information, see Accounts.

-

Public Keys

-

The XRP Ledger uses public keys to verify cryptographic signatures in several places:

-
    -
  • To authorize transactions, a public key is attached to the transaction. The public key must be mathematically associated with the sending XRP Ledger address or the sender's regular key address.
    • -
  • To secure peer-to-peer communications between rippled servers. This uses a "node public key" that the server generates randomly when it starts with an empty database.
    • -
  • To sign validation votes as part of the consensus process. This uses a "validator public key" that the server operator defines in the config file.
    • -
-

Validator public keys and node public keys use the exact same format.

-

Public keys can be represented in hexadecimal or in base-58. In hexadecimal, all three types of public keys are 33 bytes (66 characters) long.

-

In base-58 format, validator public keys and node public keys always start with the character n, commonly followed by the character 9. A validator public key in base-58 format can be up to 53 characters long. Example node public key: n9Mxf6qD4J55XeLSCEpqaePW4GjoCR5U1ZeGZGJUCNe3bQa4yQbG.

-

XRP Ledger addresses are mathematically associated with a public key. This public key is rarely encoded in base-58, but when it is, it starts with the character a.

-

Hashes

-

Many objects in the XRP Ledger, particularly transactions and ledgers, are uniquely identified by a 256-bit hash value. This value is typically calculated as a "SHA-512Half", which calculates a SHA-512 hash from some contents, then takes the first 64 characters of the hexadecimal representation. Since the hash of an object is derived from the contents in a way that is extremely unlikely to produce collisions, two objects with the same hash can be considered the same.

-

An XRP Ledger hash value has the following characteristics:

-
    -
  • Exactly 64 characters in length
    • -
  • Hexadecimal character set: 0-9 and A-F.
    • -
  • Typically written in upper case.
    • -
-

Note: SHA-512Half has similar security to the officially-defined SHA-512/256 hash function. However, the XRP Ledger's usage predates SHA-512/256 and is also easier to implement on top of an existing SHA-512 function. (As of this writing, SHA-512 support in cryptographic libraries is much more common than for SHA-512/256.)

-

Timestamps

-

All dates and times are written in ISO 8601 Timestamp Format, using UTC. This format is summarized as:

-

YYYY-MM-DDThh:mm:ssZ

-
    -
  • Four-digit year
    • -
  • Two-digit month
    • -
  • Two-digit day
    • -
  • The letter T separating the date part and the time part
    • -
  • Two-digit hour using a 24-hour clock
    • -
  • Two digit minute
    • -
  • The letter Z indicating zero offset from UTC.
    • -
-

(As of v2.0.4, the offset +00:00 is no longer used.)

-

Ledger Index

-

A ledger index is a 32-bit unsigned integer used to identify a ledger. The ledger index is also known as the ledger's sequence number. The very first ledger was ledger index 1, and each new ledger has a ledger index 1 higher than that of the ledger immediately before it.

-

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

-
    -
  • Two different rippled servers may have different contents for a current ledger with the same ledger index, due to latency in propagating transactions throughout the network.
    • -
  • There may be multiple closed ledger versions competing to be validated by consensus. These ledger versions have the same sequence number but different contents (and different hashes). Only one of these closed ledgers can become validated.
    • -
  • A current ledger's contents change over time, which would cause its hash to change, even though its ledger index number stays the same. The hash of a ledger is not calculated until the ledger is closed.
    • -
-

Account Sequence

-

A Sequence number is a 32-bit unsigned integer used to identify a transaction or Offer relative to a specific account.

-

Every account object in the XRP Ledger has a Sequence number, which starts at 1. For a transaction to be relayed to the network and possibly included in a validated ledger, it must have a Sequence field that matches the sending account's current Sequence number. An account's Sequence field is incremented whenever a transaction from that account is included in a validated ledger (regardless of whether the transaction succeeded or failed). This preserves the order of transactions submitted by an account, and differentiates transactions that would otherwise be the same.

-

Every Offer node in the XRP Ledger is marked with the sending Account Address and the Sequence value of the OfferCreate transaction that created it. These two fields, together, uniquely identify the Offer.

-

Currency Code

-

There are two kinds of currency code in the XRP Ledger:

-
    -
  • Three-character currency code. We recommend using all-uppercase ISO 4217 Currency Codes. However, any combination of the following characters is permitted: all uppercase and lowercase letters, digits, as well as the symbols ?, !, @, #, $, %, ^, &, *, <, >, (, ), {, }, [, ], and |. The currency code XRP (all-uppercase) is reserved for XRP and cannot be used by issued currencies.
    • -
  • 160-bit hexadecimal values, such as 0158415500000000C1F76FF6ECB0BAC600000000, according to the XRP Ledger's internal Currency Format. This representation is uncommon.
    • -
-

Pagination

-

Many queries may return more data than is reasonable to return in a single HTTP response. The Data API uses a "limit and marker" system to control how much is returned in a single response ("page") and to query for additional content.

-

The limit query parameter to many requests restricts the response to a specific number of results in the response. The types of results and default values vary based on the method. For most methods, the limit is 200 by default, and can be set as high as 1000. If you specify a limit larger than the maximum, the API uses the maximum value instead.

-

When a query has additional objects that are not contained in the current response, the JSON response contains a top-level field marker which indicates that you can retrieve additional results. To do so, make more requests with the previous value of the marker field as the marker query parameter. For each additional request, use the same parameters as the first request (except marker). When the response omits the marker parameter, that indicates that you have reached the end of the queryable data.

-

When a marker is or would be present, the response contains a Link header with rel="next". This is a full URL to the next page of results. You can use this to paginate over results when the response is in csv format instead of json. (New in v2.0.4)

-

Transaction Objects

-

Transactions have two formats - a compact "binary" format where the defining fields of the transaction are encoded as strings of hex, and an expanded format where the defining fields of the transaction are nested as complete JSON objects.

-

Full JSON Format

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
hashString - HashAn identifying hash value unique to this transaction, as a hex string.
dateString - TimestampThe time when this transaction was included in a validated ledger.
ledger_indexNumber - Ledger IndexThe sequence number of the ledger that included this ledger.
txObjectThe fields of this transaction object, as defined by the Transaction Format
metaObjectMetadata about the results of this transaction.
-

Binary Format

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
hashString - HashAn identifying hash value unique to this transaction, as a hex string.
dateString - TimestampThe time when this transaction was included in a validated ledger.
ledger_indexNumber - Ledger IndexThe sequence number of the ledger that included this ledger.
txStringThe binary data that represents this transaction, as a hexadecimal string.
metaStringThe binary data that represents this transaction's metadata, as a hex string.
-

Ledger Objects

-

A "ledger" is one version of the shared global ledger. Each ledger object has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
ledger_hashString - HashAn identifying hash unique to this ledger, as a hex string.
ledger_indexNumber - Ledger IndexThe sequence number of the ledger. Each new ledger has a ledger index 1 higher than the ledger that came before it.
parent_hashString - HashThe identifying hash of the previous ledger.
total_coinsString - NumberThe total number of "drops" of XRP still in existence at the time of the ledger. (Each XRP is 1,000,000 drops.)
close_time_resNumberThe ledger close time is rounded to this many seconds.
accounts_hashString - HashHash of the account information contained in this ledger, as hex.
transactions_hashString - HashHash of the transaction information contained in this ledger, as hex.
close_timeNumberWhen this ledger was closed, in UNIX time.
close_time_humanString - TimestampWhen this ledger was closed.
-

Note: Ledger close times are approximate, typically rounded to about 10 seconds. Two ledgers could have the same close_time values, when their actual close times were several seconds apart. The sequence number (ledger_index) of the ledger makes it unambiguous which ledger closed first.

-

Genesis Ledger

-

Due to a mishap early in the XRP Ledger's history, ledgers 1 through 32569 were lost. Thus, ledger #32570 is the earliest ledger available anywhere. For purposes of the Data API v2, ledger #32570 is considered the genesis ledger.

-

Account Creation Objects

-

An account creation object represents the action of creating an account in the XRP Ledger. There are two variations, depending on whether the account was already present in ledger 32570, the earliest ledger available. Accounts that were already present in ledger 32570 are termed genesis accounts.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
addressString - AddressThe identifying address of this account, in base-58.
inceptionString - TimestampThe UTC timestamp when the address was funded. For genesis accounts, this is the timestamp of ledger 32570.
ledger_indexNumber - Ledger IndexThe sequence number of the ledger when the account was created, or 32570 for genesis accounts.
parentString - Address(Omitted for genesis accounts) The address that provided the XRP to fund this address.
tx_hashString - Hash(Omitted for genesis accounts) The identifying hash of the transaction that funded this account.
initial_balanceString - Number(Omitted for genesis accounts) The amount of XRP that funded this account.
genesis_balanceString - Number(Genesis accounts only) The amount of XRP this account held as of ledger #32570.
genesis_indexNumber - Sequence Number(Genesis accounts only) The transaction sequence number of the account as of ledger #32570.
-

Exchange Objects

-

An exchange object represents an actual exchange of currency, which can occur in the XRP Ledger as the result of executing either an OfferCreate transaction or a Payment transaction. In order for currency to actually change hands, there must be a previously-unfilled Offer previously placed in the ledger with an OfferCreate transaction.

-

A single transaction can cause several exchanges to occur. In this case, the sender of the transaction is the taker for all the exchanges, but each exchange has a different provider, currency pair, or both.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
base_amountNumberThe amount of the base currency that was traded.
counter_amountNumberThe amount of the counter currency that was traded.
rateNumberThe amount of the counter currency acquired per 1 unit of the base currency.
autobridged_currencyString - Currency Code(May be omitted) If the offer was autobridged (XRP order books were used to bridge two non-XRP currencies), this is the other currency from the offer that executed this exchange.
autobridged_issuerString - Address(May be omitted) If the offer was autobridged (XRP order books were used to bridge two non-XRP currencies), this is the other currency from the offer that executed this exchange.
base_currencyString - Currency CodeThe base currency.
base_issuerString - Address(Omitted for XRP) The account that issued the base currency.
buyerString - AddressThe account that acquired the base currency.
clientString(May be omitted) If the transaction contains a memo indicating what client application sent it, this is the contents of the memo.
counter_currencyString - Currency CodeThe counter currency.
counter_issuerString - Address(Omitted for XRP) The account that issued the counter currency.
executed_timeString - TimestampThe time the exchange occurred.
ledger_indexNumber - Ledger IndexThe sequence number of the ledger that included this transaction.
offer_sequenceNumber - Sequence NumberThe sequence number of the provider's existing offer in the ledger.
providerString - AddressThe account that had an existing Offer in the ledger.
sellerString - AddressThe account that acquired the counter currency.
takerString - AddressThe account that sent the transaction which executed this exchange.
tx_hashString - HashThe identifying hash of the transaction that executed this exchange. (Note: This exchange may be one of several executed in a single transaction.)
tx_typeStringThe type of transaction that executed this exchange, either Payment or OfferCreate.
-

Reports Objects

-

Reports objects show the activity of a given account over a specific interval of time, typically a day. Reports have the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
accountString - AddressThe address of the account to which this report pertains.
dateString - TimestampThe start of the interval to which this report pertains.
high_value_receivedString - NumberLargest amount received in a single transaction, normalized to XRP (as closely as possible). This includes payments and exchanges.
high_value_sentString - NumberThe largest amount sent in a single transaction, normalized to XRP (as closely as possible).
paymentsArray of Payment Summary Objects(May be omitted) Array with information on each payment sent or received by the account during this interval.
payments_receivedNumberThe number of payments sent to this account. (This only includes payments for which this account was the destination, not payments that only rippled through the account or consumed the account's offers.)
payments_sentNumberThe number of payments sent by this account.
receiving_counterpartiesArray or NumberIf account lists requested, an array of addresses that received payments from this account. Otherwise, the number of different accounts that received payments from this account.
sending_counterpartiesArray or NumberIf account lists requested, an array of addresses that sent payments to this account. Otherwise, the number of different accounts that sent payments to this account.
total_valueString - NumberSum of total value received and sent in payments, normalized to XRP (as closely as possible).
total_value_receivedString - NumberSum value of all payments to this account, normalized to XRP (as closely as possible).
total_value_sentString - NumberSum value of all payments from this account, normalized to XRP (as closely as possible).
-

Payment Summary Objects

-

A Payment Summary Object contains a reduced amount of information about a single payment from the perspective of either the sender or receiver of that payment.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
tx_hashString - HashThe identifying hash of the transaction that caused the payment.
delivered_amountString - NumberThe amount of the destination currency actually received by the destination account.
currencyString - Currency CodeThe currency delivered to the recipient of the transaction.
issuerString - AddressThe gateway issuing the currency, or an empty string for XRP.
typeStringEither sent or received, indicating whether the perspective account is sender or receiver of this transaction.
-

Payment Objects

-

In the Data API, a Payment Object represents an event where one account sent value to another account. This mostly lines up with XRP Ledger transactions of the Payment transaction type, except that the Data API does not consider a transaction to be a payment if the sending Account and the Destination account are the same, or if the transaction failed.

-

Payment objects have the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
amountString - NumberThe amount of the destination currency that the transaction was instructed to send. In the case of Partial Payments, this is a "maximum" amount.
delivered_amountString - NumberThe amount of the destination currency actually received by the destination account.
destination_balance_changesArrayArray of balance change objects, indicating all changes made to the destination account's balances.
source_balance_changesArrayArray of balance change objects, indicating all changes to the source account's balances (except the XRP transaction cost).
transaction_costString - NumberThe amount of XRP spent by the source account on the transaction cost. (Prior to v2.0.4, this parameter was called fee.)
destination_tagInteger(May be omitted) A destination tag specified in this payment.
source_tagInteger(May be omitted) A source tag specified in this payment.
currencyString - Currency CodeThe currency that the destination account received.
destinationString - AddressThe account that received the payment.
executed_timeString - TimestampThe time the ledger that included this payment closed.
ledger_indexNumber - Ledger IndexThe sequence number of the ledger that included this payment.
sourceString - AddressThe account that sent the payment.
source_currencyString - Currency CodeThe currency that the source account spent.
tx_hashString - HashThe identifying hash of the transaction that caused the payment.
-

Balance Objects and Balance Change Objects

-

Balance objects represent an XRP Ledger account's balance in a specific currency with a specific counterparty at a single point in time. Balance change objects represent a change to such balances that occurs in transaction execution.

-

A single XRP Ledger transaction may cause changes to balances with several counterparties, as well as changes to XRP.

-

Balance objects and Balance Change objects have the same format, with the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
counterpartyString - AddressThe counterparty, or issuer, of the currency. In the case of XRP, this is an empty string.
currencyString - Currency CodeThe currency for which this balance changed.
valueString - NumberThe amount of the currency that the associated account gained or lost. In balance change objects, this value can be positive (for amounts gained) or negative (for amounts lost). In balance objects, this value can be positive (for amounts the counterparty owes the account) or negative (for amounts owed to the counterparty).
-

Balance Change Descriptors

-

Balance Change Descriptors are objects that describe and analyze a single balance change that occurs in transaction execution. They represent the same events as balance change objects, but in greater detail.

-

Balance Change Descriptors have the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
amount_changeString - NumberThe difference in the amount of currency held before and after this change. (Prior to v2.0.6, this field was called change.)
final_balanceString - NumberThe balance after the change occurred.
node_indexNumber (or null)This balance change is represented by the entry at this index of the ModifiedNodes array within the metadata section of the transaction that executed this balance change. Note: When the transaction cost is combined with other changes to XRP balance, the transaction cost has a node_index of null instead.
tx_indexNumberThe transaction that executed this balance change is at this index in the array of transactions for the ledger that included it.
change_typeStringOne of several describing what caused this balance change to occur.
currencyString - Currency CodeThe change affected this currency.
executed_timeString - TimestampThe time the change occurred. (This is based on the close time of the ledger that included the transaction that executed the change.
counterpartyString - Address(Omitted for XRP) The currency is held in a trust line to or from this account. (Prior to v2.0.6, this field was called issuer.)
ledger_indexNumber - Ledger IndexThe sequence number of the ledger that included the transaction that executed this balance change.
tx_hashString - HashThe identifying hash of the transaction that executed this balance change.
-

Change Types

-

The following values are valid for the change_type field of a Balance Change Descriptor:

- - - - - - - - - - - - - - - - - - - - - - - - - -
ValueMeaning
transaction_costThis balance change reflects XRP that was destroyed to relay a transaction. (Prior to v2.0.4, this was network fee instead.)
payment_destinationThis balance change reflects currency that was received from a payment.
payment_sourceThis balance change reflects currency that was spent in a payment.
exchangeThis balance change reflects currency that was traded for other currency, or the same currency from a different issuer. This can occur in the middle of payment execution as well as from offers.
-

Volume Objects

-

Volume objects represent the total volumes of money moved, in either payments or exchanges, during a given period.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
componentsArray of ObjectsThe data that was used to assemble this total. For payment volume, each object represents payments in a particular currency and issuer. For exchange volume, each object represents a market between two currencies.
countNumberThe total number of exchanges in this period.
endTimeString - TimestampThe end time of this interval.
exchangeObjectIndicates the display currency used, as with fields currency and (except for XRP) issuer. All amounts are normalized by first converting to XRP, and then to the display currency specified in the request.
exchangeRateNumberThe exchange rate to the displayed currency from XRP.
startTimeString - TimestampThe start of this period.
totalNumberTotal volume of all recorded exchanges in the period.
-

Server Objects

-

A "Server Object" describes one rippled server in the XRP Ledger peer-to-peer network. Server objects are returned by the Get Topology, Get Toplogy Nodes, and Get Topology Node methods. The Data API collects reported network topology approximately every 30 seconds using the peer crawler.

-

Server objects have the following fields, with some only appearing if the request specified a verbose response:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
node_public_keyString - Base-58 Public KeyThe public key used by this server to sign its peer-to-peer communications, not including validations.
versionStringThe rippled version of this server, when it was last asked.
uptimeIntegerNumber of seconds this server has been connected to the network.
ipString(May be omitted) IP address of the node (may be omitted)
portInteger(May be omitted) Port where this server speaks the rippled Peer Protocol.
inbound_countInteger(May be omitted) Number of inbound peer-to-peer connections to this server.
inbound_addedString(May be omitted) Number of new inbound peer-to-peer connections since the last measurement.
inbound_droppedString(May be omitted) Number of inbound peer-to-peer connections dropped since the last measurement.
outbound_countInteger(May be omitted) Number of outbound peer-to-peer connections to this server.
outbound_addedString(May be omitted) Number of new outbound peer-to-peer connections since the last measurement.
outbound_droppedString(May be omitted) Number of outbound peer-to-peer connections dropped since the last measurement.
cityString(Verbose only) The city where this server is located, according to IP geolocation.
regionString(Verbose only) The region where this server is located, according to IP geolocation.
countryString(Verbose only) The country where this server is located, according to IP geolocation.
region_codeString(Verbose only) The ISO code for the region where this server is located, according to IP geolocation.
country_codeString(Verbose only) The ISO code for the country where this server is located, according to IP geolocation.
postal_codeString(Verbose only) The postal code where this server is located, according to IP geolocation.
timezoneString(Verbose only) The ISO timezone where this server is located, according to IP geolocation.
latString(Verbose only) The latitude where this server is located, according to IP geolocation.
longString(Verbose only) The longitude where this server is located, according to IP geolocation.
ispString(Verbose only) The Internet Service Provider hosting this server's public IP address.
orgString(Verbose only) The organization that owns this server's public IP address.
- -

A Link Object represents a peer-to-peer network connection between two rippled servers. It has the following fields:

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
sourceString - Base-58 Public KeyThe node public key of the rippled making the outgoing connection.
targetString - Base-58 Public KeyThe node public key of the rippled receiving the incoming connection.
-

Validation Objects

-

A Validation Object represents one vote from a validator to mark a ledger version as validated. (A ledger is only validated by the consensus process if a quorum of trusted validators votes for the same exact ledger version.)

-

Note: The Data API retain only about 6 months of validation vote data.

-

A Validation Object has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
countInteger(May be omitted) The number of rippled servers that reported seeing this validation. Not available for old data.
ledger_hashString - HashThe hash of the ledger version this validation vote applies to.
reporter_public_keyString - Base-58 Public KeyThe public key of the rippled server that first reported this validation, in base-58.
validation_public_keyString - Base-58 Public KeyThe public key of the validator used to sign this validation, in base-58.
signatureStringThe validator's signature of the validation details, in hexadecimal.
first_datetimeString - TimestampDate and time of the first report of this validation.
last_datetimeString - TimestampDate and time of the last report of this validation.
-

Running the Historical Database

-

You can also serve the Data API v2 from your own instance of the Historical Database software, and populate it with transactions from your own rippled instance. This is useful if you do not want to depend on Ripple to run the historical database indefinitely, or you want access to historical transactions from within your own intranet.

-

Installation

-

Dependencies

-

The Historical Database requires the following software installed first:

- -

Version 2 of the Historical Database requires HBase instead of PostgreSQL. Postgres support is deprecated.

-

Installation Process

-

To install the Data API v2:

-
    -
  1. Install HBase. For production use, configure it in distributed mode.
    2. -
  2. -

    Clone the Historical Database Git Repository:

    -
    git clone https://github.com/ripple/rippled-historical-database.git
-
    -

    (You can also download and extract a zipped release instead.)

    -
    3. -
  3. -

    Use npm to install additional modules:

    -
    cd rippled-historical-database
-npm install
-
    -

    The install script creates the required config files: config/api.config.json and config/import.config.json

    -
    4. -
  4. -

    Change the config files as needed. Remove the postgres section from api.config.json.

    -
    5. -
-

Reports, stats, and aggregated exchange data needs more processing before the API can make it available. This processing uses Apache Storm as well as some custom scripts. See Storm Setup for more information.

-

At this point, the Data API is installed. See Services for the different components that you can run.

-

Tests

-

Dependencies:

- -
$ docker-compose build
-$ docker-compose up -d hbase
-$ docker-compose run --rm webapp npm test
-
-

Services

-

The rippled Historical Database consists of several processes that can be run separately.

-
    -
  • Live Ledger Importer - Monitors rippled for newly-validated ledgers. - Command: node import/live
    • -
  • Backfiller - Populates the database with older ledgers from a rippled instance. - Command: node import/postgres/backfill
    • -
  • API Server - Provides REST API access to the data. - Command: npm start (restarts the server automatically when source files change), - or node api/server.js (start once)
    • -
-

Importing Data

-

In order to retrieve data from the rippled Historical Database, you must first populate it with data. Broadly speaking, there are two ways this can happen:

-
    -
  • Connect to a rippled server that has the historical ledgers, and retrieve them. (Later, you can reconfigure the rippled server not to keep history older than what you have in your Historical Database.)
      -
    • You can choose to retrieve only new ledgers as they are validated, or you can retrieve old ledgers, too.
      • -
    -
    • -
  • Or, you can load a dump from a database that already has the historical ledger data. (At this time, there are no publicly-available database dumps of historical data.) Use the standard process for your database.
    • -
-

In all cases, keep in mind that the integrity of the data is only as good as the original source. If you retrieve data from a public server, you are assuming that the operator of that server is trustworthy. If you load from a database dump, you are assuming that the provider of the dump has not corrupted or tampered with the data.

-

Live Ledger Importer

-

The Live Ledger Importer is a service that connects to a rippled server using the WebSocket API, and listens for ledger close events. Each time a new ledger is closed, the Importer requests the latest validated ledger. Although this process has some fault tolerance built in to prevent ledgers from being skipped, the Importer may still miss ledgers.

-

The Live Ledger Importer includes a secondary process that runs periodically to validate the data already imported and check for gaps in the ledger history.

-

The Live Ledger Importer can import to one or more different data stores concurrently. If you have configured the historical database to use another storage scheme, you can use the --type parameter to specify the database type or types to use.

-

Example usage:

-
// start loading records into HBase:
-$ node import/live
-
-

Backfiller

-

The Backfiller retrieves old ledgers from a rippled instance by moving backwards in time. You can optionally provide start and stop indexes to retrieve a specific range of ledgers, by their sequence number.

-

The --startIndex parameter defines the most-recent ledger to retrieve. The Backfiller retrieves this ledger first and then continues retrieving progressively older ledgers. If this parameter is omitted, the Backfiller begins with the newest validated ledger.

-

The --stopIndex parameter defines the oldest ledger to retrieve. The Backfiller stops after it retrieves this ledger. If omitted, the Backfiller continues as far back as possible. Because backfilling goes from most recent to least recent, the stop index should be a smaller than the start index.

-

Caution: The Backfiller is best for filling in relatively short histories of transactions. Importing a complete history of all XRP Ledger transactions using the Backfiller could take weeks. If you want a full history, we recommend acquiring a database dump with early transctions, and importing it directly. For the public server, Ripple (the company) used the internal SQLite database from an offline rippled to populate its historical databases with the early transactions, then used the Backfiller to catch up to date after the import finished.

-

Example usage:

-
// get ledgers #1,000,000 to #2,000,000 (inclusive) and store in HBase
-node import/hbase/backfill --startIndex 2000000 --stopIndex 1000000
-
-
-
-
- - - - \ No newline at end of file diff --git a/reference-ledger-format.html b/reference-ledger-format.html deleted file mode 100644 index 5e6e68f5ad..0000000000 --- a/reference-ledger-format.html +++ /dev/null @@ -1,1454 +0,0 @@ - - - - - - - - Ledger Format - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

The Ledger

-

The XRP Ledger is a shared, global ledger that is open to all. Individual participants can trust the integrity of the ledger without having to trust any single institution to manage it. The rippled server software accomplishes this by managing a ledger database that can only be updated according to very specific rules. Each instance of rippled keeps a full copy of the ledger, and the peer-to-peer network of rippled servers distributes candidate transactions among themselves. The consensus process determines which transactions get applied to each new version of the ledger. See also: The Consensus Process.

-

Diagram: Each ledger is the result of applying transactions to the previous ledger version.

-

The shared global ledger is actually a series of individual ledgers, or ledger versions, which rippled keeps in its internal database. Every ledger version has a ledger index which identifies the order in which ledgers occur. Each closed ledger version also has an identifying hash value, which uniquely identifies the contents of that ledger. At any given time, a rippled instance has an in-progress "current" open ledger, plus some number of closed ledgers that have not yet been approved by consensus, and any number of historical ledgers that have been validated by consensus. Only the validated ledgers are certain to be correct and immutable.

-

A single ledger version consists of several parts:

-

Diagram: A ledger has transactions, a state node, and a header with the close time and validation info

-
    -
  • A header - The ledger index, hashes of its other contents, and other metadata.
    • -
  • A transaction tree - The transactions that were applied to the previous ledger to make this one. Transactions are the only way to change the ledger.
    • -
  • A state tree - All the ledger nodes that contain the settings, balances, and objects in the ledger as of this version.
    • -
-

Tree Format

-

As its name might suggest, a ledger's state tree is a tree data structure, with each node identified by a 256-bit value called an index. In JSON, a ledger node's index value is represented as a 64-character hexadecimal string like "193C591BF62482468422313F9D3274B5927CA80B4DD3707E42015DD609E39C94". Every node in the state tree has an index that you can use as a key to look up the node in the state tree; every transaction has an indentifying hash that you can use to look up the transaction in the transaction tree. Do not confuse the index (key) of a ledger node with the ledger_index (sequence number) of a ledger.

-

In the case of transactions, the identifying hash is based on the signed transaction instructions, but the contents of the transaction object when you look it up also contain the results and metadata of the transaction, which are not taken into account when generating the hash.

-

In the case of state nodes, rippled usually includes the index of the node along with its contents. However, the index itself is not part of the contents. The index is derived by hashing important contents of the node, along with a namespace identifier. The ledger node type determines which namespace identifier to use as well as which contents to include in the hash. This ensures every index is unique. For a hash function, rippled uses SHA-512 and then truncates the result to the first 256 bytes. This algorithm, informally called SHA-512Half, provides an output that has comparable security to SHA-256, but runs faster on 64-bit processors.

-

Diagram: rippled uses SHA-512Half to generate indexes for ledger nodes. The space key prevents indexes for different node types from colliding.

-

Header Format

-

[Source]

-

Every ledger version has a unique header that describes the contents. You can look up a ledger's header information with the ledger command. The contents of the ledger header are as follows:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldJSON TypeInternal TypeDescription
ledger_indexStringUInt32The sequence number of the ledger. Some API methods display this as a quoted integer; some display it as a native JSON number.
ledger_hashStringHash256The SHA-512Half of the ledger header, excluding the ledger_hash itself. This serves as a unique identifier for this ledger and all its contents.
account_hashStringHash256The SHA-512Half of this ledger's state tree information.
close_timeNumberUInt32The approximate time this ledger closed, as the number of seconds since the Ripple Epoch of 2000-01-01 00:00:00. This value is rounded based on the close_time_resolution, so later ledgers can have the same value.
closedBooleanboolIf true, this transaction is no longer accepting new transactions. (However, unless this ledger is validated, it might be replaced by a different ledger with a different set of transactions.)
parent_hashStringHash256The ledger_hash value of the previous ledger that was used to build this one. If there are different versions of the previous ledger index, this indicates from which one the ledger was derived.
total_coinsStringUInt64The total number of drops of XRP owned by accounts in the ledger. This omits XRP that has been destroyed by transaction fees. The actual amount of XRP in circulation is lower because some accounts are "black holes" whose keys are not known by anyone.
transaction_hashStringHash256The SHA-512Half of the transactions included in this ledger.
close_time_resolutionNumberUint8An integer in the range [2,120] indicating the maximum number of seconds by which the close_time could be rounded.
closeFlags(Omitted)UInt8A bit-map of flags relating to the closing of this ledger.
-

Ledger Index

-

A ledger index is a 32-bit unsigned integer used to identify a ledger. The ledger index is also known as the ledger's sequence number. The very first ledger was ledger index 1, and each new ledger has a ledger index 1 higher than that of the ledger immediately before it.

-

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

-
    -
  • Two different rippled servers may have different contents for a current ledger with the same ledger index, due to latency in propagating transactions throughout the network.
    • -
  • There may be multiple closed ledger versions competing to be validated by consensus. These ledger versions have the same sequence number but different contents (and different hashes). Only one of these closed ledgers can become validated.
    • -
  • A current ledger's contents change over time, which would cause its hash to change, even though its ledger index number stays the same. The hash of a ledger is not calculated until the ledger is closed.
    • -
-

Close Flags

-

The ledger has only one flag defined for closeFlags: sLCF_NoConsensusTime (value 1). If this flag is enabled, it means that validators had different close times for the ledger, but built otherwise the same ledger, so they declared consensus while "agreeing to disagree" on the close time. In this case, the consensus ledger version contains a close_time value that is 1 second after that of the previous ledger. (In this case, there is no official close time, but the actual real-world close time is probably 3-6 seconds later than the specified close_time.)

-

The closeFlags field is not included in any JSON representations of a ledger, but is included in the binary representation of a ledger, and is one of the fields that determine the ledger's hash.

-

Ledger Node Types

-

There are several different kinds of nodes that can appear in the ledger's state tree:

- -

Each ledger node consists of several fields. In the peer protocol that rippled servers use to communicate with each other, ledger nodes are represented in their raw binary format. In other rippled APIs, ledger nodes are represented as JSON objects.

-

AccountRoot

-

[Source]

-

The AccountRoot node type describes a single account object. Example AccountRoot node:

-
{
-    "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-    "AccountTxnID": "0D5FB50FA65C9FE1538FD7E398FFFE9D1908DFA4576D8D7A020040686F93C77D",
-    "Balance": "148446663",
-    "Domain": "6D64756F31332E636F6D",
-    "EmailHash": "98B4375E1D753E5B91627516F6D70977",
-    "Flags": 8388608,
-    "LedgerEntryType": "AccountRoot",
-    "MessageKey": "0000000000000000000000070000000300",
-    "OwnerCount": 3,
-    "PreviousTxnID": "0D5FB50FA65C9FE1538FD7E398FFFE9D1908DFA4576D8D7A020040686F93C77D",
-    "PreviousTxnLgrSeq": 14091160,
-    "Sequence": 336,
-    "TransferRate": 1004999999,
-    "index": "13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8"
-}
-
-

The AccountRoot node has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldJSON TypeInternal TypeDescription
LedgerEntryTypeStringUInt16The value 0x61, mapped to the string AccountRoot, indicates that this node is an AccountRoot object.
AccountStringAccountIDThe identifying address of this account, such as rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn.
FlagsNumberUInt32A bit-map of boolean flags enabled for this account.
SequenceNumberUInt32The sequence number of the next valid transaction for this account. (Each account starts with Sequence = 1 and increases each time a transaction is made.)
BalanceStringAmountThe account's current XRP balance in drops, represented as a string.
OwnerCountNumberUInt32The number of objects this account owns in the ledger, which contributes to its owner reserve.
PreviousTxnIDStringHash256The identifying hash of the transaction that most recently modified this node.
PreviousTxnLgrSeqNumberUInt32The index of the ledger that contains the transaction that most recently modified this node.
AccountTxnIDStringHash256(Optional) The identifying hash of the transaction most recently submitted by this account.
RegularKeyStringAccountID(Optional) The address of a keypair that can be used to sign transactions for this account instead of the master key. Use a SetRegularKey transaction to change this value.
EmailHashStringHash128(Optional) The md5 hash of an email address. Clients can use this to look up an avatar through services such as Gravatar.
WalletLocatorStringHash256(Optional) DEPRECATED. Do not use.
WalletSizeNumberUInt32(Optional) DEPRECATED. Do not use.
MessageKeyStringVariableLength(Optional) A public key that may be used to send encrypted messages to this account. In JSON, uses hexadecimal. No more than 33 bytes.
TickSizeNumberUInt8(Optional) How many significant digits to use for exchange rates of Offers involving currencies issued by this address. Valid values are 3 to 15, inclusive. (Requires the TickSize amendment.)
TransferRateNumberUInt32(Optional) A transfer fee to charge other users for sending currency issued by this account to each other.
DomainStringVariableLength(Optional) A domain associated with this account. In JSON, this is the hexadecimal for the ASCII representation of the domain.
-

AccountRoot Flags

-

There are several options which can be either enabled or disabled for an account. These options can be changed with an AccountSet transaction. In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with lsf.

-

AccountRoot nodes can have the following flag values:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Flag NameHex ValueDecimal ValueDescriptionCorresponding AccountSet Flag
lsfPasswordSpent0x0001000065536Indicates that the account has used its free SetRegularKey transaction.(None)
lsfRequireDestTag0x00020000131072Requires incoming payments to specify a Destination Tag.asfRequireDest
lsfRequireAuth0x00040000262144This account must individually approve other users for those users to hold this account's issuances.asfRequireAuth
lsfDisallowXRP0x00080000524288Client applications should not send XRP to this account. Not enforced by rippled.asfDisallowXRP
lsfDisableMaster0x001000001048576Disallows use of the master key to sign transactions for this account.asfDisableMaster
lsfNoFreeze0x002000002097152This address cannot freeze trust lines connected to it. Once enabled, cannot be disabled.asfNoFreeze
lsfGlobalFreeze0x004000004194304All assets issued by this address are frozen.asfGlobalFreeze
lsfDefaultRipple0x008000008388608Enable rippling on this addresses's trust lines by default. Required for issuing addresses; discouraged for others.asfDefaultRipple
-

AccountRoot Index Format

-

The index of an AccountRoot node is the SHA-512Half of the following values put together:

-
    -
  • The Account space key (a)
    • -
  • The AccountID of the account
    • -
-

DirectoryNode

-

[Source]

-

The DirectoryNode node type provides a list of links to other nodes in the ledger's state tree. A single conceptual Directory　takes the form of a doubly linked list, with one or more DirectoryNode objects each containing up to 32 indexes of other nodes. The first node is called the root of the directory, and all nodes other than the root node can be added or deleted as necessary.

-

There are two kinds of Directories:

-
    -
  • Owner directories list other nodes owned by an account, such as RippleState or Offer nodes.
    • -
  • Offer directories list the offers available in the distributed exchange. A single Offer Directory contains all the offers that have the same exchange rate for the same issuances.
    • -
-

Example Directories:

-
- -
{
-    "ExchangeRate": "4F069BA8FF484000",
-    "Flags": 0,
-    "Indexes": [
-        "AD7EAE148287EF12D213A251015F86E6D4BD34B3C4A0A1ED9A17198373F908AD"
-    ],
-    "LedgerEntryType": "DirectoryNode",
-    "RootIndex": "1BBEF97EDE88D40CEE2ADE6FEF121166AFE80D99EBADB01A4F069BA8FF484000",
-    "TakerGetsCurrency": "0000000000000000000000000000000000000000",
-    "TakerGetsIssuer": "0000000000000000000000000000000000000000",
-    "TakerPaysCurrency": "0000000000000000000000004A50590000000000",
-    "TakerPaysIssuer": "5BBC0F22F61D9224A110650CFE21CC0C4BE13098",
-    "index": "1BBEF97EDE88D40CEE2ADE6FEF121166AFE80D99EBADB01A4F069BA8FF484000"
-}
-
- -
{
-    "Flags": 0,
-    "Indexes": [
-        "AD7EAE148287EF12D213A251015F86E6D4BD34B3C4A0A1ED9A17198373F908AD",
-        "E83BBB58949A8303DF07172B16FB8EFBA66B9191F3836EC27A4568ED5997BAC5"
-    ],
-    "LedgerEntryType": "DirectoryNode",
-    "Owner": "rpR95n1iFkTqpoy1e878f4Z1pVHVtWKMNQ",
-    "RootIndex": "193C591BF62482468422313F9D3274B5927CA80B4DD3707E42015DD609E39C94",
-    "index": "193C591BF62482468422313F9D3274B5927CA80B4DD3707E42015DD609E39C94"
-}
-
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameJSON TypeInternal TypeDescription
LedgerEntryTypeNumberUInt16The value 0x64, mapped to the string DirectoryNode, indicates that this node is part of a Directory.
FlagsNumberUInt32A bit-map of boolean flags enabled for this directory. Currently, the protocol defines no flags for DirectoryNode objects.
RootIndexNumberHash256The index of root node for this directory.
IndexesArrayVector256The contents of this Directory: an array of indexes to other nodes.
IndexNextNumberUInt64(Optional) If this Directory consists of multiple pages, this index links to the next node in the chain, wrapping around at the end.
IndexPreviousNumberUInt64(Optional) If this Directory consists of multiple pages, this index links to the previous node in the chain, wrapping around at the beginning.
OwnerStringAccountID(Owner Directories only) The address of the account that owns the objects in this directory.
ExchangeRateNumberUInt64(Offer Directories only) DEPRECATED. Do not use.
TakerPaysCurrencyStringHash160(Offer Directories only) The currency code of the TakerPays amount from the offers in this directory.
TakerPaysIssuerStringHash160(Offer Directories only) The issuer of the TakerPays amount from the offers in this directory.
TakerGetsCurrencyStringHash160(Offer Directories only) The currency code of the TakerGets amount from the offers in this directory.
TakerGetsIssuerStringHash160(Offer Directories only) The issuer of the TakerGets amount from the offers in this directory.
-

Directory Index Formats

-

There are three different formulas for creating the index of a DirectoryNode, depending on whether the DirectoryNode represents:

-
    -
  • The first page (also called the root) of an Owner Directory,
    • -
  • The first page of an Offer Directory, or
    • -
  • Later pages of either type
    • -
-

The first page of an Owner Directory has an index that is the SHA-512Half of the following values put together:

-
    -
  • The Owner Directory space key (O, capital letter O)
    • -
  • The AccountID from the Owner field.
    • -
-

The first page of an Offer Directory has a special index: the higher 192 bits define the order book, and the remaining 64 bits define the exchange rate of the offers in that directory. (An index is big-endian, so the book is in the more significant bits, which come first, and the quality is in the less significant bits which come last.) This provides a way to iterate through an order book from best offers to worst. Specifically: the first 192 bits are the first 192 bits of the SHA-512Half of the following values put together:

-
    -
  • The Book Directory space key (B)
    • -
  • The 160-bit currency code from the TakerPaysCurrency
    • -
  • The 160-bit currency code from the TakerGetsCurrency
    • -
  • The AccountID from the TakerPaysIssuer
    • -
  • The AccountID from the TakerGetsIssuer
    • -
-

The lower 64 bits of an Offer Directory's index represent the TakerPays amount divided by TakerGets amount from the offer(s) in that directory as a 64-bit number in the XRP Ledger's internal amount format.

-

If the DirectoryNode is not the first page in the Directory (regardless of whether it is an Owner Directory or an Offer Directory), then it has an index that is the SHA-512Half of the following values put together:

-
    -
  • The Directory Node space key (d)
    • -
  • The index of the root DirectoryNode
    • -
  • The page number of this node. (Since 0 is the root DirectoryNode, this value is an integer 1 or higher.)
    • -
-

Escrow

-

[Source]

-

(Requires the Escrow Amendment.)

-

The Escrow node type represents a held payment of XRP waiting to be executed or canceled. An EscrowCreate transaction creates an Escrow node in the ledger. A successful EscrowFinish or EscrowCancel transaction deletes the node. If the Escrow node has a crypto-condition, the payment can only succeed if an EscrowFinish transaction provides the corresponding fulfillment that satisfies the condition. (The only supported crypto-condition type is PREIMAGE-SHA-256.) If the Escrow node has a FinishAfter time, the held payment can only execute after that time.

-

An Escrow node is associated with two addresses:

-
    -
  • The owner, who provides the XRP when creating the Escrow node. If the held payment is canceled, the XRP returns to the owner.
    • -
  • The destination, where the XRP is paid when the held payment succeeds. The destination can be the same as the owner.
    • -
-

Example Escrow node:

-
{
-    "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-    "Amount": "10000",
-    "CancelAfter": 545440232,
-    "Condition": "A0258020A82A88B2DF843A54F58772E4A3861866ECDB4157645DD9AE528C1D3AEEDABAB6810120",
-    "Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-    "DestinationTag": 23480,
-    "FinishAfter": 545354132,
-    "Flags": 0,
-    "LedgerEntryType": "Escrow",
-    "OwnerNode": "0000000000000000",
-    "PreviousTxnID": "C44F2EB84196B9AD820313DBEBA6316A15C9A2D35787579ED172B87A30131DA7",
-    "PreviousTxnLgrSeq": 28991004,
-    "SourceTag": 11747,
-    "index": "DC5F3851D8A1AB622F957761E5963BC5BD439D5C24AC6AD7AC4523F0640244AC"
-}
-
-

An Escrow node has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameJSON TypeInternal TypeDescription
AccountStringAccountIDThe address of the owner (sender) of this held payment. This is the account that provided the XRP, and gets it back if the held payment is canceled.
DestinationStringAccountIDThe destination address where the XRP is paid if the held payment is successful.
AmountStringAmountThe amount of XRP, in drops, to be delivered by the held payment.
ConditionStringVariableLength(Optional) A PREIMAGE-SHA-256 crypto-condition, as hexadecimal. If present, the EscrowFinish transaction must contain a fulfillment that satisfies this condition.
CancelAfterNumberUInt32(Optional) The held payment can be canceled if and only if this field is present and the time it specifies has passed. Specifically, this is specified as seconds since the Ripple Epoch and it "has passed" if it's earlier than the close time of the previous validated ledger.
FinishAfterNumberUInt32(Optional) The time, in seconds since the Ripple Epoch, after which this held payment can be finished. Any EscrowFinish transaction before this time fails. (Specifically, this is compared with the close time of the previous validated ledger.)
SourceTagNumberUInt32(Optional) An arbitrary tag to further specify the source for this held payment, such as a hosted recipient at the owner's address.
DestinationTagNumberUInt32(Optional) An arbitrary tag to further specify the destination for this held payment, such as a hosted recipient at the destination address.
OwnerNodeStringUInt64A hint indicating which page of the owner directory links to this node, in case the directory consists of multiple pages. Note: The node does not contain a direct link to the owner directory containing it, since that value can be derived from the Account.
PreviousTxnIDStringHash256The identifying hash of the transaction that most recently modified this node.
PreviousTxnLgrSeqNumberUInt32The index of the ledger that contains the transaction that most recently modified this node.
-

Escrow Index Format

-

The index of an Escrow node is the SHA-512Half of the following values put together:

-
    -
  • The Escrow space key (u)
    • -
  • The AccountID of the sender of the EscrowCreate transaction that created the Escrow node
    • -
  • The Sequence number of the EscrowCreate transaction that created the Escrow node
    • -
-

Offer

-

[Source]

-

The Offer node type describes an offer to exchange currencies, more traditionally known as an order, in the XRP Ledger's distributed exchange. An OfferCreate transaction only creates an Offer node in the ledger when the offer cannot be fully executed immediately by consuming other offers already in the ledger.

-

An offer can become unfunded through other activities in the network, while remaining in the ledger. However, rippled automatically prunes any unfunded offers it happens across in the course of transaction processing (and only transaction processing, because the ledger state must only be changed by transactions). For more information, see lifecycle of an offer.

-

Example Offer node:

-
{
-    "Account": "rBqb89MRQJnMPq8wTwEbtz4kvxrEDfcYvt",
-    "BookDirectory": "ACC27DE91DBA86FC509069EAF4BC511D73128B780F2E54BF5E07A369E2446000",
-    "BookNode": "0000000000000000",
-    "Flags": 131072,
-    "LedgerEntryType": "Offer",
-    "OwnerNode": "0000000000000000",
-    "PreviousTxnID": "F0AB71E777B2DA54B86231E19B82554EF1F8211F92ECA473121C655BFC5329BF",
-    "PreviousTxnLgrSeq": 14524914,
-    "Sequence": 866,
-    "TakerGets": {
-        "currency": "XAG",
-        "issuer": "r9Dr5xwkeLegBeXq6ujinjSBLQzQ1zQGjH",
-        "value": "37"
-    },
-    "TakerPays": "79550000000",
-    "index": "96F76F27D8A327FC48753167EC04A46AA0E382E6F57F32FD12274144D00F1797"
-}
-
-

An Offer node has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameJSON TypeInternal TypeDescription
LedgerEntryTypeStringUInt16The value 0x6F, mapped to the string Offer, indicates that this node is an Offer object.
FlagsNumberUInt32A bit-map of boolean flags enabled for this offer.
AccountStringAccountIDThe address of the account that owns this offer.
SequenceNumberUInt32The Sequence value of the OfferCreate transaction that created this Offer node. Used in combination with the Account to identify this Offer.
TakerPaysString or ObjectAmountThe remaining amount and type of currency requested by the offer creator.
TakerGetsString or ObjectAmountThe remaining amount and type of currency being provided by the offer creator.
BookDirectoryStringUInt256The index of the Offer Directory that links to this offer.
BookNodeStringUInt64A hint indicating which page of the offer directory links to this node, in case the directory consists of multiple pages.
OwnerNodeStringUInt64A hint indicating which page of the owner directory links to this node, in case the directory consists of multiple pages. Note: The offer does not contain a direct link to the owner directory containing it, since that value can be derived from the Account.
PreviousTxnIDStringHash256The identifying hash of the transaction that most recently modified this node.
PreviousTxnLgrSeqNumberUInt32The index of the ledger that contains the transaction that most recently modified this node.
ExpirationNumberUInt32(Optional) Indicates the time after which this offer is considered unfunded. See Specifying Time for details.
-

Offer Flags

-

There are several options which can be either enabled or disabled when an OfferCreate transaction creates an offer node. In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with lsf.

-

Offer nodes can have the following flag values:

- - - - - - - - - - - - - - - - - - - - - - - - - - -
Flag NameHex ValueDecimal ValueDescriptionCorresponding OfferCreate Flag
lsfPassive0x0001000065536The node was placed as a passive offer. This has no effect on the node in the ledger.tfPassive
lsfSell0x00020000131072The node was placed as a sell offer. This has no effect on the node in the ledger (because tfSell only matters if you get a better rate than you asked for, which cannot happen after the node enters the ledger).tfSell
-

Offer Index Format

-

The index of an Offer node is the SHA-512Half of the following values put together:

-
    -
  • The Offer space key (o)
    • -
  • The AccountID of the account placing the offer
    • -
  • The Sequence number of the transaction that created the offer
    • -
-

PayChannel

-

[Source]

-

(Requires the PayChan Amendment.)

-

The PayChannel node type represents a payment channel. Payment channels enable small, rapid off-ledger payments of XRP that can be later reconciled with the consensus ledger. A payment channel holds a balance of XRP that can only be paid out to a specific destination address until the channel is closed. Any unspent XRP is returned to the channel's owner (the source address that created and funded it) when the channel closes.

-

The PaymentChannelCreate transaction type creates a PayChannel node. The PaymentChannelFund and PaymentChannelClaim transaction types modify existing PayChannel nodes.

-

When a payment channel expires, at first it remains on the ledger, because only new transactions can modify ledger contents. Transaction processing automatically closes a payment channel when any transaction accesses it after the expiration. Therefore, to "finalize" the closing of an expired channel and return the unspent XRP to the owner, some address must send a new PaymentChannelClaim or PaymentChannelFund transaction accessing the channel.

- -

Example PayChannel node:

-
{
-    "Account": "rBqb89MRQJnMPq8wTwEbtz4kvxrEDfcYvt",
-    "Destination": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-    "Amount": "4325800",
-    "Balance": "2323423",
-    "PublicKey": "32D2471DB72B27E3310F355BB33E339BF26F8392D5A93D3BC0FC3B566612DA0F0A",
-    "SettleDelay": 3600,
-    "Expiration": 536027313,
-    "CancelAfter": 536891313,
-    "SourceTag": 0,
-    "DestinationTag": 1002341,
-    "Flags": 0,
-    "LedgerEntryType": "PayChannel",
-    "OwnerNode": "0000000000000000",
-    "PreviousTxnID": "F0AB71E777B2DA54B86231E19B82554EF1F8211F92ECA473121C655BFC5329BF",
-    "PreviousTxnLgrSeq": 14524914,
-    "index": "96F76F27D8A327FC48753167EC04A46AA0E382E6F57F32FD12274144D00F1797"
-}
-
-

A PayChannel node has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameJSON TypeInternal TypeDescription
LedgerEntryTypeStringUInt16The value 0x78, mapped to the string PayChannel, indicates that this node is a payment channel object.
AccountStringAccountIDThe source address that owns this payment channel. This comes from the sending address of the transaction that created the channel.
DestinationStringAccountIDThe destination address for this payment channel. While the payment channel is open, this address is the only one that can receive XRP from the channel. This comes from the Destination field of the transaction that created the channel.
AmountStringAmountTotal XRP, in drops, that has been allocated to this channel. This includes XRP that has been paid to the destination address. This is initially set by the transaction that created the channel and can be increased if the source address sends a PaymentChannelFund transaction.
BalanceStringAmountTotal XRP, in drops, already paid out by the channel. The difference between this value and the Amount field is how much XRP can still be paid to the destination address with PaymentChannelClaim transactions. If the channel closes, the remaining difference is returned to the source address.
PublicKeyStringPubKeyPublic key, in hexadecimal, of the key pair that can be used to sign claims against this channel. This can be any valid secp256k1 or Ed25519 public key. This is set by the transaction that created the channel and must match the public key used in claims against the channel. The channel source address can also send XRP from this channel to the destination without signed claims.
SettleDelayNumberUInt32Number of seconds the source address must wait to close the channel if it still has any XRP in it. Smaller values mean that the destination address has less time to redeem any outstanding claims after the source address requests to close the channel. Can be any value that fits in a 32-bit unsigned integer (0 to 2^32-1). This is set by the transaction that creates the channel.
OwnerNodeStringUInt64A hint indicating which page of the source address's owner directory links to this node, in case the directory consists of multiple pages.
PreviousTxnIDStringHash256The identifying hash of the transaction that most recently modified this node.
PreviousTxnLgrSeqNumberUInt32The index of the ledger that contains the transaction that most recently modified this node.
FlagsNumberUInt32A bit-map of boolean flags enabled for this payment channel. Currently, the protocol defines no flags for PayChannel nodes.
ExpirationNumberUInt32(Optional) The mutable expiration time for this payment channel, in seconds since the Ripple Epoch. The channel is expired if this value is present and smaller than the previous ledger's close_time field. See Setting Channel Expiration for more details.
CancelAfterNumberUInt32(Optional) The immutable expiration time for this payment channel, in seconds since the Ripple Epoch. This channel is expired if this value is present and smaller than the previous ledger's close_time field. This is optionally set by the transaction that created the channel, and cannot be changed.
SourceTagNumberUInt32(Optional) An arbitrary tag to further specify the source for this payment channel, such as a hosted recipient at the owner's address.
DestinationTagNumberUInt32(Optional) An arbitrary tag to further specify the destination for this payment channel, such as a hosted recipient at the destination address.
-

Setting Channel Expiration

-

The Expiration field of a payment channel is the mutable expiration time, in contrast to the immutable expiration time represented by the CancelAfter field. The expiration of a channel is always considered relative to the close_time field of the previous ledger. The Expiration field is omitted when a PayChannel node is created. There are several ways the Expiration field of a PayChannel node can be updated, which can be summarized as follows: a channel's source address can set the Expiration of the channel freely as long as the channel always remains open at least SettleDelay seconds after the first attempt to close it.

-

Source Address

-

The source address can set the Expiration directly with the PaymentChannelFund transaction type. The new value must not be earlier than whichever of the following values is earliest:

-
    -
  • The current Expiration value (if one is set)
    • -
  • The previous ledger's close time plus the SettleDelay of the channel
    • -
-

In other words, the source address can always make the Expiration later if an expiration is already set. The source can make an Expiration value earlier or set an Expiration if one isn't currently set, as long as the new value is at least SettleDelay seconds in the future. If the source address attempts to set an invalid Expiration date, the transaction fails with the temBAD_EXPIRATION error code.

-

The source address can also set the Expiration with the tfClose flag of the PaymentChannelClaim transaction type. If the flag is enabled, the ledger automatically sets the Expiration to whichever of the following values is earlier:

-
    -
  • The current Expiration value (if one is set)
    • -
  • The previous ledger's close time plus the SettleDelay of the channel
    • -
-

The source address can remove the Expiration with the tfRenew flag of the PaymentChannelClaim transaction type.

-

Destination Address

-

The destination address cannot set the Expiration field. However, the destination address can use the PaymentChannelClaim's tfClose flag to close a channel immediately.

-

Other Addresses

-

If any other address attempts to set an Expiration field, the transaction fails with the tecNO_PERMISSION error code. However, if the channel is already expired, the transaction causes the channel to close and results in tesSUCCESS instead.

-

PayChannel Index Format

-

The index of a PayChannel node is the SHA-512Half of the following values put together:

-
    -
  • The PayChannel space key (x)
    • -
  • The AccountID of the source account
    • -
  • The AccountID of the destination account
    • -
  • The Sequence number of the transaction that created the channel
    • -
-

RippleState

-

[Source]

-

The RippleState node type connects two accounts in a single currency. Conceptually, a RippleState node represents two trust lines between the accounts, one from each side. Each account can change the settings for its side of the RippleState node, but the balance is a single shared value. A trust line that is entirely in its default state is considered the same as trust line that does not exist, so rippled deletes RippleState nodes when their properties are entirely default.

-

Since no account is privileged in the XRP Ledger, a RippleState node sorts their account addresses numerically, to ensure a canonical form. Whichever address is numerically lower is deemed the "low account" and the other is the "high account".

-

Example RippleState node:

-
{
-    "Balance": {
-        "currency": "USD",
-        "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-        "value": "-10"
-    },
-    "Flags": 393216,
-    "HighLimit": {
-        "currency": "USD",
-        "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-        "value": "110"
-    },
-    "HighNode": "0000000000000000",
-    "LedgerEntryType": "RippleState",
-    "LowLimit": {
-        "currency": "USD",
-        "issuer": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-        "value": "0"
-    },
-    "LowNode": "0000000000000000",
-    "PreviousTxnID": "E3FE6EA3D48F0C2B639448020EA4F03D4F4F8FFDB243A852A0F59177921B4879",
-    "PreviousTxnLgrSeq": 14090896,
-    "index": "9CA88CDEDFF9252B3DE183CE35B038F57282BC9503CDFA1923EF9A95DF0D6F7B"
-}
-
-

A RippleState node has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameJSON TypeInternal TypeDescription
LedgerEntryTypeStringUInt16The value 0x72, mapped to the string RippleState, indicates that this node is a RippleState object.
FlagsNumberUInt32A bit-map of boolean options enabled for this node.
BalanceObjectAmountThe balance of the trust line, from the perspective of the low account. A negative balance indicates that the low account has issued currency to the high account. The issuer in this is always set to the neutral value ACCOUNT_ONE.
LowLimitObjectAmountThe limit that the low account has set on the trust line. The issuer is the address of the low account that set this limit.
HighLimitObjectAmountThe limit that the high account has set on the trust line. The issuer is the address of the high account that set this limit.
PreviousTxnIDStringHash256The identifying hash of the transaction that most recently modified this node.
PreviousTxnLgrSeqNumberUInt32The index of the ledger that contains the transaction that most recently modified this node.
LowNodeStringUInt64(Omitted in some historical ledgers) A hint indicating which page of the low account's owner directory links to this node, in case the directory consists of multiple pages.
HighNodeStringUInt64(Omitted in some historical ledgers) A hint indicating which page of the high account's owner directory links to this node, in case the directory consists of multiple pages.
LowQualityInNumberUInt32(Optional) The inbound quality set by the low account, as an integer in the implied ratio LowQualityIn:1,000,000,000. The value 0 is equivalent to 1 billion, or face value.
LowQualityOutNumberUInt32(Optional) The outbound quality set by the low account, as an integer in the implied ratio LowQualityOut:1,000,000,000. The value 0 is equivalent to 1 billion, or face value.
HighQualityInNumberUInt32(Optional) The inbound quality set by the high account, as an integer in the implied ratio HighQualityIn:1,000,000,000. The value 0 is equivalent to 1 billion, or face value.
HighQualityOutNumberUInt32(Optional) The outbound quality set by the high account, as an integer in the implied ratio HighQualityOut:1,000,000,000. The value 0 is equivalent to 1 billion, or face value.
-

RippleState Flags

-

There are several options which can be either enabled or disabled for a trust line. These options can be changed with a TrustSet transaction. In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with lsf.

-

RippleState nodes can have the following flag values:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Flag NameHex ValueDecimal ValueDescriptionCorresponding TrustSet Flag
lsfLowReserve0x0001000065536This RippleState node contributes to the low account's owner reserve.(None)
lsfHighReserve0x00020000131072This RippleState node contributes to the high account's owner reserve.(None)
lsfLowAuth0x00040000262144The low account has authorized the high account to hold the low account's issuances.tfSetAuth
lsfHighAuth0x00080000524288The high account has authorized the low account to hold the high account's issuances.tfSetAuth
lsfLowNoRipple0x001000001048576The low account has disabled rippling from this trust line to other trust lines with the same account's NoRipple flag set.tfSetNoRipple
lsfHighNoRipple0x002000002097152The high account has disabled rippling from this trust line to other trust lines with the same account's NoRipple flag set.tfSetNoRipple
lsfLowFreeze0x004000004194304The low account has frozen the trust line, preventing the high account from transferring the asset.tfSetFreeze
lsfHighFreeze0x008000008388608The high account has frozen the trust line, preventing the low account from transferring the asset.tfSetFreeze
-

Contributing to the Owner Reserve

-

If an account modifies a trust line to put it in a non-default state, then that trust line counts towards the account's owner reserve. In a RippleState node, the lsfLowReserve and lsfHighReserve flags indicate which account(s) are responsible for the owner reserve. The rippled server automatically sets these flags when it modifies a trust line.

-

The values that count towards a trust line's non-default state are as follows:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
High account responsible if...Low account responsible if...
Balance is negative (the high account holds currency)Balance is positive (the low account holds currency)
HighLimit is not 0LowLimit is not 0
LowQualityIn is not 0 and not 1000000000HighQualityIn is not 0 and not 1000000000
LowQualityOut is not 0 and not 1000000000HighQualityOut is not 0 and not 1000000000
lsfHighNoRipple flag is not in its default statelsfLowNoRipple flag is not in its default state
lsfHighFreeze flag is enabledlsfLowFreeze flag is enabled
-

The lsfLowAuth and lsfHighAuth flags do not count against the default state, because they cannot be disabled.

-

The default state of the two NoRipple flags depends on the state of the lsfDefaultRipple flag in their corresponding AccountRoot nodes. If DefaultRipple is disabled (the default), then the default state of the lsfNoRipple flag is enabled for all of an account's trust lines. If an account enables DefaultRipple, then the lsfNoRipple flag is disabled (rippling is enabled) for an account's trust lines by default. Note: Prior to the introduction of the DefaultRipple flags in rippled version 0.27.3 (March 10, 2015), the default state for all trust lines was with lsfNoRipple disabled (rippling enabled).

-

Fortunately, rippled uses lazy evaluation to calculate the owner reserve. This means that even if an account changes the default state of all its trust lines by changing the DefaultRipple flag, that account's reserve stays the same initially. If an account modifies a trust line, rippled re-evaluates whether that individual trust line is in its default state and should contribute the owner reserve.

-

RippleState Index Format

-

The index of a RippleState node is the SHA-512Half of the following values put together:

-
    -
  • The RippleState space key (r)
    • -
  • The AccountID of the low account
    • -
  • The AccountID of the high account
    • -
  • The 160-bit currency code of the trust line(s)
    • -
-

SignerList

-

[Source]

-

The SignerList node type represents a list of parties that, as a group, are authorized to sign a transaction in place of an individual account. You can create, replace, or remove a SignerList using the SignerListSet transaction type This node type is introduced by the MultiSign amendment. New in: rippled 0.31.0

-

Example SignerList node:

-
{
-    "Flags": 0,
-    "LedgerEntryType": "SignerList",
-    "OwnerNode": "0000000000000000",
-    "PreviousTxnID": "5904C0DC72C58A83AEFED2FFC5386356AA83FCA6A88C89D00646E51E687CDBE4",
-    "PreviousTxnLgrSeq": 16061435,
-    "SignerEntries": [
-        {
-            "SignerEntry": {
-                "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-                "SignerWeight": 2
-            }
-        },
-        {
-            "SignerEntry": {
-                "Account": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
-                "SignerWeight": 1
-            }
-        },
-        {
-            "SignerEntry": {
-                "Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
-                "SignerWeight": 1
-            }
-        }
-    ],
-    "SignerListID": 0,
-    "SignerQuorum": 3,
-    "index": "A9C28A28B85CD533217F5C0A0C7767666B093FA58A0F2D80026FCC4CD932DDC7"
-}
-
-

A SignerList node has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameJSON TypeInternal TypeDescription
OwnerNodeStringUInt64A hint indicating which page of the owner directory links to this node, in case the directory consists of multiple pages.
SignerQuorumNumberUInt32A target number for signer weights. To produce a valid signature for the owner of this SignerList, the signers must provide valid signatures whose weights sum to this value or more.
SignerEntriesArrayArrayAn array of SignerEntry objects representing the parties who are part of this signer list.
SignerListIDNumberUInt32An ID for this signer list. Currently always set to 0. If a future amendment allows multiple signer lists for an account, this may change.
PreviousTxnIDStringHash256The identifying hash of the transaction that most recently modified this node.
PreviousTxnLgrSeqNumberUInt32The index of the ledger that contains the transaction that most recently modified this node.
-

The SignerEntries may be any combination of funded and unfunded addresses that use either secp256k1 or ed25519 keys.

-

SignerEntry Object

-

Each member of the SignerEntries field is an object that describes that signer in the list. A SignerEntry has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - -
NameJSON TypeInternal TypeDescription
AccountStringAccountIDAn XRP Ledger address whose signature contributes to the multi-signature. It does not need to be a funded address in the ledger.
SignerWeightNumberUInt16The weight of a signature from this signer. A multi-signature is only valid if the sum weight of the signatures provided meets or exceeds the SignerList's SignerQuorum value.
-

When processing a multi-signed transaction, the server dereferences the Account values with respect to the ledger at the time of transaction execution. If the address does not correspond to a funded AccountRoot node, then only the master secret associated with that address can be used to produce a valid signature. If the account does exist in the ledger, then it depends on the state of that account. If the account has a Regular Key configured, the Regular Key can be used. The account's master key can only be used if it is not disabled. A multi-signature cannot be used as part of another multi-signature.

-

SignerLists and Reserves

-

A SignerList contributes to its owner's reserve requirement. The SignerList itself counts as two objects, and each member of the list counts as one. As a result, the total owner reserve associated with a SignerList is anywhere from 3 times to 10 times the reserve required by a single trust line (RippleState) or Offer node in the ledger.

-

SignerList Index Format

-

The index of a SignerList node is the SHA-512Half of the following values put together:

-
    -
  • The RippleState space key (S)
    • -
  • The AccountID of the owner of the SignerList
    • -
  • The SignerListID (currently always 0)
    • -
- -
-
-
- - - - \ No newline at end of file diff --git a/reference-rippleapi.html b/reference-rippleapi.html deleted file mode 100644 index afc4e9fe0c..0000000000 --- a/reference-rippleapi.html +++ /dev/null @@ -1,6134 +0,0 @@ - - - - - - - - RippleAPI - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

Introduction

-

RippleAPI is the official client library to the XRP Ledger. Currently, RippleAPI is only available in JavaScript. -Using RippleAPI, you can:

- -

RippleAPI only provides access to validated, immutable transaction data.

-

Boilerplate

-

Use the following boilerplate code to wrap your custom code using RippleAPI.

-
const RippleAPI = require('ripple-lib').RippleAPI;
-
-const api = new RippleAPI({
-  server: 'wss://s1.ripple.com' // Public rippled server hosted by Ripple, Inc.
-});
-api.on('error', (errorCode, errorMessage) => {
-  console.log(errorCode + ': ' + errorMessage);
-});
-api.on('connected', () => {
-  console.log('connected');
-});
-api.on('disconnected', (code) => {
-  // code - [close code](https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent) sent by the server
-  // will be 1000 if this was normal closure
-  console.log('disconnected, code:', code);
-});
-api.connect().then(() => {
-  /* insert code here */
-}).then(() => {
-  return api.disconnect();
-}).catch(console.error);
-
-

RippleAPI is designed to work in Node.js version 6.9.0 or later. RippleAPI may work on older Node.js versions if you use Babel for ECMAScript 6 support.

-

The code samples in this documentation are written with ECMAScript 6 (ES6) features, but RippleAPI also works with ECMAScript 5 (ES5). Regardless of whether you use ES5 or ES6, the methods that return Promises return ES6-style promises.

- - - -

Parameters

-

The RippleAPI constructor optionally takes one argument, an object with the following options:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
authorizationstringOptional Username and password for HTTP basic authentication to the rippled server in the format username:password.
certificatestringOptional A string containing the certificate key of the client in PEM format. (Can be an array of certificates).
feeCushionnumberOptional Factor to multiply estimated fee by to provide a cushion in case the required fee rises during submission of a transaction. Defaults to 1.2.
keystringOptional A string containing the private key of the client in PEM format. (Can be an array of keys).
passphrasestringOptional The passphrase for the private key of the client.
proxyuri stringOptional URI for HTTP/HTTPS proxy to use to connect to the rippled server.
proxyAuthorizationstringOptional Username and password for HTTP basic authentication to the proxy in the format username:password.
serveruri stringOptional URI for rippled websocket port to connect to. Must start with wss:// or ws://.
timeoutintegerOptional Timeout in milliseconds before considering a request to have failed.
tracebooleanOptional If true, log rippled requests and responses to stdout.
trustedCertificatesarray\<string>Optional Array of PEM-formatted SSL certificates to trust when connecting to a proxy. This is useful if you want to use a self-signed certificate on the proxy server. Note: Each element must contain a single certificate; concatenated certificates are not valid.
-

If you omit the server parameter, RippleAPI operates offline.

-

Installation

-
    -
  1. Install Node.js and the Node Package Manager (npm). Most Linux distros have a package for Node.js, but make sure you have version 6.9.0 or higher.
    2. -
  2. Use npm to install RippleAPI: - npm install ripple-lib
    3. -
-

After you have installed ripple-lib, you can create scripts using the boilerplate and run them using the Node.js executable, typically named node:

-
  `node script.js`
-
-

Offline functionality

-

RippleAPI can also function without internet connectivity. This can be useful in order to generate secrets and sign transactions from a secure, isolated machine.

-

To instantiate RippleAPI in offline mode, use the following boilerplate code:

-
const RippleAPI = require('ripple-lib').RippleAPI;
-
-const api = new RippleAPI();
-/* insert code here */
-
-

Methods that depend on the state of the XRP Ledger are unavailable in offline mode. To prepare transactions offline, you must specify the fee, sequence, and maxLedgerVersion parameters in the transaction instructions. You can use the following methods while offline:

- -

Basic Types

-

Address

-
"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59"
-
-

Every XRP Ledger account has an address, which is a base58-encoding of a hash of the account's public key. XRP Ledger addresses always start with the lowercase letter r.

-

Account Sequence Number

-

Every XRP Ledger account has a sequence number that is used to keep transactions in order. Every transaction must have a sequence number. A transaction can only be executed if it has the next sequence number in order, of the account sending it. This prevents one transaction from executing twice and transactions executing out of order. The sequence number starts at 1 and increments for each transaction that the account makes.

-

Currency

-

Currencies are represented as either 3-character currency codes or 40-character uppercase hexadecimal strings. We recommend using uppercase ISO 4217 Currency Codes only. The string "XRP" is disallowed on trustlines because it is reserved for the XRP Ledger's native currency. The following characters are permitted: all uppercase and lowercase letters, digits, as well as the symbols ?, !, @, #, $, %, ^, &, *, <, >, (, ), {, }, [, ], and |.

-

Value

-

A value is a quantity of a currency represented as a decimal string. Be careful: JavaScript's native number format does not have sufficient precision to represent all values. XRP has different precision from other currencies.

-

XRP has 6 significant digits past the decimal point. In other words, XRP cannot be divided into positive values smaller than 0.000001 (1e-6). XRP has a maximum value of 100000000000 (1e11).

-

Non-XRP values have 16 decimal digits of precision, with a maximum value of 9999999999999999e80. The smallest positive non-XRP value is 1e-81.

-

Amount

-

Example amount:

-
{
-  "currency": "USD",
-  "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM",
-  "value": "100"
-}
-
-

Example XRP amount:

-
{
-  "currency": "XRP",
-  "value": "2000"
-}
-
-

An amount is data structure representing a currency, a quantity of that currency, and the counterparty on the trustline that holds the value. For XRP, there is no counterparty.

-

A lax amount allows the counterparty to be omitted for all currencies. If the counterparty is not specified in an amount within a transaction specification, then any counterparty may be used for that amount.

-

A lax lax amount allows either or both the counterparty and value to be omitted.

-

A balance is an amount than can have a negative value.

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
currencycurrencyThe three-character code or hexadecimal string used to denote currencies
counterpartyaddressOptional The Ripple address of the account that owes or is owed the funds (omitted if currency is "XRP")
valuevalueOptional The quantity of the currency, denoted as a string to retain floating point precision
-

Transaction Overview

-

Transaction Types

-

A transaction type is specified by the strings in the first column in the table below.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeDescription
paymentA payment transaction represents a transfer of value from one account to another. Depending on the path taken, additional exchanges of value may occur atomically to facilitate the payment.
orderAn order transaction creates a limit order. It defines an intent to exchange currencies, and creates an order in the XRP Ledger's order book if not completely fulfilled when placed. Orders can be partially fulfilled.
orderCancellationAn orderCancellation transaction cancels an order in the XRP Ledger's order book.
trustlineA trustline transactions creates or modifies a trust line between two accounts.
settingsA settings transaction modifies the settings of an account in the XRP Ledger.
escrowCreationAn escrowCreation transaction creates an escrow on the ledger, which locks XRP until a cryptographic condition is met or it expires. It is like an escrow service where the XRP Ledger acts as the escrow agent.
escrowCancellationAn escrowCancellation transaction unlocks the funds in an escrow and sends them back to the creator of the escrow, but it will only work after the escrow expires.
escrowExecutionAn escrowExecution transaction unlocks the funds in an escrow and sends them to the destination of the escrow, but it will only work if the cryptographic condition is provided.
-

Transaction Flow

-

Executing a transaction with RippleAPI requires the following four steps:

-
    -
  1. Prepare - Create an unsigned transaction based on a specification and instructions. There is a method to prepare each type of transaction: -
    2. -
  2. Sign - Cryptographically sign the transaction locally and save the transaction ID. Signing is how the owner of an account authorizes a transaction to take place. For multisignature transactions, the signedTransaction fields returned by sign must be collected and passed to the combine method.
    3. -
  3. Submit - Submit the transaction to the connected server.
    4. -
  4. Verify - Verify that the transaction got validated by querying with getTransaction. This is necessary because transactions may fail even if they were successfully submitted.
    5. -
-

Transaction Fees

-

Every transaction must destroy a small amount of XRP as a cost to send the transaction. This is also called a transaction fee. The transaction cost is designed to increase along with the load on the XRP Ledger, making it very expensive to deliberately or inadvertently overload the peer-to-peer network that powers the XRP Ledger.

-

You can choose the size of the fee you want to pay or let a default be used. You can get an estimate of the fee required to be included in the next ledger closing with the getFee method.

-

Transaction Instructions

-

Transaction instructions indicate how to execute a transaction, complementary with the transaction specification.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
feevalueOptional An exact fee to pay for the transaction. See Transaction Fees for more information.
maxFeevalueOptional The maximum fee to pay for the transaction. See Transaction Fees for more information.
maxLedgerVersioninteger,nullOptional The highest ledger version that the transaction can be included in. If this option and maxLedgerVersionOffset are both omitted, the maxLedgerVersion option will default to 3 greater than the current validated ledger version (equivalent to maxLedgerVersionOffset=3). Use null to not set a maximum ledger version.
maxLedgerVersionOffsetintegerOptional Offset from current validated legder version to highest ledger version that the transaction can be included in.
sequencesequenceOptional The initiating account's sequence number for this transaction.
signersCountintegerOptional Number of signers that will be signing this transaction.
-

We recommended that you specify a maxLedgerVersion so that you can quickly determine that a failed transaction will never succeeed in the future. It is impossible for a transaction to succeed after the XRP Ledger's consensus-validated ledger version exceeds the transaction's maxLedgerVersion. If you omit maxLedgerVersion, the "prepare" method automatically supplies a maxLedgerVersion equal to the current ledger plus 3, which it includes in the return value from the "prepare" method.

-

Transaction ID

-
"F4AB442A6D4CBB935D66E1DA7309A5FC71C7143ED4049053EC14E3875B0CF9BF"
-
-

A transaction ID is a 64-bit hexadecimal string that uniquely identifies the transaction. The transaction ID is derived from the transaction instruction and specifications, using a strong hash function.

-

You can look up a transaction by ID using the getTransaction method.

-

Transaction Memos

-

Every transaction can optionally have an array of memos for user applications. The memos field in each transaction specification is an array of objects with the following structure:

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
datastringOptional Arbitrary string, conventionally containing the content of the memo.
formatstringOptional Conventionally containing information on how the memo is encoded, for example as a MIME type. Only characters allowed in URLs are permitted.
typestringOptional Conventionally, a unique relation (according to RFC 5988) that defines the format of this memo. Only characters allowed in URLs are permitted.
-

Transaction Specifications

-

A transaction specification specifies what a transaction should do. Each Transaction Type has its own type of specification.

-

Payment

-

See Transaction Types for a description.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
sourceobjectThe source of the funds to be sent.
source. addressaddressThe address to send from.
source. amountlaxAmountAn exact amount to send. If the counterparty is not specified, amounts with any counterparty may be used. (This field is exclusive with source.maxAmount)
source. tagintegerOptional An arbitrary unsigned 32-bit integer that identifies a reason for payment or a non-Ripple account.
source. maxAmountlaxAmountThe maximum amount to send. (This field is exclusive with source.amount)
destinationobjectThe destination of the funds to be sent.
destination. addressaddressThe address to receive at.
destination. amountlaxAmountAn exact amount to deliver to the recipient. If the counterparty is not specified, amounts with any counterparty may be used. (This field is exclusive with destination.minAmount).
destination. tagintegerOptional An arbitrary unsigned 32-bit integer that identifies a reason for payment or a non-Ripple account.
destination. addressaddressThe address to send to.
destination. minAmountlaxAmountThe minimum amount to be delivered. (This field is exclusive with destination.amount)
allowPartialPaymentbooleanOptional A boolean that, if set to true, indicates that this payment should go through even if the whole amount cannot be delivered because of a lack of liquidity or funds in the source account account
invoiceIDstringOptional A 256-bit hash that can be used to identify a particular payment.
limitQualitybooleanOptional Only take paths where all the conversions have an input:output ratio that is equal or better than the ratio of destination.amount:source.maxAmount.
memosmemosOptional Array of memos to attach to the transaction.
noDirectRipplebooleanOptional A boolean that can be set to true if paths are specified and the sender would like the Ripple Network to disregard any direct paths from the source account to the destination account. This may be used to take advantage of an arbitrage opportunity or by gateways wishing to issue balances from a hot wallet to a user who has mistakenly set a trustline directly to the hot wallet
pathsstringOptional The paths of trustlines and orders to use in executing the payment.
-

Example

-
{
-  "source": {
-    "address": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-    "maxAmount": {
-      "value": "0.01",
-      "currency": "USD",
-      "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM"
-    }
-  },
-  "destination": {
-    "address": "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo",
-    "amount": {
-      "value": "0.01",
-      "currency": "USD",
-      "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM"
-    }
-  }
-}
-
-

Trustline

-

See Transaction Types for a description.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
currencycurrencyThe currency this trustline applies to.
counterpartyaddressThe address of the account this trustline extends trust to.
limitvalueThe maximum amount that the owner of the trustline can be owed through the trustline.
authorizedbooleanOptional If true, authorize the counterparty to hold issuances from this account.
frozenbooleanOptional If true, the trustline is frozen, which means that funds can only be sent to the owner.
memosmemosOptional Array of memos to attach to the transaction.
qualityInnumberOptional Incoming balances on this trustline are valued at this ratio.
qualityOutnumberOptional Outgoing balances on this trustline are valued at this ratio.
ripplingDisabledbooleanOptional If true, payments cannot ripple through this trustline.
-

Example

-
{
-  "currency": "USD",
-  "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM",
-  "limit": "10000",
-  "qualityIn": 0.91,
-  "qualityOut": 0.87,
-  "ripplingDisabled": true,
-  "frozen": false,
-  "memos": [
-    {
-      "type": "test",
-      "format": "plain/text",
-      "data": "texted data"
-    }
-  ]
-}
-
-

Order

-

See Transaction Types for a description.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
directionstringEqual to "buy" for buy orders and "sell" for sell orders.
quantityamountThe amount of currency to buy or sell.
totalPriceamountThe total price to be paid for the quantity to be bought or sold.
expirationTimedate-time stringOptional Time after which the offer is no longer active, as an ISO 8601 date-time.
fillOrKillbooleanOptional Treat the offer as a Fill or Kill order. Only attempt to match existing offers in the ledger, and only do so if the entire quantity can be exchanged.
immediateOrCancelbooleanOptional Treat the offer as an Immediate or Cancel order. If enabled, the offer will never become a ledger node: it only attempts to match existing offers in the ledger.
memosmemosOptional Array of memos to attach to the transaction.
orderToReplacesequenceOptional The account sequence number of an order to cancel before the new order is created, effectively replacing the old order.
passivebooleanOptional If enabled, the offer will not consume offers that exactly match it, and instead becomes an Offer node in the ledger. It will still consume offers that cross it.
-

Example

-
{
-  "direction": "buy",
-  "quantity": {
-    "currency": "USD",
-    "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM",
-    "value": "10.1"
-  },
-  "totalPrice": {
-    "currency": "XRP",
-    "value": "2"
-  },
-  "passive": true,
-  "fillOrKill": true
-}
-
-

Order Cancellation

-

See Transaction Types for a description.

- - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
orderSequencesequenceThe account sequence number of the order to cancel.
memosmemosOptional Array of memos to attach to the transaction.
-

Example

-
{
-  "orderSequence": 23
-}
-
-

Settings

-

See Transaction Types for a description.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
defaultRipplebooleanOptional Enable rippling on this account’s trust lines by default. (New in rippled 0.27.3)
disableMasterKeybooleanOptional Disallows use of the master key to sign transactions for this account.
disallowIncomingXRPbooleanOptional Indicates that client applications should not send XRP to this account. Not enforced by rippled.
domainstringOptional The domain that owns this account, as a hexadecimal string representing the ASCII for the domain in lowercase.
emailHashstring,nullOptional Hash of an email address to be used for generating an avatar image. Conventionally, clients use Gravatar to display this image. Use null to clear.
enableTransactionIDTrackingbooleanOptional Track the ID of this account’s most recent transaction.
globalFreezebooleanOptional Freeze all assets issued by this account.
memosmemosOptional Array of memos to attach to the transaction.
messageKeystringOptional Public key for sending encrypted messages to this account. Conventionally, it should be a secp256k1 key, the same encryption that is used by the rest of Ripple.
noFreezebooleanOptional Permanently give up the ability to freeze individual trust lines. This flag can never be disabled after being enabled.
passwordSpentbooleanOptional Indicates that the account has used its free SetRegularKey transaction.
regularKeyaddress,nullOptional The public key of a new keypair, to use as the regular key to this account, as a base-58-encoded string in the same format as an account address. Use null to remove the regular key.
requireAuthorizationbooleanOptional If set, this account must individually approve other users in order for those users to hold this account’s issuances.
requireDestinationTagbooleanOptional Requires incoming payments to specify a destination tag.
signersobjectOptional Settings that determine what sets of accounts can be used to sign a transaction on behalf of this account using multisigning.
signers. thresholdintegerOptional A target number for the signer weights. A multi-signature from this list is valid only if the sum weights of the signatures provided is equal or greater than this value. To delete the signers setting, use the value 0.
signers. weightsarrayOptional Weights of signatures for each signer.
signers. weights[]objectAn association of an address and a weight.
signers.weights[]. addressaddressA Ripple account address
signers.weights[]. weightintegerThe weight that the signature of this account counts as towards the threshold.
transferRatenumber,nullOptional The fee to charge when users transfer this account’s issuances, as the decimal amount that must be sent to deliver 1 unit. Has precision up to 9 digits beyond the decimal point. Use null to set no fee.
-

Example

-
{
-  "domain": "ripple.com",
-  "memos": [
-    {
-      "type": "test",
-      "format": "plain/text",
-      "data": "texted data"
-    }
-  ]
-}
-
-

Escrow Creation

-

See Transaction Types for a description.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
amountvalueAmount of XRP for sender to escrow.
destinationaddressAddress to receive escrowed XRP.
allowCancelAfterdate-time stringOptional If present, the escrow may be cancelled after this time.
allowExecuteAfterdate-time stringOptional If present, the escrow can not be executed before this time.
conditionstringOptional A hex value representing a PREIMAGE-SHA-256 crypto-condition. If present, fulfillment is required upon execution.
destinationTagintegerOptional Destination tag.
memosmemosOptional Array of memos to attach to the transaction.
sourceTagintegerOptional Source tag.
-

Example

-
{
-  "destination": "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo",
-  "amount": "0.01",
-  "allowCancelAfter": "2014-09-24T21:21:50.000Z"
-}
-
-

Escrow Cancellation

-

See Transaction Types for a description.

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
owneraddressThe address of the owner of the escrow to cancel.
escrowSequencesequenceThe account sequence number of the Escrow Creation transaction for the escrow to cancel.
memosmemosOptional Array of memos to attach to the transaction.
-

Example

-
{
-  "owner": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-  "escrowSequence": 1234
-}
-
-

Escrow Execution

-

See Transaction Types for a description.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
owneraddressThe address of the owner of the escrow to execute.
escrowSequencesequenceThe account sequence number of the Escrow Creation transaction for the escrow to execute.
conditionstringOptional A hex value representing a PREIMAGE-SHA-256 crypto-condition. This must match the original condition from the escrow creation transaction.
fulfillmentstringOptional A hex value representing the PREIMAGE-SHA-256 crypto-condition fulfillment for condition.
memosmemosOptional Array of memos to attach to the transaction.
-

Example

-
{
-  "owner": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-  "escrowSequence": 1234,
-  "condition": "A0258020E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855810100",
-  "fulfillment": "A0028000"
-}
-
-

Payment Channel Create

-

See Transaction Types for a description.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
amountvalueAmount of XRP for sender to set aside in this channel.
destinationaddressAddress to receive XRP claims against this channel.
settleDelaynumberAmount of seconds the source address must wait before closing the channel if it has unclaimed XRP.
publicKeystringPublic key of the key pair the source will use to sign claims against this channel.
cancelAfterdate-time stringOptional Time when this channel expires.
destinationTagintegerOptional Destination tag.
sourceTagintegerOptional Source tag.
-

Example

-
{
-  "amount": "1",
-  "destination": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-  "settleDelay": 86400,
-  "publicKey": "32D2471DB72B27E3310F355BB33E339BF26F8392D5A93D3BC0FC3B566612DA0F0A"
-}
-
-

Payment Channel Fund

-

See Transaction Types for a description.

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
amountvalueAmount of XRP to fund the channel with.
channelstring256-bit hexadecimal channel identifier.
expirationdate-time stringOptional New expiration for this channel.
-

Example

-
{
-  "channel": "C1AE6DDDEEC05CF2978C0BAD6FE302948E9533691DC749DCDD3B9E5992CA6198",
-  "amount": "1"
-}
-
-

Payment Channel Claim

-

See Transaction Types for a description.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
channelstring256-bit hexadecimal channel identifier.
amountvalueOptional XRP balance of this channel after claim is processed.
balancevalueOptional Amount of XRP authorized by signature.
closebooleanOptional Request to close the channel.
publicKeystringOptional Public key of the channel's sender
renewbooleanOptional Clear the channel's expiration time.
signaturestringOptional Signature of this claim.
-

Example

-
{
-  "channel": "C1AE6DDDEEC05CF2978C0BAD6FE302948E9533691DC749DCDD3B9E5992CA6198"
-}
-
-

API Methods

-

connect

-

connect(): Promise<void>

-

Tells the RippleAPI instance to connect to its rippled server.

-

Parameters

-

This method has no parameters.

-

Return Value

-

This method returns a promise that resolves with a void value when a connection is established.

-

Example

-

See Boilerplate for code sample.

-

disconnect

-

disconnect(): Promise<void>

-

Tells the RippleAPI instance to disconnect from its rippled server.

-

Parameters

-

This method has no parameters.

-

Return Value

-

This method returns a promise that resolves with a void value when a connection is destroyed.

-

Example

-

See Boilerplate for code sample

-

isConnected

-

isConnected(): boolean

-

Checks if the RippleAPI instance is connected to its rippled server.

-

Parameters

-

This method has no parameters.

-

Return Value

-

This method returns true if connected and false if not connected.

-

Example

-
return api.isConnected();
-
-
true
-
-

getServerInfo

-

getServerInfo(): Promise<object>

-

Get status information about the server that the RippleAPI instance is connected to.

-

Parameters

-

This method has no parameters.

-

Return Value

-

This method returns a promise that resolves with an object with the following structure:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
buildVersionstringThe version number of the running rippled version.
completeLedgersstringRange expression indicating the sequence numbers of the ledger versions the local rippled has in its database. It is possible to be a disjoint sequence, e.g. “2500-5000,32570-7695432”.
hostIDstringOn an admin request, returns the hostname of the server running the rippled instance; otherwise, returns a unique four letter word.
ioLatencyMsnumberAmount of time spent waiting for I/O operations to be performed, in milliseconds. If this number is not very, very low, then the rippled server is probably having serious load issues.
lastCloseobjectInformation about the last time the server closed a ledger.
lastClose. convergeTimeSnumberThe time it took to reach a consensus for the last ledger closing, in seconds.
lastClose. proposersintegerNumber of trusted validators participating in the ledger closing.
loadFactornumberThe load factor the server is currently enforcing, as a multiplier on the base transaction fee. The load factor is determined by the highest of the individual server’s load factor, cluster’s load factor, and the overall network’s load factor.
peersintegerHow many other rippled servers the node is currently connected to.
pubkeyNodestringPublic key used to verify this node for internal communications; this key is automatically generated by the server the first time it starts up. (If deleted, the node can just create a new pair of keys.)
serverStatestringA string indicating to what extent the server is participating in the network. See Possible Server States for more details.
validatedLedgerobjectInformation about the fully-validated ledger with the highest sequence number (the most recent).
validatedLedger. ageintegerThe time since the ledger was closed, in seconds.
validatedLedger. baseFeeXRPvalueBase fee, in XRP. This may be represented in scientific notation such as 1e-05 for 0.00005.
validatedLedger. hashstringUnique hash for the ledger, as an uppercase hexadecimal string.
validatedLedger. reserveBaseXRPvalueMinimum amount of XRP necessary for every account to keep in reserve.
validatedLedger. reserveIncrementXRPvalueAmount of XRP added to the account reserve for each object an account is responsible for in the ledger.
validatedLedger. ledgerVersionintegerIdentifying sequence number of this ledger version.
validationQuorumnumberMinimum number of trusted validations required in order to validate a ledger version. Some circumstances may cause the server to require more validations.
loadobjectOptional (Admin only) Detailed information about the current load state of the server.
load. jobTypesarray\<object>(Admin only) Information about the rate of different types of jobs being performed by the server and how much time it spends on each.
load. threadsnumber(Admin only) The number of threads in the server’s main job pool, performing various Ripple Network operations.
pubkeyValidatorstringOptional (Admin only) Public key used by this node to sign ledger validations.
-

Example

-
return api.getServerInfo().then(info => {/* ... */});
-
-
{
-  "buildVersion": "0.24.0-rc1",
-  "completeLedgers": "32570-6595042",
-  "hostID": "ARTS",
-  "ioLatencyMs": 1,
-  "lastClose": {
-    "convergeTimeS": 2.007,
-    "proposers": 4
-  },
-  "loadFactor": 1,
-  "peers": 53,
-  "pubkeyNode": "n94wWvFUmaKGYrKUGgpv1DyYgDeXRGdACkNQaSe7zJiy5Znio7UC",
-  "serverState": "full",
-  "validatedLedger": {
-    "age": 5,
-    "baseFeeXRP": "0.00001",
-    "hash": "4482DEE5362332F54A4036ED57EE1767C9F33CF7CE5A6670355C16CECE381D46",
-    "reserveBaseXRP": "20",
-    "reserveIncrementXRP": "5",
-    "ledgerVersion": 6595042
-  },
-  "validationQuorum": 3
-}
-
-

getFee

-

getFee(): Promise<number>

-

Returns the estimated transaction fee for the rippled server the RippleAPI instance is connected to.

-

Parameters

-

This method has no parameters.

-

Return Value

-

This method returns a promise that resolves with a string encoded floating point value representing the estimated fee to submit a transaction, expressed in XRP.

-

Example

-
return api.getFee().then(fee => {/* ... */});
-
-
"0.012"
-
-

getLedgerVersion

-

getLedgerVersion(): Promise<number>

-

Returns the most recent validated ledger version number known to the connected server.

-

Parameters

-

This method has no parameters.

-

Return Value

-

This method returns a promise that resolves with a positive integer representing the most recent validated ledger version number known to the connected server.

-

Example

-
return api.getLedgerVersion().then(ledgerVersion => {
-  /* ... */
-});
-
-
16869039
-
-

getTransaction

-

getTransaction(id: string, options: Object): Promise<Object>

-

Retrieves a transaction by its Transaction ID.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
ididA hash of a transaction used to identify the transaction, represented in hexadecimal.
optionsobjectOptional Options to limit the ledger versions to search.
options. maxLedgerVersionintegerOptional The highest ledger version to search
options. minLedgerVersionintegerOptional The lowest ledger version to search.
-

Return Value

-

This method returns a promise that resolves with a transaction object containing the following fields.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
ididA hash of the transaction that can be used to identify it.
addressaddressThe address of the account that initiated the transaction.
sequencesequenceThe account sequence number of the transaction for the account that initiated it.
typetransactionTypeThe type of the transaction.
specificationobjectA specification that would produce the same outcome as this transaction. The structure of the specification depends on the value of the type field (see Transaction Types for details). Note: This is not necessarily the same as the original specification.
outcomeobjectThe outcome of the transaction (what effects it had).
outcome. resultstringResult code returned by rippled. See Transaction Results for a complete list.
outcome. feevalueThe XRP fee that was charged for the transaction.
outcome.balanceChanges. *array\<balance>Key is the ripple address; value is an array of signed amounts representing changes of balances for that address.
outcome.orderbookChanges. *arrayKey is the maker's ripple address; value is an array of changes
outcome.orderbookChanges. *[]objectA change to an order.
outcome.orderbookChanges.*[]. directionstringEqual to "buy" for buy orders and "sell" for sell orders.
outcome.orderbookChanges.*[]. quantityamountThe amount to be bought or sold by the maker.
outcome.orderbookChanges.*[]. totalPriceamountThe total amount to be paid or received by the taker.
outcome.orderbookChanges.*[]. sequencesequenceThe order sequence number, used to identify the order for cancellation
outcome.orderbookChanges.*[]. statusstringThe status of the order. One of "created", "filled", "partially-filled", "cancelled".
outcome.orderbookChanges.*[]. expirationTimedate-time stringOptional The time after which the order expires, if any.
outcome.orderbookChanges.*[]. makerExchangeRatevalueOptional The exchange rate between the quantity currency and the totalPrice currency from the point of view of the maker.
outcome. ledgerVersionintegerThe ledger version that the transaction was validated in.
outcome. indexInLedgerintegerThe ordering index of the transaction in the ledger.
outcome. deliveredAmountamountOptional For payment transactions, it is impossible to reliably compute the actual delivered amount from the balanceChanges due to fixed precision. If the payment is not a partial payment and the transaction succeeded, the deliveredAmount should always be considered to be the amount specified in the transaction.
outcome. timestampdate-time stringOptional The timestamp when the transaction was validated. (May be missing when requesting transactions in binary mode.)
-

Example

-
const id = '01CDEAA89BF99D97DFD47F79A0477E1DCC0989D39F70E8AACBFE68CC83BD1E94';
-return api.getTransaction(id).then(transaction => {
-  /* ... */
-});
-
-
{
-  "type": "payment",
-  "address": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-  "sequence": 4,
-  "id": "F4AB442A6D4CBB935D66E1DA7309A5FC71C7143ED4049053EC14E3875B0CF9BF",
-  "specification": {
-    "source": {
-      "address": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-      "maxAmount": {
-        "currency": "XRP",
-        "value": "1.112209"
-      }
-    },
-    "destination": {
-      "address": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM",
-      "amount": {
-        "currency": "USD",
-        "value": "0.001"
-      }
-    },
-    "paths": "[[{\"currency\":\"USD\",\"issuer\":\"rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo\",\"type\":48,\"type_hex\":\"0000000000000030\"},{\"account\":\"rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo\",\"currency\":\"USD\",\"issuer\":\"rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo\",\"type\":49,\"type_hex\":\"0000000000000031\"}]]"
-  },
-  "outcome": {
-    "result": "tesSUCCESS",
-    "timestamp": "2013-03-12T23:56:50.000Z",
-    "fee": "0.00001",
-    "deliveredAmount": {
-      "currency": "USD",
-      "value": "0.001",
-      "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM"
-    },
-    "balanceChanges": {
-      "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo": [
-        {
-          "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM",
-          "currency": "USD",
-          "value": "-0.001"
-        },
-        {
-          "counterparty": "r9tGqzZgKxVFvzKFdUqXAqTzazWBUia8Qr",
-          "currency": "USD",
-          "value": "0.001002"
-        }
-      ],
-      "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM": [
-        {
-          "counterparty": "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo",
-          "currency": "USD",
-          "value": "0.001"
-        }
-      ],
-      "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59": [
-        {
-          "currency": "XRP",
-          "value": "-1.101208"
-        }
-      ],
-      "r9tGqzZgKxVFvzKFdUqXAqTzazWBUia8Qr": [
-        {
-          "currency": "XRP",
-          "value": "1.101198"
-        },
-        {
-          "counterparty": "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo",
-          "currency": "USD",
-          "value": "-0.001002"
-        }
-      ]
-    },
-    "orderbookChanges": {
-      "r9tGqzZgKxVFvzKFdUqXAqTzazWBUia8Qr": [
-        {
-          "direction": "buy",
-          "quantity": {
-            "currency": "XRP",
-            "value": "1.101198"
-          },
-          "totalPrice": {
-            "currency": "USD",
-            "counterparty": "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo",
-            "value": "0.001002"
-          },
-          "makerExchangeRate": "1099",
-          "sequence": 58,
-          "status": "partially-filled"
-        }
-      ]
-    },
-    "ledgerVersion": 348860,
-    "indexInLedger": 0
-  }
-}
-
-

getTransactions

-

getTransactions(address: string, options: Object): Promise<Array<Object>>

-

Retrieves historical transactions of an account.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
addressaddressThe address of the account to get transactions for.
optionsobjectOptional Options to filter the resulting transactions.
options. binarybooleanOptional If true, the transactions will be sent from the server in a condensed binary format rather than JSON.
options. counterpartyaddressOptional If provided, only return transactions with this account as a counterparty to the transaction.
options. earliestFirstbooleanOptional If true, sort transactions so that the earliest ones come first. By default, the newest transactions will come first.
options. excludeFailuresbooleanOptional If true, the result will omit transactions that did not succeed.
options. initiatedbooleanOptional If true, return only transactions initiated by the account specified by address. If false, return only transactions not initiated by the account specified by address.
options. limitintegerOptional If specified, return at most this many transactions.
options. maxLedgerVersionintegerOptional Return only transactions in this ledger version or lower.
options. minLedgerVersionintegerOptional Return only transactions in this ledger verion or higher.
options. startstringOptional If specified, this transaction will be the first transaction in the result.
options. typesarray\<transactionType>Optional Only return transactions of the specified Transaction Types.
-

Return Value

-

This method returns a promise that resolves with an array of transaction object in the same format as getTransaction.

-

Example

-
const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
-return api.getTransactions(address).then(transaction => {
-  /* ... */
-});
-
-
[
-  {
-    "type": "payment",
-    "address": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-    "sequence": 4,
-    "id": "99404A34E8170319521223A6C604AF48B9F1E3000C377E6141F9A1BF60B0B865",
-    "specification": {
-      "memos": [
-        {
-          "type": "client",
-          "format": "rt1.5.2"
-        }
-      ],
-      "source": {
-        "address": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-        "maxAmount": {
-          "currency": "XRP",
-          "value": "1.112209"
-        }
-      },
-      "destination": {
-        "address": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM",
-        "amount": {
-          "currency": "USD",
-          "value": "0.001"
-        }
-      },
-      "paths": "[[{\"issuer\":\"rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo\",\"currency\":\"USD\"},{\"account\":\"rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo\",\"issuer\":\"rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo\",\"currency\":\"USD\"}]]"
-    },
-    "outcome": {
-      "result": "tesSUCCESS",
-      "fee": "0.00001",
-      "deliveredAmount": {
-        "currency": "USD",
-        "value": "0.001",
-        "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM"
-      },
-      "balanceChanges": {
-        "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo": [
-          {
-            "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM",
-            "currency": "USD",
-            "value": "-0.001"
-          },
-          {
-            "counterparty": "r9tGqzZgKxVFvzKFdUqXAqTzazWBUia8Qr",
-            "currency": "USD",
-            "value": "0.001002"
-          }
-        ],
-        "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM": [
-          {
-            "counterparty": "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo",
-            "currency": "USD",
-            "value": "0.001"
-          }
-        ],
-        "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59": [
-          {
-            "currency": "XRP",
-            "value": "-1.101208"
-          }
-        ],
-        "r9tGqzZgKxVFvzKFdUqXAqTzazWBUia8Qr": [
-          {
-            "currency": "XRP",
-            "value": "1.101198"
-          },
-          {
-            "counterparty": "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo",
-            "currency": "USD",
-            "value": "-0.001002"
-          }
-        ]
-      },
-      "orderbookChanges": {
-        "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59": [
-          {
-            "direction": "buy",
-            "quantity": {
-              "currency": "XRP",
-              "value": "1.101198"
-            },
-            "totalPrice": {
-              "currency": "USD",
-              "counterparty": "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo",
-              "value": "0.001002"
-            },
-            "makerExchangeRate": "1099",
-            "sequence": 58,
-            "status": "partially-filled"
-          }
-        ]
-      },
-      "ledgerVersion": 348859,
-      "indexInLedger": 0
-    }
-  },
-  {
-    "type": "payment",
-    "address": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-    "id": "99404A34E8170319521223A6C604AF48B9F1E3000C377E6141F9A1BF60B0B865",
-    "sequence": 4,
-    "specification": {
-      "memos": [
-        {
-          "type": "client",
-          "format": "rt1.5.2"
-        }
-      ],
-      "source": {
-        "address": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-        "maxAmount": {
-          "currency": "XRP",
-          "value": "1.112209"
-        }
-      },
-      "destination": {
-        "address": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM",
-        "amount": {
-          "currency": "USD",
-          "value": "0.001"
-        }
-      },
-      "paths": "[[{\"issuer\":\"rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo\",\"currency\":\"USD\"},{\"account\":\"rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo\",\"issuer\":\"rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo\",\"currency\":\"USD\"}]]"
-    },
-    "outcome": {
-      "result": "tesSUCCESS",
-      "fee": "0.00001",
-      "deliveredAmount": {
-        "currency": "USD",
-        "value": "0.001",
-        "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM"
-      },
-      "balanceChanges": {
-        "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo": [
-          {
-            "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM",
-            "currency": "USD",
-            "value": "-0.001"
-          },
-          {
-            "counterparty": "r9tGqzZgKxVFvzKFdUqXAqTzazWBUia8Qr",
-            "currency": "USD",
-            "value": "0.001002"
-          }
-        ],
-        "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM": [
-          {
-            "counterparty": "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo",
-            "currency": "USD",
-            "value": "0.001"
-          }
-        ],
-        "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59": [
-          {
-            "currency": "XRP",
-            "value": "-1.101208"
-          }
-        ],
-        "r9tGqzZgKxVFvzKFdUqXAqTzazWBUia8Qr": [
-          {
-            "currency": "XRP",
-            "value": "1.101198"
-          },
-          {
-            "counterparty": "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo",
-            "currency": "USD",
-            "value": "-0.001002"
-          }
-        ]
-      },
-      "orderbookChanges": {
-        "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59": [
-          {
-            "direction": "buy",
-            "quantity": {
-              "currency": "XRP",
-              "value": "1.101198"
-            },
-            "totalPrice": {
-              "currency": "USD",
-              "counterparty": "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo",
-              "value": "0.001002"
-            },
-            "makerExchangeRate": "1099",
-            "sequence": 58,
-            "status": "partially-filled"
-          }
-        ]
-      },
-      "ledgerVersion": 348858,
-      "indexInLedger": 0
-    }
-  }
-]
-
-

getTrustlines

-

getTrustlines(address: string, options: Object): Promise<Array<Object>>

-

Returns trustlines for a specified account.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
addressaddressThe address of the account to get trustlines for.
optionsobjectOptional Options to filter and determine which trustlines to return.
options. counterpartyaddressOptional Only return trustlines with this counterparty.
options. currencycurrencyOptional Only return trustlines for this currency.
options. ledgerVersionintegerOptional Return trustlines as they were in this historical ledger version.
options. limitintegerOptional Return at most this many trustlines.
-

Return Value

-

This method returns a promise that resolves with an array of objects with the following structure.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
specificationtrustlineA trustline specification that would produce this trustline in its current state.
counterpartyobjectProperties of the trustline from the perspective of the counterparty.
counterparty. limitvalueThe maximum amount that the counterparty can be owed through the trustline.
counterparty. authorizedbooleanOptional If true, the counterparty authorizes this party to hold issuances from the counterparty.
counterparty. frozenbooleanOptional If true, the trustline is frozen, which means that funds can only be sent to the counterparty.
counterparty. ripplingDisabledbooleanOptional If true, payments cannot ripple through this trustline.
stateobjectProperties of the trustline regarding it's current state that are not part of the specification.
state. balancesignedValueThe balance on the trustline, representing which party owes the other and by how much.
-

Example

-
const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
-return api.getTrustlines(address).then(trustlines =>
-  {/* ... */});
-
-
[
-  {
-    "specification": {
-      "limit": "5",
-      "currency": "USD",
-      "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-      "ripplingDisabled": true,
-      "frozen": true
-    },
-    "counterparty": {
-      "limit": "0"
-    },
-    "state": {
-      "balance": "2.497605752725159"
-    }
-  },
-  {
-    "specification": {
-      "limit": "5000",
-      "currency": "USD",
-      "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-    },
-    "counterparty": {
-      "limit": "0"
-    },
-    "state": {
-      "balance": "0"
-    }
-  },
-  {
-    "specification": {
-      "limit": "1",
-      "currency": "USD",
-      "counterparty": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun"
-    },
-    "counterparty": {
-      "limit": "0"
-    },
-    "state": {
-      "balance": "1"
-    }
-  },
-  {
-    "specification": {
-      "limit": "1",
-      "currency": "USD",
-      "counterparty": "r9vbV3EHvXWjSkeQ6CAcYVPGeq7TuiXY2X",
-      "ripplingDisabled": true
-    },
-    "counterparty": {
-      "limit": "0"
-    },
-    "state": {
-      "balance": "0"
-    }
-  },
-  {
-    "specification": {
-      "limit": "500",
-      "currency": "USD",
-      "counterparty": "rfF3PNkwkq1DygW2wum2HK3RGfgkJjdPVD",
-      "ripplingDisabled": true
-    },
-    "counterparty": {
-      "limit": "0"
-    },
-    "state": {
-      "balance": "35"
-    }
-  },
-  {
-    "specification": {
-      "limit": "0",
-      "currency": "USD",
-      "counterparty": "rE6R3DWF9fBD7CyiQciePF9SqK58Ubp8o2"
-    },
-    "counterparty": {
-      "limit": "100",
-      "ripplingDisabled": true
-    },
-    "state": {
-      "balance": "0"
-    }
-  },
-  {
-    "specification": {
-      "limit": "0",
-      "currency": "USD",
-      "counterparty": "rEhDDUUNxpXgEHVJtC2cjXAgyx5VCFxdMF",
-      "frozen": true
-    },
-    "counterparty": {
-      "limit": "1"
-    },
-    "state": {
-      "balance": "0"
-    }
-  }
-]
-
-

getBalances

-

getBalances(address: string, options: Object): Promise<Array<Object>>

-

Returns balances for a specified account.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
addressaddressThe address of the account to get balances for.
optionsobjectOptional Options to filter and determine which balances to return.
options. counterpartyaddressOptional Only return balances with this counterparty.
options. currencycurrencyOptional Only return balances for this currency.
options. ledgerVersionintegerOptional Return balances as they were in this historical ledger version.
options. limitintegerOptional Return at most this many balances.
-

Return Value

-

This method returns a promise that resolves with an array of objects with the following structure:

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
currencycurrencyThe three-character code or hexadecimal string used to denote currencies
valuesignedValueThe balance on the trustline
counterpartyaddressOptional The Ripple address of the account that owes or is owed the funds.
-

Example

-
const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
-return api.getBalances(address).then(balances =>
-  {/* ... */});
-
-
[
-  {
-    "value": "922.913243",
-    "currency": "XRP"
-  },
-  {
-    "value": "0",
-    "currency": "ASP",
-    "counterparty": "r3vi7mWxru9rJCxETCyA1CHvzL96eZWx5z"
-  },
-  {
-    "value": "0",
-    "currency": "XAU",
-    "counterparty": "r3vi7mWxru9rJCxETCyA1CHvzL96eZWx5z"
-  },
-  {
-    "value": "2.497605752725159",
-    "currency": "USD",
-    "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q"
-  },
-  {
-    "value": "481.992867407479",
-    "currency": "MXN",
-    "counterparty": "rHpXfibHgSb64n8kK9QWDpdbfqSpYbM9a4"
-  },
-  {
-    "value": "0.793598266778297",
-    "currency": "EUR",
-    "counterparty": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun"
-  },
-  {
-    "value": "0",
-    "currency": "CNY",
-    "counterparty": "rnuF96W4SZoCJmbHYBFoJZpR8eCaxNvekK"
-  },
-  {
-    "value": "1.294889190631542",
-    "currency": "DYM",
-    "counterparty": "rGwUWgN5BEg3QGNY3RX2HfYowjUTZdid3E"
-  },
-  {
-    "value": "0.3488146605801446",
-    "currency": "CHF",
-    "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-  },
-  {
-    "value": "2.114103174931847",
-    "currency": "BTC",
-    "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-  },
-  {
-    "value": "0",
-    "currency": "USD",
-    "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-  },
-  {
-    "value": "-0.00111",
-    "currency": "BTC",
-    "counterparty": "rpgKWEmNqSDAGFhy5WDnsyPqfQxbWxKeVd"
-  },
-  {
-    "value": "-0.1010780000080207",
-    "currency": "BTC",
-    "counterparty": "rBJ3YjwXi2MGbg7GVLuTXUWQ8DjL7tDXh4"
-  },
-  {
-    "value": "1",
-    "currency": "USD",
-    "counterparty": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun"
-  },
-  {
-    "value": "8.07619790068559",
-    "currency": "CNY",
-    "counterparty": "razqQKzJRdB4UxFPWf5NEpEG3WMkmwgcXA"
-  },
-  {
-    "value": "7.292695098901099",
-    "currency": "JPY",
-    "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-  },
-  {
-    "value": "0",
-    "currency": "AUX",
-    "counterparty": "r3vi7mWxru9rJCxETCyA1CHvzL96eZWx5z"
-  },
-  {
-    "value": "0",
-    "currency": "USD",
-    "counterparty": "r9vbV3EHvXWjSkeQ6CAcYVPGeq7TuiXY2X"
-  },
-  {
-    "value": "12.41688780720394",
-    "currency": "EUR",
-    "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-  },
-  {
-    "value": "35",
-    "currency": "USD",
-    "counterparty": "rfF3PNkwkq1DygW2wum2HK3RGfgkJjdPVD"
-  },
-  {
-    "value": "-5",
-    "currency": "JOE",
-    "counterparty": "rwUVoVMSURqNyvocPCcvLu3ygJzZyw8qwp"
-  },
-  {
-    "value": "0",
-    "currency": "USD",
-    "counterparty": "rE6R3DWF9fBD7CyiQciePF9SqK58Ubp8o2"
-  },
-  {
-    "value": "0",
-    "currency": "JOE",
-    "counterparty": "rE6R3DWF9fBD7CyiQciePF9SqK58Ubp8o2"
-  },
-  {
-    "value": "0",
-    "currency": "015841551A748AD2C1F76FF6ECB0CCCD00000000",
-    "counterparty": "rs9M85karFkCRjvc6KMWn8Coigm9cbcgcx"
-  },
-  {
-    "value": "0",
-    "currency": "USD",
-    "counterparty": "rEhDDUUNxpXgEHVJtC2cjXAgyx5VCFxdMF"
-  }
-]
-
-

getBalanceSheet

-

getBalanceSheet(address: string, options: Object): Promise<Object>

-

Returns aggregate balances by currency plus a breakdown of assets and obligations for a specified account.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
addressaddressThe Ripple address of the account to get the balance sheet of.
optionsobjectOptional Options to determine how the balances will be calculated.
options. excludeAddressesarray\<address>Optional Addresses to exclude from the balance totals.
options. ledgerVersionintegerOptional Get the balance sheet as of this historical ledger version.
-

Return Value

-

This method returns a promise that resolves with an object with the following structure:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
assetsarray\<amount>Optional Total amounts held that are issued by others. For the recommended gateway configuration, there should be none.
balancesarray\<amount>Optional Amounts issued to the hotwallet accounts from the request. The keys are hot wallet addresses and the values are arrays of currency amounts they hold. The issuer (omitted from the currency amounts) is the account from the request.
obligationsarrayOptional Total amounts issued to accounts that are not hot wallets, as a map of currencies to the total value issued.
obligations[]objectAn amount that is owed.
obligations[]. currencycurrencyThe three-character code or hexadecimal string used to denote currencies
obligations[]. valuevalueA string representation of a non-negative floating point number
-

Example

-
const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
-return api.getBalanceSheet(address).then(balanceSheet =>
-  {/* ... */});
-
-
{
-  "balances": [
-    {
-    "counterparty": "rKm4uWpg9tfwbVSeATv4KxDe6mpE9yPkgJ",
-    "currency": "EUR",
-    "value": "29826.1965999999"
-  },
-  {
-    "counterparty": "rKm4uWpg9tfwbVSeATv4KxDe6mpE9yPkgJ",
-    "currency": "USD",
-    "value": "10.0"
-  },
-  {
-    "counterparty": "ra7JkEzrgeKHdzKgo4EUUVBnxggY4z37kt",
-    "currency": "USD",
-    "value": "13857.70416"
-  }
-  ],
-  "assets": [
-    {
-    "counterparty": "r9F6wk8HkXrgYWoJ7fsv4VrUBVoqDVtzkH",
-    "currency": "BTC",
-    "value": "5444166510000000e-26"
-  },
-  {
-    "counterparty": "r9F6wk8HkXrgYWoJ7fsv4VrUBVoqDVtzkH",
-    "currency": "USD",
-    "value": "100.0"
-  },
-  {
-    "counterparty": "rwmUaXsWtXU4Z843xSYwgt1is97bgY8yj6",
-    "currency": "BTC",
-    "value": "8700000000000000e-30"
-  }
-  ],
-  "obligations": [
-    {
-      "currency": "BTC",
-      "value": "5908.324927635318"
-    },
-    {
-      "currency": "EUR",
-      "value": "992471.7419793958"
-    },
-    {
-      "currency": "GBP",
-      "value": "4991.38706013193"
-    },
-    {
-      "currency": "USD",
-      "value": "1997134.20229482"
-    }
-  ]
-}
-
-

getPaths

-

getPaths(pathfind: Object): Promise<Array<Object>>

-

Finds paths to send a payment. Paths are options for how to route a payment.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
pathfindobjectSpecification of a pathfind request.
pathfind. sourceobjectProperties of the source of funds.
pathfind.source. addressaddressThe Ripple address of the account where funds will come from.
pathfind.source. amountlaxAmountOptional The amount of funds to send.
pathfind.source. currenciesarrayOptional An array of currencies (with optional counterparty) that may be used in the payment paths.
pathfind.source. currencies[]objectA currency with optional counterparty.
pathfind.source.currencies[]. currencycurrencyThe three-character code or hexadecimal string used to denote currencies
pathfind.source.currencies[]. counterpartyaddressOptional The counterparty for the currency; if omitted any counterparty may be used.
pathfind. destinationobjectProperties of the destination of funds.
pathfind.destination. addressaddressThe address to send to.
pathfind.destination. amountlaxLaxAmountThe amount to be received by the receiver (value may be ommitted if a source amount is specified).
-

Return Value

-

This method returns a promise that resolves with an array of objects with the following structure:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
sourceobjectProperties of the source of the payment.
source. addressaddressThe address to send from.
source. amountlaxAmountAn exact amount to send. If the counterparty is not specified, amounts with any counterparty may be used. (This field is exclusive with source.maxAmount)
source. tagintegerOptional An arbitrary unsigned 32-bit integer that identifies a reason for payment or a non-Ripple account.
source. maxAmountlaxAmountThe maximum amount to send. (This field is exclusive with source.amount)
destinationobjectProperties of the destination of the payment.
destination. addressaddressThe address to receive at.
destination. amountlaxAmountAn exact amount to deliver to the recipient. If the counterparty is not specified, amounts with any counterparty may be used. (This field is exclusive with destination.minAmount).
destination. tagintegerOptional An arbitrary unsigned 32-bit integer that identifies a reason for payment or a non-Ripple account.
destination. addressaddressThe address to send to.
destination. minAmountlaxAmountThe minimum amount to be delivered. (This field is exclusive with destination.amount)
pathsstringThe paths of trustlines and orders to use in executing the payment.
-

Example

-
const pathfind = {
-  "source": {
-    "address": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59"
-  },
-  "destination": {
-    "address": "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo",
-    "amount": {
-      "currency": "USD",
-      "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM",
-      "value": "100"
-    }
-  }
-};
-return api.getPaths(pathfind)
-  .then(paths => {/* ... */});
-
-
[
-  {
-    "source": {
-      "address": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-      "maxAmount": {
-        "currency": "JPY",
-        "value": "0.1117218827811721"
-      }
-    },
-    "destination": {
-      "address": "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo",
-      "amount": {
-        "currency": "USD",
-        "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM",
-        "value": "100"
-      }
-    },
-    "paths": "[[{\"account\":\"rMAz5ZnK73nyNUL4foAvaxdreczCkG3vA6\"},{\"currency\":\"USD\",\"issuer\":\"rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM\"},{\"account\":\"rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM\"}],[{\"account\":\"rMAz5ZnK73nyNUL4foAvaxdreczCkG3vA6\"},{\"currency\":\"XRP\"},{\"currency\":\"USD\",\"issuer\":\"rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM\"},{\"account\":\"rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM\"}],[{\"account\":\"rMAz5ZnK73nyNUL4foAvaxdreczCkG3vA6\"},{\"currency\":\"XRP\"},{\"currency\":\"USD\",\"issuer\":\"rpHgehzdpfWRXKvSv6duKvVuo1aZVimdaT\"},{\"account\":\"rpHgehzdpfWRXKvSv6duKvVuo1aZVimdaT\"},{\"account\":\"rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM\"}],[{\"account\":\"rMAz5ZnK73nyNUL4foAvaxdreczCkG3vA6\"},{\"currency\":\"XRP\"},{\"currency\":\"USD\",\"issuer\":\"rHHa9t2kLQyXRbdLkSzEgkzwf9unmFgZs9\"},{\"account\":\"rHHa9t2kLQyXRbdLkSzEgkzwf9unmFgZs9\"},{\"account\":\"rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM\"}]]"
-  },
-  {
-    "source": {
-      "address": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-      "maxAmount": {
-        "currency": "USD",
-        "value": "0.001002"
-      }
-    },
-    "destination": {
-      "address": "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo",
-      "amount": {
-        "currency": "USD",
-        "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM",
-        "value": "100"
-      }
-    },
-    "paths": "[[{\"account\":\"rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM\"}],[{\"account\":\"rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q\"},{\"currency\":\"USD\",\"issuer\":\"rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM\"},{\"account\":\"rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM\"}],[{\"account\":\"rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q\"},{\"currency\":\"XRP\"},{\"currency\":\"USD\",\"issuer\":\"rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM\"},{\"account\":\"rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM\"}],[{\"account\":\"rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q\"},{\"currency\":\"XRP\"},{\"currency\":\"USD\",\"issuer\":\"rpHgehzdpfWRXKvSv6duKvVuo1aZVimdaT\"},{\"account\":\"rpHgehzdpfWRXKvSv6duKvVuo1aZVimdaT\"},{\"account\":\"rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM\"}]]"
-  },
-  {
-    "source": {
-      "address": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-      "maxAmount": {
-        "currency": "XRP",
-        "value": "0.207669"
-      }
-    },
-    "destination": {
-      "address": "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo",
-      "amount": {
-        "currency": "USD",
-        "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM",
-        "value": "100"
-      }
-    },
-    "paths": "[[{\"currency\":\"USD\",\"issuer\":\"rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM\"},{\"account\":\"rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM\"}],[{\"currency\":\"USD\",\"issuer\":\"rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc\"},{\"account\":\"rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc\"},{\"account\":\"rf9X8QoYnWLHMHuDfjkmRcD2UE5qX5aYV\"},{\"account\":\"rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM\"}],[{\"currency\":\"USD\",\"issuer\":\"rDVdJ62foD1sn7ZpxtXyptdkBSyhsQGviT\"},{\"account\":\"rDVdJ62foD1sn7ZpxtXyptdkBSyhsQGviT\"},{\"account\":\"rfQPFZ3eLcaSUKjUy7A3LAmDNM4F9Hz9j1\"},{\"account\":\"rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM\"}],[{\"currency\":\"USD\",\"issuer\":\"rpHgehzdpfWRXKvSv6duKvVuo1aZVimdaT\"},{\"account\":\"rpHgehzdpfWRXKvSv6duKvVuo1aZVimdaT\"},{\"account\":\"rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM\"}]]"
-  }
-]
-
-

getOrders

-

getOrders(address: string, options: Object): Promise<Array<Object>>

-

Returns open orders for the specified account. Open orders are orders that have not yet been fully executed and are still in the order book.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
addressaddressThe Ripple address of the account to get open orders for.
optionsobjectOptional Options that determine what orders will be returned.
options. ledgerVersionintegerOptional Return orders as of this historical ledger version.
options. limitintegerOptional At most this many orders will be returned.
-

Return Value

-

This method returns a promise that resolves with an array of objects with the following structure:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
specificationorderAn order specification that would create an order equivalent to the current state of this order.
propertiesobjectProperties of the order not in the specification.
properties. makeraddressThe address of the account that submitted the order.
properties. sequencesequenceThe account sequence number of the transaction that created this order.
properties. makerExchangeRatevalueThe exchange rate from the point of view of the account that submitted the order (also known as "quality").
-

Example

-
const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
-return api.getOrders(address).then(orders =>
-  {/* ... */});
-
-
[
-  {
-    "specification": {
-      "direction": "sell",
-      "quantity": {
-        "currency": "EUR",
-        "value": "17.70155237781915",
-        "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q"
-      },
-      "totalPrice": {
-        "currency": "USD",
-        "value": "1122.990930900328",
-        "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q"
-      }
-    },
-    "properties": {
-      "maker": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-      "sequence": 719930,
-      "makerExchangeRate": "63.44025128030504"
-    }
-  },
-  {
-    "specification": {
-      "direction": "buy",
-      "quantity": {
-        "currency": "EUR",
-        "value": "750",
-        "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q"
-      },
-      "totalPrice": {
-        "currency": "USD",
-        "value": "19.11697137482289",
-        "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q"
-      }
-    },
-    "properties": {
-      "maker": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-      "sequence": 756999,
-      "makerExchangeRate": "39.23215583132338"
-    }
-  },
-  {
-    "specification": {
-      "direction": "buy",
-      "quantity": {
-        "currency": "USD",
-        "value": "19.50899530491766",
-        "counterparty": "rpDMez6pm6dBve2TJsmDpv7Yae6V5Pyvy2"
-      },
-      "totalPrice": {
-        "currency": "USD",
-        "value": "18.46856867857617",
-        "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q"
-      }
-    },
-    "properties": {
-      "maker": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-      "sequence": 757002,
-      "makerExchangeRate": "1.056334989703257"
-    }
-  },
-  {
-    "specification": {
-      "direction": "buy",
-      "quantity": {
-        "currency": "USD",
-        "value": "1445.796633544794",
-        "counterparty": "rpDMez6pm6dBve2TJsmDpv7Yae6V5Pyvy2"
-      },
-      "totalPrice": {
-        "currency": "USD",
-        "value": "14.40727807030772",
-        "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q"
-      }
-    },
-    "properties": {
-      "maker": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-      "sequence": 757003,
-      "makerExchangeRate": "100.3518240218094"
-    }
-  },
-  {
-    "specification": {
-      "direction": "buy",
-      "quantity": {
-        "currency": "USD",
-        "value": "750",
-        "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q"
-      },
-      "totalPrice": {
-        "currency": "NZD",
-        "value": "9.178557969538755",
-        "counterparty": "rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc"
-      }
-    },
-    "properties": {
-      "maker": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-      "sequence": 782148,
-      "makerExchangeRate": "81.7121820757743"
-    }
-  },
-  {
-    "specification": {
-      "direction": "buy",
-      "quantity": {
-        "currency": "USD",
-        "value": "500",
-        "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-      },
-      "totalPrice": {
-        "currency": "USD",
-        "value": "9.94768291869523",
-        "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q"
-      }
-    },
-    "properties": {
-      "maker": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-      "sequence": 787368,
-      "makerExchangeRate": "50.26296114247091"
-    }
-  },
-  {
-    "specification": {
-      "direction": "buy",
-      "quantity": {
-        "currency": "USD",
-        "value": "10000",
-        "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-      },
-      "totalPrice": {
-        "currency": "USD",
-        "value": "9.994805759894176",
-        "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q"
-      }
-    },
-    "properties": {
-      "maker": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-      "sequence": 787408,
-      "makerExchangeRate": "1000.519693952099"
-    }
-  },
-  {
-    "specification": {
-      "direction": "buy",
-      "quantity": {
-        "currency": "MXN",
-        "value": "15834.53653918684",
-        "counterparty": "rG6FZ31hDHN1K5Dkbma3PSB5uVCuVVRzfn"
-      },
-      "totalPrice": {
-        "currency": "USD",
-        "value": "11.67691646304319",
-        "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q"
-      }
-    },
-    "properties": {
-      "maker": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-      "sequence": 803438,
-      "makerExchangeRate": "1356.054621894598"
-    }
-  },
-  {
-    "specification": {
-      "direction": "buy",
-      "quantity": {
-        "currency": "USD",
-        "value": "3968.240250979598",
-        "counterparty": "r9Dr5xwkeLegBeXq6ujinjSBLQzQ1zQGjH"
-      },
-      "totalPrice": {
-        "currency": "XAU",
-        "value": "0.03206299605333101",
-        "counterparty": "r9Dr5xwkeLegBeXq6ujinjSBLQzQ1zQGjH"
-      }
-    },
-    "properties": {
-      "maker": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-      "sequence": 807858,
-      "makerExchangeRate": "123763.8630020459"
-    }
-  },
-  {
-    "specification": {
-      "direction": "buy",
-      "quantity": {
-        "currency": "USD",
-        "value": "4139.022125516302",
-        "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-      },
-      "totalPrice": {
-        "currency": "XAU",
-        "value": "0.03347459066593226",
-        "counterparty": "r9Dr5xwkeLegBeXq6ujinjSBLQzQ1zQGjH"
-      }
-    },
-    "properties": {
-      "maker": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-      "sequence": 807896,
-      "makerExchangeRate": "123646.6837435794"
-    }
-  },
-  {
-    "specification": {
-      "direction": "buy",
-      "quantity": {
-        "currency": "XRP",
-        "value": "115760.19"
-      },
-      "totalPrice": {
-        "currency": "NZD",
-        "value": "6.840555705",
-        "counterparty": "rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc"
-      }
-    },
-    "properties": {
-      "maker": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-      "sequence": 814018,
-      "makerExchangeRate": "16922.62953364839"
-    }
-  },
-  {
-    "specification": {
-      "direction": "buy",
-      "quantity": {
-        "currency": "USD",
-        "value": "902.4050961259154",
-        "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-      },
-      "totalPrice": {
-        "currency": "EUR",
-        "value": "14.40843766044656",
-        "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q"
-      }
-    },
-    "properties": {
-      "maker": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-      "sequence": 827522,
-      "makerExchangeRate": "62.63032241192674"
-    }
-  },
-  {
-    "specification": {
-      "direction": "buy",
-      "quantity": {
-        "currency": "USD",
-        "value": "181.4887131319798",
-        "counterparty": "r9Dr5xwkeLegBeXq6ujinjSBLQzQ1zQGjH"
-      },
-      "totalPrice": {
-        "currency": "XAG",
-        "value": "1.128432823485989",
-        "counterparty": "r9Dr5xwkeLegBeXq6ujinjSBLQzQ1zQGjH"
-      }
-    },
-    "properties": {
-      "maker": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-      "sequence": 833591,
-      "makerExchangeRate": "160.8325363767064"
-    }
-  },
-  {
-    "specification": {
-      "direction": "buy",
-      "quantity": {
-        "currency": "USD",
-        "value": "1814.887131319799",
-        "counterparty": "r9Dr5xwkeLegBeXq6ujinjSBLQzQ1zQGjH"
-      },
-      "totalPrice": {
-        "currency": "XAG",
-        "value": "1.128432823485991",
-        "counterparty": "r9Dr5xwkeLegBeXq6ujinjSBLQzQ1zQGjH"
-      }
-    },
-    "properties": {
-      "maker": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-      "sequence": 833592,
-      "makerExchangeRate": "1608.325363767062"
-    }
-  },
-  {
-    "specification": {
-      "direction": "buy",
-      "quantity": {
-        "currency": "USD",
-        "value": "118.6872603846736",
-        "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-      },
-      "totalPrice": {
-        "currency": "XAG",
-        "value": "0.7283371225235964",
-        "counterparty": "r9Dr5xwkeLegBeXq6ujinjSBLQzQ1zQGjH"
-      }
-    },
-    "properties": {
-      "maker": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-      "sequence": 838954,
-      "makerExchangeRate": "162.9564891233845"
-    }
-  },
-  {
-    "specification": {
-      "direction": "buy",
-      "quantity": {
-        "currency": "XAU",
-        "value": "1",
-        "counterparty": "r9Dr5xwkeLegBeXq6ujinjSBLQzQ1zQGjH"
-      },
-      "totalPrice": {
-        "currency": "XRP",
-        "value": "2229.229447"
-      }
-    },
-    "properties": {
-      "maker": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-      "sequence": 843730,
-      "makerExchangeRate": "0.0004485854972648762"
-    }
-  },
-  {
-    "specification": {
-      "direction": "buy",
-      "quantity": {
-        "currency": "EUR",
-        "value": "750",
-        "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q"
-      },
-      "totalPrice": {
-        "currency": "USD",
-        "value": "17.77537376072202",
-        "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-      }
-    },
-    "properties": {
-      "maker": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-      "sequence": 844068,
-      "makerExchangeRate": "42.19320561670911"
-    }
-  }
-]
-
-

getOrderbook

-

getOrderbook(address: string, orderbook: Object, options: Object): Promise<Object>

-

Returns open orders for the specified account. Open orders are orders that have not yet been fully executed and are still in the order book.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
addressaddressAddress of an account to use as point-of-view. (This affects which unfunded offers are returned.)
orderbookobjectThe order book to get.
orderbook. baseobjectA currency-counterparty pair, or just currency if it's XRP
orderbook. counterobjectA currency-counterparty pair, or just currency if it's XRP
optionsobjectOptional Options to determine what to return.
options. ledgerVersionintegerOptional Return the order book as of this historical ledger version.
options. limitintegerOptional Return at most this many orders from the order book.
-

Return Value

-

This method returns a promise that resolves with an object with the following structure (Note: the structures of bids and asks are identical):

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
bidsarrayThe buy orders in the order book.
bids[]objectAn order in the order book.
bids[]. specificationorderAn order specification that would create an order equivalent to the current state of this order.
bids[]. propertiesobjectProperties of the order not in the specification.
bids[].properties. makeraddressThe address of the account that submitted the order.
bids[].properties. sequencesequenceThe account sequence number of the transaction that created this order.
bids[].properties. makerExchangeRatevalueThe exchange rate from the point of view of the account that submitted the order (also known as "quality").
bids[]. stateobjectOptional The state of the order.
bids[].state. fundedAmountamountHow much of the amount the maker would have to pay that the maker currently holds.
bids[].state. priceOfFundedAmountamountHow much the fundedAmount would convert to through the exchange rate of this order.
asksarrayThe sell orders in the order book.
asks[]objectAn order in the order book.
asks[]. specificationorderAn order specification that would create an order equivalent to the current state of this order.
asks[]. propertiesobjectProperties of the order not in the specification.
asks[].properties. makeraddressThe address of the account that submitted the order.
asks[].properties. sequencesequenceThe account sequence number of the transaction that created this order.
asks[].properties. makerExchangeRatevalueThe exchange rate from the point of view of the account that submitted the order (also known as "quality").
asks[]. stateobjectOptional The state of the order.
asks[].state. fundedAmountamountHow much of the amount the maker would have to pay that the maker currently holds.
asks[].state. priceOfFundedAmountamountHow much the fundedAmount would convert to through the exchange rate of this order.
-

Example

-
const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
-const orderbook = {
-  "base": {
-    "currency": "USD",
-    "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-  },
-  "counter": {
-    "currency": "BTC",
-    "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-  }
-};
-return api.getOrderbook(address, orderbook)
-  .then(orderbook => {/* ... */});
-
-
{
-  "bids": [
-    {
-      "specification": {
-        "direction": "buy",
-        "quantity": {
-          "currency": "USD",
-          "value": "93.030522464522",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "totalPrice": {
-          "currency": "BTC",
-          "value": "0.2849323720855092",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        }
-      },
-      "properties": {
-        "maker": "rwBYyfufTzk77zUSKEu4MvixfarC35av1J",
-        "sequence": 386940,
-        "makerExchangeRate": "326.5003614141928"
-      }
-    },
-    {
-      "specification": {
-        "direction": "buy",
-        "quantity": {
-          "currency": "USD",
-          "value": "1",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "totalPrice": {
-          "currency": "BTC",
-          "value": "0.00302447007930511",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        }
-      },
-      "properties": {
-        "maker": "rwjsRktX1eguUr1pHTffyHnC4uyrvX58V1",
-        "sequence": 207855,
-        "makerExchangeRate": "330.6364334177034"
-      }
-    },
-    {
-      "specification": {
-        "direction": "buy",
-        "quantity": {
-          "currency": "USD",
-          "value": "99.34014894048333",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "totalPrice": {
-          "currency": "BTC",
-          "value": "0.3",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "expirationTime": "2014-12-25T01:14:43.000Z"
-      },
-      "properties": {
-        "maker": "raudnGKfTK23YKfnS7ixejHrqGERTYNFXk",
-        "sequence": 110103,
-        "makerExchangeRate": "331.1338298016111"
-      }
-    },
-    {
-      "specification": {
-        "direction": "buy",
-        "quantity": {
-          "currency": "USD",
-          "value": "268.754",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "totalPrice": {
-          "currency": "BTC",
-          "value": "0.8095",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        }
-      },
-      "properties": {
-        "maker": "rPyYxUGK8L4dgEvjPs3aRc1B1jEiLr3Hx5",
-        "sequence": 392,
-        "makerExchangeRate": "332"
-      },
-      "state": {
-        "fundedAmount": {
-          "currency": "BTC",
-          "value": "0.8078974385735969",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "priceOfFundedAmount": {
-          "currency": "USD",
-          "value": "268.2219496064341",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        }
-      }
-    },
-    {
-      "specification": {
-        "direction": "buy",
-        "quantity": {
-          "currency": "USD",
-          "value": "152.0098333185607",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "totalPrice": {
-          "currency": "BTC",
-          "value": "0.4499999999999999",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "expirationTime": "2014-12-25T01:14:44.000Z"
-      },
-      "properties": {
-        "maker": "raudnGKfTK23YKfnS7ixejHrqGERTYNFXk",
-        "sequence": 110105,
-        "makerExchangeRate": "337.7996295968016"
-      }
-    },
-    {
-      "specification": {
-        "direction": "buy",
-        "quantity": {
-          "currency": "USD",
-          "value": "1.308365894430151",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "totalPrice": {
-          "currency": "BTC",
-          "value": "0.003768001830745216",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        }
-      },
-      "properties": {
-        "maker": "rDbsCJr5m8gHDCNEHCZtFxcXHsD4S9jH83",
-        "sequence": 110061,
-        "makerExchangeRate": "347.2306949944844"
-      }
-    },
-    {
-      "specification": {
-        "direction": "buy",
-        "quantity": {
-          "currency": "USD",
-          "value": "176.3546101589987",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "totalPrice": {
-          "currency": "BTC",
-          "value": "0.5",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "expirationTime": "2014-12-25T00:41:38.000Z"
-      },
-      "properties": {
-        "maker": "rDVBvAQScXrGRGnzrxRrcJPeNLeLeUTAqE",
-        "sequence": 35788,
-        "makerExchangeRate": "352.7092203179974"
-      }
-    },
-    {
-      "specification": {
-        "direction": "buy",
-        "quantity": {
-          "currency": "USD",
-          "value": "179.48",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "totalPrice": {
-          "currency": "BTC",
-          "value": "0.5",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        }
-      },
-      "properties": {
-        "maker": "rN6jbxx4H6NxcnmkzBxQnbCWLECNKrgSSf",
-        "sequence": 491,
-        "makerExchangeRate": "358.96"
-      },
-      "state": {
-        "fundedAmount": {
-          "currency": "BTC",
-          "value": "0.499001996007984",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "priceOfFundedAmount": {
-          "currency": "USD",
-          "value": "179.1217564870259",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        }
-      }
-    },
-    {
-      "specification": {
-        "direction": "buy",
-        "quantity": {
-          "currency": "USD",
-          "value": "288.7710263794967",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "totalPrice": {
-          "currency": "BTC",
-          "value": "0.8",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "expirationTime": "2014-12-25T00:41:39.000Z"
-      },
-      "properties": {
-        "maker": "rDVBvAQScXrGRGnzrxRrcJPeNLeLeUTAqE",
-        "sequence": 35789,
-        "makerExchangeRate": "360.9637829743709"
-      }
-    },
-    {
-      "specification": {
-        "direction": "buy",
-        "quantity": {
-          "currency": "USD",
-          "value": "182.9814890090516",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "totalPrice": {
-          "currency": "BTC",
-          "value": "0.5",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        }
-      },
-      "properties": {
-        "maker": "rUeCeioKJkbYhv4mRGuAbZpPcqkMCoYq6N",
-        "sequence": 5255,
-        "makerExchangeRate": "365.9629780181032"
-      },
-      "state": {
-        "fundedAmount": {
-          "currency": "BTC",
-          "value": "0.2254411038203033",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "priceOfFundedAmount": {
-          "currency": "USD",
-          "value": "82.50309772176658",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        }
-      }
-    }
-  ],
-  "asks": [
-    {
-      "specification": {
-        "direction": "sell",
-        "quantity": {
-          "currency": "USD",
-          "value": "3205.1",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "totalPrice": {
-          "currency": "BTC",
-          "value": "10",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        }
-      },
-      "properties": {
-        "maker": "r49y2xKuKVG2dPkNHgWQAV61cjxk8gryjQ",
-        "sequence": 434,
-        "makerExchangeRate": "0.003120027456241615"
-      }
-    },
-    {
-      "specification": {
-        "direction": "sell",
-        "quantity": {
-          "currency": "USD",
-          "value": "1599.063669386278",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "totalPrice": {
-          "currency": "BTC",
-          "value": "4.99707396683212",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        }
-      },
-      "properties": {
-        "maker": "rDYCRhpahKEhCFV25xScg67Bwf4W9sTYAm",
-        "sequence": 233,
-        "makerExchangeRate": "0.003125"
-      }
-    },
-    {
-      "specification": {
-        "direction": "sell",
-        "quantity": {
-          "currency": "USD",
-          "value": "143.1050962074379",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "totalPrice": {
-          "currency": "BTC",
-          "value": "0.4499999999999999",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "expirationTime": "2014-12-25T01:14:44.000Z"
-      },
-      "properties": {
-        "maker": "raudnGKfTK23YKfnS7ixejHrqGERTYNFXk",
-        "sequence": 110104,
-        "makerExchangeRate": "0.003144542101755081"
-      },
-      "state": {
-        "fundedAmount": {
-          "currency": "USD",
-          "value": "0",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "priceOfFundedAmount": {
-          "currency": "BTC",
-          "value": "0",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        }
-      }
-    },
-    {
-      "specification": {
-        "direction": "sell",
-        "quantity": {
-          "currency": "USD",
-          "value": "254.329207354604",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "totalPrice": {
-          "currency": "BTC",
-          "value": "0.8",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "expirationTime": "2014-12-24T21:44:11.000Z"
-      },
-      "properties": {
-        "maker": "rDVBvAQScXrGRGnzrxRrcJPeNLeLeUTAqE",
-        "sequence": 35625,
-        "makerExchangeRate": "0.003145529403882357"
-      },
-      "state": {
-        "fundedAmount": {
-          "currency": "USD",
-          "value": "0",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "priceOfFundedAmount": {
-          "currency": "BTC",
-          "value": "0",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        }
-      }
-    },
-    {
-      "specification": {
-        "direction": "sell",
-        "quantity": {
-          "currency": "USD",
-          "value": "390.4979",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "totalPrice": {
-          "currency": "BTC",
-          "value": "1.23231134568807",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        }
-      },
-      "properties": {
-        "maker": "rwBYyfufTzk77zUSKEu4MvixfarC35av1J",
-        "sequence": 387756,
-        "makerExchangeRate": "0.003155743848271834"
-      }
-    },
-    {
-      "specification": {
-        "direction": "sell",
-        "quantity": {
-          "currency": "USD",
-          "value": "1",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "totalPrice": {
-          "currency": "BTC",
-          "value": "0.003160328237957649",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        }
-      },
-      "properties": {
-        "maker": "rwjsRktX1eguUr1pHTffyHnC4uyrvX58V1",
-        "sequence": 208927,
-        "makerExchangeRate": "0.003160328237957649"
-      }
-    },
-    {
-      "specification": {
-        "direction": "sell",
-        "quantity": {
-          "currency": "USD",
-          "value": "4725",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "totalPrice": {
-          "currency": "BTC",
-          "value": "15",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        }
-      },
-      "properties": {
-        "maker": "r49y2xKuKVG2dPkNHgWQAV61cjxk8gryjQ",
-        "sequence": 429,
-        "makerExchangeRate": "0.003174603174603175"
-      }
-    },
-    {
-      "specification": {
-        "direction": "sell",
-        "quantity": {
-          "currency": "USD",
-          "value": "1.24252537879871",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "totalPrice": {
-          "currency": "BTC",
-          "value": "0.003967400879423823",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        }
-      },
-      "properties": {
-        "maker": "rDbsCJr5m8gHDCNEHCZtFxcXHsD4S9jH83",
-        "sequence": 110099,
-        "makerExchangeRate": "0.003193013959408667"
-      }
-    },
-    {
-      "specification": {
-        "direction": "sell",
-        "quantity": {
-          "currency": "USD",
-          "value": "496.5429474010489",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "totalPrice": {
-          "currency": "BTC",
-          "value": "1.6",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "expirationTime": "2014-12-24T21:44:12.000Z"
-      },
-      "properties": {
-        "maker": "rDVBvAQScXrGRGnzrxRrcJPeNLeLeUTAqE",
-        "sequence": 35627,
-        "makerExchangeRate": "0.003222279177208227"
-      },
-      "state": {
-        "fundedAmount": {
-          "currency": "USD",
-          "value": "0",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "priceOfFundedAmount": {
-          "currency": "BTC",
-          "value": "0",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        }
-      }
-    },
-    {
-      "specification": {
-        "direction": "sell",
-        "quantity": {
-          "currency": "USD",
-          "value": "3103",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        },
-        "totalPrice": {
-          "currency": "BTC",
-          "value": "10",
-          "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-        }
-      },
-      "properties": {
-        "maker": "r49y2xKuKVG2dPkNHgWQAV61cjxk8gryjQ",
-        "sequence": 431,
-        "makerExchangeRate": "0.003222687721559781"
-      }
-    }
-  ]
-}
-
-

getSettings

-

getSettings(address: string, options: Object): Promise<Object>

-

Returns settings for the specified account. Note: For account data that is not modifiable by the user, see getAccountInfo.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
addressaddressThe address of the account to get the settings of.
optionsobjectOptional Options that affect what to return.
options. ledgerVersionintegerOptional Get the settings as of this historical ledger version.
-

Return Value

-

This method returns a promise that resolves with an array of objects with the following structure (Note: all fields are optional as they will not be shown if they are set to their default value):

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
defaultRipplebooleanOptional Enable rippling on this account’s trust lines by default. (New in rippled 0.27.3)
disableMasterKeybooleanOptional Disallows use of the master key to sign transactions for this account.
disallowIncomingXRPbooleanOptional Indicates that client applications should not send XRP to this account. Not enforced by rippled.
domainstringOptional The domain that owns this account, as a hexadecimal string representing the ASCII for the domain in lowercase.
emailHashstring,nullOptional Hash of an email address to be used for generating an avatar image. Conventionally, clients use Gravatar to display this image. Use null to clear.
enableTransactionIDTrackingbooleanOptional Track the ID of this account’s most recent transaction.
globalFreezebooleanOptional Freeze all assets issued by this account.
memosmemosOptional Array of memos to attach to the transaction.
messageKeystringOptional Public key for sending encrypted messages to this account. Conventionally, it should be a secp256k1 key, the same encryption that is used by the rest of Ripple.
noFreezebooleanOptional Permanently give up the ability to freeze individual trust lines. This flag can never be disabled after being enabled.
passwordSpentbooleanOptional Indicates that the account has used its free SetRegularKey transaction.
regularKeyaddress,nullOptional The public key of a new keypair, to use as the regular key to this account, as a base-58-encoded string in the same format as an account address. Use null to remove the regular key.
requireAuthorizationbooleanOptional If set, this account must individually approve other users in order for those users to hold this account’s issuances.
requireDestinationTagbooleanOptional Requires incoming payments to specify a destination tag.
signersobjectOptional Settings that determine what sets of accounts can be used to sign a transaction on behalf of this account using multisigning.
signers. thresholdintegerOptional A target number for the signer weights. A multi-signature from this list is valid only if the sum weights of the signatures provided is equal or greater than this value. To delete the signers setting, use the value 0.
signers. weightsarrayOptional Weights of signatures for each signer.
signers. weights[]objectAn association of an address and a weight.
signers.weights[]. addressaddressA Ripple account address
signers.weights[]. weightintegerThe weight that the signature of this account counts as towards the threshold.
transferRatenumber,nullOptional The fee to charge when users transfer this account’s issuances, as the decimal amount that must be sent to deliver 1 unit. Has precision up to 9 digits beyond the decimal point. Use null to set no fee.
-

Example

-
const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
-return api.getSettings(address).then(settings =>
-  {/* ... */});
-
-
{
-  "requireDestinationTag": true,
-  "disallowIncomingXRP": true,
-  "emailHash": "23463B99B62A72F26ED677CC556C44E8",
-  "domain": "example.com",
-  "transferRate": 1.002
-}
-
-

getAccountInfo

-

getAccountInfo(address: string, options: Object): Promise<Object>

-

Returns information for the specified account. Note: For account data that is modifiable by the user, see getSettings.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
addressaddressThe address of the account to get the account info of.
optionsobjectOptional Options that affect what to return.
options. ledgerVersionintegerOptional Get the account info as of this historical ledger version.
-

Return Value

-

This method returns a promise that resolves with an object with the following structure:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
sequencesequenceThe next (smallest unused) sequence number for this account.
xrpBalancevalueThe XRP balance owned by the account.
ownerCountintegerNumber of other ledger entries (specifically, trust lines and offers) attributed to this account. This is used to calculate the total reserve required to use the account.
previousAffectingTransactionIDstringHash value representing the most recent transaction that affected this account node directly. Note: This does not include changes to the account’s trust lines and offers.
previousAffectingTransactionLedgerVersionintegerThe ledger version that the transaction identified by the previousAffectingTransactionID was validated in.
previousInitiatedTransactionIDstringOptional Hash value representing the most recent transaction that was initiated by this account.
-

Example

-
const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
-return api.getAccountInfo(address).then(info =>
-  {/* ... */});
-
-
{
-  "sequence": 23,
-  "xrpBalance": "922.913243",
-  "ownerCount": 1,
-  "previousAffectingTransactionID": "19899273706A9E040FDB5885EE991A1DC2BAD878A0D6E7DBCFB714E63BF737F7",
-  "previousAffectingTransactionLedgerVersion": 6614625
-}
-
-

getPaymentChannel

-

getPaymentChannel(id: string): Promise<Object>

-

Returns specified payment channel.

-

Parameters

- - - - - - - - - - - - - - - -
NameTypeDescription
idstring256-bit hexadecimal channel identifier.
-

Return Value

-

This method returns a promise that resolves with an object with the following structure:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
accountaddressAddress that created the payment channel.
destinationaddressAddress to receive XRP claims against this channel.
amountvalueThe total amount of XRP funded in this channel.
balancevalueThe total amount of XRP delivered by this channel.
settleDelaynumberAmount of seconds the source address must wait before closing the channel if it has unclaimed XRP.
previousAffectingTransactionIDstringHash value representing the most recent transaction that affected this payment channel.
previousAffectingTransactionLedgerVersionintegerThe ledger version that the transaction identified by the previousAffectingTransactionID was validated in.
cancelAfterdate-time stringOptional Time when this channel expires as specified at creation.
destinationTagintegerOptional Destination tag.
expirationdate-time stringOptional Time when this channel expires.
publicKeystringOptional Public key of the key pair the source will use to sign claims against this channel.
sourceTagintegerOptional Source tag.
-

Example

-
const channelId =
-  'E30E709CF009A1F26E0E5C48F7AA1BFB79393764F15FB108BDC6E06D3CBD8415';
-return api.getPaymentChannel(channelId).then(channel =>
-  {/* ... */});
-
-
{
-  "account": "r6ZtfQFWbCkp4XqaUygzHaXsQXBT67xLj",
-  "amount": "10",
-  "balance": "0",
-  "destination": "rQf9vCwQtzQQwtnGvr6zc1fqzqg7QBuj7G",
-  "publicKey": "02A05282CB6197E34490BACCD9405E81D9DFBE123B0969F9F40EC3F9987AD9A97D",
-  "settleDelay": 10000,
-  "previousAffectingTransactionID": "F939A0BEF139465403C56CCDC49F59A77C868C78C5AEC184E29D15E9CD1FF675",
-  "previousAffectingTransactionLedgerVersion": 151322
-}
-
-

getLedger

-

getLedger(options: Object): Promise<Object>

-

Returns header information for the specified ledger (or the most recent validated ledger if no ledger is specified). Optionally, all the transactions that were validated in the ledger or the account state information can be returned with the ledger header.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
optionsobjectOptional Options affecting what ledger and how much data to return.
options. includeAllDatabooleanOptional Include full transactions and/or state information if includeTransactions and/or includeState is set.
options. includeStatebooleanOptional Return an array of hashes for all state data or an array of all state data in this ledger version, depending on whether includeAllData is set.
options. includeTransactionsbooleanOptional Return an array of hashes for each transaction or an array of all transactions that were validated in this ledger version, depending on whether includeAllData is set.
options. ledgerVersionintegerOptional Get ledger data for this historical ledger version.
-

Return Value

-

This method returns a promise that resolves with an object with the following structure:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
stateHashstringHash of all state information in this ledger.
closeTimedate-time stringThe time at which this ledger was closed.
closeTimeResolutionintegerApproximate number of seconds between closing one ledger version and closing the next one.
closeFlagsintegerA bit-map of flags relating to the closing of this ledger. Currently, the ledger has only one flag defined for closeFlags: sLCF_NoConsensusTime (value 1). If this flag is enabled, it means that validators were in conflict regarding the correct close time for the ledger, but built otherwise the same ledger, so they declared consensus while "agreeing to disagree" on the close time. In this case, the consensus ledger contains a closeTime value that is 1 second after that of the previous ledger. (In this case, there is no official close time, but the actual real-world close time is probably 3-6 seconds later than the specified closeTime.)
ledgerHashstringUnique identifying hash of the entire ledger.
ledgerVersionintegerThe ledger version of this ledger.
parentLedgerHashstringUnique identifying hash of the ledger that came immediately before this one.
parentCloseTimedate-time stringThe time at which the previous ledger was closed.
totalDropsvalueTotal number of drops (1/1,000,000th of an XRP) in the network, as a quoted integer. (This decreases as transaction fees cause XRP to be destroyed.)
transactionHashstringHash of the transaction information included in this ledger.
rawStatestringOptional A JSON string containing all state data for this ledger in rippled JSON format.
rawTransactionsstringOptional A JSON string containing rippled format transaction JSON for all transactions that were validated in this ledger.
stateHashesarray\<string>Optional An array of hashes of all state data in this ledger.
transactionHashesarray\<id>Optional An array of hashes of all transactions that were validated in this ledger.
transactionsarray\<getTransaction>Optional Array of all transactions that were validated in this ledger. Transactions are represented in the same format as the return value of getTransaction.
-

Example

-
return api.getLedger()
-  .then(ledger => {/* ... */});
-
-
{
-  "stateHash": "EC028EC32896D537ECCA18D18BEBE6AE99709FEFF9EF72DBD3A7819E918D8B96",
-  "closeTime": "2014-09-24T21:21:50.000Z",
-  "closeTimeResolution": 10,
-  "closeFlags": 0,
-  "ledgerHash": "0F7ED9F40742D8A513AE86029462B7A6768325583DF8EE21B7EC663019DD6A0F",
-  "ledgerVersion": 9038214,
-  "parentLedgerHash": "4BB9CBE44C39DC67A1BE849C7467FE1A6D1F73949EA163C38A0121A15E04FFDE",
-  "parentCloseTime": "2014-09-24T21:21:40.000Z",
-  "totalDrops": "99999973964317514",
-  "transactionHash": "ECB730839EB55B1B114D5D1AD2CD9A932C35BA9AB6D3A8C2F08935EAC2BAC239"
-}
-
-

preparePayment

-

preparePayment(address: string, payment: Object, instructions: Object): Promise<Object>

-

Prepare a payment transaction. The prepared transaction must subsequently be signed and submitted.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
addressaddressThe address of the account that is creating the transaction.
paymentpaymentThe specification of the payment to prepare.
instructionsinstructionsOptional Instructions for executing the transaction
-

Return Value

-

This method returns a promise that resolves with an object with the following structure:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
txJSONstringThe prepared transaction in rippled JSON format.
instructionsobjectThe instructions for how to execute the transaction after adding automatic defaults.
instructions. feevalueAn exact fee to pay for the transaction. See Transaction Fees for more information.
instructions. sequencesequenceThe initiating account's sequence number for this transaction.
instructions. maxLedgerVersioninteger,nullThe highest ledger version that the transaction can be included in. Set to null if there is no maximum.
-

Example

-
const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
-const payment = {
-  "source": {
-    "address": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-    "maxAmount": {
-      "value": "0.01",
-      "currency": "USD",
-      "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM"
-    }
-  },
-  "destination": {
-    "address": "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo",
-    "amount": {
-      "value": "0.01",
-      "currency": "USD",
-      "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM"
-    }
-  }
-};
-return api.preparePayment(address, payment).then(prepared =>
-  {/* ... */});
-
-
{
-  "txJSON": "{\"Flags\":2147483648,\"TransactionType\":\"Payment\",\"Account\":\"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59\",\"Destination\":\"rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo\",\"Amount\":{\"value\":\"0.01\",\"currency\":\"USD\",\"issuer\":\"rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM\"},\"SendMax\":{\"value\":\"0.01\",\"currency\":\"USD\",\"issuer\":\"rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM\"},\"LastLedgerSequence\":8820051,\"Fee\":\"12\",\"Sequence\":23}",
-  "instructions": {
-    "fee": "0.000012",
-    "sequence": 23,
-    "maxLedgerVersion": 8820051
-  }
-}
-
-

prepareTrustline

-

prepareTrustline(address: string, trustline: Object, instructions: Object): Promise<Object>

-

Prepare a trustline transaction. The prepared transaction must subsequently be signed and submitted.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
addressaddressThe address of the account that is creating the transaction.
trustlinetrustlineThe specification of the trustline to prepare.
instructionsinstructionsOptional Instructions for executing the transaction
-

Return Value

-

This method returns a promise that resolves with an object with the following structure:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
txJSONstringThe prepared transaction in rippled JSON format.
instructionsobjectThe instructions for how to execute the transaction after adding automatic defaults.
instructions. feevalueAn exact fee to pay for the transaction. See Transaction Fees for more information.
instructions. sequencesequenceThe initiating account's sequence number for this transaction.
instructions. maxLedgerVersioninteger,nullThe highest ledger version that the transaction can be included in. Set to null if there is no maximum.
-

Example

-
const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
-const trustline = {
-  "currency": "USD",
-  "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM",
-  "limit": "10000",
-  "qualityIn": 0.91,
-  "qualityOut": 0.87,
-  "ripplingDisabled": true,
-  "frozen": false,
-  "memos": [
-    {
-      "type": "test",
-      "format": "plain/text",
-      "data": "texted data"
-    }
-  ]
-};
-return api.prepareTrustline(address, trustline).then(prepared =>
-  {/* ... */});
-
-
{
-  "txJSON": "{\"TransactionType\":\"TrustSet\",\"Account\":\"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59\",\"LimitAmount\":{\"currency\":\"USD\",\"issuer\":\"rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM\",\"value\":\"10000\"},\"Flags\":2149711872,\"QualityIn\":910000000,\"QualityOut\":870000000,\"Memos\":[{\"Memo\":{\"MemoData\":\"7465787465642064617461\",\"MemoType\":\"74657374\",\"MemoFormat\":\"706C61696E2F74657874\"}}],\"LastLedgerSequence\":8820051,\"Fee\":\"12\",\"Sequence\":23}",
-  "instructions": {
-    "fee": "0.000012",
-    "sequence": 23,
-    "maxLedgerVersion": 8820051
-  }
-}
-
-

prepareOrder

-

prepareOrder(address: string, order: Object, instructions: Object): Promise<Object>

-

Prepare an order transaction. The prepared transaction must subsequently be signed and submitted.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
addressaddressThe address of the account that is creating the transaction.
orderorderThe specification of the order to prepare.
instructionsinstructionsOptional Instructions for executing the transaction
-

Return Value

-

This method returns a promise that resolves with an object with the following structure:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
txJSONstringThe prepared transaction in rippled JSON format.
instructionsobjectThe instructions for how to execute the transaction after adding automatic defaults.
instructions. feevalueAn exact fee to pay for the transaction. See Transaction Fees for more information.
instructions. sequencesequenceThe initiating account's sequence number for this transaction.
instructions. maxLedgerVersioninteger,nullThe highest ledger version that the transaction can be included in. Set to null if there is no maximum.
-

Example

-
const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
-const order = {
-  "direction": "buy",
-  "quantity": {
-    "currency": "USD",
-    "counterparty": "rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM",
-    "value": "10.1"
-  },
-  "totalPrice": {
-    "currency": "XRP",
-    "value": "2"
-  },
-  "passive": true,
-  "fillOrKill": true
-};
-return api.prepareOrder(address, order)
-  .then(prepared => {/* ... */});
-
-
{
-  "txJSON": "{\"Flags\":2147811328,\"TransactionType\":\"OfferCreate\",\"Account\":\"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59\",\"TakerGets\":\"2000000\",\"TakerPays\":{\"value\":\"10.1\",\"currency\":\"USD\",\"issuer\":\"rMH4UxPrbuMa1spCBR98hLLyNJp4d8p4tM\"},\"LastLedgerSequence\":8819954,\"Fee\":\"12\",\"Sequence\":23}",
-  "instructions": {
-    "fee": "0.000012",
-    "sequence": 23,
-    "maxLedgerVersion": 8819954
-  }
-}
-
-

prepareOrderCancellation

-

prepareOrderCancellation(address: string, orderCancellation: Object, instructions: Object): Promise<Object>

-

Prepare an order cancellation transaction. The prepared transaction must subsequently be signed and submitted.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
addressaddressThe address of the account that is creating the transaction.
orderCancellationorderCancellationThe specification of the order cancellation to prepare.
instructionsinstructionsOptional Instructions for executing the transaction
-

Return Value

-

This method returns a promise that resolves with an object with the following structure:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
txJSONstringThe prepared transaction in rippled JSON format.
instructionsobjectThe instructions for how to execute the transaction after adding automatic defaults.
instructions. feevalueAn exact fee to pay for the transaction. See Transaction Fees for more information.
instructions. sequencesequenceThe initiating account's sequence number for this transaction.
instructions. maxLedgerVersioninteger,nullThe highest ledger version that the transaction can be included in. Set to null if there is no maximum.
-

Example

-
const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
-const orderCancellation = {orderSequence: 123};
-return api.prepareOrderCancellation(address, orderCancellation)
-  .then(prepared => {/* ... */});
-
-
{
-  "txJSON": "{\"Flags\":2147483648,\"TransactionType\":\"OfferCancel\",\"Account\":\"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59\",\"OfferSequence\":23,\"LastLedgerSequence\":8820051,\"Fee\":\"12\",\"Sequence\":23}",
-  "instructions": {
-    "fee": "0.000012",
-    "sequence": 23,
-    "maxLedgerVersion": 8820051
-  }
-}
-
-

prepareSettings

-

prepareSettings(address: string, settings: Object, instructions: Object): Promise<Object>

-

Prepare a settings transaction. The prepared transaction must subsequently be signed and submitted.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
addressaddressThe address of the account that is creating the transaction.
settingssettingsThe specification of the settings to prepare.
instructionsinstructionsOptional Instructions for executing the transaction
-

Return Value

-

This method returns a promise that resolves with an object with the following structure:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
txJSONstringThe prepared transaction in rippled JSON format.
instructionsobjectThe instructions for how to execute the transaction after adding automatic defaults.
instructions. feevalueAn exact fee to pay for the transaction. See Transaction Fees for more information.
instructions. sequencesequenceThe initiating account's sequence number for this transaction.
instructions. maxLedgerVersioninteger,nullThe highest ledger version that the transaction can be included in. Set to null if there is no maximum.
-

Example

-
const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
-const settings = {
-  "domain": "ripple.com",
-  "memos": [
-    {
-      "type": "test",
-      "format": "plain/text",
-      "data": "texted data"
-    }
-  ]
-};
-return api.prepareSettings(address, settings)
-  .then(prepared => {/* ... */});
-
-
{
-  "domain": "ripple.com",
-  "memos": [
-    {
-      "type": "test",
-      "format": "plain/text",
-      "data": "texted data"
-    }
-  ]
-}
-
-

prepareEscrowCreation

-

prepareEscrowCreation(address: string, escrowCreation: Object, instructions: Object): Promise<Object>

-

Prepare an escrow creation transaction. The prepared transaction must subsequently be signed and submitted.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
addressaddressThe address of the account that is creating the transaction.
escrowCreationescrowCreationThe specification of the escrow creation to prepare.
instructionsinstructionsOptional Instructions for executing the transaction
-

Return Value

-

This method returns a promise that resolves with an object with the following structure:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
txJSONstringThe prepared transaction in rippled JSON format.
instructionsobjectThe instructions for how to execute the transaction after adding automatic defaults.
instructions. feevalueAn exact fee to pay for the transaction. See Transaction Fees for more information.
instructions. sequencesequenceThe initiating account's sequence number for this transaction.
instructions. maxLedgerVersioninteger,nullThe highest ledger version that the transaction can be included in. Set to null if there is no maximum.
-

Example

-
const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
-const escrowCreation = {
-  "destination": "rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo",
-  "amount": "0.01",
-  "allowCancelAfter": "2014-09-24T21:21:50.000Z"
-};
-return api.prepareEscrowCreation(address, escrowCreation).then(prepared =>
-  {/* ... */});
-
-
{
-  "txJSON": "{\"Flags\":2147483648,\"TransactionType\":\"EscrowCreate\",\"Account\":\"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59\",\"Destination\":\"rpZc4mVfWUif9CRoHRKKcmhu1nx2xktxBo\",\"Amount\":\"10000\",\"CancelAfter\":464908910,\"LastLedgerSequence\":8820051,\"Fee\":\"12\",\"Sequence\":23}",
-  "instructions": {
-    "fee": "0.000012",
-    "sequence": 23,
-    "maxLedgerVersion": 8820051
-  }
-}
-
-

prepareEscrowCancellation

-

prepareEscrowCancellation(address: string, escrowCancellation: Object, instructions: Object): Promise<Object>

-

Prepare an escrow cancellation transaction. The prepared transaction must subsequently be signed and submitted.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
addressaddressThe address of the account that is creating the transaction.
escrowCancellationescrowCancellationThe specification of the escrow cancellation to prepare.
instructionsinstructionsOptional Instructions for executing the transaction
-

Return Value

-

This method returns a promise that resolves with an object with the following structure:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
txJSONstringThe prepared transaction in rippled JSON format.
instructionsobjectThe instructions for how to execute the transaction after adding automatic defaults.
instructions. feevalueAn exact fee to pay for the transaction. See Transaction Fees for more information.
instructions. sequencesequenceThe initiating account's sequence number for this transaction.
instructions. maxLedgerVersioninteger,nullThe highest ledger version that the transaction can be included in. Set to null if there is no maximum.
-

Example

-
const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
-const escrowCancellation = {
-  "owner": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-  "escrowSequence": 1234
-};
-return api.prepareEscrowCancellation(address, escrowCancellation).then(prepared =>
-  {/* ... */});
-
-
{
-  "txJSON": "{\"Flags\":2147483648,\"TransactionType\":\"EscrowCancel\",\"Account\":\"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59\",\"Owner\":\"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59\",\"OfferSequence\":1234,\"LastLedgerSequence\":8820051,\"Fee\":\"12\",\"Sequence\":23}",
-  "instructions": {
-    "fee": "0.000012",
-    "sequence": 23,
-    "maxLedgerVersion": 8820051
-  }
-}
-
-

prepareEscrowExecution

-

prepareEscrowExecution(address: string, escrowExecution: Object, instructions: Object): Promise<Object>

-

Prepare an escrow execution transaction. The prepared transaction must subsequently be signed and submitted.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
addressaddressThe address of the account that is creating the transaction.
escrowExecutionescrowExecutionThe specification of the escrow execution to prepare.
instructionsinstructionsOptional Instructions for executing the transaction
-

Return Value

-

This method returns a promise that resolves with an object with the following structure:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
txJSONstringThe prepared transaction in rippled JSON format.
instructionsobjectThe instructions for how to execute the transaction after adding automatic defaults.
instructions. feevalueAn exact fee to pay for the transaction. See Transaction Fees for more information.
instructions. sequencesequenceThe initiating account's sequence number for this transaction.
instructions. maxLedgerVersioninteger,nullThe highest ledger version that the transaction can be included in. Set to null if there is no maximum.
-

Example

-
const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
-const escrowExecution = {
-  "owner": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-  "escrowSequence": 1234,
-  "condition": "A0258020E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855810100",
-  "fulfillment": "A0028000"
-};
-return api.prepareEscrowExecution(address, escrowExecution).then(prepared =>
-  {/* ... */});
-
-
{
-  "txJSON": "{\"Flags\":2147483648,\"TransactionType\":\"EscrowFinish\",\"Account\":\"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59\",\"Owner\":\"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59\",\"OfferSequence\":1234,\"Condition\":\"A0258020E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855810100\",\"Fulfillment\":\"A0028000\",\"LastLedgerSequence\":8820051,\"Fee\":\"396\",\"Sequence\":23}",
-  "instructions": {
-    "fee": "0.000396",
-    "sequence": 23,
-    "maxLedgerVersion": 8820051
-  }
-}
-
-

preparePaymentChannelCreate

-

preparePaymentChannelCreate(address: string, paymentChannelCreate: Object, instructions: Object): Promise<Object>

-

Prepare a payment channel creation transaction. The prepared transaction must subsequently be signed and submitted.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
addressaddressThe address of the account that is creating the transaction.
paymentChannelCreatepaymentChannelCreateThe specification of the payment channel to create.
instructionsinstructionsOptional Instructions for executing the transaction
-

Return Value

-

This method returns a promise that resolves with an object with the following structure:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
txJSONstringThe prepared transaction in rippled JSON format.
instructionsobjectThe instructions for how to execute the transaction after adding automatic defaults.
instructions. feevalueAn exact fee to pay for the transaction. See Transaction Fees for more information.
instructions. sequencesequenceThe initiating account's sequence number for this transaction.
instructions. maxLedgerVersioninteger,nullThe highest ledger version that the transaction can be included in. Set to null if there is no maximum.
-

Example

-
const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
-const paymentChannelCreate = {
-  "amount": "1",
-  "destination": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-  "settleDelay": 86400,
-  "publicKey": "32D2471DB72B27E3310F355BB33E339BF26F8392D5A93D3BC0FC3B566612DA0F0A"
-};
-return api.preparePaymentChannelCreate(address, paymentChannelCreate).then(prepared =>
-  {/* ... */});
-
-
{
-  "txJSON":"{\"Account\":\"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59\",\"TransactionType\":\"PaymentChannelCreate\",\"Amount\":\"1000000\",\"Destination\":\"rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW\",\"SettleDelay\":86400,\"PublicKey\":\"32D2471DB72B27E3310F355BB33E339BF26F8392D5A93D3BC0FC3B566612DA0F0A\",\"Flags\":2147483648,\"LastLedgerSequence\":8820051,\"Fee\":\"12\",\"Sequence\":23}",
-  "instructions": {
-    "fee": "0.000012",
-    "sequence": 23,
-    "maxLedgerVersion": 8820051
-  }
-}
-
-

preparePaymentChannelClaim

-

preparePaymentChannelClaim(address: string, paymentChannelClaim: Object, instructions: Object): Promise<Object>

-

Prepare a payment channel claim transaction. The prepared transaction must subsequently be signed and submitted.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
addressaddressThe address of the account that is creating the transaction.
paymentChannelClaimpaymentChannelClaimDetails of the channel and claim.
instructionsinstructionsOptional Instructions for executing the transaction
-

Return Value

-

This method returns a promise that resolves with an object with the following structure:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
txJSONstringThe prepared transaction in rippled JSON format.
instructionsobjectThe instructions for how to execute the transaction after adding automatic defaults.
instructions. feevalueAn exact fee to pay for the transaction. See Transaction Fees for more information.
instructions. sequencesequenceThe initiating account's sequence number for this transaction.
instructions. maxLedgerVersioninteger,nullThe highest ledger version that the transaction can be included in. Set to null if there is no maximum.
-

Example

-
const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
-const paymentChannelClaim = {
-  "channel": "C1AE6DDDEEC05CF2978C0BAD6FE302948E9533691DC749DCDD3B9E5992CA6198"
-};
-return api.preparePaymentChannelClaim(address, paymentChannelClaim).then(prepared =>
-  {/* ... */});
-
-
{
-  "txJSON": "{\"Account\":\"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59\",\"TransactionType\":\"PaymentChannelClaim\",\"Channel\":\"C1AE6DDDEEC05CF2978C0BAD6FE302948E9533691DC749DCDD3B9E5992CA6198\",\"Flags\":2147483648,\"LastLedgerSequence\":8820051,\"Fee\":\"12\",\"Sequence\":23}",
-  "instructions": {
-    "fee": "0.000012",
-    "sequence": 23,
-    "maxLedgerVersion": 8820051
-  }
-}
-
-

preparePaymentChannelFund

-

preparePaymentChannelFund(address: string, paymentChannelFund: Object, instructions: Object): Promise<Object>

-

Prepare a payment channel fund transaction. The prepared transaction must subsequently be signed and submitted.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
addressaddressThe address of the account that is creating the transaction.
paymentChannelFundpaymentChannelFundThe channel to fund, and the details of how to fund it.
instructionsinstructionsOptional Instructions for executing the transaction
-

Return Value

-

This method returns a promise that resolves with an object with the following structure:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
txJSONstringThe prepared transaction in rippled JSON format.
instructionsobjectThe instructions for how to execute the transaction after adding automatic defaults.
instructions. feevalueAn exact fee to pay for the transaction. See Transaction Fees for more information.
instructions. sequencesequenceThe initiating account's sequence number for this transaction.
instructions. maxLedgerVersioninteger,nullThe highest ledger version that the transaction can be included in. Set to null if there is no maximum.
-

Example

-
const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
-const paymentChannelFund = {
-  "channel": "C1AE6DDDEEC05CF2978C0BAD6FE302948E9533691DC749DCDD3B9E5992CA6198",
-  "amount": "1"
-};
-return api.preparePaymentChannelFund(address, paymentChannelFund).then(prepared =>
-  {/* ... */});
-
-
{
-  "txJSON":"{\"Account\":\"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59\",\"TransactionType\":\"PaymentChannelFund\",\"Channel\":\"C1AE6DDDEEC05CF2978C0BAD6FE302948E9533691DC749DCDD3B9E5992CA6198\",\"Amount\":\"1000000\",\"Flags\":2147483648,\"LastLedgerSequence\":8820051,\"Fee\":\"12\",\"Sequence\":23}",
-  "instructions": {
-    "fee": "0.000012",
-    "sequence": 23,
-    "maxLedgerVersion": 8820051
-  }
-}
-
-

sign

-

sign(txJSON: string, secret: string, options: Object): {signedTransaction: string, id: string}

-

Sign a prepared transaction. The signed transaction must subsequently be submitted.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
txJSONstringTransaction represented as a JSON string in rippled format.
secretsecret stringThe secret of the account that is initiating the transaction.
optionsobjectOptional Options that control the type of signature that will be generated.
options. signAsaddressOptional The account that the signature should count for in multisigning.
-

Return Value

-

This method returns an object with the following structure:

- - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
signedTransactionstringThe signed transaction represented as an uppercase hexadecimal string.
ididThe Transaction ID of the signed transaction.
-

Example

-
const txJSON = '{"Flags":2147483648,"TransactionType":"AccountSet","Account":"r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59","Domain":"726970706C652E636F6D","LastLedgerSequence":8820051,"Fee":"12","Sequence":23}';
-const secret = 'shsWGZcmZz6YsWWmcnpfr6fLTdtFV';
-return api.sign(txJSON, secret);
-
-
{
-  "signedTransaction": "12000322800000002400000017201B0086955368400000000000000C732102F89EAEC7667B30F33D0687BBA86C3FE2A08CCA40A9186C5BDE2DAA6FA97A37D874473045022100BDE09A1F6670403F341C21A77CF35BA47E45CDE974096E1AA5FC39811D8269E702203D60291B9A27F1DCABA9CF5DED307B4F23223E0B6F156991DB601DFB9C41CE1C770A726970706C652E636F6D81145E7B112523F68D2F5E879DB4EAC51C6698A69304",
-  "id": "02ACE87F1996E3A23690A5BB7F1774BF71CCBA68F79805831B42ABAD5913D6F4"
-}
-
-

combine

-

combine(signedTransactions: Array<string>): {signedTransaction: string, id: string}

-

Combines signed transactions from multiple accounts for a multisignature transaction. The signed transaction must subsequently be submitted.

-

Parameters

- - - - - - - - - - - - - - - -
NameTypeDescription
signedTransactionsarray\<string>An array of signed transactions (from the output of sign) to combine.
-

Return Value

-

This method returns an object with the following structure:

- - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
signedTransactionstringThe signed transaction represented as an uppercase hexadecimal string.
ididThe Transaction ID of the signed transaction.
-

Example

-
const signedTransactions = [ "12000322800000002400000004201B000000116840000000000F42407300770B6578616D706C652E636F6D811407C532442A675C881BA1235354D4AB9D023243A6F3E0107321026C784C1987F83BACBF02CD3E484AFC84ADE5CA6B36ED4DCA06D5BA233B9D382774473045022100E484F54FF909469FA2033E22EFF3DF8EDFE62217062680BB2F3EDF2F185074FE0220350DB29001C710F0450DAF466C5D819DC6D6A3340602DE9B6CB7DA8E17C90F798114FE9337B0574213FA5BCC0A319DBB4A7AC0CCA894E1F1",
-  "12000322800000002400000004201B000000116840000000000F42407300770B6578616D706C652E636F6D811407C532442A675C881BA1235354D4AB9D023243A6F3E01073210287AAAB8FBE8C4C4A47F6F1228C6E5123A7ED844BFE88A9B22C2F7CC34279EEAA74473045022100B09DDF23144595B5A9523B20E605E138DC6549F5CA7B5984D7C32B0E3469DF6B022018845CA6C203D4B6288C87DDA439134C83E7ADF8358BD41A8A9141A9B631419F8114517D9B9609229E0CDFE2428B586738C5B2E84D45E1F1" ];
-return api.combine(signedTransactions);
-
-
{
-  "signedTransaction": "12000322800000002400000004201B000000116840000000000F42407300770B6578616D706C652E636F6D811407C532442A675C881BA1235354D4AB9D023243A6F3E01073210287AAAB8FBE8C4C4A47F6F1228C6E5123A7ED844BFE88A9B22C2F7CC34279EEAA74473045022100B09DDF23144595B5A9523B20E605E138DC6549F5CA7B5984D7C32B0E3469DF6B022018845CA6C203D4B6288C87DDA439134C83E7ADF8358BD41A8A9141A9B631419F8114517D9B9609229E0CDFE2428B586738C5B2E84D45E1E0107321026C784C1987F83BACBF02CD3E484AFC84ADE5CA6B36ED4DCA06D5BA233B9D382774473045022100E484F54FF909469FA2033E22EFF3DF8EDFE62217062680BB2F3EDF2F185074FE0220350DB29001C710F0450DAF466C5D819DC6D6A3340602DE9B6CB7DA8E17C90F798114FE9337B0574213FA5BCC0A319DBB4A7AC0CCA894E1F1",
-  "id": "8A3BFD2214B4C8271ED62648FCE9ADE4EE82EF01827CF7D1F7ED497549A368CC"
-}
-
-

submit

-

submit(signedTransaction: string): Promise<Object>

-

Submits a signed transaction. The transaction is not guaranteed to succeed; it must be verified with getTransaction.

-

Parameters

- - - - - - - - - - - - - - - -
NameTypeDescription
signedTransactionstringA signed transaction as returned by sign.
-

Return Value

-

This method returns an object with the following structure:

- - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
resultCodestringThe result code returned by rippled. List of transaction responses
resultMessagestringHuman-readable explanation of the status of the transaction.
-

Example

-
const signedTransaction = '12000322800000002400000017201B0086955368400000000000000C732102F89EAEC7667B30F33D0687BBA86C3FE2A08CCA40A9186C5BDE2DAA6FA97A37D874473045022100BDE09A1F6670403F341C21A77CF35BA47E45CDE974096E1AA5FC39811D8269E702203D60291B9A27F1DCABA9CF5DED307B4F23223E0B6F156991DB601DFB9C41CE1C770A726970706C652E636F6D81145E7B112523F68D2F5E879DB4EAC51C6698A69304';
-return api.submit(signedTransaction)
-  .then(result => {/* ... */});
-
-
{
-  "resultCode": "tesSUCCESS",
-  "resultMessage": "The transaction was applied. Only final in a validated ledger."
-}
-
-

generateAddress

-

generateAddress(): {address: string, secret: string}

-

Generate a new XRP Ledger address and corresponding secret.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
optionsobjectOptional Options to control how the address and secret are generated.
options. algorithmstringOptional The digital signature algorithm to generate an address for. Can be ecdsa-secp256k1 (default) or ed25519.
options. entropyarray\<integer>Optional The entropy to use to generate the seed.
-

Return Value

-

This method returns an object with the following structure:

- - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
addressaddressA randomly generated Ripple account address.
secretsecret stringThe secret corresponding to the address.
-

Example

-
return api.generateAddress();
-
-
{
-  "address": "rGCkuB7PBr5tNy68tPEABEtcdno4hE6Y7f",
-  "secret": "sp6JS7f14BuwFY8Mw6bTtLKWauoUs"
-}
-
-

signPaymentChannelClaim

-

signPaymentChannelClaim(channel: string, amount: string, privateKey: string): string

-

Sign a payment channel claim. The signature can be submitted in a subsequent PaymentChannelClaim transaction.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
channelstring256-bit hexadecimal channel identifier.
amountvalueAmount of XRP authorized by the claim.
privateKeystringThe private key to sign the payment channel claim.
-

Return Value

-

This method returns a signature string:

- - - - - - - - - - - - - - - -
NameTypeDescription
stringThe hexadecimal representation of a signature.
-

Example

-
const channel =
-  '3E18C05AD40319B809520F1A136370C4075321B285217323396D6FD9EE1E9037';
-const amount = '.00001';
-const privateKey =
-  'ACCD3309DB14D1A4FC9B1DAE608031F4408C85C73EE05E035B7DC8B25840107A';
-return api.signPaymentChannelClaim(channel, amount, privateKey);
-
-
"3045022100B5C54654221F154347679B97AE7791CBEF5E6772A3F894F9C781B8F1B400F89F022021E466D29DC5AEB5DFAFC76E8A88D2E388EBD25A84143B6AC3B647F479CB89B7"
-
-

verifyPaymentChannelClaim

-

verifyPaymentChannelClaim(channel: string, amount: string, signature: string, publicKey: string): boolean

-

Verify a payment channel claim signature.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
channelstring256-bit hexadecimal channel identifier.
amountvalueAmount of XRP authorized by the claim.
signaturestringSignature of this claim.
publicKeystringPublic key of the channel's sender
-

Return Value

-

This method returns true if the claim signature is valid.

- - - - - - - - - - - - - - - -
NameTypeDescription
boolean
-

Example

-
const channel =
-  '3E18C05AD40319B809520F1A136370C4075321B285217323396D6FD9EE1E9037';
-const amount = '.00001';
-const signature = "3045022100B5C54654221F154347679B97AE7791CBEF5E6772A3F894F9C781B8F1B400F89F022021E466D29DC5AEB5DFAFC76E8A88D2E388EBD25A84143B6AC3B647F479CB89B7";
-const publicKey =
-  '02F89EAEC7667B30F33D0687BBA86C3FE2A08CCA40A9186C5BDE2DAA6FA97A37D8';
-return api.verifyPaymentChannelClaim(channel, amount, signature, publicKey);
-
-
true
-
-

computeLedgerHash

-

computeLedgerHash(ledger: Object): string

-

Compute the hash of a ledger.

-

Parameters

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
ledgerobjectThe ledger header to hash.
ledger. stateHashstringHash of all state information in this ledger.
ledger. closeTimedate-time stringThe time at which this ledger was closed.
ledger. closeTimeResolutionintegerApproximate number of seconds between closing one ledger version and closing the next one.
ledger. closeFlagsintegerA bit-map of flags relating to the closing of this ledger. Currently, the ledger has only one flag defined for closeFlags: sLCF_NoConsensusTime (value 1). If this flag is enabled, it means that validators were in conflict regarding the correct close time for the ledger, but built otherwise the same ledger, so they declared consensus while "agreeing to disagree" on the close time. In this case, the consensus ledger contains a closeTime value that is 1 second after that of the previous ledger. (In this case, there is no official close time, but the actual real-world close time is probably 3-6 seconds later than the specified closeTime.)
ledger. ledgerHashstringUnique identifying hash of the entire ledger.
ledger. ledgerVersionintegerThe ledger version of this ledger.
ledger. parentLedgerHashstringUnique identifying hash of the ledger that came immediately before this one.
ledger. parentCloseTimedate-time stringThe time at which the previous ledger was closed.
ledger. totalDropsvalueTotal number of drops (1/1,000,000th of an XRP) in the network, as a quoted integer. (This decreases as transaction fees cause XRP to be destroyed.)
ledger. transactionHashstringHash of the transaction information included in this ledger.
ledger. rawStatestringOptional A JSON string containing all state data for this ledger in rippled JSON format.
ledger. rawTransactionsstringOptional A JSON string containing rippled format transaction JSON for all transactions that were validated in this ledger.
ledger. stateHashesarray\<string>Optional An array of hashes of all state data in this ledger.
ledger. transactionHashesarray\<id>Optional An array of hashes of all transactions that were validated in this ledger.
ledger. transactionsarray\<getTransaction>Optional Array of all transactions that were validated in this ledger. Transactions are represented in the same format as the return value of getTransaction.
-

Return Value

-

This method returns an uppercase hexadecimal string representing the hash of the ledger.

-

Example

-
const ledger = {
-  "stateHash": "D9ABF622DA26EEEE48203085D4BC23B0F77DC6F8724AC33D975DA3CA492D2E44",
-  "closeTime": "2015-08-12T01:01:10.000Z",
-  "parentCloseTime": "2015-08-12T01:01:00.000Z",
-  "closeFlags": 0,
-  "closeTimeResolution": 10,
-  "ledgerVersion": 15202439,
-  "parentLedgerHash": "12724A65B030C15A1573AA28B1BBB5DF3DA4589AA3623675A31CAE69B23B1C4E",
-  "totalDrops": "99998831688050493",
-  "transactionHash": "325EACC5271322539EEEC2D6A5292471EF1B3E72AE7180533EFC3B8F0AD435C8"
-};
-return api.computeLedgerHash(ledger);
-
-
"F4D865D83EB88C1A1911B9E90641919A1314F36E1B099F8E95FE3B7C77BE3349"
-
-

API Events

-

ledger

-

This event is emitted whenever a new ledger version is validated on the connected server.

-

Return Value

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
baseFeeXRPvalueBase fee, in XRP.
ledgerHashstringUnique hash of the ledger that was closed, as hex.
ledgerTimestampdate-time stringThe time at which this ledger closed.
reserveBaseXRPvalueThe minimum reserve, in XRP, that is required for an account.
reserveIncrementXRPvalueThe increase in account reserve that is added for each item the account owns, such as offers or trust lines.
transactionCountintegerNumber of new transactions included in this ledger.
ledgerVersionintegerLedger version of the ledger that closed.
validatedLedgerVersionsstringRange of ledgers that the server has available. This may be discontiguous.
-

Example

-
api.on('ledger', ledger => {
-  console.log(JSON.stringify(ledger, null, 2));
-});
-
-
{
-  "baseFeeXRP": "0.00001",
-  "ledgerVersion": 14804627,
-  "ledgerHash": "9141FA171F2C0CE63E609466AF728FF66C12F7ACD4B4B50B0947A7F3409D593A",
-  "ledgerTimestamp": "2015-07-23T05:50:40.000Z",
-  "reserveBaseXRP": "20",
-  "reserveIncrementXRP": "5",
-  "transactionCount": 19,
-  "validatedLedgerVersions": "13983423-14804627"
-}
-
-

error

-

This event is emitted when there is an error on the connection to the server that cannot be associated to a specific request.

-

Return Value

-

The first parameter is a string indicating the error type: - badMessage - rippled returned a malformed message - websocket - the websocket library emitted an error -* one of the error codes found in the rippled Universal Errors.

-

The second parameter is a message explaining the error.

-

The third parameter is: - the message that caused the error for badMessage - the error object emitted for websocket -* the parsed response for rippled errors

-

Example

-
api.on('error', (errorCode, errorMessage, data) => {
-  console.log(errorCode + ': ' + errorMessage);
-});
-
-
tooBusy: The server is too busy to help you now.
-
-

connected

-

This event is emitted after connection successfully opened.

-

Example

-
api.on('connected', () => {
-  console.log('Connection is open now.');
-});
-
-

disconnected

-

This event is emitted when connection is closed.

-

Return Value

-

The only parameter is a number containing the close code send by the server.

-

Example

-
api.on('disconnected', (code) => {
-  if (code !== 1000) {
-    console.log('Connection is closed due to error.');
-  } else {
-    console.log('Connection is closed normally.');
-  }
-});
-
-
-
-
- - - - \ No newline at end of file diff --git a/reference-rippled.html b/reference-rippled.html deleted file mode 100644 index 3b4ad12922..0000000000 --- a/reference-rippled.html +++ /dev/null @@ -1,13826 +0,0 @@ - - - - - - - - rippled - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

rippled

-

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

- -

WebSocket and JSON-RPC APIs

-

If you want to communicate directly with a rippled server, you can use either the WebSocket API or the JSON-RPC API. Both APIs use the same list of commands, with almost entirely the same parameters in each command. Alternatively, you can use RippleAPI, which is a simplified JavaScript client library, which communicates directly with a rippled server from Node.js or a web browser.

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

In general, we recommend using WebSocket, because WebSocket's push paradigm has less latency and less network overhead. WebSocket is also more reliable; you can worry less about missing messages and establishing multiple connections. On the other hand, there is widespread support for JSON-RPC because you can use a standard HTTP library to connect to rippled's JSON-RPC API.

-

Changes to the APIs

-

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

-

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

-

Connecting to rippled

-

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

-

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

-

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

-

WebSocket API

-

If you are looking to try out some methods on the XRP Ledger, you can skip writing your own WebSocket code and go straight to using the API at the Ripple WebSocket API Tool. Later on, when you want to connect to your own rippled server, you can build your own client in the browser or in Node.js.

-

Request Formatting

-

After you open a WebSocket to the rippled server, you can send commands as a JSON object, with the following attributes:

-
    -
  • Put command name in top-level "command" field
    • -
  • All the relevant parameters for the command are also in the top level
    • -
  • Optionally include an "id" field with an arbitrary value. The response to this request uses the same "id" field. This way, even if responses arrive out of order, you know which request prompted which response.
    • -
-

The response comes as a JSON object.

-

Public Servers

-

Currently Ripple (the company) maintains a set of public WebSocket servers at:

- - - - - - - - - - - - - - - - - - - - -
DomainPortNotes
s1.ripple.com443wss:// only; general purpose server
s2.ripple.com443wss:// only; full-history server
-

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

-

JSON-RPC

-

You can use any HTTP client (like Poster for Firefox or Postman for Chrome) to make JSON-RPC calls a rippled server. Most programming languages have a library for making HTTP requests built in.

-

Request Formatting

-

To make a JSON-RPC request, send an HTTP POST request to the root path (/) on the port and IP where the rippled server is listening for JSON-RPC connections. You can use HTTP/1.0 or HTTP/1.1. If you use HTTPS, you should use TLS v1.2. For security reasons, rippled does not support SSL v3 or earlier.

-

Always include a Content-Type header with the value application/json.

-

If you plan on making multiple requests, use Keep-Alives so that you do not have to close and re-open the connection in between requests.

-

Send request body as a JSON object with the following attributes:

-
    -
  • Put the command in the top-level "method" field
    • -
  • Include a top-level "params" field. The contents of this field should be a one-item array containing only a nested JSON object with all the parameters for the command.
    • -
-

The response is also a JSON object.

-

Public Servers

-

Currently, Ripple (the company) maintains a set of public JSON-RPC servers at:

- - - - - - - - - - - - - - - - - - - - -
DomainPortNotes
s1.ripple.com51234General purpose server
s2.ripple.com51234Full-history server
-

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

-

Commandline

-

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

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

Request Formatting

-

The commandline puts the command after any normal (dash-prefaced) commandline options, followed by a limited set of parameters, separated by spaces. For any parameter values that might contain spaces or other unusual characters, use single-quotes to encapsulate them.

-

Example Request

-
- -
{
-  "id": 2,
-  "command": "account_info",
-  "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-  "strict": true,
-  "ledger_index": "validated"
-}
-
- -
POST http://s1.ripple.com:51234/
-{
-    "method": "account_info",
-    "params": [
-        {
-            "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-            "strict": true,
-            "ledger_index": "validated"
-        }
-    ]
-}
-
- -
rippled account_info r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 validated true
-
-
-

Response Formatting

-

Example Successful Response

-
- -
{
-  "id": 2,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "account_data": {
-      "Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-      "Balance": "27389517749",
-      "Flags": 0,
-      "LedgerEntryType": "AccountRoot",
-      "OwnerCount": 18,
-      "PreviousTxnID": "B6B410172C0B65575D89E464AF5B99937CC568822929ABF87DA75CBD11911932",
-      "PreviousTxnLgrSeq": 6592159,
-      "Sequence": 1400,
-      "index": "4F83A2CF7E70F77F79A307E6A472BFC2585B806A70833CCD1C26105BAE0D6E05"
-    },
-    "ledger_index": 6760970
-  }
-}
-
- -
HTTP Status: 200 OK
-{
-    "result": {
-        "account_data": {
-            "Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-            "Balance": "27389517749",
-            "Flags": 0,
-            "LedgerEntryType": "AccountRoot",
-            "OwnerCount": 18,
-            "PreviousTxnID": "B6B410172C0B65575D89E464AF5B99937CC568822929ABF87DA75CBD11911932",
-            "PreviousTxnLgrSeq": 6592159,
-            "Sequence": 1400,
-            "index": "4F83A2CF7E70F77F79A307E6A472BFC2585B806A70833CCD1C26105BAE0D6E05"
-        },
-        "ledger_index": 6761012,
-        "status": "success"
-    }
-}
-
- -
{
-    "result": {
-        "account_data": {
-            "Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-            "Balance": "27389517749",
-            "Flags": 0,
-            "LedgerEntryType": "AccountRoot",
-            "OwnerCount": 18,
-            "PreviousTxnID": "B6B410172C0B65575D89E464AF5B99937CC568822929ABF87DA75CBD11911932",
-            "PreviousTxnLgrSeq": 6592159,
-            "Sequence": 1400,
-            "index": "4F83A2CF7E70F77F79A307E6A472BFC2585B806A70833CCD1C26105BAE0D6E05"
-        },
-        "ledger_index": 6761012,
-        "status": "success"
-    }
-}
-
-
-

The fields of a successful response include:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
id(Varies)(WebSocket only) ID provided in the request that prompted this response
statusString(WebSocket only) The value success indicates the request was successfully received and understood by the server.
result.statusString(JSON-RPC and Commandline) The value success indicates the request was successfully received and understood by the server.
typeString(WebSocket only) The value response indicates a successful response to a command. Asynchronous notifications use a different value such as ledgerClosed or transaction.
resultObjectThe result of the query; contents vary depending on the command.
-

Commandline

-

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

-

Error Responses

-

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

-

Some example errors:

-
- -
{
-  "id": 3,
-  "status": "error",
-  "type": "response",
-  "error": "ledgerIndexMalformed",
-  "request": {
-    "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-    "command": "account_info",
-    "id": 3,
-    "ledger_index": "-",
-    "strict": true
-  }
-}
-
- -
HTTP Status: 200 OK
-{
-    "result": {
-        "error": "ledgerIndexMalformed",
-        "request": {
-            "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-            "command": "account_info",
-            "ledger_index": "-",
-            "strict": true
-        },
-        "status": "error"
-    }
-}
-
- -
{
-    "result": {
-        "error": "ledgerIndexMalformed",
-        "request": {
-            "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-            "command": "account_info",
-            "ledger_index": "-",
-            "strict": true
-        },
-        "status": "error"
-    }
-}
-
-
-

WebSocket API Error Response Format

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
id(Varies)ID provided in the Web Socket request that prompted this response
statusString"error" if the request caused an error
typeStringTypically "response", which indicates a successful response to a command.
errorStringA unique code for the type of error that occurred
requestObjectA copy of the request that prompted this error, in JSON format. Caution: If the request contained any account secrets, they are copied here!
-

JSON-RPC API Error Response Format

-

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

-
HTTP Status: 400 Bad Request
-Null method
-
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
resultObjectObject containing the response to the query
result.errorStringA unique code for the type of error that occurred
result.statusString"error" if the request caused an error
result.requestObjectA copy of the request that prompted this error, in JSON format. Caution: If the request contained any account secrets, they are copied here! Note: The request is re-formatted in WebSocket format, regardless of the request made.
-

Caution on Errors

-

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

-

Universal Errors

-

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

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

Formatting Conventions

-

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

-

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

-

Basic Data Types

-

Different types of objects are uniquely identified in different ways:

-

Accounts are identified by their Address, for example "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59". Addresses always start with "r". Many rippled methods also accept a hexadecimal representation.

-

Transactions are identified by a Hash of the transaction's binary format. You can also identify a transaction by its sending account and Sequence Number.

-

Each closed Ledger has a Ledger Index and a Hash value. When Specifying a Ledger Instance you can use either one.

-

Addresses

-

Accounts in the XRP Ledger are identified by a base58 XRP Ledger Address. The address is derived from the account's master public key, which is in turn derived from a secret key. An address is represented as a string in JSON and has the following characteristics:

-
    -
  • Between 25 and 35 characters in length
    • -
  • Starts with the character r
    • -
  • Uses alphanumeric characters, excluding the number "0" capital letter "O", capital letter "I", and lowercase letter "l"
    • -
  • Case-sensitive
    • -
  • Includes a 4-byte checksum so that the probability of generating a valid address from random characters is approximately 1 in 2^32
    • -
-

For more information, see Accounts.

-

Hashes

-

Many objects in the XRP Ledger, particularly transactions and ledgers, are uniquely identified by a 256-bit hash value. This value is typically calculated as a "SHA-512Half", which calculates a SHA-512 hash from some contents, then takes the first 64 characters of the hexadecimal representation. Since the hash of an object is derived from the contents in a way that is extremely unlikely to produce collisions, two objects with the same hash can be considered the same.

-

An XRP Ledger hash value has the following characteristics:

-
    -
  • Exactly 64 characters in length
    • -
  • Hexadecimal character set: 0-9 and A-F.
    • -
  • Typically written in upper case.
    • -
-

Note: SHA-512Half has similar security to the officially-defined SHA-512/256 hash function. However, the XRP Ledger's usage predates SHA-512/256 and is also easier to implement on top of an existing SHA-512 function. (As of this writing, SHA-512 support in cryptographic libraries is much more common than for SHA-512/256.)

-

Account Sequence

-

A Sequence number is a 32-bit unsigned integer used to identify a transaction or Offer relative to a specific account.

-

Every account object in the XRP Ledger has a Sequence number, which starts at 1. For a transaction to be relayed to the network and possibly included in a validated ledger, it must have a Sequence field that matches the sending account's current Sequence number. An account's Sequence field is incremented whenever a transaction from that account is included in a validated ledger (regardless of whether the transaction succeeded or failed). This preserves the order of transactions submitted by an account, and differentiates transactions that would otherwise be the same.

-

Every Offer node in the XRP Ledger is marked with the sending Account Address and the Sequence value of the OfferCreate transaction that created it. These two fields, together, uniquely identify the Offer.

-

Ledger Index

-

A ledger index is a 32-bit unsigned integer used to identify a ledger. The ledger index is also known as the ledger's sequence number. The very first ledger was ledger index 1, and each new ledger has a ledger index 1 higher than that of the ledger immediately before it.

-

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

-
    -
  • Two different rippled servers may have different contents for a current ledger with the same ledger index, due to latency in propagating transactions throughout the network.
    • -
  • There may be multiple closed ledger versions competing to be validated by consensus. These ledger versions have the same sequence number but different contents (and different hashes). Only one of these closed ledgers can become validated.
    • -
  • A current ledger's contents change over time, which would cause its hash to change, even though its ledger index number stays the same. The hash of a ledger is not calculated until the ledger is closed.
    • -
-

Specifying Ledgers

-

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

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

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

-

If you do not specify a ledger, the current (in-progress) ledger is chosen by default. If you provide more than one field specifying ledgers, the deprecated ledger field is used first if it exists, falling back to ledger_hash. The ledger_index field is ignored unless neither of the other two are present.

-

Note: Do not rely on this default behavior for specifying a ledger; it is subject to change. Always specify a ledger version in the request if you can.

-

Currencies

-

There are two kinds of currencies in the XRP Ledger: XRP, and everything else. There are many differences between the two:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
XRPIssued Currencies
Has no issuer.Always issued by an XRP Ledger account
Specified as a stringSpecified as an object
Tracked in accountsTracked in trust lines
Can never be created; can only be destroyedCan be issued or redeemed freely
Maximum value 100000000000 (1e11)Maximum value 9999999999999999e80
Precise to the nearest "drop" (0.000001 XRP)15 decimal digits of precision, with a minimum nonzero absolute value of 1000000000000000e-96
-

Caution: The XRP Ledger uses decimal math with different precision than typical floating-point numbers, so currency amounts are always presented as strings.

-

Specifying Currency Amounts

-

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

-

XRP

-

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

-
"1000000"
-
-

Do not specify XRP as an object.

-

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

-

Non-XRP

-

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

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
currencyString - Currency CodeArbitrary code for currency to issue. Cannot be XRP.
valueStringQuoted decimal representation of the amount of currency. This can include scientific notation, such as 1.23e11 meaning 123,000,000,000. Both e and E may be used.
issuerStringUnique account address of the entity issuing the currency. In other words, the person or business where the currency can be redeemed.
-

Caution: These field names are case-sensitive.

-

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

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

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

-

Specifying Currencies Without Amounts

-

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

-

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

-

Finally, if the recipient account of the payment trusts multiple issuers for a currency, you can indicate that the payment should be made in any combination of issuers that the recipient accepts. To do this, specify the recipient account's address as the issuer value in the JSON object.

-

Currency Codes

-

There are two kinds of currency code in the XRP Ledger:

-
    -
  • Three-character currency code. We recommend using all-uppercase ISO 4217 Currency Codes. However, any combination of the following characters is permitted: all uppercase and lowercase letters, digits, as well as the symbols ?, !, @, #, $, %, ^, &, *, <, >, (, ), {, }, [, ], and |. The currency code XRP (all-uppercase) is reserved for XRP and cannot be used by issued currencies.
    • -
  • 160-bit hexadecimal values, such as 0158415500000000C1F76FF6ECB0BAC600000000, according to the XRP Ledger's internal Currency Format. This representation is uncommon.
    • -
-

Specifying Time

-

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

-

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

-

Possible Server States

-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ValueDescription
disconnectedThe server is not connected to the XRP Ledger peer-to-peer network whatsoever. It may be running in offline mode, or it may not be able to access the network for whatever reason.
connectedThe server believes it is connected to the network.
syncingThe server is currently behind on ledger versions. (It is normal for a server to spend a few minutes catching up after you start it.)
trackingThe server is in agreement with the network
fullThe server is fully caught-up with the network and could participate in validation, but is not doing so (possibly because it has not been configured as a validator).
validatingThe server is currently participating in validation of the ledger
proposingThe server is participating in validation of the ledger and currently proposing its own version.
-

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

-

Markers and Pagination

-

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

-

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

-

Modifying the Ledger

-

All changes to the XRP Ledger happen as the result of transactions. The only API methods that can change the contents of the XRP Ledger are the submit command and the submit_multisigned command. Most other methods represent different ways to view the data represented in the XRP Ledger. The remaining commands generate data for your convenience. (The wallet_propose, path_find, and random commands fall into this category.)

-

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

-

API Methods

-

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

-

List of Public Commands

- -

The owner_info command is deprecated. Use account_objects instead.

-

List of Admin Commands

-

Admin commands are only available if you connect to rippled on a host and port that the config file identifies as admin. (By default, the commandline client uses an admin connection.)

- -

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

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

Commandline Access

-

You can use the rippled application (as a separate instance) as a JSON-RPC client. In this mode, it has syntax for triggering most API methods with a single line from the command prompt, as described in each method. However, some methods or options don't have commandline syntax. For otherwise unsupported syntax, you can use the following method:

- -

Account Information

-

An "Account" in the XRP Ledger represents a holder of XRP and a sender of transactions. Accounts can send and receive XRP and issued assets, participate in the decentralized exchange, and change their own settings. Creating an account involves generating keys and then receiving XRP from another account. For more information, see Accounts.

-

account_currencies

-

[Source]

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-    "command": "account_currencies",
-    "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-    "strict": true,
-    "ledger_index": "validated"
-}
-
- -
{
-    "method": "account_currencies",
-    "params": [
-        {
-            "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-            "account_index": 0,
-            "ledger_index": "validated",
-            "strict": true
-        }
-    ]
-}
-
-
-

Try it!

-

The request includes the following parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
accountStringA unique identifier for the account, most commonly the account's Address.
strictBoolean(Optional) If true, only accept an address or public key for the account parameter. Defaults to false.
ledger_hashString(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger)
ledger_indexString or Unsigned Integer(Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)
-

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

-

Response Format

-

An example of a successful response:

-
- -
{
-    "result": {
-        "ledger_index": 11775844,
-        "receive_currencies": [
-            "BTC",
-            "CNY",
-            "DYM",
-            "EUR",
-            "JOE",
-            "MXN",
-            "USD",
-            "015841551A748AD2C1F76FF6ECB0CCCD00000000"
-        ],
-        "send_currencies": [
-            "ASP",
-            "BTC",
-            "CHF",
-            "CNY",
-            "DYM",
-            "EUR",
-            "JOE",
-            "JPY",
-            "MXN",
-            "USD"
-        ],
-        "validated": true
-    },
-    "status": "success",
-    "type": "response"
-}
-
- -
200 OK
-{
-    "result": {
-        "ledger_index": 11775823,
-        "receive_currencies": [
-            "BTC",
-            "CNY",
-            "DYM",
-            "EUR",
-            "JOE",
-            "MXN",
-            "USD",
-            "015841551A748AD2C1F76FF6ECB0CCCD00000000"
-        ],
-        "send_currencies": [
-            "ASP",
-            "BTC",
-            "CHF",
-            "CNY",
-            "DYM",
-            "EUR",
-            "JOE",
-            "JPY",
-            "MXN",
-            "USD"
-        ],
-        "status": "success",
-        "validated": true
-    }
-}
-
-
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
ledger_hashString - Hash(May be omitted) The identifying hash of the ledger version used to retrieve this data, as hex.
ledger_indexInteger - Ledger IndexThe sequence number of the ledger version used to retrieve this data.
receive_currenciesArray of StringsArray of Currency Codes for currencies that this account can receive.
send_currenciesArray of StringsArray of Currency Codes for currencies that this account can send.
validatedBooleanIf true, this data comes from a validated ledger.
-

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

-

Possible Errors

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

account_channels

-

[Source]

-

(Requires the PayChan amendment to be enabled. New in: rippled 0.33.0)

-

The account_channels method returns information about an account's Payment Channels. This includes only channels where the specified account is the channel's source, not the destination. (A channel's "source" and "owner" are the same.) All information retrieved is relative to a particular version of the ledger.

-

Request Format

-

An example of the request format:

-
- -
{
-  "id": 1,
-  "command": "account_channels",
-  "account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-  "destination_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-  "ledger_index": "validated"
-}
-
- -
{
-    "method": "account_channels",
-    "params": [{
-        "account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-        "destination_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-        "ledger_index": "validated"
-    }]
-}
-
- -
#Syntax: account_channels <account> [<destination_account>] [<ledger>]
-rippled account_channels rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn validated
-
-
-

The request includes the following parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
accountStringThe unique identifier of an account, typically the account's Address. The request returns channels where this account is the channel's owner/source.
destination_accountString(Optional) The unique identifier of an account, typically the account's Address. If provided, filter results to payment channels whose destination is this account.
ledger_hashString(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger)
ledger_indexString or Unsigned Integer(Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)
limitInteger(Optional) Limit the number of transactions to retrieve. The server is not required to honor this value. Must be within the inclusive range 10 to 400. Defaults to 200.
marker(Not Specified)(Optional) Value from a previous paginated response. Resume retrieving data where that response left off.
-

Response Format

-

An example of a successful response:

-
- -
{
-  "id": 2,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-    "channels": [
-      {
-        "account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-        "amount": "100000000",
-        "balance": "1000000",
-        "channel_id": "5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3",
-        "destination_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-        "destination_tag": 20170428,
-        "expiration": 547073182,
-        "public_key": "aB44YfzW24VDEJQ2UuLPV2PvqcPCSoLnL7y5M1EzhdW4LnK5xMS3",
-        "public_key_hex": "023693F15967AE357D0327974AD46FE3C127113B1110D6044FD41E723689F81CC6",
-        "settle_delay": 86400
-      }
-    ]
-  }
-}
-
- -
200 OK
-
-{
-    "result": {
-        "account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-        "channels": [{
-            "account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-            "amount": "100000000",
-            "balance": "0",
-            "channel_id": "5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3",
-            "destination_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-            "destination_tag": 20170428,
-            "public_key": "aB44YfzW24VDEJQ2UuLPV2PvqcPCSoLnL7y5M1EzhdW4LnK5xMS3",
-            "public_key_hex": "023693F15967AE357D0327974AD46FE3C127113B1110D6044FD41E723689F81CC6",
-            "settle_delay": 86400
-        }],
-        "status": "success"
-    }
-}
-
- -
200 OK
-
-{
-    "result": {
-        "account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-        "channels": [{
-            "account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-            "amount": "100000000",
-            "balance": "0",
-            "channel_id": "5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3",
-            "destination_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-            "destination_tag": 20170428,
-            "public_key": "aB44YfzW24VDEJQ2UuLPV2PvqcPCSoLnL7y5M1EzhdW4LnK5xMS3",
-            "public_key_hex": "023693F15967AE357D0327974AD46FE3C127113B1110D6044FD41E723689F81CC6",
-            "settle_delay": 86400
-        }],
-        "status": "success"
-    }
-}
-
-
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
accountStringThe address of the source/owner of the payment channels. This corresponds to the account field of the request.
channelsArray of Channel ObjectsPayment channels owned by this account.
limitNumber(May be omitted) The limit to how many channel objects were actually returned by this request.
marker(Not Specified)(May be omitted) Server-defined value for pagination. Pass this to the next call to resume getting results where this call left off. Omitted when there are no additional pages after this one.
-

Each Channel Object has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
accountStringThe owner of the channel, as an Address.
amountStringThe total amount of XRP, in drops allocated to this channel.
balanceStringThe total amount of XRP, in drops, paid out from this channel, as of the ledger version used. (You can calculate the amount of XRP remaining in the channel by subtracting balance from amount.)
channel_idStringA unique ID for this channel, as a 64-character hexadecimal string. This is also the index of the channel in the ledger's state data.
destination_accountStringthe destination account of the channel, as an Address. Only this account can receive the XRP in the channel while it remains open.
public_keyString(May be omitted) The public key for the payment channel in base58 format. Signed claims against this channel must be redeemed with the matching key pair.
public_key_hexString(May be omitted) The public key for the payment channel in hexadecimal format, if one was specified at channel creation. Signed claims against this channel must be redeemed with the matching key pair.
settle_delayUnsigned IntegerThe number of seconds the payment channel must remain open after the owner of the channel requests to close it.
expirationUnsigned Integer(May be omitted) Time, in seconds since the Ripple Epoch, when this channel is set to expire. This expiration date is mutable. If this is before the close time of the most recent validated ledger, the channel is expired.
cancel_afterUnsigned Integer(May be omitted) Time, in seconds since the Ripple Epoch, of this channel's immutable expiration, if one was specified at channel creation. If this is before the close time of the most recent validated ledger, the channel is expired.
source_tagUnsigned Integer(May be omitted) A 32-bit unsigned integer to use as a source tag for payments through this payment channel, if one was specified at channel creation. This indicates the payment channel's originator or other purpose at the source account. Conventionally, if you bounce payments from this channel, you should specify this value in the DestinationTag of the return payment.
destination_tagUnsigned Integer(May be omitted) A 32-bit unsigned integer to use as a destination tag for payments through this channel, if one was specified at channel creation. This indicates the payment channel's beneficiary or other purpose at the destination account.
-

Possible Errors

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

account_info

-

[Source]

-

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

-

Request Format

-

An example of an account_info request:

-
- -
{
-  "id": 2,
-  "command": "account_info",
-  "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-  "strict": true,
-  "ledger_index": "current",
-  "queue": true
-}
-
- -
{
-    "method": "account_info",
-    "params": [
-        {
-            "account": "rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn",
-            "strict": true,
-            "ledger_index": "current",
-            "queue": true
-        }
-    ]
-}
-
- -
#Syntax: account_info account [ledger_index|ledger_hash] [strict]
-rippled account_info r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 true
-
-
-

Try it!

-

The request contains the following parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
accountStringA unique identifier for the account, most commonly the account's Address.
strictBoolean(Optional, defaults to False) If set to True, then the account field only accepts a public key or XRP Ledger address.
ledger_hashString(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger)
ledger_indexString or Unsigned Integer(Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)
queueBoolean(Optional) If true, and the FeeEscalation amendment is enabled, also returns stats about queued transactions associated with this account. Can only be used when querying for the data from the current open ledger. New in: rippled 0.33.0
signer_listsBoolean(Optional) If true, and the MultiSign amendment is enabled, also returns any SignerList objects associated with this account. New in: rippled 0.31.0
-

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

-

Response Format

-

An example of a successful response:

-
- -
{
-    "id": 5,
-    "status": "success",
-    "type": "response",
-    "result": {
-        "account_data": {
-            "Account": "rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn",
-            "Balance": "999999999960",
-            "Flags": 8388608,
-            "LedgerEntryType": "AccountRoot",
-            "OwnerCount": 0,
-            "PreviousTxnID": "4294BEBE5B569A18C0A2702387C9B1E7146DC3A5850C1E87204951C6FDAA4C42",
-            "PreviousTxnLgrSeq": 3,
-            "Sequence": 6,
-            "index": "92FA6A9FC8EA6018D5D16532D7795C91BFB0831355BDFDA177E86C8BF997985F"
-        },
-        "ledger_current_index": 4,
-        "queue_data": {
-            "auth_change_queued": true,
-            "highest_sequence": 10,
-            "lowest_sequence": 6,
-            "max_spend_drops_total": "500",
-            "transactions": [
-                {
-                    "auth_change": false,
-                    "fee": "100",
-                    "fee_level": "2560",
-                    "max_spend_drops": "100",
-                    "seq": 6
-                },
-                ... (trimmed for length) ...
-                {
-                    "LastLedgerSequence": 10,
-                    "auth_change": true,
-                    "fee": "100",
-                    "fee_level": "2560",
-                    "max_spend_drops": "100",
-                    "seq": 10
-                }
-            ],
-            "txn_count": 5
-        },
-        "validated": false
-    }
-}
-
- -
{
-    "result": {
-        "account_data": {
-            "Account": "rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn",
-            "Balance": "999999999960",
-            "Flags": 8388608,
-            "LedgerEntryType": "AccountRoot",
-            "OwnerCount": 0,
-            "PreviousTxnID": "4294BEBE5B569A18C0A2702387C9B1E7146DC3A5850C1E87204951C6FDAA4C42",
-            "PreviousTxnLgrSeq": 3,
-            "Sequence": 6,
-            "index": "92FA6A9FC8EA6018D5D16532D7795C91BFB0831355BDFDA177E86C8BF997985F"
-        },
-        "ledger_current_index": 4,
-        "queue_data": {
-            "auth_change_queued": true,
-            "highest_sequence": 10,
-            "lowest_sequence": 6,
-            "max_spend_drops_total": "500",
-            "transactions": [
-                {
-                    "auth_change": false,
-                    "fee": "100",
-                    "fee_level": "2560",
-                    "max_spend_drops": "100",
-                    "seq": 6
-                },
-                ... (trimmed for length) ...
-                {
-                    "LastLedgerSequence": 10,
-                    "auth_change": true,
-                    "fee": "100",
-                    "fee_level": "2560",
-                    "max_spend_drops": "100",
-                    "seq": 10
-                }
-            ],
-            "txn_count": 5
-        },
-        "status": "success",
-        "validated": false
-    }
-}
-
-
-

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:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
account_dataObjectThe AccountRoot ledger node with this account's information, as stored in the ledger.
signer_listsArray(Omitted unless the request specified signer_lists and at least one SignerList is associated with the account.) Array of SignerList ledger nodes associated with this account for Multi-Signing. Since an account can own at most one SignerList, this array must have exactly one member if it is present. New in: rippled 0.31.0
ledger_current_indexInteger(Omitted if ledger_index is provided instead) The sequence number of the most-current ledger, which was used when retrieving this information. The information does not contain any changes from ledgers newer than this one.
ledger_indexInteger(Omitted if ledger_current_index is provided instead) The sequence number of the ledger used when retrieving this information. The information does not contain any changes from ledgers newer than this one.
queue_dataObject(Omitted unless queue specified as true and querying the current open ledger.) Information about queued transactions sent by this account. This information describes the state of the local rippled server, which may be different from other servers in the consensus network. Some fields may be omitted because the values are calculated "lazily" by the queuing mechanism.
validatedBooleanTrue if this data is from a validated ledger version; if omitted or set to false, this data is not final. New in: rippled 0.26.0
-

The queue_data parameter, if present, contains the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
txn_countIntegerNumber of queued transactions from this address.
auth_change_queuedBoolean(May be omitted) Whether a transaction in the queue changes this address's ways of authorizing transactions. If true, this address can queue no further transactions until that transaction has been executed or dropped from the queue.
lowest_sequenceInteger(May be omitted) The lowest Sequence Number among transactions queued by this address.
highest_sequenceInteger(May be omitted) The highest Sequence Number among transactions queued by this address.
max_spend_drops_totalString(May be omitted) Integer amount of drops of XRP that could be debited from this address if every transaction in the queue consumes the maximum amount of XRP possible.
transactionsArray(May be omitted) Information about each queued transaction from this address.
-

Each object in the transactions array, if present, may contain any or all of the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
auth_changeBooleanWhether this transaction changes this address's ways of authorizing transactions.
feeStringThe Transaction Cost of this transaction, in drops of XRP.
fee_levelStringThe transaction cost of this transaction, relative to the minimum cost for this type of transaction, in fee levels.
max_spend_dropsStringThe maximum amount of XRP, in drops, this transaction could send or destroy.
seqIntegerThe Sequence Number of this transaction.
-

Possible Errors

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

account_lines

-

[Source]

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-  "id": 1,
-  "command": "account_lines",
-  "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-  "ledger": "current"
-}
-
- -
{
-    "method": "account_lines",
-    "params": [
-        {
-            "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-            "ledger": "current"
-        }
-    ]
-}
-
-
-

Try it!

-

The request accepts the following paramters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
accountStringA unique identifier for the account, most commonly the account's Address.
ledger_hashString(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger)
ledger_indexString or Unsigned Integer(Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)
peerString(Optional) The Address of a second account. If provided, show only lines of trust connecting the two accounts.
limitInteger(Optional, default varies) Limit the number of transactions to retrieve. The server is not required to honor this value. Must be within the inclusive range 10 to 400. New in: rippled 0.26.4
marker(Not Specified)(Optional) Value from a previous paginated response. Resume retrieving data where that response left off. New in: rippled 0.26.4
-

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

-

Response Format

-

An example of a successful response:

-
- -
{
-    "id": 1,
-    "status": "success",
-    "type": "response",
-    "result": {
-        "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-        "lines": [
-            {
-                "account": "r3vi7mWxru9rJCxETCyA1CHvzL96eZWx5z",
-                "balance": "0",
-                "currency": "ASP",
-                "limit": "0",
-                "limit_peer": "10",
-                "quality_in": 0,
-                "quality_out": 0
-            },
-            {
-                "account": "r3vi7mWxru9rJCxETCyA1CHvzL96eZWx5z",
-                "balance": "0",
-                "currency": "XAU",
-                "limit": "0",
-                "limit_peer": "0",
-                "no_ripple": true,
-                "no_ripple_peer": true,
-                "quality_in": 0,
-                "quality_out": 0
-            },
-            {
-                "account": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-                "balance": "3.497605752725159",
-                "currency": "USD",
-                "limit": "5",
-                "limit_peer": "0",
-                "no_ripple": true,
-                "quality_in": 0,
-                "quality_out": 0
-            }
-        ]
-    }
-}
-
- -
200 OK
-{
-    "result": {
-        "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-        "lines": [
-            {
-                "account": "r3vi7mWxru9rJCxETCyA1CHvzL96eZWx5z",
-                "balance": "0",
-                "currency": "ASP",
-                "limit": "0",
-                "limit_peer": "10",
-                "quality_in": 0,
-                "quality_out": 0
-            },
-            {
-                "account": "r3vi7mWxru9rJCxETCyA1CHvzL96eZWx5z",
-                "balance": "0",
-                "currency": "XAU",
-                "limit": "0",
-                "limit_peer": "0",
-                "no_ripple": true,
-                "no_ripple_peer": true,
-                "quality_in": 0,
-                "quality_out": 0
-            },
-            {
-                "account": "rs9M85karFkCRjvc6KMWn8Coigm9cbcgcx",
-                "balance": "0",
-                "currency": "015841551A748AD2C1F76FF6ECB0CCCD00000000",
-                "limit": "10.01037626125837",
-                "limit_peer": "0",
-                "no_ripple": true,
-                "quality_in": 0,
-                "quality_out": 0
-            }
-        ],
-        "status": "success"
-    }
-}
-
-
-

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:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
accountStringUnique Address of the account this request corresponds to. This is the "perspective account" for purpose of the trust lines.
linesArrayArray of trust line objects, as described below. If the number of trust lines is large, only returns up to the limit at a time.
ledger_current_indexInteger(Omitted if ledger_hash or ledger_index provided) Sequence number of the ledger version used when retrieving this data. New in: rippled 0.26.4-sp1
ledger_indexInteger(Omitted if ledger_current_index provided instead) Sequence number, provided in the request, of the ledger version that was used when retrieving this data. New in: rippled 0.26.4-sp1
ledger_hashString(May be omitted) Hex hash, provided in the request, of the ledger version that was used when retrieving this data. New in: rippled 0.26.4-sp1
marker(Not Specified)Server-defined value indicating the response is paginated. Pass this to the next call to resume where this call left off. Omitted when there are no additional pages after this one. New in: rippled 0.26.4
-

Each trust line object has some combination of the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
accountStringThe unique Address of the counterparty to this trust line.
balanceStringRepresentation of the numeric balance currently held against this line. A positive balance means that the perspective account holds value; a negative balance means that the perspective account owes value.
currencyStringA Currency Code identifying what currency this trust line can hold.
limitStringThe maximum amount of the given currency that this account is willing to owe the peer account
limit_peerStringThe maximum amount of currency that the counterparty account is willing to owe the perspective account
quality_inUnsigned IntegerRate at which the account values incoming balances on this trust line, as a ratio of this value per 1 billion units. (For example, a value of 500 million represents a 0.5:1 ratio.) As a special case, 0 is treated as a 1:1 ratio.
quality_outUnsigned IntegerRate at which the account values outgoing balances on this trust line, as a ratio of this value per 1 billion units. (For example, a value of 500 million represents a 0.5:1 ratio.) As a special case, 0 is treated as a 1:1 ratio.
no_rippleBoolean(May be omitted) true if this account has enabled the NoRipple flag for this line. If omitted, that is the same as false.
no_ripple_peerBoolean(May be omitted) true if the peer account has enabled the NoRipple flag. If omitted, that is the same as false.
freezeBoolean(May be omitted) true if this account has frozen this trust line. If omitted, that is the same as false.
freeze_peerBoolean(May be omitted) true if the peer account has frozen this trust line. If omitted, that is the same as false.
-

Possible Errors

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

account_offers

-

[Source]

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-  "id": 2,
-  "command": "account_offers",
-  "account": "rpP2JgiMyTF5jR5hLG3xHCPi1knBb1v9cM",
-  "ledger": "current"
-}
-
- -
{
-    "method": "account_offers",
-    "params": [
-        {
-            "account": "rpP2JgiMyTF5jR5hLG3xHCPi1knBb1v9cM",
-            "ledger_index": "current"
-        }
-    ]
-}
-
- -
#Syntax: account_offers account [ledger_index]
-rippled account_offers r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 current
-
-
-

Try it!

-

A request can include the following parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
accountStringA unique identifier for the account, most commonly the account's Address.
ledgerUnsigned integer, or String(Deprecated, Optional) A unique identifier for the ledger version to use, such as a ledger sequence number, a hash, or a shortcut such as "validated".
ledger_hashString(Optional) A 20-byte hex string identifying the ledger version to use.
ledger_index(Optional) Ledger Index(Optional, defaults to current) The sequence number of the ledger to use, or "current", "closed", or "validated" to select a ledger dynamically. (See Specifying Ledgers)
limitInteger(Optional, default varies) Limit the number of transactions to retrieve. The server is not required to honor this value. Must be within the inclusive range 10 to 400. New in: rippled 0.26.4
marker(Not Specified)Value from a previous paginated response. Resume retrieving data where that response left off. New in: rippled 0.26.4
-

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

-

Response Format

-

An example of a successful response:

-
- -
{
-  "id": 9,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "account": "rpP2JgiMyTF5jR5hLG3xHCPi1knBb1v9cM",
-    "ledger_current_index": 18539550,
-    "offers": [
-      {
-        "flags": 0,
-        "quality": "0.00000000574666765650638",
-        "seq": 6577664,
-        "taker_gets": "33687728098",
-        "taker_pays": {
-          "currency": "EUR",
-          "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
-          "value": "193.5921774819578"
-        }
-      },
-      {
-        "flags": 0,
-        "quality": "7989247009094510e-27",
-        "seq": 6572128,
-        "taker_gets": "2361918758",
-        "taker_pays": {
-          "currency": "XAU",
-          "issuer": "rrh7rf1gV2pXAoqA8oYbpHd8TKv5ZQeo67",
-          "value": "0.01886995237307572"
-        }
-      },
-      ... trimmed for length ...
-    ],
-    "validated": false
-  }
-}
-
- -
200 OK
-{
-    "result": {
-        "account": "rpP2JgiMyTF5jR5hLG3xHCPi1knBb1v9cM",
-        "ledger_current_index": 18539596,
-        "offers": [{
-            "flags": 0,
-            "quality": "0.000000007599140009999998",
-            "seq": 6578020,
-            "taker_gets": "29740867287",
-            "taker_pays": {
-                "currency": "USD",
-                "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-                "value": "226.0050145327418"
-            }
-        }, {
-            "flags": 0,
-            "quality": "7989247009094510e-27",
-            "seq": 6572128,
-            "taker_gets": "2361918758",
-            "taker_pays": {
-                "currency": "XAU",
-                "issuer": "rrh7rf1gV2pXAoqA8oYbpHd8TKv5ZQeo67",
-                "value": "0.01886995237307572"
-            }
-        }, {
-            "flags": 0,
-            "quality": "0.00000004059594001318974",
-            "seq": 6576905,
-            "taker_gets": "3892952574",
-            "taker_pays": {
-                "currency": "CNY",
-                "issuer": "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y",
-                "value": "158.0380691682966"
-            }
-        },
-
-        ...
-
-        ],
-        "status": "success",
-        "validated": false
-    }
-}
-
-
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
accountStringUnique Address identifying the account that made the offers
offersArrayArray of objects, where each object represents an offer made by this account that is outstanding as of the requested ledger version. If the number of offers is large, only returns up to limit at a time.
ledger_current_indexInteger(Omitted if ledger_hash or ledger_index provided) Sequence number of the ledger version used when retrieving this data. New in: rippled 0.26.4-sp1
ledger_indexInteger(Omitted if ledger_current_index provided instead) Sequence number, provided in the request, of the ledger version that was used when retrieving this data. New in: rippled 0.26.4-sp1
ledger_hashString(May be omitted) Hex hash, provided in the request, of the ledger version that was used when retrieving this data. New in: rippled 0.26.4-sp1
marker(Not Specified)Server-defined value indicating the response is paginated. Pass this to the next call to resume where this call left off. Omitted when there are no pages of information after this one. New in: rippled 0.26.4
-

Each offer object contains the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
flagsUnsigned integerOptions set for this offer entry as bit-flags.
seqUnsigned integerSequence number of the transaction that created this entry. (Transaction sequence numbers are relative to accounts.)
taker_getsString 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)
taker_paysString 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)
qualityNumberThe exchange rate of the offer, as the ratio of the original taker_pays divided by the original taker_gets. When executing offers, the offer with the most favorable (lowest) quality is consumed first; offers with the same quality are executed from oldest to newest. New in: rippled 0.29.0
expirationUnsigned integer(May be omitted) A time after which this offer is considered unfunded, as the number of seconds since the Ripple Epoch. See also: Offer Expiration. New in: rippled 0.30.1
-

Possible Errors

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

account_objects

-

[Source]

-

The account_objects command returns the raw ledger format for all objects owned by an account. For a higher-level view of an account's trust lines and balances, see account_lines instead.

-

The types of objects that may appear in the account_objects response for an account include:

- -

Request Format

-

An example of the request format:

-
- -
{
-  "id": 1,
-  "command": "account_objects",
-  "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-  "ledger_index": "validated",
-  "type": "state",
-  "limit": 10
-}
-
- -
{
-    "method": "account_objects",
-    "params": [
-        {
-            "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-            "ledger_index": "validated",
-            "limit": 10,
-            "type": "state"
-        }
-    ]
-}
-
- -
#Syntax: account_objects <account> [<ledger>]
-rippled account_objects r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 validated
-
-
-

The request includes the following parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
accountStringA unique identifier for the account, most commonly the account's address.
typeString(Optional) If included, filter results to include only this type of ledger node. Valid types include state (trust lines), offer (offers), and ticket (part of the forthcoming signing process).
ledger_hashString(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger)
ledger_indexString or Unsigned Integer(Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)
limitUnsigned Integer(Optional) The maximum number of objects to include in the results. Must be within the inclusive range 10 to 400 on non-admin connections. Defaults to 200.
marker(Not Specified)(Optional) Value from a previous paginated response. Resume retrieving data where that response left off.
-

Response Format

-

An example of a successful response:

-
- -
{
-    "id": 8,
-    "status": "success",
-    "type": "response",
-    "result": {
-        "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-        "account_objects": [
-            {
-                "Balance": {
-                    "currency": "ASP",
-                    "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                    "value": "0"
-                },
-                "Flags": 65536,
-                "HighLimit": {
-                    "currency": "ASP",
-                    "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "value": "0"
-                },
-                "HighNode": "0000000000000000",
-                "LedgerEntryType": "RippleState",
-                "LowLimit": {
-                    "currency": "ASP",
-                    "issuer": "r3vi7mWxru9rJCxETCyA1CHvzL96eZWx5z",
-                    "value": "10"
-                },
-                "LowNode": "0000000000000000",
-                "PreviousTxnID": "BF7555B0F018E3C5E2A3FF9437A1A5092F32903BE246202F988181B9CED0D862",
-                "PreviousTxnLgrSeq": 1438879,
-                "index": "2243B0B630EA6F7330B654EFA53E27A7609D9484E535AB11B7F946DF3D247CE9"
-            },
-            {
-                "Balance": {
-                    "currency": "XAU",
-                    "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                    "value": "0"
-                },
-                "Flags": 3342336,
-                "HighLimit": {
-                    "currency": "XAU",
-                    "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "value": "0"
-                },
-                "HighNode": "0000000000000000",
-                "LedgerEntryType": "RippleState",
-                "LowLimit": {
-                    "currency": "XAU",
-                    "issuer": "r3vi7mWxru9rJCxETCyA1CHvzL96eZWx5z",
-                    "value": "0"
-                },
-                "LowNode": "0000000000000000",
-                "PreviousTxnID": "79B26D7D34B950AC2C2F91A299A6888FABB376DD76CFF79D56E805BF439F6942",
-                "PreviousTxnLgrSeq": 5982530,
-                "index": "9ED4406351B7A511A012A9B5E7FE4059FA2F7650621379C0013492C315E25B97"
-            },
-            {
-                "Balance": {
-                    "currency": "USD",
-                    "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                    "value": "0"
-                },
-                "Flags": 1114112,
-                "HighLimit": {
-                    "currency": "USD",
-                    "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-                    "value": "0"
-                },
-                "HighNode": "0000000000000000",
-                "LedgerEntryType": "RippleState",
-                "LowLimit": {
-                    "currency": "USD",
-                    "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "value": "5"
-                },
-                "LowNode": "0000000000000000",
-                "PreviousTxnID": "6FE8C824364FB1195BCFEDCB368DFEE3980F7F78D3BF4DC4174BB4C86CF8C5CE",
-                "PreviousTxnLgrSeq": 10555014,
-                "index": "2DECFAC23B77D5AEA6116C15F5C6D4669EBAEE9E7EE050A40FE2B1E47B6A9419"
-            },
-            {
-                "Balance": {
-                    "currency": "MXN",
-                    "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                    "value": "481.992867407479"
-                },
-                "Flags": 65536,
-                "HighLimit": {
-                    "currency": "MXN",
-                    "issuer": "rHpXfibHgSb64n8kK9QWDpdbfqSpYbM9a4",
-                    "value": "0"
-                },
-                "HighNode": "0000000000000000",
-                "LedgerEntryType": "RippleState",
-                "LowLimit": {
-                    "currency": "MXN",
-                    "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "value": "1000"
-                },
-                "LowNode": "0000000000000000",
-                "PreviousTxnID": "A467BACE5F183CDE1F075F72435FE86BAD8626ED1048EDEFF7562A4CC76FD1C5",
-                "PreviousTxnLgrSeq": 3316170,
-                "index": "EC8B9B6B364AF6CB6393A423FDD2DDBA96375EC772E6B50A3581E53BFBDFDD9A"
-            },
-            {
-                "Balance": {
-                    "currency": "EUR",
-                    "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                    "value": "0.793598266778297"
-                },
-                "Flags": 1114112,
-                "HighLimit": {
-                    "currency": "EUR",
-                    "issuer": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
-                    "value": "0"
-                },
-                "HighNode": "0000000000000000",
-                "LedgerEntryType": "RippleState",
-                "LowLimit": {
-                    "currency": "EUR",
-                    "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "value": "1"
-                },
-                "LowNode": "0000000000000000",
-                "PreviousTxnID": "E9345D44433EA368CFE1E00D84809C8E695C87FED18859248E13662D46A0EC46",
-                "PreviousTxnLgrSeq": 5447146,
-                "index": "4513749B30F4AF8DA11F077C448128D6486BF12854B760E4E5808714588AA915"
-            },
-            {
-                "Balance": {
-                    "currency": "CNY",
-                    "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                    "value": "0"
-                },
-                "Flags": 2228224,
-                "HighLimit": {
-                    "currency": "CNY",
-                    "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "value": "3"
-                },
-                "HighNode": "0000000000000000",
-                "LedgerEntryType": "RippleState",
-                "LowLimit": {
-                    "currency": "CNY",
-                    "issuer": "rnuF96W4SZoCJmbHYBFoJZpR8eCaxNvekK",
-                    "value": "0"
-                },
-                "LowNode": "0000000000000008",
-                "PreviousTxnID": "2FDDC81F4394695B01A47913BEC4281AC9A283CC8F903C14ADEA970F60E57FCF",
-                "PreviousTxnLgrSeq": 5949673,
-                "index": "578C327DA8944BDE2E10C9BA36AFA2F43E06C8D1E8819FB225D266CBBCFDE5CE"
-            },
-            {
-                "Balance": {
-                    "currency": "DYM",
-                    "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                    "value": "1.336889190631542"
-                },
-                "Flags": 65536,
-                "HighLimit": {
-                    "currency": "DYM",
-                    "issuer": "rGwUWgN5BEg3QGNY3RX2HfYowjUTZdid3E",
-                    "value": "0"
-                },
-                "HighNode": "0000000000000000",
-                "LedgerEntryType": "RippleState",
-                "LowLimit": {
-                    "currency": "DYM",
-                    "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "value": "3"
-                },
-                "LowNode": "0000000000000000",
-                "PreviousTxnID": "6DA2BD02DFB83FA4DAFC2651860B60071156171E9C021D9E0372A61A477FFBB1",
-                "PreviousTxnLgrSeq": 8818732,
-                "index": "5A2A5FF12E71AEE57564E624117BBA68DEF78CD564EF6259F92A011693E027C7"
-            },
-            {
-                "Balance": {
-                    "currency": "CHF",
-                    "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                    "value": "-0.3488146605801446"
-                },
-                "Flags": 131072,
-                "HighLimit": {
-                    "currency": "CHF",
-                    "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "value": "0"
-                },
-                "HighNode": "0000000000000000",
-                "LedgerEntryType": "RippleState",
-                "LowLimit": {
-                    "currency": "CHF",
-                    "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-                    "value": "0"
-                },
-                "LowNode": "000000000000008C",
-                "PreviousTxnID": "722394372525A13D1EAAB005642F50F05A93CF63F7F472E0F91CDD6D38EB5869",
-                "PreviousTxnLgrSeq": 2687590,
-                "index": "F2DBAD20072527F6AD02CE7F5A450DBC72BE2ABB91741A8A3ADD30D5AD7A99FB"
-            },
-            {
-                "Balance": {
-                    "currency": "BTC",
-                    "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                    "value": "0"
-                },
-                "Flags": 131072,
-                "HighLimit": {
-                    "currency": "BTC",
-                    "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "value": "3"
-                },
-                "HighNode": "0000000000000000",
-                "LedgerEntryType": "RippleState",
-                "LowLimit": {
-                    "currency": "BTC",
-                    "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-                    "value": "0"
-                },
-                "LowNode": "0000000000000043",
-                "PreviousTxnID": "03EDF724397D2DEE70E49D512AECD619E9EA536BE6CFD48ED167AE2596055C9A",
-                "PreviousTxnLgrSeq": 8317037,
-                "index": "767C12AF647CDF5FEB9019B37018748A79C50EDAF87E8D4C7F39F78AA7CA9765"
-            },
-            {
-                "Balance": {
-                    "currency": "USD",
-                    "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                    "value": "-16.00534471983042"
-                },
-                "Flags": 131072,
-                "HighLimit": {
-                    "currency": "USD",
-                    "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "value": "5000"
-                },
-                "HighNode": "0000000000000000",
-                "LedgerEntryType": "RippleState",
-                "LowLimit": {
-                    "currency": "USD",
-                    "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-                    "value": "0"
-                },
-                "LowNode": "000000000000004A",
-                "PreviousTxnID": "CFFF5CFE623C9543308C6529782B6A6532207D819795AAFE85555DB8BF390FE7",
-                "PreviousTxnLgrSeq": 14365854,
-                "index": "826CF5BFD28F3934B518D0BDF3231259CBD3FD0946E3C3CA0C97D2C75D2D1A09"
-            }
-        ],
-        "ledger_hash": "053DF17D2289D1C4971C22F235BC1FCA7D4B3AE966F842E5819D0749E0B8ECD3",
-        "ledger_index": 14378733,
-        "limit": 10,
-        "marker": "F60ADF645E78B69857D2E4AEC8B7742FEABC8431BD8611D099B428C3E816DF93,94A9F05FEF9A153229E2E997E64919FD75AAE2028C8153E8EBDB4440BD3ECBB5",
-        "validated": true
-    }
-}
-
- -
200 OK
-{
-    "result": {
-        "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-        "account_objects": [
-            {
-                "Balance": {
-                    "currency": "ASP",
-                    "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                    "value": "0"
-                },
-                "Flags": 65536,
-                "HighLimit": {
-                    "currency": "ASP",
-                    "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "value": "0"
-                },
-                "HighNode": "0000000000000000",
-                "LedgerEntryType": "RippleState",
-                "LowLimit": {
-                    "currency": "ASP",
-                    "issuer": "r3vi7mWxru9rJCxETCyA1CHvzL96eZWx5z",
-                    "value": "10"
-                },
-                "LowNode": "0000000000000000",
-                "PreviousTxnID": "BF7555B0F018E3C5E2A3FF9437A1A5092F32903BE246202F988181B9CED0D862",
-                "PreviousTxnLgrSeq": 1438879,
-                "index": "2243B0B630EA6F7330B654EFA53E27A7609D9484E535AB11B7F946DF3D247CE9"
-            },
-            {
-                "Balance": {
-                    "currency": "XAU",
-                    "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                    "value": "0"
-                },
-                "Flags": 3342336,
-                "HighLimit": {
-                    "currency": "XAU",
-                    "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "value": "0"
-                },
-                "HighNode": "0000000000000000",
-                "LedgerEntryType": "RippleState",
-                "LowLimit": {
-                    "currency": "XAU",
-                    "issuer": "r3vi7mWxru9rJCxETCyA1CHvzL96eZWx5z",
-                    "value": "0"
-                },
-                "LowNode": "0000000000000000",
-                "PreviousTxnID": "79B26D7D34B950AC2C2F91A299A6888FABB376DD76CFF79D56E805BF439F6942",
-                "PreviousTxnLgrSeq": 5982530,
-                "index": "9ED4406351B7A511A012A9B5E7FE4059FA2F7650621379C0013492C315E25B97"
-            },
-            {
-                "Balance": {
-                    "currency": "USD",
-                    "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                    "value": "0"
-                },
-                "Flags": 1114112,
-                "HighLimit": {
-                    "currency": "USD",
-                    "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-                    "value": "0"
-                },
-                "HighNode": "0000000000000000",
-                "LedgerEntryType": "RippleState",
-                "LowLimit": {
-                    "currency": "USD",
-                    "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "value": "5"
-                },
-                "LowNode": "0000000000000000",
-                "PreviousTxnID": "6FE8C824364FB1195BCFEDCB368DFEE3980F7F78D3BF4DC4174BB4C86CF8C5CE",
-                "PreviousTxnLgrSeq": 10555014,
-                "index": "2DECFAC23B77D5AEA6116C15F5C6D4669EBAEE9E7EE050A40FE2B1E47B6A9419"
-            },
-            {
-                "Balance": {
-                    "currency": "MXN",
-                    "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                    "value": "481.992867407479"
-                },
-                "Flags": 65536,
-                "HighLimit": {
-                    "currency": "MXN",
-                    "issuer": "rHpXfibHgSb64n8kK9QWDpdbfqSpYbM9a4",
-                    "value": "0"
-                },
-                "HighNode": "0000000000000000",
-                "LedgerEntryType": "RippleState",
-                "LowLimit": {
-                    "currency": "MXN",
-                    "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "value": "1000"
-                },
-                "LowNode": "0000000000000000",
-                "PreviousTxnID": "A467BACE5F183CDE1F075F72435FE86BAD8626ED1048EDEFF7562A4CC76FD1C5",
-                "PreviousTxnLgrSeq": 3316170,
-                "index": "EC8B9B6B364AF6CB6393A423FDD2DDBA96375EC772E6B50A3581E53BFBDFDD9A"
-            },
-            {
-                "Balance": {
-                    "currency": "EUR",
-                    "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                    "value": "0.793598266778297"
-                },
-                "Flags": 1114112,
-                "HighLimit": {
-                    "currency": "EUR",
-                    "issuer": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
-                    "value": "0"
-                },
-                "HighNode": "0000000000000000",
-                "LedgerEntryType": "RippleState",
-                "LowLimit": {
-                    "currency": "EUR",
-                    "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "value": "1"
-                },
-                "LowNode": "0000000000000000",
-                "PreviousTxnID": "E9345D44433EA368CFE1E00D84809C8E695C87FED18859248E13662D46A0EC46",
-                "PreviousTxnLgrSeq": 5447146,
-                "index": "4513749B30F4AF8DA11F077C448128D6486BF12854B760E4E5808714588AA915"
-            },
-            {
-                "Balance": {
-                    "currency": "CNY",
-                    "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                    "value": "0"
-                },
-                "Flags": 2228224,
-                "HighLimit": {
-                    "currency": "CNY",
-                    "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "value": "3"
-                },
-                "HighNode": "0000000000000000",
-                "LedgerEntryType": "RippleState",
-                "LowLimit": {
-                    "currency": "CNY",
-                    "issuer": "rnuF96W4SZoCJmbHYBFoJZpR8eCaxNvekK",
-                    "value": "0"
-                },
-                "LowNode": "0000000000000008",
-                "PreviousTxnID": "2FDDC81F4394695B01A47913BEC4281AC9A283CC8F903C14ADEA970F60E57FCF",
-                "PreviousTxnLgrSeq": 5949673,
-                "index": "578C327DA8944BDE2E10C9BA36AFA2F43E06C8D1E8819FB225D266CBBCFDE5CE"
-            },
-            {
-                "Balance": {
-                    "currency": "DYM",
-                    "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                    "value": "1.336889190631542"
-                },
-                "Flags": 65536,
-                "HighLimit": {
-                    "currency": "DYM",
-                    "issuer": "rGwUWgN5BEg3QGNY3RX2HfYowjUTZdid3E",
-                    "value": "0"
-                },
-                "HighNode": "0000000000000000",
-                "LedgerEntryType": "RippleState",
-                "LowLimit": {
-                    "currency": "DYM",
-                    "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "value": "3"
-                },
-                "LowNode": "0000000000000000",
-                "PreviousTxnID": "6DA2BD02DFB83FA4DAFC2651860B60071156171E9C021D9E0372A61A477FFBB1",
-                "PreviousTxnLgrSeq": 8818732,
-                "index": "5A2A5FF12E71AEE57564E624117BBA68DEF78CD564EF6259F92A011693E027C7"
-            },
-            {
-                "Balance": {
-                    "currency": "CHF",
-                    "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                    "value": "-0.3488146605801446"
-                },
-                "Flags": 131072,
-                "HighLimit": {
-                    "currency": "CHF",
-                    "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "value": "0"
-                },
-                "HighNode": "0000000000000000",
-                "LedgerEntryType": "RippleState",
-                "LowLimit": {
-                    "currency": "CHF",
-                    "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-                    "value": "0"
-                },
-                "LowNode": "000000000000008C",
-                "PreviousTxnID": "722394372525A13D1EAAB005642F50F05A93CF63F7F472E0F91CDD6D38EB5869",
-                "PreviousTxnLgrSeq": 2687590,
-                "index": "F2DBAD20072527F6AD02CE7F5A450DBC72BE2ABB91741A8A3ADD30D5AD7A99FB"
-            },
-            {
-                "Balance": {
-                    "currency": "BTC",
-                    "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                    "value": "0"
-                },
-                "Flags": 131072,
-                "HighLimit": {
-                    "currency": "BTC",
-                    "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "value": "3"
-                },
-                "HighNode": "0000000000000000",
-                "LedgerEntryType": "RippleState",
-                "LowLimit": {
-                    "currency": "BTC",
-                    "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-                    "value": "0"
-                },
-                "LowNode": "0000000000000043",
-                "PreviousTxnID": "03EDF724397D2DEE70E49D512AECD619E9EA536BE6CFD48ED167AE2596055C9A",
-                "PreviousTxnLgrSeq": 8317037,
-                "index": "767C12AF647CDF5FEB9019B37018748A79C50EDAF87E8D4C7F39F78AA7CA9765"
-            },
-            {
-                "Balance": {
-                    "currency": "USD",
-                    "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                    "value": "-16.00534471983042"
-                },
-                "Flags": 131072,
-                "HighLimit": {
-                    "currency": "USD",
-                    "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "value": "5000"
-                },
-                "HighNode": "0000000000000000",
-                "LedgerEntryType": "RippleState",
-                "LowLimit": {
-                    "currency": "USD",
-                    "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-                    "value": "0"
-                },
-                "LowNode": "000000000000004A",
-                "PreviousTxnID": "CFFF5CFE623C9543308C6529782B6A6532207D819795AAFE85555DB8BF390FE7",
-                "PreviousTxnLgrSeq": 14365854,
-                "index": "826CF5BFD28F3934B518D0BDF3231259CBD3FD0946E3C3CA0C97D2C75D2D1A09"
-            }
-        ],
-        "ledger_hash": "4C99E5F63C0D0B1C2283B4F5DCE2239F80CE92E8B1A6AED1E110C198FC96E659",
-        "ledger_index": 14380380,
-        "limit": 10,
-        "marker": "F60ADF645E78B69857D2E4AEC8B7742FEABC8431BD8611D099B428C3E816DF93,94A9F05FEF9A153229E2E997E64919FD75AAE2028C8153E8EBDB4440BD3ECBB5",
-        "status": "success",
-        "validated": true
-    }
-}
-
-
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
accountStringUnique Address of the account this request corresponds to
account_objectsArrayArray of objects owned by this account. Each object is in its raw ledger format.
ledger_hashString(May be omitted) The identifying hash of the ledger that was used to generate this response.
ledger_indexNumber(May be omitted) The sequence number of the ledger version that was used to generate this response.
ledger_current_indexNumber(May be omitted) The sequence number of the current in-progress ledger version that was used to generate this response.
limitNumber(May be omitted) The limit that was used in this request, if any.
marker(Not Specified)Server-defined value indicating the response is paginated. Pass this to the next call to resume where this call left off. Omitted when there are no additional pages after this one.
validatedBooleanIf true, this information comes from ledger version that has been validated by consensus.
-

Possible Errors

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

account_tx

-

[Source]

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-  "id": 2,
-  "command": "account_tx",
-  "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-  "ledger_index_min": -1,
-  "ledger_index_max": -1,
-  "binary": false,
-  "count": false,
-  "limit": 2,
-  "forward": false
-}
-
- -
{
-    "method": "account_tx",
-    "params": [
-        {
-            "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-            "binary": false,
-            "count": false,
-            "descending": false,
-            "forward": false,
-            "ledger_index_max": -1,
-            "ledger_index_min": -1,
-            "limit": 2,
-            "offset": 1
-        }
-    ]
-}
-
- -
#Syntax account_tx account [ledger_index_min [ledger_index_max [limit]]] [binary] [count] [forward]
-rippled account_tx r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 -1 -1 2 false false false
-
-
-

Try it!

-

The request includes the following parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
accountStringA unique identifier for the account, most commonly the account's address.
ledger_index_minIntegerUse to specify the earliest ledger to include transactions from. A value of -1 instructs the server to use the earliest validated ledger version available.
ledger_index_maxIntegerUse to specify the most recent ledger to include transactions from. A value of -1 instructs the server to use the most recent validated ledger version available.
ledger_hashString(Optional) Use instead of ledger_index_min and ledger_index_max to look for transactions from a single ledger only. (See Specifying a Ledger)
ledger_indexString or Unsigned Integer(Optional) Use instead of ledger_index_min and ledger_index_max to look for transactions from a single ledger only. (See Specifying a Ledger)
binaryBoolean(Optional, defaults to False) If set to True, return transactions as hex strings instead of JSON.
forwardboolean(Optional, defaults to False) If set to True, return values indexed with the oldest ledger first. Otherwise, the results are indexed with the newest ledger first. (Each page of results may not be internally ordered, but the pages are overall ordered.)
limitInteger(Optional, default varies) Limit the number of transactions to retrieve. The server is not required to honor this value.
marker(Not Specified)Value from a previous paginated response. Resume retrieving data where that response left off. This value is stable even if there is a change in the server's range of available ledgers.
-

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

-
Iterating over queried data
-

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

-

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

-

Response Format

-

An example of a successful response:

-
- -
{
-    "id": 2,
-    "status": "success",
-    "type": "response",
-    "result": {
-        "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-        "ledger_index_max": 6542489,
-        "ledger_index_min": 32570,
-        "limit": 2,
-        "offset": 1,
-        "transactions": [
-            {
-                "meta": {
-                    "AffectedNodes": [
-                        {
-                            "ModifiedNode": {
-                                "FinalFields": {
-                                    "Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                                    "Balance": "9999999980",
-                                    "Flags": 0,
-                                    "OwnerCount": 2,
-                                    "Sequence": 3
-                                },
-                                "LedgerEntryType": "AccountRoot",
-                                "LedgerIndex": "4F83A2CF7E70F77F79A307E6A472BFC2585B806A70833CCD1C26105BAE0D6E05",
-                                "PreviousFields": {
-                                    "Balance": "9999999990",
-                                    "OwnerCount": 1,
-                                    "Sequence": 2
-                                },
-                                "PreviousTxnID": "389720F6FD8A144F171708F9ECB334D704CBCFEFBCDA152D931AC34FB5F9E32B",
-                                "PreviousTxnLgrSeq": 95405
-                            }
-                        },
-                        {
-                            "CreatedNode": {
-                                "LedgerEntryType": "RippleState",
-                                "LedgerIndex": "718C6D58DD3BBAAAEBFE48B8FBE3C32C9F6F2EBC395233BA95D0057078EE07DB",
-                                "NewFields": {
-                                    "Balance": {
-                                        "currency": "USD",
-                                        "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                                        "value": "0"
-                                    },
-                                    "Flags": 131072,
-                                    "HighLimit": {
-                                        "currency": "USD",
-                                        "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                                        "value": "100"
-                                    },
-                                    "LowLimit": {
-                                        "currency": "USD",
-                                        "issuer": "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV",
-                                        "value": "0"
-                                    }
-                                }
-                            }
-                        },
-                        {
-                            "ModifiedNode": {
-                                "FinalFields": {
-                                    "Flags": 0,
-                                    "Owner": "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV",
-                                    "RootIndex": "77F65EFF930ED7E93C6CC839C421E394D6B1B6A47CEA8A140D63EC9C712F46F5"
-                                },
-                                "LedgerEntryType": "DirectoryNode",
-                                "LedgerIndex": "77F65EFF930ED7E93C6CC839C421E394D6B1B6A47CEA8A140D63EC9C712F46F5"
-                            }
-                        },
-                        {
-                            "ModifiedNode": {
-                                "FinalFields": {
-                                    "Account": "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV",
-                                    "Balance": "78991384535796",
-                                    "Flags": 0,
-                                    "OwnerCount": 3,
-                                    "Sequence": 188
-                                },
-                                "LedgerEntryType": "AccountRoot",
-                                "LedgerIndex": "B33FDD5CF3445E1A7F2BE9B06336BEBD73A5E3EE885D3EF93F7E3E2992E46F1A",
-                                "PreviousTxnID": "E9E1988A0F061679E5D14DE77DB0163CE0BBDC00F29E396FFD1DA0366E7D8904",
-                                "PreviousTxnLgrSeq": 195455
-                            }
-                        },
-                        {
-                            "ModifiedNode": {
-                                "FinalFields": {
-                                    "ExchangeRate": "4E11C37937E08000",
-                                    "Flags": 0,
-                                    "RootIndex": "F60ADF645E78B69857D2E4AEC8B7742FEABC8431BD8611D099B428C3E816DF93",
-                                    "TakerGetsCurrency": "0000000000000000000000000000000000000000",
-                                    "TakerGetsIssuer": "0000000000000000000000000000000000000000",
-                                    "TakerPaysCurrency": "0000000000000000000000004254430000000000",
-                                    "TakerPaysIssuer": "5E7B112523F68D2F5E879DB4EAC51C6698A69304"
-                                },
-                                "LedgerEntryType": "DirectoryNode",
-                                "LedgerIndex": "F60ADF645E78B69857D2E4AEC8B7742FEABC8431BD8611D099B428C3E816DF93"
-                            }
-                        }
-                    ],
-                    "TransactionIndex": 0,
-                    "TransactionResult": "tesSUCCESS"
-                },
-                "tx": {
-                    "Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "Fee": "10",
-                    "Flags": 0,
-                    "LimitAmount": {
-                        "currency": "USD",
-                        "issuer": "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV",
-                        "value": "100"
-                    },
-                    "Sequence": 2,
-                    "SigningPubKey": "02BC8C02199949B15C005B997E7C8594574E9B02BA2D0628902E0532989976CF9D",
-                    "TransactionType": "TrustSet",
-                    "TxnSignature": "304402200EF81EC32E0DFA9BE376B20AFCA11765ED9FEA04CA8B77C7178DAA699F7F5AFF02202DA484DBD66521AC317D84F7717EC4614E2F5DB743E313E8B48440499CC0DBA4",
-                    "date": 413620090,
-                    "hash": "002AA492496A1543DBD3680BF8CF21B6D6A078CE4A01D2C1A4B63778033792CE",
-                    "inLedger": 195480,
-                    "ledger_index": 195480
-                },
-                "validated": true
-            },
-            {
-                "meta": {
-                    "AffectedNodes": [
-                        {
-                            "ModifiedNode": {
-                                "FinalFields": {
-                                    "Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                                    "Balance": "9999999970",
-                                    "Flags": 0,
-                                    "OwnerCount": 3,
-                                    "Sequence": 4
-                                },
-                                "LedgerEntryType": "AccountRoot",
-                                "LedgerIndex": "4F83A2CF7E70F77F79A307E6A472BFC2585B806A70833CCD1C26105BAE0D6E05",
-                                "PreviousFields": {
-                                    "Balance": "9999999980",
-                                    "OwnerCount": 2,
-                                    "Sequence": 3
-                                },
-                                "PreviousTxnID": "002AA492496A1543DBD3680BF8CF21B6D6A078CE4A01D2C1A4B63778033792CE",
-                                "PreviousTxnLgrSeq": 195480
-                            }
-                        },
-                        {
-                            "ModifiedNode": {
-                                "FinalFields": {
-                                    "Flags": 0,
-                                    "Owner": "r3PDtZSa5LiYp1Ysn1vMuMzB59RzV3W9QH",
-                                    "RootIndex": "A39F044D860C5B5846AA7E0FAAD44DC8897F0A62B2F628AA073B21B3EC146010"
-                                },
-                                "LedgerEntryType": "DirectoryNode",
-                                "LedgerIndex": "A39F044D860C5B5846AA7E0FAAD44DC8897F0A62B2F628AA073B21B3EC146010"
-                            }
-                        },
-                        {
-                            "ModifiedNode": {
-                                "LedgerEntryType": "AccountRoot",
-                                "LedgerIndex": "E0D7BDE68B468FF0B8D948FD865576517DA987569833A05374ADB9A72E870A06",
-                                "PreviousTxnID": "0222B59280D165D40C464EA75AAD08A4D152C46A38C0625DEECF6EE87FC5B9E1",
-                                "PreviousTxnLgrSeq": 343555
-                            }
-                        },
-                        {
-                            "CreatedNode": {
-                                "LedgerEntryType": "RippleState",
-                                "LedgerIndex": "EA4BF03B4700123CDFFB6EB09DC1D6E28D5CEB7F680FB00FC24BC1C3BB2DB959",
-                                "NewFields": {
-                                    "Balance": {
-                                        "currency": "USD",
-                                        "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                                        "value": "0"
-                                    },
-                                    "Flags": 131072,
-                                    "HighLimit": {
-                                        "currency": "USD",
-                                        "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                                        "value": "100"
-                                    },
-                                    "LowLimit": {
-                                        "currency": "USD",
-                                        "issuer": "r3PDtZSa5LiYp1Ysn1vMuMzB59RzV3W9QH",
-                                        "value": "0"
-                                    }
-                                }
-                            }
-                        },
-                        {
-                            "ModifiedNode": {
-                                "FinalFields": {
-                                    "ExchangeRate": "4E11C37937E08000",
-                                    "Flags": 0,
-                                    "RootIndex": "F60ADF645E78B69857D2E4AEC8B7742FEABC8431BD8611D099B428C3E816DF93",
-                                    "TakerGetsCurrency": "0000000000000000000000000000000000000000",
-                                    "TakerGetsIssuer": "0000000000000000000000000000000000000000",
-                                    "TakerPaysCurrency": "0000000000000000000000004254430000000000",
-                                    "TakerPaysIssuer": "5E7B112523F68D2F5E879DB4EAC51C6698A69304"
-                                },
-                                "LedgerEntryType": "DirectoryNode",
-                                "LedgerIndex": "F60ADF645E78B69857D2E4AEC8B7742FEABC8431BD8611D099B428C3E816DF93"
-                            }
-                        }
-                    ],
-                    "TransactionIndex": 0,
-                    "TransactionResult": "tesSUCCESS"
-                },
-                "tx": {
-                    "Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "Fee": "10",
-                    "Flags": 0,
-                    "LimitAmount": {
-                        "currency": "USD",
-                        "issuer": "r3PDtZSa5LiYp1Ysn1vMuMzB59RzV3W9QH",
-                        "value": "100"
-                    },
-                    "Sequence": 3,
-                    "SigningPubKey": "02BC8C02199949B15C005B997E7C8594574E9B02BA2D0628902E0532989976CF9D",
-                    "TransactionType": "TrustSet",
-                    "TxnSignature": "3044022058A89552068D1A274EE72BA71363E33E54E6608BC28A84DEC6EE530FC2B5C979022029F4D1EA1237A1F717C5F5EC526E6CFB6DF54C30BADD25EDDE7D2FDBC8F17E34",
-                    "date": 416347560,
-                    "hash": "53354D84BAE8FDFC3F4DA879D984D24B929E7FEB9100D2AD9EFCD2E126BCCDC8",
-                    "inLedger": 343570,
-                    "ledger_index": 343570
-                },
-                "validated": true
-            }
-        ],
-        "validated": true
-    }
-}
-
- -
200 OK
-{
-    "result": {
-        "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-        "ledger_index_max": 8696227,
-        "ledger_index_min": 32570,
-        "limit": 2,
-        "offset": 1,
-        "status": "success",
-        "transactions": [
-            {
-                "meta": {
-                    "AffectedNodes": [
-                        {
-                            "ModifiedNode": {
-                                "FinalFields": {
-                                    "Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                                    "Balance": "9999999980",
-                                    "Flags": 0,
-                                    "OwnerCount": 2,
-                                    "Sequence": 3
-                                },
-                                "LedgerEntryType": "AccountRoot",
-                                "LedgerIndex": "4F83A2CF7E70F77F79A307E6A472BFC2585B806A70833CCD1C26105BAE0D6E05",
-                                "PreviousFields": {
-                                    "Balance": "9999999990",
-                                    "OwnerCount": 1,
-                                    "Sequence": 2
-                                },
-                                "PreviousTxnID": "389720F6FD8A144F171708F9ECB334D704CBCFEFBCDA152D931AC34FB5F9E32B",
-                                "PreviousTxnLgrSeq": 95405
-                            }
-                        },
-                        {
-                            "CreatedNode": {
-                                "LedgerEntryType": "RippleState",
-                                "LedgerIndex": "718C6D58DD3BBAAAEBFE48B8FBE3C32C9F6F2EBC395233BA95D0057078EE07DB",
-                                "NewFields": {
-                                    "Balance": {
-                                        "currency": "USD",
-                                        "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                                        "value": "0"
-                                    },
-                                    "Flags": 131072,
-                                    "HighLimit": {
-                                        "currency": "USD",
-                                        "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                                        "value": "100"
-                                    },
-                                    "LowLimit": {
-                                        "currency": "USD",
-                                        "issuer": "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV",
-                                        "value": "0"
-                                    }
-                                }
-                            }
-                        },
-                        {
-                            "ModifiedNode": {
-                                "FinalFields": {
-                                    "Flags": 0,
-                                    "Owner": "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV",
-                                    "RootIndex": "77F65EFF930ED7E93C6CC839C421E394D6B1B6A47CEA8A140D63EC9C712F46F5"
-                                },
-                                "LedgerEntryType": "DirectoryNode",
-                                "LedgerIndex": "77F65EFF930ED7E93C6CC839C421E394D6B1B6A47CEA8A140D63EC9C712F46F5"
-                            }
-                        },
-                        {
-                            "ModifiedNode": {
-                                "FinalFields": {
-                                    "Account": "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV",
-                                    "Balance": "78991384535796",
-                                    "Flags": 0,
-                                    "OwnerCount": 3,
-                                    "Sequence": 188
-                                },
-                                "LedgerEntryType": "AccountRoot",
-                                "LedgerIndex": "B33FDD5CF3445E1A7F2BE9B06336BEBD73A5E3EE885D3EF93F7E3E2992E46F1A",
-                                "PreviousTxnID": "E9E1988A0F061679E5D14DE77DB0163CE0BBDC00F29E396FFD1DA0366E7D8904",
-                                "PreviousTxnLgrSeq": 195455
-                            }
-                        },
-                        {
-                            "ModifiedNode": {
-                                "FinalFields": {
-                                    "ExchangeRate": "4E11C37937E08000",
-                                    "Flags": 0,
-                                    "RootIndex": "F60ADF645E78B69857D2E4AEC8B7742FEABC8431BD8611D099B428C3E816DF93",
-                                    "TakerGetsCurrency": "0000000000000000000000000000000000000000",
-                                    "TakerGetsIssuer": "0000000000000000000000000000000000000000",
-                                    "TakerPaysCurrency": "0000000000000000000000004254430000000000",
-                                    "TakerPaysIssuer": "5E7B112523F68D2F5E879DB4EAC51C6698A69304"
-                                },
-                                "LedgerEntryType": "DirectoryNode",
-                                "LedgerIndex": "F60ADF645E78B69857D2E4AEC8B7742FEABC8431BD8611D099B428C3E816DF93"
-                            }
-                        }
-                    ],
-                    "TransactionIndex": 0,
-                    "TransactionResult": "tesSUCCESS"
-                },
-                "tx": {
-                    "Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "Fee": "10",
-                    "Flags": 0,
-                    "LimitAmount": {
-                        "currency": "USD",
-                        "issuer": "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV",
-                        "value": "100"
-                    },
-                    "Sequence": 2,
-                    "SigningPubKey": "02BC8C02199949B15C005B997E7C8594574E9B02BA2D0628902E0532989976CF9D",
-                    "TransactionType": "TrustSet",
-                    "TxnSignature": "304402200EF81EC32E0DFA9BE376B20AFCA11765ED9FEA04CA8B77C7178DAA699F7F5AFF02202DA484DBD66521AC317D84F7717EC4614E2F5DB743E313E8B48440499CC0DBA4",
-                    "date": 413620090,
-                    "hash": "002AA492496A1543DBD3680BF8CF21B6D6A078CE4A01D2C1A4B63778033792CE",
-                    "inLedger": 195480,
-                    "ledger_index": 195480
-                },
-                "validated": true
-            },
-            {
-                "meta": {
-                    "AffectedNodes": [
-                        {
-                            "ModifiedNode": {
-                                "FinalFields": {
-                                    "Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                                    "Balance": "9999999970",
-                                    "Flags": 0,
-                                    "OwnerCount": 3,
-                                    "Sequence": 4
-                                },
-                                "LedgerEntryType": "AccountRoot",
-                                "LedgerIndex": "4F83A2CF7E70F77F79A307E6A472BFC2585B806A70833CCD1C26105BAE0D6E05",
-                                "PreviousFields": {
-                                    "Balance": "9999999980",
-                                    "OwnerCount": 2,
-                                    "Sequence": 3
-                                },
-                                "PreviousTxnID": "002AA492496A1543DBD3680BF8CF21B6D6A078CE4A01D2C1A4B63778033792CE",
-                                "PreviousTxnLgrSeq": 195480
-                            }
-                        },
-                        {
-                            "ModifiedNode": {
-                                "FinalFields": {
-                                    "Flags": 0,
-                                    "Owner": "r3PDtZSa5LiYp1Ysn1vMuMzB59RzV3W9QH",
-                                    "RootIndex": "A39F044D860C5B5846AA7E0FAAD44DC8897F0A62B2F628AA073B21B3EC146010"
-                                },
-                                "LedgerEntryType": "DirectoryNode",
-                                "LedgerIndex": "A39F044D860C5B5846AA7E0FAAD44DC8897F0A62B2F628AA073B21B3EC146010"
-                            }
-                        },
-                        {
-                            "ModifiedNode": {
-                                "LedgerEntryType": "AccountRoot",
-                                "LedgerIndex": "E0D7BDE68B468FF0B8D948FD865576517DA987569833A05374ADB9A72E870A06",
-                                "PreviousTxnID": "0222B59280D165D40C464EA75AAD08A4D152C46A38C0625DEECF6EE87FC5B9E1",
-                                "PreviousTxnLgrSeq": 343555
-                            }
-                        },
-                        {
-                            "CreatedNode": {
-                                "LedgerEntryType": "RippleState",
-                                "LedgerIndex": "EA4BF03B4700123CDFFB6EB09DC1D6E28D5CEB7F680FB00FC24BC1C3BB2DB959",
-                                "NewFields": {
-                                    "Balance": {
-                                        "currency": "USD",
-                                        "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                                        "value": "0"
-                                    },
-                                    "Flags": 131072,
-                                    "HighLimit": {
-                                        "currency": "USD",
-                                        "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                                        "value": "100"
-                                    },
-                                    "LowLimit": {
-                                        "currency": "USD",
-                                        "issuer": "r3PDtZSa5LiYp1Ysn1vMuMzB59RzV3W9QH",
-                                        "value": "0"
-                                    }
-                                }
-                            }
-                        },
-                        {
-                            "ModifiedNode": {
-                                "FinalFields": {
-                                    "ExchangeRate": "4E11C37937E08000",
-                                    "Flags": 0,
-                                    "RootIndex": "F60ADF645E78B69857D2E4AEC8B7742FEABC8431BD8611D099B428C3E816DF93",
-                                    "TakerGetsCurrency": "0000000000000000000000000000000000000000",
-                                    "TakerGetsIssuer": "0000000000000000000000000000000000000000",
-                                    "TakerPaysCurrency": "0000000000000000000000004254430000000000",
-                                    "TakerPaysIssuer": "5E7B112523F68D2F5E879DB4EAC51C6698A69304"
-                                },
-                                "LedgerEntryType": "DirectoryNode",
-                                "LedgerIndex": "F60ADF645E78B69857D2E4AEC8B7742FEABC8431BD8611D099B428C3E816DF93"
-                            }
-                        }
-                    ],
-                    "TransactionIndex": 0,
-                    "TransactionResult": "tesSUCCESS"
-                },
-                "tx": {
-                    "Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                    "Fee": "10",
-                    "Flags": 0,
-                    "LimitAmount": {
-                        "currency": "USD",
-                        "issuer": "r3PDtZSa5LiYp1Ysn1vMuMzB59RzV3W9QH",
-                        "value": "100"
-                    },
-                    "Sequence": 3,
-                    "SigningPubKey": "02BC8C02199949B15C005B997E7C8594574E9B02BA2D0628902E0532989976CF9D",
-                    "TransactionType": "TrustSet",
-                    "TxnSignature": "3044022058A89552068D1A274EE72BA71363E33E54E6608BC28A84DEC6EE530FC2B5C979022029F4D1EA1237A1F717C5F5EC526E6CFB6DF54C30BADD25EDDE7D2FDBC8F17E34",
-                    "date": 416347560,
-                    "hash": "53354D84BAE8FDFC3F4DA879D984D24B929E7FEB9100D2AD9EFCD2E126BCCDC8",
-                    "inLedger": 343570,
-                    "ledger_index": 343570
-                },
-                "validated": true
-            }
-        ],
-        "validated": true
-    }
-}
-
-
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
accountStringUnique Address identifying the related account
ledger_index_minIntegerThe sequence number of the earliest ledger actually searched for transactions.
ledger_index_maxIntegerThe sequence number of the most recent ledger actually searched for transactions.
limitIntegerThe limit value used in the request. (This may differ from the actual limit value enforced by the server.)
marker(Not Specified)Server-defined value indicating the response is paginated. Pass this to the next call to resume where this call left off.
offsetIntegerThe offset value used in the request.
transactionsArrayArray of transactions matching the request's criteria, as explained below.
validatedBooleanIf included and set to true, the information in this request comes from a validated ledger version. Otherwise, the information is subject to change.
-

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

-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
ledger_indexIntegerThe sequence number of the ledger version that included this transaction.
metaObject (JSON) or String (Binary)If binary is True, then this is a hex string of the transaction metadata. Otherwise, the transaction metadata is included in JSON format.
txObject(JSON mode only) JSON object defining the transaction
tx_blobString(Binary mode only) Unique hashed String representing the transaction.
validatedBooleanWhether or not the transaction is included in a validated ledger. Any transaction not yet in a validated ledger is subject to change.
-

Possible Errors

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

noripple_check

-

[Source]

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-    "id": 0,
-    "command": "noripple_check",
-    "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-    "role": "gateway",
-    "ledger_index": "current",
-    "limit": 2,
-    "transactions": true
-}
-
- -
{
-    "method": "noripple_check",
-    "params": [
-        {
-            "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-            "ledger_index": "current",
-            "limit": 2,
-            "role": "gateway",
-            "transactions": true
-        }
-    ]
-}
-
-
-

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

-

The request includes the following parameters:

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

Response Format

-

An example of a successful response:

-
- -
{
-  "id": 0,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "ledger_current_index": 14342939,
-    "problems": [
-      "You should immediately set your default ripple flag",
-      "You should clear the no ripple flag on your XAU line to r3vi7mWxru9rJCxETCyA1CHvzL96eZWx5z",
-      "You should clear the no ripple flag on your USD line to rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q"
-    ],
-    "transactions": [
-      {
-        "Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-        "Fee": 10000,
-        "Sequence": 1406,
-        "SetFlag": 8,
-        "TransactionType": "AccountSet"
-      },
-      {
-        "Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-        "Fee": 10000,
-        "Flags": 262144,
-        "LimitAmount": {
-          "currency": "XAU",
-          "issuer": "r3vi7mWxru9rJCxETCyA1CHvzL96eZWx5z",
-          "value": "0"
-        },
-        "Sequence": 1407,
-        "TransactionType": "TrustSet"
-      },
-      {
-        "Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-        "Fee": 10000,
-        "Flags": 262144,
-        "LimitAmount": {
-          "currency": "USD",
-          "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-          "value": "5"
-        },
-        "Sequence": 1408,
-        "TransactionType": "TrustSet"
-      }
-    ],
-    "validated": false
-  }
-}
-
- -
200 OK
-{
-    "result": {
-        "ledger_current_index": 14380381,
-        "problems": [
-            "You should immediately set your default ripple flag",
-            "You should clear the no ripple flag on your XAU line to r3vi7mWxru9rJCxETCyA1CHvzL96eZWx5z",
-            "You should clear the no ripple flag on your USD line to rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-        ],
-        "status": "success",
-        "transactions": [
-            {
-                "Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                "Fee": 10000,
-                "Sequence": 1406,
-                "SetFlag": 8,
-                "TransactionType": "AccountSet"
-            },
-            {
-                "Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                "Fee": 10000,
-                "Flags": 262144,
-                "LimitAmount": {
-                    "currency": "XAU",
-                    "issuer": "r3vi7mWxru9rJCxETCyA1CHvzL96eZWx5z",
-                    "value": "0"
-                },
-                "Sequence": 1407,
-                "TransactionType": "TrustSet"
-            },
-            {
-                "Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                "Fee": 10000,
-                "Flags": 262144,
-                "LimitAmount": {
-                    "currency": "USD",
-                    "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-                    "value": "5"
-                },
-                "Sequence": 1408,
-                "TransactionType": "TrustSet"
-            }
-        ],
-        "validated": false
-    }
-}
-
-
-

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

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

Possible Errors

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

gateway_balances

-

[Source]

-

The gateway_balances command calculates the total balances issued by a given account, optionally excluding amounts held by operational addresses. New in: rippled 0.28.2

-

Request Format

-

An example of the request format:

-
- -
{
-    "id": "example_gateway_balances_1",
-    "command": "gateway_balances",
-    "account": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-    "strict": true,
-    "hotwallet": ["rKm4uWpg9tfwbVSeATv4KxDe6mpE9yPkgJ","ra7JkEzrgeKHdzKgo4EUUVBnxggY4z37kt"],
-    "ledger_index": "validated"
-}
-
- -
{
-    "method": "gateway_balances",
-    "params": [
-        {
-            "account": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-            "hotwallet": [
-                "rKm4uWpg9tfwbVSeATv4KxDe6mpE9yPkgJ",
-                "ra7JkEzrgeKHdzKgo4EUUVBnxggY4z37kt"
-            ],
-            "ledger_index": "validated",
-            "strict": true
-        }
-    ]
-}
-
-
-

The request includes the following parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
accountStringThe Address to check. This should be the issuing address
strictBoolean(Optional) If true, only accept an address or public key for the account parameter. Defaults to false.
hotwalletString or ArrayAn operational address to exclude from the balances issued, or an array of such addresses.
ledger_hashString(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger)
ledger_indexString or Unsigned Integer(Optional) The sequence number of the ledger version to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)
-

Response Format

-

An example of a successful response:

-
- -
{
-  "id": 3,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "account": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-    "assets": {
-      "r9F6wk8HkXrgYWoJ7fsv4VrUBVoqDVtzkH": [
-        {
-          "currency": "BTC",
-          "value": "5444166510000000e-26"
-        }
-      ],
-      "rPFLkxQk6xUGdGYEykqe7PR25Gr7mLHDc8": [
-        {
-          "currency": "EUR",
-          "value": "4000000000000000e-27"
-        }
-      ],
-      "rPU6VbckqCLW4kb51CWqZdxvYyQrQVsnSj": [
-        {
-          "currency": "BTC",
-          "value": "1029900000000000e-26"
-        }
-      ],
-      "rpR95n1iFkTqpoy1e878f4Z1pVHVtWKMNQ": [
-        {
-          "currency": "BTC",
-          "value": "4000000000000000e-30"
-        }
-      ],
-      "rwmUaXsWtXU4Z843xSYwgt1is97bgY8yj6": [
-        {
-          "currency": "BTC",
-          "value": "8700000000000000e-30"
-        }
-      ]
-    },
-    "balances": {
-      "rKm4uWpg9tfwbVSeATv4KxDe6mpE9yPkgJ": [
-        {
-          "currency": "EUR",
-          "value": "29826.1965999999"
-        }
-      ],
-      "ra7JkEzrgeKHdzKgo4EUUVBnxggY4z37kt": [
-        {
-          "currency": "USD",
-          "value": "13857.70416"
-        }
-      ]
-    },
-    "ledger_hash": "61DDBF304AF6E8101576BF161D447CA8E4F0170DDFBEAFFD993DC9383D443388",
-    "ledger_index": 14483195,
-    "obligations": {
-      "BTC": "5908.324927635318",
-      "EUR": "992471.7419793958",
-      "GBP": "4991.38706013193",
-      "USD": "1997134.20229482"
-    },
-    "validated": true
-  }
-}
-
- -
200 OK
-{
-    "result": {
-        "account": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-        "assets": {
-            "r9F6wk8HkXrgYWoJ7fsv4VrUBVoqDVtzkH": [
-                {
-                    "currency": "BTC",
-                    "value": "5444166510000000e-26"
-                }
-            ],
-            "rPFLkxQk6xUGdGYEykqe7PR25Gr7mLHDc8": [
-                {
-                    "currency": "EUR",
-                    "value": "4000000000000000e-27"
-                }
-            ],
-            "rPU6VbckqCLW4kb51CWqZdxvYyQrQVsnSj": [
-                {
-                    "currency": "BTC",
-                    "value": "1029900000000000e-26"
-                }
-            ],
-            "rpR95n1iFkTqpoy1e878f4Z1pVHVtWKMNQ": [
-                {
-                    "currency": "BTC",
-                    "value": "4000000000000000e-30"
-                }
-            ],
-            "rwmUaXsWtXU4Z843xSYwgt1is97bgY8yj6": [
-                {
-                    "currency": "BTC",
-                    "value": "8700000000000000e-30"
-                }
-            ]
-        },
-        "balances": {
-            "rKm4uWpg9tfwbVSeATv4KxDe6mpE9yPkgJ": [
-                {
-                    "currency": "EUR",
-                    "value": "29826.1965999999"
-                }
-            ],
-            "ra7JkEzrgeKHdzKgo4EUUVBnxggY4z37kt": [
-                {
-                    "currency": "USD",
-                    "value": "13857.70416"
-                }
-            ]
-        },
-        "ledger_hash": "980FECF48CA4BFDEC896692C31A50D484BDFE865EC101B00259C413AA3DBD672",
-        "ledger_index": 14483212,
-        "obligations": {
-            "BTC": "5908.324927635318",
-            "EUR": "992471.7419793958",
-            "GBP": "4991.38706013193",
-            "USD": "1997134.20229482"
-        },
-        "status": "success",
-        "validated": true
-    }
-}
-
-
-

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

-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
obligationsObject(Omitted if empty) Total amounts issued to addresses not excluded, as a map of currencies to the total value issued.
balancesObject(Omitted if empty) Amounts issued to the hotwallet addresses from the request. The keys are addresses and the values are arrays of currency amounts they hold.
assetsObject(Omitted if empty) Total amounts held that are issued by others. In the recommended configuration, the issuing address should have none.
ledger_hashString(May be omitted) The identifying hash of the ledger that was used to generate this response.
ledger_indexNumber(May be omitted) The sequence number of the ledger version that was used to generate this response.
ledger_current_indexNumber(May be omitted) The sequence number of the current in-progress ledger version that was used to generate this response.
-

Possible Errors

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

wallet_propose

-

[Source]

-

Use the wallet_propose method to generate a key pair and XRP Ledger address. This command only generates keys, and does not affect the XRP Ledger itself in any way. To become a funded address stored in the ledger, the address must receive a Payment transaction that provides enough XRP to meet the reserve requirement.

-

The wallet_propose request is an admin command that cannot be run by unprivileged users! (This command is restricted to protect against people sniffing network traffic for account secrets, since admin commands are not usually transmitted over the outside network.)

-

Updated in: rippled 0.31.0

-

Request Format

-

An example of the request format:

-
- -
{
-    "command": "wallet_propose",
-    "seed": "snoPBrXtMeMyMHUVTgbuqAfg1SUTb",
-    "key_type": "secp256k1"
-}
-
- -
{
-    "command": "wallet_propose",
-    "passphrase": "masterpassphrase"
-}
-
- -
{
-    "method": "wallet_propose",
-    "params": [
-        {
-            "seed": "snoPBrXtMeMyMHUVTgbuqAfg1SUTb",
-            "key_type": "secp256k1"
-        }
-    ]
-}
-
- -
{
-    "method": "wallet_propose",
-    "params": [
-        {
-            "passphrase": "snoPBrXtMeMyMHUVTgbuqAfg1SUTb"
-        }
-    ]
-}
-
- -
#Syntax: wallet_propose [passphrase]
-rippled wallet_propose masterpassphrase
-
-
-

The request can contain the following parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
key_typeStringWhich elliptic curve to use for this key pair. Valid values are ed25519 and secp256k1 (all lower case). Defaults to secp256k1.
passphraseString(Optional) Generate a key pair and address from this seed value. This value can be formatted in hexadecimal, base58, RFC-1751, or as an arbitrary string. Cannot be used with seed or seed_hex.
seedString(Optional) Generate the key pair and address from this base58-encoded seed value. Cannot be used with passphrase or seed_hex.
seed_hexString(Optional) Generate the key pair and address from this seed value in hexadecimal format. Cannot be used with passphrase or seed.
-

You must provide at most one of the following fields: passphrase, seed, or seed_hex. If you omit all three, rippled uses a random seed.

-

Note: Ed25519 support is experimental. The commandline version of this command cannot generate Ed25519 keys.

-
Specifying a Seed
-

For most cases, you should use a seed value generated from a strong source of randomness. Anyone who knows the seed value for an address has full power to send transactions signed by that address. Generally, running this command with no parameters is a good way to generate a random seed.

-

Cases where you would specify a known seed include:

-
    -
  • Re-calculating your address when you only know the seed associated with that address
    • -
  • Testing rippled functionality
    • -
-

If you do specify a seed, you can specify it in any of the following formats:

-
    -
  • As a base58 secret key format string. Example: snoPBrXtMeMyMHUVTgbuqAfg1SUTb.
    • -
  • As an RFC-1751 format string (secp256k1 key pairs only). Example: I IRE BOND BOW TRIO LAID SEAT GOAL HEN IBIS IBIS DARE.
    • -
  • As a 128-bit hexadecimal string. Example: DEDCE9CE67B451D852FD4E846FCDE31C.
    • -
  • An arbitrary string to use as a seed value. For example: masterpassphrase.
    • -
-

Response Format

-

An example of a successful response:

-
- -
{
-  "id": 2,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "account_id": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
-    "key_type": "secp256k1",
-    "master_key": "I IRE BOND BOW TRIO LAID SEAT GOAL HEN IBIS IBIS DARE",
-    "master_seed": "snoPBrXtMeMyMHUVTgbuqAfg1SUTb",
-    "master_seed_hex": "DEDCE9CE67B451D852FD4E846FCDE31C",
-    "public_key": "aBQG8RQAzjs1eTKFEAQXr2gS4utcDiEC9wmi7pfUPTi27VCahwgw",
-    "public_key_hex": "0330E7FC9D56BB25D6893BA3F317AE5BCF33B3291BD63DB32654A313222F7FD020"
-  }
-}
-
- -
{
-    "result": {
-        "account_id": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
-        "key_type": "secp256k1",
-        "master_key": "I IRE BOND BOW TRIO LAID SEAT GOAL HEN IBIS IBIS DARE",
-        "master_seed": "snoPBrXtMeMyMHUVTgbuqAfg1SUTb",
-        "master_seed_hex": "DEDCE9CE67B451D852FD4E846FCDE31C",
-        "public_key": "aBQG8RQAzjs1eTKFEAQXr2gS4utcDiEC9wmi7pfUPTi27VCahwgw",
-        "public_key_hex": "0330E7FC9D56BB25D6893BA3F317AE5BCF33B3291BD63DB32654A313222F7FD020",
-        "status": "success"
-    }
-}
-
- -
Loading: "/etc/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "account_id" : "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
-      "key_type" : "secp256k1",
-      "master_key" : "I IRE BOND BOW TRIO LAID SEAT GOAL HEN IBIS IBIS DARE",
-      "master_seed" : "snoPBrXtMeMyMHUVTgbuqAfg1SUTb",
-      "master_seed_hex" : "DEDCE9CE67B451D852FD4E846FCDE31C",
-      "public_key" : "aBQG8RQAzjs1eTKFEAQXr2gS4utcDiEC9wmi7pfUPTi27VCahwgw",
-      "public_key_hex" : "0330E7FC9D56BB25D6893BA3F317AE5BCF33B3291BD63DB32654A313222F7FD020",
-      "status" : "success"
-   }
-}
-
-
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
master_seedStringThe master seed from which all other information about this account is derived, in Ripple's base58 encoded string format. This is the private key of the key pair.
master_seed_hexStringThe master seed, in hex format.
master_keyStringThe master seed, in RFC 1751 format.
account_idStringThe Address of the account.
public_keyStringThe public key of the account, in encoded string format.
public_key_hexStringThe public key of the account, in hex format.
warningString(May be omitted) If the request specified a seed value, this field provides a warning that it may be insecure. New in: rippled 0.32.0
-

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

-

Possible Errors

-
    -
  • Any of the universal error types.
    • -
  • invalidParams - One or more fields are specified incorrectly.
    • -
  • badSeed - The request specified a disallowed seed value (in the passphrase, seed, or seed_hex fields), such as an empty string, or a string resembling a XRP Ledger address.
    • -
-

Ledger Information

-

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

-

ledger

-

[Source]

-

Retrieve information about the public ledger.

-

Request Format

-

An example of the request format:

-
- -
{
-    "id": 14,
-    "command": "ledger",
-    "ledger_index": "validated",
-    "full": false,
-    "accounts": false,
-    "transactions": false,
-    "expand": false,
-    "owner_funds": false
-}
-
- -
{
-    "method": "ledger",
-    "params": [
-        {
-            "ledger_index": "validated",
-            "accounts": false,
-            "full": false,
-            "transactions": false,
-            "expand": false,
-            "owner_funds": false
-        }
-    ]
-}
-
- -
#Syntax: ledger ledger_index|ledger_hash [full|tx]
-# "full" is equivalent to "full": true
-# "tx" is equivalent to "transactions": true
-rippled ledger current
-
-
-

Try it!

-

The request can contain the following parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
ledger_hashString(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger).
ledger_indexString or Unsigned Integer(Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)
fullBoolean(Optional) Admin required If true, return full information on the entire ledger. Ignored if you did not specify a ledger version. Defaults to false. (Equivalent to enabling transactions, accounts, and expand.) Caution: This is a very large amount of data -- on the order of several hundred megabytes!
accountsBoolean(Optional) Admin required. If true, return information on accounts in the ledger. Ignored if you did not specify a ledger version. Defaults to false. Caution: This returns a very large amount of data!
transactionsBoolean(Optional) If true, return information on transactions in the specified ledger version. Defaults to false. Ignored if you did not specify a ledger version.
expandBoolean(Optional) Provide full JSON-formatted information for transaction/account information instead of only hashes. Defaults to false. Ignored unless you request transactions, accounts, or both.
owner_fundsBoolean(Optional) If true, include owner_funds field in the metadata of OfferCreate transactions in the response. Defaults to false. Ignored unless transactions are included and expand is true.
binaryBoolean(Optional) If true, and transactions and expand are both also true, return transaction information in binary format (hexadecimal string) instead of JSON format. New in: rippled 0.28.0
queueBoolean(Optional) If true, and the command is requesting the current ledger, includes an array of queued transactions in the results.
-

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

-

Response Format

-

An example of a successful response:

-
- -
{
-  "id": 4,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "ledger": {
-      "accepted": true,
-      "account_hash": "FD2709F6C07284C3EE85EDE32AC452D9013A89D9B9E781D67D9784457E86A9BB",
-      "close_flags": 0,
-      "close_time": 508541181,
-      "close_time_human": "2016-Feb-11 21:26:21",
-      "close_time_resolution": 10,
-      "closed": true,
-      "hash": "F1433E9D15F33E746B8820DEEE4879F48181704364E459332561DF8E52E4EB7E",
-      "ledger_hash": "F1433E9D15F33E746B8820DEEE4879F48181704364E459332561DF8E52E4EB7E",
-      "ledger_index": "18851530",
-      "parent_close_time": 508541180,
-      "parent_hash": "8300B70AA5A865961DED7DAC5B88047028762D5946ECA887D09D32DE442E2305",
-      "seqNum": "18851530",
-      "totalCoins": "99998102799411646",
-      "total_coins": "99998102799411646",
-      "transaction_hash": "E0DB0471A1D198611E1C050ADA4AE74EEB38CEC26E0550663E0FCB1364212A3B"
-    },
-    "ledger_hash": "F1433E9D15F33E746B8820DEEE4879F48181704364E459332561DF8E52E4EB7E",
-    "ledger_index": 18851530,
-    "validated": true
-  }
-}
-
- -
200 OK
-{
-    "result": {
-        "ledger": {
-            "accepted": true,
-            "account_hash": "B089E7CD4F5167249951611AAEC863D4BF84FF098500E9CB50561F1A89EED825",
-            "close_flags": 0,
-            "close_time": 508541222,
-            "close_time_human": "2016-Feb-11 21:27:02",
-            "close_time_resolution": 10,
-            "closed": true,
-            "hash": "85E6D422F1A3AE0BEA315C4F09CD0B45022312A4BBF0D308246E901536B61157",
-            "ledger_hash": "85E6D422F1A3AE0BEA315C4F09CD0B45022312A4BBF0D308246E901536B61157",
-            "ledger_index": "18851543",
-            "parent_close_time": 508541221,
-            "parent_hash": "C382DB117F2D5AAECFBFB43EA509F8E56D6E1D1297CE00C0D02A3EE695ABB78F",
-            "seqNum": "18851543",
-            "totalCoins": "99998102795090646",
-            "total_coins": "99998102795090646",
-            "transaction_hash": "BEC71A3CAD11BFC4E4013CD109F220E0850E9A3808B15FAA6DAE4D898970EFAF"
-        },
-        "ledger_hash": "85E6D422F1A3AE0BEA315C4F09CD0B45022312A4BBF0D308246E901536B61157",
-        "ledger_index": 18851543,
-        "status": "success",
-        "validated": true
-    }
-}
-
-
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
ledgerObjectThe complete header data of this ledger.
ledger.account_hashStringHash of all account state information in this ledger, as hex
ledger.accountsArray(Omitted unless requested) All the account-state information in this ledger.
ledger.close_timeIntegerThe time this ledger was closed, in seconds since the Ripple Epoch
ledger.close_time_humanStringThe time this ledger was closed, in human-readable format
ledger.close_time_resolutionIntegerLedger close times are rounded to within this many seconds.
ledger.closedBooleanWhether or not this ledger has been closed
ledger.ledger_hashStringUnique identifying hash of the entire ledger.
ledger.ledger_indexStringThe Ledger Index of this ledger, as a quoted integer
ledger.parent_hashStringUnique identifying hash of the ledger that came immediately before this one.
ledger.total_coinsStringTotal number of XRP drops in the network, as a quoted integer. (This decreases as transaction costs destroy XRP.)
ledger.transaction_hashStringHash of the transaction information included in this ledger, as hex
ledger.transactionsArray(Omitted unless requested) Transactions applied in this ledger version. By default, members are the transactions' identifying Hash strings. If the request specified expand as true, members are full representations of the transactions instead, in either JSON or binary depending on whether the request specified binary as true.
ledger_hashStringUnique identifying hash of the entire ledger.
ledger_indexNumberThe Ledger Index of this ledger.
queue_dataArray(Omitted unless requested with the queue parameter) Array of objects describing queued transactions, in the same order as the queue. If the request specified expand as true, members contain full representations of the transactions, in either JSON or binary depending on whether the request specified binary as true. Requires the FeeEscalation amendment. New in: rippled 0.70.0
-

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

-

Each member of the queue_data array represents one transaction in the queue. Some fields of this object may be omitted because they have not yet been calculated. The fields of this object are as follows:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
accountStringThe Address of the sender for this queued transaction.
txString or ObjectBy default, this is a String containing the identifying hash of the transaction. If transactions are expanded in binary format, this is an object whose only field is tx_blob, containing the binary form of the transaction as a decimal string. If transactions are expanded in JSON format, this is an object containing the transaction object including the transaction's identifying hash in the hash field.
retries_remainingNumberHow many times this transaction can be retried before being dropped.
preflight_resultStringThe tentative result from preliminary transaction checking. This is always tesSUCCESS.
last_resultString(May be omitted) If this transaction was left in the queue after getting a retriable (ter) result, this is the exact ter result code it got.
auth_changeBoolean(May be omitted) Whether this transaction changes this address's ways of authorizing transactions.
feeString(May be omitted) The Transaction Cost of this transaction, in drops of XRP.
fee_levelString(May be omitted) The transaction cost of this transaction, relative to the minimum cost for this type of transaction, in fee levels.
max_spend_dropsString(May be omitted) The maximum amount of XRP, in drops, this transaction could potentially send or destroy.
-

If the request specified "owner_funds": true and expanded transactions, the response has a field owner_funds in the metaData object of each OfferCreate-type transaction. The purpose of this field is to make it easier to track the funding status of offers with each new validated ledger. This field is defined slightly differently than the version of this field in Order Book subscription streams:

- - - - - - - - - - - - - - - -
FieldValueDescription
owner_fundsStringNumeric amount of the TakerGets currency that the Account sending this OfferCreate transaction has after the execution of all transactions in this ledger. This does not check whether the currency amount is frozen.
-

Possible Errors

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

ledger_closed

-

[Source]

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-   "id": 2,
-   "command": "ledger_closed"
-}
-
- -
{
-    "method": "ledger_closed",
-    "params": [
-        {}
-    ]
-}
-
- -
#Syntax: ledger_closed
-rippled ledger_closed
-
-
-

Try it!

-

This method accepts no parameters.

-

Response Format

-

An example of a successful response:

-
- -
{
-  "id": 1,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "ledger_hash": "17ACB57A0F73B5160713E81FE72B2AC9F6064541004E272BD09F257D57C30C02",
-    "ledger_index": 6643099
-  }
-}
-
- -
200 OK
-{
-    "result": {
-        "ledger_hash": "8B5A0C5F6B198254A6E411AF55C29EE40AA86251D2E78DD0BB17647047FA9C24",
-        "ledger_index": 8696231,
-        "status": "success"
-    }
-}
-
-
-

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

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
ledger_hashString20-byte hex string with a unique hash of the ledger
ledger_indexUnsigned IntegerSequence number of this ledger
-

Possible Errors

- -

ledger_current

-

[Source]

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-   "id": 2,
-   "command": "ledger_current"
-}
-
- -
{
-    "method": "ledger_current",
-    "params": [
-        {}
-    ]
-}
-
- -
#Syntax: ledger_current
-rippled ledger_current
-
-
-

Try it!

-

The request contains no parameters.

-

Response Format

-

An example of a successful response:

-
- -
{
-  "id": 2,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "ledger_current_index": 6643240
-  }
-}
-
- -
200 OK
-{
-    "result": {
-        "ledger_current_index": 8696233,
-        "status": "success"
-    }
-}
-
-
-

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

- - - - - - - - - - - - - - - -
FieldTypeDescription
ledger_current_indexUnsigned IntegerSequence number of this ledger
-

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

-

Possible Errors

- -

ledger_data

-

[Source]

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-   "id": 2,
-   "ledger_hash": "842B57C1CC0613299A686D3E9F310EC0422C84D3911E5056389AA7E5808A93C8",
-   "command": "ledger_data",
-   "limit": 5,
-   "binary": true
-}
-
- -
{
-    "method": "ledger_data",
-    "params": [
-        {
-            "binary": true,
-            "ledger_hash": "842B57C1CC0613299A686D3E9F310EC0422C84D3911E5056389AA7E5808A93C8",
-            "limit": 5
-        }
-    ]
-}
-
-
-

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

-

A request can include the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
id(Arbitrary)(WebSocket only) Any identifier to separate this request from others in case the responses are delayed or out of order.
ledger_hashString(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger)
ledger_indexString or Unsigned Integer(Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)
binaryBoolean(Optional, defaults to False) If set to true, return data nodes as hashed hex strings instead of JSON.
limitInteger(Optional, default varies) Limit the number of nodes to retrieve. The server is not required to honor this value.
marker(Not Specified)Value from a previous paginated response. Resume retrieving data where that response left off.
-

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

-

Response Format

-

An example of a successful response:

-
- -
{
-    "id": 2,
-    "result": {
-        "ledger_hash": "842B57C1CC0613299A686D3E9F310EC0422C84D3911E5056389AA7E5808A93C8",
-        "ledger_index": "6885842",
-        "marker": "0002A590029B53BE7857EFF9985F770EC792CE483720EB5E963C4D6A607D43DF",
-        "state": [
-            {
-                "data": "11006122000000002400000001250062FEA42D0000000055C204A65CF2542946289A3358C67D991B5E135FABFA89F271DBA7A150C08CA0466240000000354540208114C909F42250CFE8F12A7A1A0DFBD3CBD20F32CD79",
-                "index": "00001A2969BE1FC85F1D7A55282FA2E6D95C71D2E4B9C0FDD3D9994F3C00FF8F"
-            },
-            {
-                "data": "11006F22000000002400000003250035788533000000000000000034000000000000000055555B93628BF3EC318892BB7C7CDCB6732FF53D12B6EEC4FAF60DD1AEE1C6101F501071633D7DE1B6AEB32F87F1A73258B13FC8CC32942D53A66D4F038D7EA4C6800064D4838D7EA4C68000000000000000000000000000425443000000000035DD7DF146893456296BF4061FBE68735D28F3286540000000000F42408114A4B8F5F7B644AEDC3447F9459C132EEB016A133B",
-                "index": "000037C6659BB98F8D09F2F4CFEB27DE8EFEAFE54DD9E1C13AECDF5794B0C0F5"
-            },
-            {
-                "data": "11006F2200020000240000000A250067395C33000000000000000034000000000000000055A160BC41A45B6BB118DF23D77E4FF23C723431B917F50DCB41319ECC2821F34C5010DFA3B6DDAB58C7E8E5D944E736DA4B7046C30E4F460FD9DE4C1AA535D3D0C00064D554C88B43EFA00000000000000000000000000055534400000000000A20B3C85F482532A9578DBB3950B85CA06594D165400000B59B9F780081148366FB9ACD2A0FD822E31112D2EB6F98C317C2C1",
-                "index": "0000A8791F78CC9B39200E12A9BDAACCF40A72A512FA815525CFC9BA772990F7"
-            },
-            {
-                "data": "1100612200000000240000000125003E742F2D0000000055286498B513710CFEB2D723A554C7557983D1952DF4DEE342C40DCB43067C9A21624000000306DC42008114225BAB89C4A4B94624BB069D6DB3C819F934991C",
-                "index": "0000B717320558E2DE1A3B9FDB24E9A695BF05D1A44E4A4683212BB1DD0FBA23"
-            },
-            {
-                "data": "110072220002000025000B65783700000000000000003800000000000000005587591A63051645F37B85D1FBA55EE69B1C96BFF16904F5C99F03FB93D42D03756280000000000000000000000000000000000000004254430000000000000000000000000000000000000000000000000166800000000000000000000000000000000000000042544300000000000A20B3C85F482532A9578DBB3950B85CA06594D167D4C38D7EA4C680000000000000000000000000004254430000000000C795FDF8A637BCAAEDAD1C434033506236C82A2D",
-                "index": "000103996A3BAD918657F86E12A67D693E8FC8A814DA4B958A244B5F14D93E58"
-            }
-        ]
-    },
-    "status": "success",
-    "type": "response"
-}
-
- -
{
-    "id": 2,
-    "result": {
-        "ledger_hash": "842B57C1CC0613299A686D3E9F310EC0422C84D3911E5056389AA7E5808A93C8",
-        "ledger_index": "6885842",
-        "marker": "0002A590029B53BE7857EFF9985F770EC792CE483720EB5E963C4D6A607D43DF",
-        "state": [
-            {
-                "Account": "rKKzk9ghA2iuy3imqMXUHJqdRPMtNDGf4c",
-                "Balance": "893730848",
-                "Flags": 0,
-                "LedgerEntryType": "AccountRoot",
-                "OwnerCount": 0,
-                "PreviousTxnID": "C204A65CF2542946289A3358C67D991B5E135FABFA89F271DBA7A150C08CA046",
-                "PreviousTxnLgrSeq": 6487716,
-                "Sequence": 1,
-                "index": "00001A2969BE1FC85F1D7A55282FA2E6D95C71D2E4B9C0FDD3D9994F3C00FF8F"
-            },
-            {
-                "Account": "rGryPmNWFognBgMtr9k4quqPbbEcCrhNmD",
-                "BookDirectory": "71633D7DE1B6AEB32F87F1A73258B13FC8CC32942D53A66D4F038D7EA4C68000",
-                "BookNode": "0000000000000000",
-                "Flags": 0,
-                "LedgerEntryType": "Offer",
-                "OwnerNode": "0000000000000000",
-                "PreviousTxnID": "555B93628BF3EC318892BB7C7CDCB6732FF53D12B6EEC4FAF60DD1AEE1C6101F",
-                "PreviousTxnLgrSeq": 3504261,
-                "Sequence": 3,
-                "TakerGets": "1000000",
-                "TakerPays": {
-                    "currency": "BTC",
-                    "issuer": "rnuF96W4SZoCJmbHYBFoJZpR8eCaxNvekK",
-                    "value": "1"
-                },
-                "index": "000037C6659BB98F8D09F2F4CFEB27DE8EFEAFE54DD9E1C13AECDF5794B0C0F5"
-            },
-            {
-                "Account": "rUy8tW38MW9ma7kSjRgB2GHtTkQAFRyrN8",
-                "BookDirectory": "DFA3B6DDAB58C7E8E5D944E736DA4B7046C30E4F460FD9DE4C1AA535D3D0C000",
-                "BookNode": "0000000000000000",
-                "Flags": 131072,
-                "LedgerEntryType": "Offer",
-                "OwnerNode": "0000000000000000",
-                "PreviousTxnID": "A160BC41A45B6BB118DF23D77E4FF23C723431B917F50DCB41319ECC2821F34C",
-                "PreviousTxnLgrSeq": 6764892,
-                "Sequence": 10,
-                "TakerGets": "780000000000",
-                "TakerPays": {
-                    "currency": "USD",
-                    "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-                    "value": "5850"
-                },
-                "index": "0000A8791F78CC9B39200E12A9BDAACCF40A72A512FA815525CFC9BA772990F7"
-            },
-            {
-                "Account": "rh3C81VfNDhhWPQWCU8ZGgknvdgNUvRtM9",
-                "Balance": "13000000000",
-                "Flags": 0,
-                "LedgerEntryType": "AccountRoot",
-                "OwnerCount": 0,
-                "PreviousTxnID": "286498B513710CFEB2D723A554C7557983D1952DF4DEE342C40DCB43067C9A21",
-                "PreviousTxnLgrSeq": 4092975,
-                "Sequence": 1,
-                "index": "0000B717320558E2DE1A3B9FDB24E9A695BF05D1A44E4A4683212BB1DD0FBA23"
-            },
-            {
-                "Balance": {
-                    "currency": "BTC",
-                    "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                    "value": "0"
-                },
-                "Flags": 131072,
-                "HighLimit": {
-                    "currency": "BTC",
-                    "issuer": "rKUK9omZqVEnraCipKNFb5q4tuNTeqEDZS",
-                    "value": "10"
-                },
-                "HighNode": "0000000000000000",
-                "LedgerEntryType": "RippleState",
-                "LowLimit": {
-                    "currency": "BTC",
-                    "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-                    "value": "0"
-                },
-                "LowNode": "0000000000000000",
-                "PreviousTxnID": "87591A63051645F37B85D1FBA55EE69B1C96BFF16904F5C99F03FB93D42D0375",
-                "PreviousTxnLgrSeq": 746872,
-                "index": "000103996A3BAD918657F86E12A67D693E8FC8A814DA4B958A244B5F14D93E58"
-            }
-        ]
-    },
-    "status": "success",
-    "type": "response"
-}
-
- -
200 OK
-{
-    "result": {
-        "ledger_hash": "842B57C1CC0613299A686D3E9F310EC0422C84D3911E5056389AA7E5808A93C8",
-        "ledger_index": "6885842",
-        "marker": "0002A590029B53BE7857EFF9985F770EC792CE483720EB5E963C4D6A607D43DF",
-        "state": [
-            {
-                "data": "11006122000000002400000001250062FEA42D0000000055C204A65CF2542946289A3358C67D991B5E135FABFA89F271DBA7A150C08CA0466240000000354540208114C909F42250CFE8F12A7A1A0DFBD3CBD20F32CD79",
-                "index": "00001A2969BE1FC85F1D7A55282FA2E6D95C71D2E4B9C0FDD3D9994F3C00FF8F"
-            },
-            {
-                "data": "11006F22000000002400000003250035788533000000000000000034000000000000000055555B93628BF3EC318892BB7C7CDCB6732FF53D12B6EEC4FAF60DD1AEE1C6101F501071633D7DE1B6AEB32F87F1A73258B13FC8CC32942D53A66D4F038D7EA4C6800064D4838D7EA4C68000000000000000000000000000425443000000000035DD7DF146893456296BF4061FBE68735D28F3286540000000000F42408114A4B8F5F7B644AEDC3447F9459C132EEB016A133B",
-                "index": "000037C6659BB98F8D09F2F4CFEB27DE8EFEAFE54DD9E1C13AECDF5794B0C0F5"
-            },
-            {
-                "data": "11006F2200020000240000000A250067395C33000000000000000034000000000000000055A160BC41A45B6BB118DF23D77E4FF23C723431B917F50DCB41319ECC2821F34C5010DFA3B6DDAB58C7E8E5D944E736DA4B7046C30E4F460FD9DE4C1AA535D3D0C00064D554C88B43EFA00000000000000000000000000055534400000000000A20B3C85F482532A9578DBB3950B85CA06594D165400000B59B9F780081148366FB9ACD2A0FD822E31112D2EB6F98C317C2C1",
-                "index": "0000A8791F78CC9B39200E12A9BDAACCF40A72A512FA815525CFC9BA772990F7"
-            },
-            {
-                "data": "1100612200000000240000000125003E742F2D0000000055286498B513710CFEB2D723A554C7557983D1952DF4DEE342C40DCB43067C9A21624000000306DC42008114225BAB89C4A4B94624BB069D6DB3C819F934991C",
-                "index": "0000B717320558E2DE1A3B9FDB24E9A695BF05D1A44E4A4683212BB1DD0FBA23"
-            },
-            {
-                "data": "110072220002000025000B65783700000000000000003800000000000000005587591A63051645F37B85D1FBA55EE69B1C96BFF16904F5C99F03FB93D42D03756280000000000000000000000000000000000000004254430000000000000000000000000000000000000000000000000166800000000000000000000000000000000000000042544300000000000A20B3C85F482532A9578DBB3950B85CA06594D167D4C38D7EA4C680000000000000000000000000004254430000000000C795FDF8A637BCAAEDAD1C434033506236C82A2D",
-                "index": "000103996A3BAD918657F86E12A67D693E8FC8A814DA4B958A244B5F14D93E58"
-            }
-        ],
-        "status": "success"
-    }
-}
-
-
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
ledger_indexUnsigned IntegerSequence number of this ledger
ledger_hashStringUnique identifying hash of the entire ledger.
stateArrayArray of JSON objects containing data from the tree, as defined below
marker(Not Specified)Server-defined value indicating the response is paginated. Pass this to the next call to resume where this call left off.
-

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

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

Possible Errors

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

ledger_entry

-

[Source]

-

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

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-  "id": 3,
-  "command": "ledger_entry",
-  "type": "account_root",
-  "account_root": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-  "ledger_index": "validated"
-}
-
- -
{
-    "method": "ledger_entry",
-    "params": [
-        {
-            "account_root": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-            "ledger_index": "validated",
-            "type": "account_root"
-        }
-    ]
-}
-
-
-

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 any type of ledger node by its unique index
    2. -
  2. account_root - Retrieve an AccountRoot node. This is roughly equivalent to the account_info command.
    3. -
  3. directory - Retrieve a DirectoryNode, which contains a list of other nodes
    4. -
  4. offer - Retrieve an Offer node, which defines an offer to exchange currency
    5. -
  5. ripple_state - Retrieve a RippleState node, which tracks a (non-XRP) currency balance between two accounts.
    6. -
-

If you specify more than one of the above items, the server retrieves only of them; it is undefined which it chooses.

-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
indexString(Optional) Specify the unique identifier of a single ledger entry to retrieve.
account_rootString - Address(Optional) Specify an AccountRoot node to retrieve.
directoryObject or String(Optional) Specify a DirectoryNode. (Directory nodes each contain a list of IDs for things contained in them.) If a string, interpret as the unique index to the directory, in hex. If an object, requires either dir_root or owner as a sub-field, plus optionally a sub_index sub-field.
directory.sub_indexUnsigned Integer(Optional) If provided, jumps to a further sub-node in the DirectoryNode.
directory.dir_rootString(Required if directory is specified as an object and directory.owner is not provided) Unique index identifying the directory to retrieve, as a hex string.
directory.ownerString(Required if directory is specified as an object and directory.dir_root is not provided) Unique address of the account associated with this directory
offerObject or String(Optional) Specify an Offer node to retrieve. If a string, interpret as the unique index to the Offer. If an object, requires the sub-fields account and seq to uniquely identify the offer.
offer.accountString - Address(Required if offer specified) The account that placed the offer.
offer.seqUnsigned Integer(Required if offer specified) The sequence number of the transaction that created the Offer node.
ripple_stateObject(Optional) Object specifying the RippleState (trust line) node to retrieve. The accounts and currency sub-fields are required to uniquely specify the RippleState entry to retrieve.
ripple_state.accountsArray(Required if ripple_state specified) 2-length array of account Addresses, defining the two accounts linked by this RippleState node
ripple_state.currencyString(Required if ripple_state specified) Currency Code of the RippleState node to retrieve.
binaryBoolean(Optional, defaults to false) If true, return the requested ledger node's contents as a hex string. Otherwise, return data in JSON format.
ledger_hashString(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger)
ledger_indexString or Unsigned Integer(Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)
-

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

-

Response Format

-

An example of a successful response:

-
- -
    "id": 3,
-    "result": {
-        "index": "4F83A2CF7E70F77F79A307E6A472BFC2585B806A70833CCD1C26105BAE0D6E05",
-        "ledger_index": 6889347,
-        "node": {
-            "Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-            "Balance": "27389517749",
-            "Flags": 0,
-            "LedgerEntryType": "AccountRoot",
-            "OwnerCount": 18,
-            "PreviousTxnID": "B6B410172C0B65575D89E464AF5B99937CC568822929ABF87DA75CBD11911932",
-            "PreviousTxnLgrSeq": 6592159,
-            "Sequence": 1400,
-            "index": "4F83A2CF7E70F77F79A307E6A472BFC2585B806A70833CCD1C26105BAE0D6E05"
-        }
-    },
-    "status": "success",
-    "type": "response"
-}
-
- -
200 OK
-{
-    "result": {
-        "index": "4F83A2CF7E70F77F79A307E6A472BFC2585B806A70833CCD1C26105BAE0D6E05",
-        "ledger_index": 8696234,
-        "node": {
-            "Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-            "Balance": "13176802787",
-            "Flags": 0,
-            "LedgerEntryType": "AccountRoot",
-            "OwnerCount": 17,
-            "PreviousTxnID": "E5D0235A236F7CD162C1AB87A0325056AE61CFC63D92D1494AB5D826AAD0CDCA",
-            "PreviousTxnLgrSeq": 8554742,
-            "Sequence": 1406,
-            "index": "4F83A2CF7E70F77F79A307E6A472BFC2585B806A70833CCD1C26105BAE0D6E05"
-        },
-        "status": "success",
-        "validated": true
-    }
-}
-
-
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
indexStringUnique identifying key for this ledger_entry
ledger_indexUnsigned IntegerUnique sequence number of the ledger from which this data was retrieved
nodeObject(Omitted if "binary": true specified.) Object containing the data of this ledger node, according to the ledger format.
node_binaryString(Omitted unless "binary":true specified) Binary data of the ledger node, as hex.
-

Possible Errors

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

ledger_request

-

[Source]

-

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

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-    "id": 102,
-    "command": "ledger_request",
-    "ledger_index": 13800000
-}
-
- -
rippled ledger_request 13800000
-
-
-

The request includes the following parameters:

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
ledger_indexNumber(Optional) Retrieve the specified ledger by its Ledger Index.
ledger_hashString(Optional) Retrieve the specified ledger by its identifying Hash.
-

You must provide either ledger_index or ledger_hash but not both.

-

Response Format

-

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

-

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

-

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

-
- -
Loading: "/etc/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "acquiring" : {
-         "hash" : "01DDD89B6605E20338B8EEB8EB2B0E0DD2F685A2B164F3790C4D634B5734CC26",
-         "have_header" : false,
-         "peers" : 2,
-         "timeouts" : 0
-      },
-      "error" : "lgrNotFound",
-      "error_code" : 20,
-      "error_message" : "acquiring ledger containing requested index",
-      "request" : {
-         "command" : "ledger_request",
-         "ledger_index" : 18851277
-      },
-      "status" : "error"
-   }
-}
-
- -
Loading: "/etc/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "hash" : "EB68B5B4F6F06BF59B6D7532BCB98BB98E2F10C2435D895217AA0AA7E910FBD5",
-      "have_header" : true,
-      "have_state" : false,
-      "have_transactions" : false,
-      "needed_state_hashes" : [
-         "C46F7B9E795135447AF24BAF999AB8FC1612A997F6EAAF8B784C226FF0BD8E25",
-         "E48F528E4FC2A1DC492C6264B27B420E2285B2A3ECF3A253DB480DA5BFB7F858",
-         "B62CD0B2E1277F78BC279FA037F3F747587299B60D23A551C3F63DD137DC0CF8",
-         "30014C55701FB8426E496A47B297BEC9E8F5BFA47763CC22DBD9024CC81D39DD",
-         "7EB59A853913898FCEA7B701637F33B1054BD36C32A0B910B612EFB9CDFF6334",
-         "07ECAD3066D62583883979A2FADAADC8F7D89FA07375843C8A47452639AB2421",
-         "97A87E5246AF78463485CB27E08D561E22AAF33D5E2F08FE2FACAE0D05CB5478",
-         "50A0525E238629B32324C9F59B4ECBEFE3C21DC726DB9AB3B6758BD1838DFF68",
-         "8C541B1ED47C9282E2A28F0B7F3DDFADF06644CAB71B15A3E67D04C5FAFE9BF4",
-         "2C6CC536C778D8C0F601E35DA7DD9888C288897E4F603E76357CE2F47E8A7A9F",
-         "309E78DEC67D5725476A59E114850556CC693FB6D92092997ADE97E3EFF473CC",
-         "8EFF61B6A636AF6B4314CAC0C08F4FED0759E1F782178A822EDE98275E5E4B10",
-         "9535645E5D249AC0B6126005B79BB981CBA00286E00154D20A3BCF65743EA3CA",
-         "69F5D6FCB41D1E6CEA5ADD42CBD194086B45E957D497DF7AEE62ADAD485660CE",
-         "07E93A95DBB0B8A00925DE0DF6D27E41CACC77EF75055A89815006109D82EAD3",
-         "7FDF25F660235DCAD649676E3E6729DF920A9B0B4B6A3B090A3C64D7BDE2FB20"
-      ],
-      "needed_transaction_hashes" : [
-         "BA914854F2F5EDFCBD6E3E0B168E5D4CD0FC92927BEE408C6BD38D4F52505A34",
-         "AE3A2DB537B01EB33BB3A677242DE52C9AE0A64BD9222EE55E52855276E7EA2A",
-         "E145F737B255D93769673CBA6DEBA4F6AC7387A309DAACC72EA5B07ECF03C215",
-         "073A118552AA60E1D3C6BE6F65E4AFA01C582D9C41CCC2887244C19D9BFA7741",
-         "562DB8580CD3FE19AF5CEA61C2858C10091151B924DBF2AEB7CBB8722E683204",
-         "437C0D1C2391057079E9539CF028823D29E6437A965284F6E54CEBF1D25C5D56",
-         "1F069486AF5533883609E5C8DB907E97273D9A782DF26F5E5811F1C42ED63A3D",
-         "CAA6B7DA68EBA71254C218C81A9EA029A179694BDD0D75A49FB03A7D57BCEE49"
-      ],
-      "peers" : 6,
-      "status" : "success",
-      "timeouts" : 1
-   }
-}
-
- -
Loading: "/etc/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "ledger" : {
-         "accepted" : true,
-         "account_hash" : "84EBB27D9510AD5B9A3A328201921B3FD418D4A349E85D3DC69E33C7B506407F",
-         "close_time" : 486691300,
-         "close_time_human" : "2015-Jun-04 00:01:40",
-         "close_time_resolution" : 10,
-         "closed" : true,
-         "hash" : "DCF5D723ECEE1EF56D2B0024CD9BDFF2D8E3DC211BD2B9460165922564ACD863",
-         "ledger_hash" : "DCF5D723ECEE1EF56D2B0024CD9BDFF2D8E3DC211BD2B9460165922564ACD863",
-         "ledger_index" : "13840000",
-         "parent_hash" : "8A3F6FBC62C11DE4538D969F9C7966234635FE6CEB1133DDC37220978F8100A9",
-         "seqNum" : "13840000",
-         "totalCoins" : "99999022883526403",
-         "total_coins" : "99999022883526403",
-         "transaction_hash" : "3D759EF3AF1AE2F78716A8CCB2460C3030F82687E54206E883703372B9E1770C"
-      },
-      "ledger_index" : 13840000,
-      "status" : "success"
-   }
-}
-
-
-
-

The three possible response formats are as follows:

-
    -
  1. When returning a lgrNotFound error, the response has a field, acquiring with a Ledger Request Object indicating the progress of fetching the ledger from the peer-to-peer network.
    2. -
  2. When the response shows the server is currently fetching the ledger, the body of the result is a Ledger Request Object indicating the progress of fetching the ledger from the peer-to-peer network.
    3. -
  3. When the ledger is fully available, the response is a representation of the ledger header.
    4. -
-

Ledger Request Object

-

When the server is in the progress of fetching a ledger, but has not yet finished, the rippled server returns a ledger request object indicating its progress towards fetching the ledger. This object has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
hashString(May be omitted) The Hash of the requested ledger, if the server knows it.
have_headerBooleanWhether the server has the header section of the requested ledger.
have_stateBoolean(May be omitted) Whether the server has the account-state section of the requested ledger.
have_transactionsBoolean(May be omitted) Whether the server has the transaction section of the requested ledger.
needed_state_hashesArray of Strings(May be omitted) Up to 16 hashes of nodes in the state tree that the server still needs to retrieve.
needed_transaction_hashesArray of Strings(May be omitted) Up to 16 hashes of nodes in the transaction tree that the server still needs to retrieve.
peersNumberHow many peers the server is querying to find this ledger.
timeoutsNumberNumber of times fetching this ledger has timed out so far.
-

Possible Errors

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

ledger_accept

-

[Source]

-

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

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-   "id": "Accept my ledger!",
-   "command": "ledger_accept"
-}
-
- -
#Syntax: ledger_accept
-rippled ledger_accept
-
-
-

The request accepts no parameters.

-

Response Format

-

An example of a successful response:

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

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

- - - - - - - - - - - - - - - -
FieldTypeDescription
ledger_current_indexUnsigned IntegerSequence number of the newly created 'current' ledger
-

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

-

Possible Errors

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

Transactions

-

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

-

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

-

tx

-

[Source]

-

The tx method retrieves information on a single transaction.

-

Request Format

-

An example of the request format:

-
- -
{
-  "id": 1,
-  "command": "tx",
-  "transaction": "E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7",
-  "binary": false
-}
-
- -
{
-    "method": "tx",
-    "params": [
-        {
-            "transaction": "E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7",
-            "binary": false
-        }
-    ]
-}
-
- -
#Syntax: tx transaction [binary]
-rippled tx E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7 false
-
-
-

Try it!

-

The request includes the following parameters:

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
transactionStringThe 256-bit hash of the transaction, as hex.
binaryBoolean(Optional, defaults to false) If true, return transaction data and metadata as hex strings instead of JSON
-

Response Format

-

An example of a successful response:

-
- -
{
-    "id": 1,
-    "result": {
-        "Account": "r3PDtZSa5LiYp1Ysn1vMuMzB59RzV3W9QH",
-        "Amount": {
-            "currency": "USD",
-            "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-            "value": "1"
-        },
-        "Destination": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-        "Fee": "10",
-        "Flags": 0,
-        "Paths": [
-            [
-                {
-                    "account": "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV",
-                    "currency": "USD",
-                    "issuer": "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV",
-                    "type": 49,
-                    "type_hex": "0000000000000031"
-                }
-            ],
-            [
-                {
-                    "account": "rD1jovjQeEpvaDwn9wKaYokkXXrqo4D23x",
-                    "currency": "USD",
-                    "issuer": "rD1jovjQeEpvaDwn9wKaYokkXXrqo4D23x",
-                    "type": 49,
-                    "type_hex": "0000000000000031"
-                },
-                {
-                    "account": "rB5TihdPbKgMrkFqrqUC3yLdE8hhv4BdeY",
-                    "currency": "USD",
-                    "issuer": "rB5TihdPbKgMrkFqrqUC3yLdE8hhv4BdeY",
-                    "type": 49,
-                    "type_hex": "0000000000000031"
-                },
-                {
-                    "account": "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV",
-                    "currency": "USD",
-                    "issuer": "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV",
-                    "type": 49,
-                    "type_hex": "0000000000000031"
-                }
-            ]
-        ],
-        "SendMax": {
-            "currency": "USD",
-            "issuer": "r3PDtZSa5LiYp1Ysn1vMuMzB59RzV3W9QH",
-            "value": "1.01"
-        },
-        "Sequence": 88,
-        "SigningPubKey": "02EAE5DAB54DD8E1C49641D848D5B97D1B29149106174322EDF98A1B2CCE5D7F8E",
-        "TransactionType": "Payment",
-        "TxnSignature": "30440220791B6A3E036ECEFFE99E8D4957564E8C84D1548C8C3E80A87ED1AA646ECCFB16022037C5CAC97E34E3021EBB426479F2ACF3ACA75DB91DCC48D1BCFB4CF547CFEAA0",
-        "hash": "E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7",
-        "inLedger": 348734,
-        "ledger_index": 348734,
-        "meta": {
-            "AffectedNodes": [
-                {
-                    "ModifiedNode": {
-                        "FinalFields": {
-                            "Account": "r3PDtZSa5LiYp1Ysn1vMuMzB59RzV3W9QH",
-                            "Balance": "59328999119",
-                            "Flags": 0,
-                            "OwnerCount": 11,
-                            "Sequence": 89
-                        },
-                        "LedgerEntryType": "AccountRoot",
-                        "LedgerIndex": "E0D7BDE68B468FF0B8D948FD865576517DA987569833A05374ADB9A72E870A06",
-                        "PreviousFields": {
-                            "Balance": "59328999129",
-                            "Sequence": 88
-                        },
-                        "PreviousTxnID": "C26AA6B4F7C3B9F55E17CD0D11F12032A1C7AD2757229FFD277C9447A8815E6E",
-                        "PreviousTxnLgrSeq": 348700
-                    }
-                },
-                {
-                    "ModifiedNode": {
-                        "FinalFields": {
-                            "Balance": {
-                                "currency": "USD",
-                                "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                                "value": "-1"
-                            },
-                            "Flags": 131072,
-                            "HighLimit": {
-                                "currency": "USD",
-                                "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                                "value": "100"
-                            },
-                            "HighNode": "0000000000000000",
-                            "LowLimit": {
-                                "currency": "USD",
-                                "issuer": "r3PDtZSa5LiYp1Ysn1vMuMzB59RzV3W9QH",
-                                "value": "0"
-                            },
-                            "LowNode": "0000000000000000"
-                        },
-                        "LedgerEntryType": "RippleState",
-                        "LedgerIndex": "EA4BF03B4700123CDFFB6EB09DC1D6E28D5CEB7F680FB00FC24BC1C3BB2DB959",
-                        "PreviousFields": {
-                            "Balance": {
-                                "currency": "USD",
-                                "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                                "value": "0"
-                            }
-                        },
-                        "PreviousTxnID": "53354D84BAE8FDFC3F4DA879D984D24B929E7FEB9100D2AD9EFCD2E126BCCDC8",
-                        "PreviousTxnLgrSeq": 343570
-                    }
-                }
-            ],
-            "TransactionIndex": 0,
-            "TransactionResult": "tesSUCCESS"
-        },
-        "validated": true
-    },
-    "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:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
hashStringThe SHA-512 hash of the transaction
inLedgerUnsigned Integer(Deprecated) Alias for ledger_index.
ledger_indexUnsigned IntegerThe sequence number of the ledger that includes this transaction.
metaObjectVarious metadata about the transaction.
validatedBooleanTrue if this data is from a validated ledger version; if omitted or set to false, this data is not final.
(Various)(Various)Other fields from the Transaction object
-

Possible Errors

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

transaction_entry

-

[Source]

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-  "id": 4,
-  "command": "transaction_entry",
-  "tx_hash": "E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7",
-  "ledger_index": 348734
-}
-
- -
{
-    "method": "transaction_entry",
-    "params": [
-        {
-            "tx_hash": "E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7",
-            "ledger_index": 348734
-        }
-    ]
-}
-
- -
#Syntax: transaction_entry transaction_hash ledger_index|ledger_hash
-rippled transaction_entry E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7 348734
-
-
-

Try it!

-

The request includes the following parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
ledger_hashString(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger)
ledger_indexString or Unsigned Integer(Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)
tx_hashStringUnique hash of the transaction you are looking up
-

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

-

Response Format

-

An example of a successful response:

-
- -
{
-    "id": 4,
-    "result": {
-        "ledger_index": 348734,
-        "metadata": {
-            "AffectedNodes": [
-                {
-                    "ModifiedNode": {
-                        "FinalFields": {
-                            "Account": "r3PDtZSa5LiYp1Ysn1vMuMzB59RzV3W9QH",
-                            "Balance": "59328999119",
-                            "Flags": 0,
-                            "OwnerCount": 11,
-                            "Sequence": 89
-                        },
-                        "LedgerEntryType": "AccountRoot",
-                        "LedgerIndex": "E0D7BDE68B468FF0B8D948FD865576517DA987569833A05374ADB9A72E870A06",
-                        "PreviousFields": {
-                            "Balance": "59328999129",
-                            "Sequence": 88
-                        },
-                        "PreviousTxnID": "C26AA6B4F7C3B9F55E17CD0D11F12032A1C7AD2757229FFD277C9447A8815E6E",
-                        "PreviousTxnLgrSeq": 348700
-                    }
-                },
-                {
-                    "ModifiedNode": {
-                        "FinalFields": {
-                            "Balance": {
-                                "currency": "USD",
-                                "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                                "value": "-1"
-                            },
-                            "Flags": 131072,
-                            "HighLimit": {
-                                "currency": "USD",
-                                "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                                "value": "100"
-                            },
-                            "HighNode": "0000000000000000",
-                            "LowLimit": {
-                                "currency": "USD",
-                                "issuer": "r3PDtZSa5LiYp1Ysn1vMuMzB59RzV3W9QH",
-                                "value": "0"
-                            },
-                            "LowNode": "0000000000000000"
-                        },
-                        "LedgerEntryType": "RippleState",
-                        "LedgerIndex": "EA4BF03B4700123CDFFB6EB09DC1D6E28D5CEB7F680FB00FC24BC1C3BB2DB959",
-                        "PreviousFields": {
-                            "Balance": {
-                                "currency": "USD",
-                                "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                                "value": "0"
-                            }
-                        },
-                        "PreviousTxnID": "53354D84BAE8FDFC3F4DA879D984D24B929E7FEB9100D2AD9EFCD2E126BCCDC8",
-                        "PreviousTxnLgrSeq": 343570
-                    }
-                }
-            ],
-            "TransactionIndex": 0,
-            "TransactionResult": "tesSUCCESS"
-        },
-        "tx_json": {
-            "Account": "r3PDtZSa5LiYp1Ysn1vMuMzB59RzV3W9QH",
-            "Amount": {
-                "currency": "USD",
-                "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-                "value": "1"
-            },
-            "Destination": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-            "Fee": "10",
-            "Flags": 0,
-            "Paths": [
-                [
-                    {
-                        "account": "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV",
-                        "currency": "USD",
-                        "issuer": "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV",
-                        "type": 49,
-                        "type_hex": "0000000000000031"
-                    }
-                ],
-                [
-                    {
-                        "account": "rD1jovjQeEpvaDwn9wKaYokkXXrqo4D23x",
-                        "currency": "USD",
-                        "issuer": "rD1jovjQeEpvaDwn9wKaYokkXXrqo4D23x",
-                        "type": 49,
-                        "type_hex": "0000000000000031"
-                    },
-                    {
-                        "account": "rB5TihdPbKgMrkFqrqUC3yLdE8hhv4BdeY",
-                        "currency": "USD",
-                        "issuer": "rB5TihdPbKgMrkFqrqUC3yLdE8hhv4BdeY",
-                        "type": 49,
-                        "type_hex": "0000000000000031"
-                    },
-                    {
-                        "account": "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV",
-                        "currency": "USD",
-                        "issuer": "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV",
-                        "type": 49,
-                        "type_hex": "0000000000000031"
-                    }
-                ]
-            ],
-            "SendMax": {
-                "currency": "USD",
-                "issuer": "r3PDtZSa5LiYp1Ysn1vMuMzB59RzV3W9QH",
-                "value": "1.01"
-            },
-            "Sequence": 88,
-            "SigningPubKey": "02EAE5DAB54DD8E1C49641D848D5B97D1B29149106174322EDF98A1B2CCE5D7F8E",
-            "TransactionType": "Payment",
-            "TxnSignature": "30440220791B6A3E036ECEFFE99E8D4957564E8C84D1548C8C3E80A87ED1AA646ECCFB16022037C5CAC97E34E3021EBB426479F2ACF3ACA75DB91DCC48D1BCFB4CF547CFEAA0",
-            "hash": "E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7",
-            "inLedger": 348734,
-            "ledger_index": 348734
-        }
-    },
-    "status": "success",
-    "type": "response"
-}
-
-
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
ledger_indexUnsigned IntegerSequence number of the ledger version the transaction was found in; this is the same as the one from the request.
ledger_hashString(May be omitted) Unique hash of the ledger version the transaction was found in; this is the same as the one from the request.
metadataObjectVarious metadata about the transaction.
tx_jsonObjectJSON representation of the Transaction object
-

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

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

Possible Errors

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

tx_history

-

[Source]

-

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

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-  "id": 5,
-  "command": "tx_history",
-  "start": 0
-}
-
- -
{
-    "method": "tx_history",
-    "params": [
-        {
-            "start": 0
-        }
-    ]
-}
-
- -
#Syntax: tx_history [start]
-rippled tx_history 0
-
-
-

Try it!

-

The request includes the following parameters:

- - - - - - - - - - - - - - - -
FieldTypeDescription
startUnsigned IntegerNumber of transactions to skip over.
-

Response Format

-

An example of a successful response:

-
- -
{
-  "id": 2,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "index": 0,
-    "txs": [
-      {
-        "Account": "r9bf8V4ae5xReYnKPXgnwERDFPoW34FhGy",
-        "Fee": "12",
-        "Flags": 2147483648,
-        "LastLedgerSequence": 6907169,
-        "Sequence": 3276,
-        "SigningPubKey": "03B7857216DF96BABCC839686670A67602B3EE50D0F12B41C15F73760B8ED394C1",
-        "TransactionType": "AccountSet",
-        "TxnSignature": "3045022100CC0A2688DC36DC47BDBD5A571407316DD16A6CB3289E60C9589531707D30EBDB022010A2ED1F8562FEF61461B89E90E9D7245F5DD1AAE6680401A60F7FDA60184312",
-        "hash": "30FF69D2F2C2FF517A82EC8BA62AA4879E27A6EAF2C9B4AA422B77C23CD11B35",
-        "inLedger": 6907162,
-        "ledger_index": 6907162
-      },
-      {
-        "Account": "rHsZHqa5oMQNL5hFm4kfLd47aEMYjPstpg",
-        "Fee": "15",
-        "Flags": 0,
-        "Sequence": 1479735,
-        "SigningPubKey": "025718736160FA6632F48EA4354A35AB0340F8D7DC7083799B9C57C3E937D71851",
-        "TakerGets": "9999999999",
-        "TakerPays": {
-          "currency": "USD",
-          "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-          "value": "48.050907917"
-        },
-        "TransactionType": "OfferCreate",
-        "TxnSignature": "3045022100C110F47609CED085E0C184396877685ACAFF0A5846C859E9A57A8E238788FAE2022042A578D36F3D911E2536A39D74B10A741EF4C77B40738DB66E9E4FA85B797DF2",
-        "hash": "A5DE72E2E97CB0FA548713FB7C8542FD1A9723EC556D386F13B25F052435B29F",
-        "inLedger": 6907162,
-        "ledger_index": 6907162
-      },
-      {
-        "Account": "r9bf8V4ae5xReYnKPXgnwERDFPoW34FhGy",
-        "Fee": "12",
-        "Flags": 2147483648,
-        "LastLedgerSequence": 6907169,
-        "Sequence": 3275,
-        "SigningPubKey": "03B7857216DF96BABCC839686670A67602B3EE50D0F12B41C15F73760B8ED394C1",
-        "TransactionType": "AccountSet",
-        "TxnSignature": "3044022030E4CCDCBA8D9984C16AD9807D0FE654D4C558C08728B33A6D9F4D05DA811CF102202A6B53015583A6C24054EE93D9B9DDF0D17133676848304BBA5156DD2C2875BE",
-        "hash": "55DFC8F7EF3976B5968DC462D91B29274E8097C35D43D6B3740AB20584336A9C",
-        "inLedger": 6907162,
-        "ledger_index": 6907162
-      },
-      {
-        "Account": "rHsZHqa5oMQNL5hFm4kfLd47aEMYjPstpg",
-        "Fee": "15",
-        "Flags": 131072,
-        "Sequence": 1479734,
-        "SigningPubKey": "025718736160FA6632F48EA4354A35AB0340F8D7DC7083799B9C57C3E937D71851",
-        "TakerGets": {
-          "currency": "BTC",
-          "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-          "value": "0.009194668"
-        },
-        "TakerPays": "1073380944",
-        "TransactionType": "OfferCreate",
-        "TxnSignature": "304402202C0D26EABE058FCE8B6862EF5CAB70674637CE32B1B4E2F3551B9D5A2E1CDC7E02202C191D2697C65478BC2C1489721EB5799A6F3D4A1ECD8FE87A0C4FDCA3704A03",
-        "hash": "2499BAE9947BE731D7FE2F8E7B6A55E1E5B43BA8D3A9F22E39F79A0CC027A1C8",
-        "inLedger": 6907161,
-        "ledger_index": 6907161
-      },
-      {
-        "Account": "rHsZHqa5oMQNL5hFm4kfLd47aEMYjPstpg",
-        "Fee": "15",
-        "Flags": 131072,
-        "Sequence": 1479733,
-        "SigningPubKey": "025718736160FA6632F48EA4354A35AB0340F8D7DC7083799B9C57C3E937D71851",
-        "TakerGets": {
-          "currency": "USD",
-          "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-          "value": "5.298037873"
-        },
-        "TakerPays": {
-          "currency": "BTC",
-          "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-          "value": "0.008937558999999999"
-        },
-        "TransactionType": "OfferCreate",
-        "TxnSignature": "3044022075EF6054ABD08F9B8287314AD4904944A74A6C3BBED9D035BCE7D409FC46E49E022025CFEE7F72BEC1F87EA83E3565CB653643A57CDD13661798D6B70F47AF63FDB6",
-        "hash": "F873CB065791DDD503580931A500BB896B9DBAFC9C285C1159B884354F3EF48B",
-        "inLedger": 6907161,
-        "ledger_index": 6907161
-      },
-      {
-        "Account": "rHsZHqa5oMQNL5hFm4kfLd47aEMYjPstpg",
-        "Fee": "15",
-        "Flags": 0,
-        "OfferSequence": 1479726,
-        "Sequence": 1479732,
-        "SigningPubKey": "025718736160FA6632F48EA4354A35AB0340F8D7DC7083799B9C57C3E937D71851",
-        "TransactionType": "OfferCancel",
-        "TxnSignature": "3045022100E82B813DA3896051EAAA3D53E197F8F426DF4E51F07A2AB83E43B10CD4008D8402204D93BABA74E63E775D44D77F4F9B07D69B0C86930F2865BBBBD2DC956FA8AE4E",
-        "hash": "203613CFA3CB7BFBCFABBBCF80D932DFBBFDECCBB869CCDBE756EAA4C8EEA41D",
-        "inLedger": 6907161,
-        "ledger_index": 6907161
-      },
-      {
-        "Account": "rHsZHqa5oMQNL5hFm4kfLd47aEMYjPstpg",
-        "Fee": "15",
-        "Flags": 0,
-        "OfferSequence": 1479725,
-        "Sequence": 1479731,
-        "SigningPubKey": "025718736160FA6632F48EA4354A35AB0340F8D7DC7083799B9C57C3E937D71851",
-        "TransactionType": "OfferCancel",
-        "TxnSignature": "30440220678FF2E754A879EAE72207F191614BBA01B8088CD174AF509E9AA11448798CD502205B326E187A0530E4E90BDD1ED875492836657E4D593FBD655F64604178693D2F",
-        "hash": "1CF4D0D583F6FC85BFD15A0BEF5E4779A8ACAD0DE43823F07C9CC2A20E29E422",
-        "inLedger": 6907161,
-        "ledger_index": 6907161
-      },
-      {
-        "Account": "rHsZHqa5oMQNL5hFm4kfLd47aEMYjPstpg",
-        "Fee": "15",
-        "Flags": 0,
-        "OfferSequence": 1479724,
-        "Sequence": 1479730,
-        "SigningPubKey": "025718736160FA6632F48EA4354A35AB0340F8D7DC7083799B9C57C3E937D71851",
-        "TransactionType": "OfferCancel",
-        "TxnSignature": "3045022100A5533E81A67B6A88B674864E898FDF31D83787FECE496544EBEE88E6FC220500022002438599B2A0E4F70C2B46FB049CD339F76E466399CA4A8F72C4ADA03F615D90",
-        "hash": "D96EC06F2ADF3CF7ED59BD76B8F1BDB127CDE46B45977B477703DB05B8DF5208",
-        "inLedger": 6907161,
-        "ledger_index": 6907161
-      },
-      {
-        "Account": "rHsZHqa5oMQNL5hFm4kfLd47aEMYjPstpg",
-        "Fee": "15",
-        "Flags": 0,
-        "OfferSequence": 1479723,
-        "Sequence": 1479729,
-        "SigningPubKey": "025718736160FA6632F48EA4354A35AB0340F8D7DC7083799B9C57C3E937D71851",
-        "TransactionType": "OfferCancel",
-        "TxnSignature": "304402206DEF8C70103AE45BCED6762B238E6F155A57D46300E8FF0A1CD0197362483CAE022007BBDFD93A0BC2473EE4537B44095D1BB5EB83F76661A14230FB3B27C4EABB6D",
-        "hash": "089D22F601FB52D0E55A8E27D393F05570DC24E92028BB9D9DCAD7BC3337ADF9",
-        "inLedger": 6907161,
-        "ledger_index": 6907161
-      },
-      {
-        "Account": "rHsZHqa5oMQNL5hFm4kfLd47aEMYjPstpg",
-        "Fee": "15",
-        "Flags": 0,
-        "OfferSequence": 1479722,
-        "Sequence": 1479728,
-        "SigningPubKey": "025718736160FA6632F48EA4354A35AB0340F8D7DC7083799B9C57C3E937D71851",
-        "TransactionType": "OfferCancel",
-        "TxnSignature": "3044022065051B7240DE1D46865453B3D7F8FC59FB2B9FD609196AB394F857B75E2B8409022044683F3A35740FC97655A8A4516184D8C582E5D88CA360301B1AD308F4126763",
-        "hash": "F6A660EF99E32D02B9AF761B14993CA1ED8BAF3507F580D90A7759ABFAF0284E",
-        "inLedger": 6907161,
-        "ledger_index": 6907161
-      },
-      {
-        "Account": "rUBLCjWdsPPMkppdFXVJWhHnr3FNqCzgG3",
-        "Fee": "15",
-        "Flags": 0,
-        "LastLedgerSequence": 6907168,
-        "Sequence": 173286,
-        "SigningPubKey": "03D606359EEA9C0A49CA9EF55F6AED6C8AEDDE604223C1BE51A2D0460A725CF173",
-        "TakerGets": {
-          "currency": "BTC",
-          "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-          "value": "0.44942631"
-        },
-        "TakerPays": {
-          "currency": "USD",
-          "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-          "value": "260"
-        },
-        "TransactionType": "OfferCreate",
-        "TxnSignature": "304502205395AF4127AD0B890AC9C47F765B4F4046C70C3DFC6F8DCD2729552FAA97F13C022100C8C2DBA6A466D76D0F103AC88DB166D1EC7F6339238E2C4245C2C26308B38058",
-        "hash": "F20F06F36B5FEFF43DD1E8AEDBE9A0ECEF0CE41402AE6F0FE4BEE1F2F82A4D54",
-        "inLedger": 6907161,
-        "ledger_index": 6907161
-      },
-      {
-        "Account": "rDVynssGDojUPpM4abx9rxYeHG4HiLGxC",
-        "Fee": "15",
-        "Flags": 2147483648,
-        "LastLedgerSequence": 6907169,
-        "OfferSequence": 859,
-        "Sequence": 860,
-        "SigningPubKey": "02C37DA8D793142BD190CE13BB697521A89D1DC318A045816EE657F42527EBFC4E",
-        "TakerGets": "19871628459",
-        "TakerPays": {
-          "currency": "BTC",
-          "issuer": "rfYv1TXnwgDDK4WQNbFALykYuEBnrR4pDX",
-          "value": "0.166766470665369"
-        },
-        "TransactionType": "OfferCreate",
-        "TxnSignature": "3044022074737D253A0DB39DBB6C63E5BD522C1313CC57658B0A567E1F1DD3414DA3817502201F333D81F29845C53A0271D0C5B005DEE4A250529DAD1A880838E242D358EE35",
-        "hash": "AD197326AEF75AA466F32FEA87358C9FB587F1C1ABF41C73E2C3EFDD83B6F33B",
-        "inLedger": 6907161,
-        "ledger_index": 6907161
-      },
-      {
-        "Account": "rHsZHqa5oMQNL5hFm4kfLd47aEMYjPstpg",
-        "Fee": "15",
-        "Flags": 0,
-        "OfferSequence": 1479721,
-        "Sequence": 1479727,
-        "SigningPubKey": "025718736160FA6632F48EA4354A35AB0340F8D7DC7083799B9C57C3E937D71851",
-        "TransactionType": "OfferCancel",
-        "TxnSignature": "3045022100CCD7336F78291E1BCAA4F86695119175E0DBC26281B2F13B30A24C726419DFCA022062547E0A4894CEAE87C42CABA94E0731134560F07D8860AE62F4A87AFD16BC43",
-        "hash": "20353EA4152C32E63941DE2F3175BA69657BA9FAB39D22BCE38B6CA1B3734D4B",
-        "inLedger": 6907161,
-        "ledger_index": 6907161
-      },
-      {
-        "Account": "r9bf8V4ae5xReYnKPXgnwERDFPoW34FhGy",
-        "Fee": "12",
-        "Flags": 2147483648,
-        "LastLedgerSequence": 6907168,
-        "Sequence": 3274,
-        "SigningPubKey": "03B7857216DF96BABCC839686670A67602B3EE50D0F12B41C15F73760B8ED394C1",
-        "TransactionType": "AccountSet",
-        "TxnSignature": "3045022100F8412BBB1DB830F314F7400E99570A9F92668ACCDEA6096144A47EDF98E18D5D02204AD89122224F353155EACC30F80BA214350968F744A480B4CD5A3174B473D6AF",
-        "hash": "16F266ABCC617CF906A25AA83BDDAD2577125E6A692A36543934AA0F0C3B77C0",
-        "inLedger": 6907161,
-        "ledger_index": 6907161
-      },
-      {
-        "Account": "r9bf8V4ae5xReYnKPXgnwERDFPoW34FhGy",
-        "Fee": "12",
-        "Flags": 2147483648,
-        "LastLedgerSequence": 6907167,
-        "Sequence": 3273,
-        "SigningPubKey": "03B7857216DF96BABCC839686670A67602B3EE50D0F12B41C15F73760B8ED394C1",
-        "TakerGets": "5397",
-        "TakerPays": {
-          "currency": "USD",
-          "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-          "value": "0.00002593363079073453"
-        },
-        "TransactionType": "OfferCreate",
-        "TxnSignature": "3044022061685E23375A299747DE45DA302966C6AF8C07D2DA9BEBB4F5572E3B02C6564D02207187E626EC817EFAFFAD002E75FC16E17A5BD54DA41D4E339F3C2A9F86FFD523",
-        "hash": "C9112B7C246FC8A9B377BD762F1D64F0DCA1128D55254A442E5735935A09D83E",
-        "inLedger": 6907160,
-        "ledger_index": 6907160
-      },
-      {
-        "Account": "rBHMbioz9znTCqgjZ6Nx43uWY43kToEPa9",
-        "Amount": {
-          "currency": "USD",
-          "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-          "value": "4"
-        },
-        "Destination": "r4X3WWZ3UZMDw3Z7T32FXK2NAaiitSWZ9c",
-        "Fee": "12",
-        "Flags": 0,
-        "LastLedgerSequence": 6907168,
-        "Paths": [
-          [
-            {
-              "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            },
-            {
-              "currency": "XRP",
-              "type": 16,
-              "type_hex": "0000000000000010"
-            },
-            {
-              "currency": "USD",
-              "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-              "type": 48,
-              "type_hex": "0000000000000030"
-            },
-            {
-              "account": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            }
-          ],
-          [
-            {
-              "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            },
-            {
-              "currency": "USD",
-              "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-              "type": 48,
-              "type_hex": "0000000000000030"
-            },
-            {
-              "account": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            }
-          ],
-          [
-            {
-              "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            },
-            {
-              "currency": "XRP",
-              "type": 16,
-              "type_hex": "0000000000000010"
-            },
-            {
-              "currency": "USD",
-              "issuer": "rwmUaXsWtXU4Z843xSYwgt1is97bgY8yj6",
-              "type": 48,
-              "type_hex": "0000000000000030"
-            },
-            {
-              "account": "rwmUaXsWtXU4Z843xSYwgt1is97bgY8yj6",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            },
-            {
-              "account": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            }
-          ],
-          [
-            {
-              "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            },
-            {
-              "currency": "XRP",
-              "type": 16,
-              "type_hex": "0000000000000010"
-            },
-            {
-              "currency": "USD",
-              "issuer": "rfsEoNBUBbvkf4jPcFe2u9CyaQagLVHGfP",
-              "type": 48,
-              "type_hex": "0000000000000030"
-            },
-            {
-              "account": "rfsEoNBUBbvkf4jPcFe2u9CyaQagLVHGfP",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            },
-            {
-              "account": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            }
-          ]
-        ],
-        "SendMax": {
-          "currency": "USD",
-          "issuer": "rBHMbioz9znTCqgjZ6Nx43uWY43kToEPa9",
-          "value": "4.132649022"
-        },
-        "Sequence": 4660,
-        "SigningPubKey": "03DFEFC9A95AEF55232A2B89867745CE45373F5CE23C34D51D21343CEA92BD61AD",
-        "TransactionType": "Payment",
-        "TxnSignature": "30450220636E405B96C998BF5EBB665D519FA8B4431A6CB5962F754EEDD48EBE95F8C45F02210097851E297FEDA44F7DFED844AE109CF2D968BD58CD3C0E951B435278A91002FA",
-        "hash": "5007E8ECAE64482D258E915FFDEFAF2FE35ED9520BA7BB424BE280691F997435",
-        "inLedger": 6907160,
-        "ledger_index": 6907160
-      },
-      {
-        "Account": "rfESTMcbvbvCBqU1FTvGWiJP8cmUSu4GKg",
-        "Amount": {
-          "currency": "BTC",
-          "issuer": "rTJdjjQ5wWAMh8TL1ToXXD2mZzesa6DSX",
-          "value": "0.0998"
-        },
-        "Destination": "r3AWbdp2jQLXLywJypdoNwVSvr81xs3uhn",
-        "Fee": "10",
-        "Flags": 2147483648,
-        "InvoiceID": "A98FD36C17BE2B8511AD36DC335478E7E89F06262949F36EB88E2D683BBCC50A",
-        "SendMax": {
-          "currency": "BTC",
-          "issuer": "rTJdjjQ5wWAMh8TL1ToXXD2mZzesa6DSX",
-          "value": "0.100798"
-        },
-        "Sequence": 18697,
-        "SigningPubKey": "025D9E40A50D78347EB8AFF7A36222BBE173CB9D06E68D109D189FF8616FC21107",
-        "TransactionType": "Payment",
-        "TxnSignature": "3044022007AA39E0117963ABF03BAEF0C5AB45862093525344362D34B9F6BA8373A0C9DC02206AB4FE915F4CBDA84E668F7F21A9914DC95C83A72FB3F9A114B10D4ECB697A25",
-        "hash": "C738A5095DCE3A256C843AA48BB26F0339EAD3FF09B6D75C2EF50C4AD4B4D17C",
-        "inLedger": 6907159,
-        "ledger_index": 6907159
-      },
-      {
-        "Account": "rHsZHqa5oMQNL5hFm4kfLd47aEMYjPstpg",
-        "Fee": "15",
-        "Flags": 0,
-        "Sequence": 1479726,
-        "SigningPubKey": "025718736160FA6632F48EA4354A35AB0340F8D7DC7083799B9C57C3E937D71851",
-        "TakerGets": "37284087",
-        "TakerPays": {
-          "currency": "NZD",
-          "issuer": "rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc",
-          "value": "0.291570426"
-        },
-        "TransactionType": "OfferCreate",
-        "TxnSignature": "3045022100F246F043C97C0DA7947793E9390DBA5AB0C6EB4A0165DADF0E96C939B70D113C0220797F572368EF68490813663C0E2ACF03424CB73B64F3D6C8508C7E8F6D2CC767",
-        "hash": "CAE39A38C222DF0BBC9AA25D30320220DC216646CE0A447F330BE279B20BD008",
-        "inLedger": 6907159,
-        "ledger_index": 6907159
-      },
-      {
-        "Account": "rHsZHqa5oMQNL5hFm4kfLd47aEMYjPstpg",
-        "Fee": "15",
-        "Flags": 0,
-        "Sequence": 1479725,
-        "SigningPubKey": "025718736160FA6632F48EA4354A35AB0340F8D7DC7083799B9C57C3E937D71851",
-        "TakerGets": "10000000000",
-        "TakerPays": {
-          "currency": "BTC",
-          "issuer": "ra9eZxMbJrUcgV8ui7aPc161FgrqWScQxV",
-          "value": "0.091183099"
-        },
-        "TransactionType": "OfferCreate",
-        "TxnSignature": "30440220376E6D149435B87CA761ED1A9BD205BA93C0C30D6EB1FB26D8B5D06A55977F510220213E882DD43BC78C96B51E43273D9BD451F8337DDF6960CBFB9802A347FF18E4",
-        "hash": "CC07A503ED60F14AF023AB839C726B73591DE5C986D1234671E2518D8F840E12",
-        "inLedger": 6907159,
-        "ledger_index": 6907159
-      },
-      {
-        "Account": "rHsZHqa5oMQNL5hFm4kfLd47aEMYjPstpg",
-        "Fee": "15",
-        "Flags": 0,
-        "Sequence": 1479724,
-        "SigningPubKey": "025718736160FA6632F48EA4354A35AB0340F8D7DC7083799B9C57C3E937D71851",
-        "TakerGets": "9094329166",
-        "TakerPays": {
-          "currency": "XAG",
-          "issuer": "r9Dr5xwkeLegBeXq6ujinjSBLQzQ1zQGjH",
-          "value": "3.022830117"
-        },
-        "TransactionType": "OfferCreate",
-        "TxnSignature": "3045022100CFD63762B3809B37B6A1294C4B4C8DA39023D66893045BA4AA9767DD8570A8F9022005F42B08E94190637158E80DAE99F3FB104EC2AA30F69BBA3417E5BBCDB5DB77",
-        "hash": "64029D736C34D21CDB100D976A06A988E2CA6E3BBC0DDFCE840D9619B853B47C",
-        "inLedger": 6907159,
-        "ledger_index": 6907159
-      }
-    ]
-  }
-}
-
- -
200 OK
-{
-    "result": {
-        "index": 0,
-        "status": "success",
-        "txs": [
-            {
-                "Account": "rPJnufUfjS22swpE7mWRkn2VRNGnHxUSYc",
-                "Fee": "10",
-                "Flags": 2147483648,
-                "Sequence": 567546,
-                "SigningPubKey": "0317766BFFC0AAF5DB4AFDE23236624304AC4BC903AA8B172AE468F6B512616D6A",
-                "TakerGets": {
-                    "currency": "BTC",
-                    "issuer": "rNPRNzBB92BVpAhhZr4iXDTveCgV5Pofm9",
-                    "value": "1.12582"
-                },
-                "TakerPays": {
-                    "currency": "ILS",
-                    "issuer": "rNPRNzBB92BVpAhhZr4iXDTveCgV5Pofm9",
-                    "value": "1981.893528"
-                },
-                "TransactionType": "OfferCreate",
-                "TxnSignature": "3045022100C66F3EE8F955724D750D148E3BB9DCAC16A002F9E4FC612C03AFBE9D8C13888902202607508AD0546C496093C9743B13FD596A1F5BE2B778EFE85BDB99F0E5B1D55F",
-                "hash": "A95C701F6120061BC40323AE846BBDA51576E67EC38105030BE75C1D32231B61",
-                "inLedger": 8696235,
-                "ledger_index": 8696235
-            },
-            {
-                "Account": "rwpxNWdpKu2QVgrh5LQXEygYLshhgnRL1Y",
-                "Fee": "10",
-                "Flags": 2147483648,
-                "Sequence": 1865518,
-                "SigningPubKey": "02BD6F0CFD0182F2F408512286A0D935C58FF41169DAC7E721D159D711695DFF85",
-                "TakerGets": {
-                    "currency": "LTC",
-                    "issuer": "rNPRNzBB92BVpAhhZr4iXDTveCgV5Pofm9",
-                    "value": "1.12095"
-                },
-                "TakerPays": {
-                    "currency": "ILS",
-                    "issuer": "rNPRNzBB92BVpAhhZr4iXDTveCgV5Pofm9",
-                    "value": "20.77526133899999"
-                },
-                "TransactionType": "OfferCreate",
-                "TxnSignature": "304402203F7435A2587A71878B09129A1F4C05066CE6E6463A4A10CD5C40C15FCBD9E42502207E0CB8421FEA4CE8FC052E5A63ACD2444ADAE253B174A153A1DBE901E21B3695",
-                "hash": "A8C79DF180167E4D1281247325E2869984F54CBFA68631C1AF13DA346E6B3370",
-                "inLedger": 8696235,
-                "ledger_index": 8696235
-            },
-            {
-                "Account": "rMWUykAmNQDaM9poSes8VLDZDDKEbmo7MX",
-                "Fee": "10",
-                "Flags": 2147483648,
-                "Sequence": 1886203,
-                "SigningPubKey": "0256C64F0378DCCCB4E0224B36F7ED1E5586455FF105F760245ADB35A8B03A25FD",
-                "TakerGets": {
-                    "currency": "LTC",
-                    "issuer": "rNPRNzBB92BVpAhhZr4iXDTveCgV5Pofm9",
-                    "value": "24.154"
-                },
-                "TakerPays": {
-                    "currency": "BTC",
-                    "issuer": "rNPRNzBB92BVpAhhZr4iXDTveCgV5Pofm9",
-                    "value": "0.26907556"
-                },
-                "TransactionType": "OfferCreate",
-                "TxnSignature": "30440220102CF96A86AF56BA11698C70D60F22436D763634FEA179D2FF45EB329CFF1CF8022029BF9301B11D09B38EBD4E8EB445ECC53B98C4F0CA7E19BE895272085ED6DBA2",
-                "hash": "9EE340379612529F308CA1E4619EC0C8842C1D4308FCA136E25316CE28C28189",
-                "inLedger": 8696235,
-                "ledger_index": 8696235
-            },
-            {
-                "Account": "rJJksugQDMVu12NrZyw3C55fEUmPtRYVRC",
-                "Fee": "10",
-                "Flags": 2147483648,
-                "Sequence": 119205,
-                "SigningPubKey": "03B918730C9FA2451284A00B1EFD08E9BEFD735D84CE09C6B3D7CB8FB0D1F9A84F",
-                "TakerGets": "10136500000",
-                "TakerPays": {
-                    "currency": "USD",
-                    "issuer": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
-                    "value": "50"
-                },
-                "TransactionType": "OfferCreate",
-                "TxnSignature": "3044022044DB48A760AA7FBA2B1840E1357EF6B1EA9CC9DBBFFB5415C6BE301597B66766022021AA86070416330312E3AFC938376AD0A67A28195D7CD92EC8B03A6039D5C86C",
-                "hash": "8149067582081FA1499A53841642345D21FE0750E29C61C6DC3C914E0D1819AB",
-                "inLedger": 8696235,
-                "ledger_index": 8696235
-            },
-            {
-                "Account": "rLPrL6KUtVZZbDfJMjDXzTKkwH39Udfw6e",
-                "Fee": "10",
-                "Flags": 2147483648,
-                "Sequence": 428775,
-                "SigningPubKey": "03B2B67209DBDE2FA68555FB10BD791C4732C685349979FDC47D0DEF2B27EFA364",
-                "TakerGets": {
-                    "currency": "PPC",
-                    "issuer": "rNPRNzBB92BVpAhhZr4iXDTveCgV5Pofm9",
-                    "value": "8.0635"
-                },
-                "TakerPays": {
-                    "currency": "BTC",
-                    "issuer": "rNPRNzBB92BVpAhhZr4iXDTveCgV5Pofm9",
-                    "value": "0.01355474349999999"
-                },
-                "TransactionType": "OfferCreate",
-                "TxnSignature": "3045022100EDDC17FE2C32DEAD8ED5D9540B2ECE25D6CD1C65414211D2E4F98FC5BDABB99E0220389D6B3DE8BA50D27406BCE28E67D1E270C6A3A854CDEF25F042BBA52CDB53F8",
-                "hash": "70B7DB8E2BD65E554CBF418D591E050A6FD0A387E9500ED0B79BEB775019D9CA",
-                "inLedger": 8696235,
-                "ledger_index": 8696235
-            },
-            {
-                "Account": "rM7WN56kktEkE5qKwNkQ1af4BZ56bynVUf",
-                "Fee": "10",
-                "Flags": 2147483648,
-                "Sequence": 435008,
-                "SigningPubKey": "0256AE48790FEF5F61C1AB3765287EABCBE6B47C5098271F596A576DF7CFA15720",
-                "TakerGets": {
-                    "currency": "PPC",
-                    "issuer": "rNPRNzBB92BVpAhhZr4iXDTveCgV5Pofm9",
-                    "value": "0.365"
-                },
-                "TakerPays": {
-                    "currency": "ILS",
-                    "issuer": "rNPRNzBB92BVpAhhZr4iXDTveCgV5Pofm9",
-                    "value": "0.9977421"
-                },
-                "TransactionType": "OfferCreate",
-                "TxnSignature": "3044022057ECAE71B36746AA1574936B03016DC5747EB7DBBA7D85533063E8D35DD2BAF402204F37BCA51CB0D943758BCA89641C2655FB76F20B8AD1883A3ABF232D1E964E80",
-                "hash": "572B0B2E96F4A9A88C7EDBDEB6D90AD2975528478186D9179AEC0E366D2778FC",
-                "inLedger": 8696235,
-                "ledger_index": 8696235
-            },
-            {
-                "Account": "rLjhDX8zT6vy8T7hjUDvK48wTy5SYFpfwZ",
-                "Fee": "10",
-                "Flags": 2147483648,
-                "OfferSequence": 432536,
-                "Sequence": 432561,
-                "SigningPubKey": "03892D08CE3CE600369BA83A92C3C7785FEA162739643358F1F35F8BE672AFD4A3",
-                "TransactionType": "OfferCancel",
-                "TxnSignature": "3045022100C25CE3756EB273F6ADD219E951DB7585ADFAF28090BEA3510458785D2EB91866022057A480F167F6D7263CDBFB0E13D571041313F6476176FFE2645CE867BA85DC2D",
-                "hash": "521D7F2CF76DEAC8ED695AC5570DFF1E445EB8C599158A351BD46F1D34528373",
-                "inLedger": 8696235,
-                "ledger_index": 8696235
-            },
-            {
-                "Account": "rn694SpeUFw3VJwapyRKx6bpru3ZpDHzji",
-                "Fee": "10",
-                "Flags": 2147483648,
-                "Sequence": 396235,
-                "SigningPubKey": "03896496732D098F2D8EE22D65ED9A88C0FF116785AE448EA1F521534C7C5BC6E3",
-                "TakerGets": {
-                    "currency": "ILS",
-                    "issuer": "rNPRNzBB92BVpAhhZr4iXDTveCgV5Pofm9",
-                    "value": "0.700491"
-                },
-                "TakerPays": {
-                    "currency": "NMC",
-                    "issuer": "rNPRNzBB92BVpAhhZr4iXDTveCgV5Pofm9",
-                    "value": "0.22"
-                },
-                "TransactionType": "OfferCreate",
-                "TxnSignature": "30440220218B5B90AB26EAE9FC9833E580653B20A15CEE86E8F1166F626FCDF4EFD4146902207FD99E35EE67E45142776CCD8F910A9E6E1A3C498737B59F182C73183C63D51F",
-                "hash": "454479D7EEE4081CF25378571D74858C01B0B43D3A2530781647BD40CD0465E5",
-                "inLedger": 8696235,
-                "ledger_index": 8696235
-            },
-            {
-                "Account": "rRh634Y6QtoqkwTTrGzX66UYoCAvgE6jL",
-                "Fee": "10",
-                "Flags": 2147483648,
-                "Sequence": 676061,
-                "SigningPubKey": "030BB49C591C9CD65C945D4B78332F27633D7771E6CF4D4B942D26BA40748BB8B4",
-                "TakerGets": {
-                    "currency": "BTC",
-                    "issuer": "rNPRNzBB92BVpAhhZr4iXDTveCgV5Pofm9",
-                    "value": "0.09675"
-                },
-                "TakerPays": "10527647107",
-                "TransactionType": "OfferCreate",
-                "TxnSignature": "3044022014196BC5867AC2689F7EF31F23E4B2D1D1B7755465AC388B20F8E7721333EEE302201575263F381755E47AFCD37C1D5CCA4C012D624E7947140B40ABF1975959AA78",
-                "hash": "22B2F477ADE9C22599EB5CEF70B3377C0478D708D74A47866D9E59B7A2CF57CF",
-                "inLedger": 8696235,
-                "ledger_index": 8696235
-            },
-            {
-                "Account": "rJJksugQDMVu12NrZyw3C55fEUmPtRYVRC",
-                "Fee": "10",
-                "Flags": 2147483648,
-                "OfferSequence": 119183,
-                "Sequence": 119204,
-                "SigningPubKey": "03B918730C9FA2451284A00B1EFD08E9BEFD735D84CE09C6B3D7CB8FB0D1F9A84F",
-                "TransactionType": "OfferCancel",
-                "TxnSignature": "30440220481760ED4F771F960F37FDF32DDEC70D10F9D5F9868571A58D6F5C09D75B71DE022049B35BEA448686D0929271E64EADA684D7684A9195D22826288AD9D9526B4FE9",
-                "hash": "5E0E42BDDC7A929875F5E9214AB00C3673CC047833C0EFC093532F2EE1F790C2",
-                "inLedger": 8696234,
-                "ledger_index": 8696234
-            },
-            {
-                "Account": "rM7WN56kktEkE5qKwNkQ1af4BZ56bynVUf",
-                "Fee": "10",
-                "Flags": 2147483648,
-                "OfferSequence": 434977,
-                "Sequence": 435007,
-                "SigningPubKey": "0256AE48790FEF5F61C1AB3765287EABCBE6B47C5098271F596A576DF7CFA15720",
-                "TransactionType": "OfferCancel",
-                "TxnSignature": "304402204B04325A39F3D394A7EBC91CE3A1232E538EFFC80014473C97E84310886A19B302205B2D18C544086BB99E49A1037B65ADDF4864DA60545E33E4116A41599EEE63E3",
-                "hash": "E8E55606C757219A740AFA0700506FE99781797E2F54A5144EF43582C65BF0F2",
-                "inLedger": 8696234,
-                "ledger_index": 8696234
-            },
-            {
-                "Account": "rLPrL6KUtVZZbDfJMjDXzTKkwH39Udfw6e",
-                "Fee": "10",
-                "Flags": 2147483648,
-                "OfferSequence": 428744,
-                "Sequence": 428774,
-                "SigningPubKey": "03B2B67209DBDE2FA68555FB10BD791C4732C685349979FDC47D0DEF2B27EFA364",
-                "TransactionType": "OfferCancel",
-                "TxnSignature": "304402202BCB4FCE73C3417AD3E67D795077DE025E766A9136CA20D5B07DA28EA717643E0220579CA32A7BB225DA01999637B316BF7D3902059F9A8DDB2D721F8A62685E5BB7",
-                "hash": "E86788EC72CA9CFBBAE4C399744C6B7495E3F6443FE87D7A4118F16FA4A316DB",
-                "inLedger": 8696234,
-                "ledger_index": 8696234
-            },
-            {
-                "Account": "rHsZHqa5oMQNL5hFm4kfLd47aEMYjPstpg",
-                "Fee": "64",
-                "Flags": 0,
-                "Sequence": 4216371,
-                "SigningPubKey": "025718736160FA6632F48EA4354A35AB0340F8D7DC7083799B9C57C3E937D71851",
-                "TakerGets": "12566721624",
-                "TakerPays": {
-                    "currency": "USD",
-                    "issuer": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
-                    "value": "74.999999999"
-                },
-                "TransactionType": "OfferCreate",
-                "TxnSignature": "3045022100D0FA06A78D3333D35C798B45590CD47BD844164ED25FCA4149F5F0CF24BE9A380220243EB636C656D1FBA6888CE8E2873CDA40FE6DE5987BE2FF1C418610D8BDC300",
-                "hash": "DD4CAD3EBCF67CE9B184A917FF2C78A80F0FE40A01187840E0EBC6B479DBFE1A",
-                "inLedger": 8696234,
-                "ledger_index": 8696234
-            },
-            {
-                "Account": "rJJksugQDMVu12NrZyw3C55fEUmPtRYVRC",
-                "Fee": "10",
-                "Flags": 2147483648,
-                "OfferSequence": 119182,
-                "Sequence": 119203,
-                "SigningPubKey": "03B918730C9FA2451284A00B1EFD08E9BEFD735D84CE09C6B3D7CB8FB0D1F9A84F",
-                "TransactionType": "OfferCancel",
-                "TxnSignature": "304402202F13D25C82240ABBBEE0D7E8BC2351C49FD6FDD62359EA232233C5A6C989BFAA022005A521A2C5A67BAC27218A6AD9E6917689CBD2F9BB9CE884B6B0EAAEDDEC2057",
-                "hash": "C9D8A2ECE636057E8255A231E6C6B6464A730155BA0E75B5111A81EA769FBC89",
-                "inLedger": 8696234,
-                "ledger_index": 8696234
-            },
-            {
-                "Account": "rGJrzrNBfv6ndJmzt1hTUJVx7z8o2bg3of",
-                "Fee": "15",
-                "Flags": 2147483648,
-                "LastLedgerSequence": 8696241,
-                "OfferSequence": 1579754,
-                "Sequence": 1579755,
-                "SigningPubKey": "03325EB29A014DDE22289D0EA989861D481D54D54C727578AB6C2F18BC342D3829",
-                "TransactionType": "OfferCancel",
-                "TxnSignature": "3045022100C9F283D461F8A56575A56F8AA31F84683AB0B44D58C9EFD5DC20D448D8AC13E3022012E0A8726BE2D900C4FB7A61AB8FBFEBEBE1F12B2A9880A2BA2AB8D3EC61CB8C",
-                "hash": "C4953FE328D54E9104F66253AF50AEBC26E30D5826B433465A795262DFA75B48",
-                "inLedger": 8696234,
-                "ledger_index": 8696234
-            },
-            {
-                "Account": "rn694SpeUFw3VJwapyRKx6bpru3ZpDHzji",
-                "Fee": "10",
-                "Flags": 2147483648,
-                "Sequence": 396234,
-                "SigningPubKey": "03896496732D098F2D8EE22D65ED9A88C0FF116785AE448EA1F521534C7C5BC6E3",
-                "TakerGets": {
-                    "currency": "ILS",
-                    "issuer": "rNPRNzBB92BVpAhhZr4iXDTveCgV5Pofm9",
-                    "value": "0.3335471399999999"
-                },
-                "TakerPays": {
-                    "currency": "NMC",
-                    "issuer": "rNPRNzBB92BVpAhhZr4iXDTveCgV5Pofm9",
-                    "value": "0.102"
-                },
-                "TransactionType": "OfferCreate",
-                "TxnSignature": "3045022100DEA2B6D5B0D555D54A4EB7A8FADC187F44C6A9CF7282A1D5491538200DFC97DA022033A52D1EC219553C86DB829108BB5A52B49ED7EF0A566941665DE7FFF70917ED",
-                "hash": "A6BE633AECE9FF9CA83D67D09E7EF67F614A9D8B952D7AFB5CB630D03C54C9FC",
-                "inLedger": 8696234,
-                "ledger_index": 8696234
-            },
-            {
-                "Account": "rwpxNWdpKu2QVgrh5LQXEygYLshhgnRL1Y",
-                "Fee": "10",
-                "Flags": 2147483648,
-                "OfferSequence": 1865490,
-                "Sequence": 1865517,
-                "SigningPubKey": "02BD6F0CFD0182F2F408512286A0D935C58FF41169DAC7E721D159D711695DFF85",
-                "TransactionType": "OfferCancel",
-                "TxnSignature": "3044022074A4E9859A5A94169B2C902F074AA964C45E2B86EABEA73E83E083E1EC7549A402203E8F4D46705AFEDFC78C2D40FAA036792E6485AF8CADF7445EA3D427E9DC2474",
-                "hash": "A49285E2CA7C5765B68A41EF4A8A65AD5CC7D4EF6C7B7F6D5040B2DE429E0125",
-                "inLedger": 8696234,
-                "ledger_index": 8696234
-            },
-            {
-                "Account": "rPJnufUfjS22swpE7mWRkn2VRNGnHxUSYc",
-                "Fee": "10",
-                "Flags": 2147483648,
-                "Sequence": 567545,
-                "SigningPubKey": "0317766BFFC0AAF5DB4AFDE23236624304AC4BC903AA8B172AE468F6B512616D6A",
-                "TakerGets": {
-                    "currency": "BTC",
-                    "issuer": "rNPRNzBB92BVpAhhZr4iXDTveCgV5Pofm9",
-                    "value": "0.66099"
-                },
-                "TakerPays": {
-                    "currency": "ILS",
-                    "issuer": "rNPRNzBB92BVpAhhZr4iXDTveCgV5Pofm9",
-                    "value": "1157.5521276"
-                },
-                "TransactionType": "OfferCreate",
-                "TxnSignature": "3045022100CABC7C1F9FB42C8498E1E9C6C5E8482F325D39B15D9DAE4BD9878D5E508B8FDD0220407B059A22BBBF4FC4AE18BEDCD2DDA80109EE7226D679A8A3BBFC108EFDD3AB",
-                "hash": "A0BED2F5A85C48A2AFBA252FF91FD2D5C90A6D6B769068B18891B031812E2AC0",
-                "inLedger": 8696234,
-                "ledger_index": 8696234
-            },
-            {
-                "Account": "rLLq27Wat93Gxkq5mV5GxtKkT146Su949V",
-                "Fee": "10",
-                "Flags": 2147483648,
-                "Sequence": 722529,
-                "SigningPubKey": "02A1BC1CCFACECD00ADC6EE990E2E27148E00D5386A99791F25B6A880BCEC94EC9",
-                "TakerGets": "130272502088",
-                "TakerPays": {
-                    "currency": "BTC",
-                    "issuer": "rNPRNzBB92BVpAhhZr4iXDTveCgV5Pofm9",
-                    "value": "1.3177"
-                },
-                "TransactionType": "OfferCreate",
-                "TxnSignature": "30440220436C4A368D534FE1E9A2596C51D1D54931432B789F249E312877FF9B38A3F4D502202A2DBF9517358C009FBEA61EE927DAF72A065A840C7B9136B10C125F25FCD175",
-                "hash": "9627AEFC735A848AAE6C36D1089CB8797373DBE95B60E89F5412508CA907243A",
-                "inLedger": 8696234,
-                "ledger_index": 8696234
-            },
-            {
-                "Account": "rMWUykAmNQDaM9poSes8VLDZDDKEbmo7MX",
-                "Fee": "10",
-                "Flags": 2147483648,
-                "OfferSequence": 1886173,
-                "Sequence": 1886202,
-                "SigningPubKey": "0256C64F0378DCCCB4E0224B36F7ED1E5586455FF105F760245ADB35A8B03A25FD",
-                "TransactionType": "OfferCancel",
-                "TxnSignature": "304402202C7BD2C125A0B837CBD2E2FF568AEA1E0EE94615B22564A51C0434460C506C6F02204E39A7BD49086AA794B20F4EE28656217561909ECFBB18636CD400AB33AB0B17",
-                "hash": "57277F527B8EBD68FE85906E613338D68F8F8BC4EB3D1748D9A204D7CDC3E174",
-                "inLedger": 8696234,
-                "ledger_index": 8696234
-            }
-        ]
-    }
-}
-
-
-

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

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
indexUnsigned IntegerThe value of start used in the request.
txsArrayArray of transaction objects.
-

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

-

Possible Errors

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

path_find

-

[Source]

-

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

-

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

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

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

-

path_find create

-

[Source]

-

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

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-    "id": 8,
-    "command": "path_find",
-    "subcommand": "create",
-    "source_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-    "destination_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-    "destination_amount": {
-        "value": "0.001",
-        "currency": "USD",
-        "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-    }
-}
-
-
-

Try it!

-

The request includes the following parameters:

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

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

-

Response Format

-

An example of a successful response:

-
- -
{
-  "id": 1,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "alternatives": [
-      {
-        "paths_computed": [
-          [
-            {
-              "currency": "USD",
-              "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 48,
-              "type_hex": "0000000000000030"
-            },
-            {
-              "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            }
-          ],
-          [
-            {
-              "currency": "USD",
-              "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-              "type": 48,
-              "type_hex": "0000000000000030"
-            },
-            {
-              "account": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            }
-          ],
-          [
-            {
-              "currency": "USD",
-              "issuer": "r9vbV3EHvXWjSkeQ6CAcYVPGeq7TuiXY2X",
-              "type": 48,
-              "type_hex": "0000000000000030"
-            },
-            {
-              "account": "r9vbV3EHvXWjSkeQ6CAcYVPGeq7TuiXY2X",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            }
-          ],
-          [
-            {
-              "currency": "USD",
-              "issuer": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
-              "type": 48,
-              "type_hex": "0000000000000030"
-            },
-            {
-              "account": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            }
-          ]
-        ],
-        "source_amount": "251686"
-      },
-      {
-        "paths_computed": [
-          [
-            {
-              "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            },
-            {
-              "currency": "USD",
-              "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 48,
-              "type_hex": "0000000000000030"
-            },
-            {
-              "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            }
-          ],
-          [
-            {
-              "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            },
-            {
-              "currency": "USD",
-              "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-              "type": 48,
-              "type_hex": "0000000000000030"
-            },
-            {
-              "account": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            }
-          ],
-          [
-            {
-              "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            },
-            {
-              "currency": "USD",
-              "issuer": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
-              "type": 48,
-              "type_hex": "0000000000000030"
-            },
-            {
-              "account": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            }
-          ]
-        ],
-        "source_amount": {
-          "currency": "BTC",
-          "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-          "value": "0.000001541291269274307"
-        }
-      },
-      {
-        "paths_computed": [
-          [
-            {
-              "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            },
-            {
-              "currency": "USD",
-              "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 48,
-              "type_hex": "0000000000000030"
-            },
-            {
-              "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            }
-          ]
-        ],
-        "source_amount": {
-          "currency": "CHF",
-          "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-          "value": "0.0009211546262510451"
-        }
-      },
-      {
-        "paths_computed": [
-          [
-            {
-              "account": "razqQKzJRdB4UxFPWf5NEpEG3WMkmwgcXA",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            },
-            {
-              "currency": "USD",
-              "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-              "type": 48,
-              "type_hex": "0000000000000030"
-            },
-            {
-              "account": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            }
-          ],
-          [
-            {
-              "account": "razqQKzJRdB4UxFPWf5NEpEG3WMkmwgcXA",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            },
-            {
-              "currency": "USD",
-              "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 48,
-              "type_hex": "0000000000000030"
-            },
-            {
-              "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            }
-          ]
-        ],
-        "source_amount": {
-          "currency": "CNY",
-          "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-          "value": "0.006293562"
-        }
-      },
-      {
-        "paths_computed": [
-          [
-            {
-              "account": "rGwUWgN5BEg3QGNY3RX2HfYowjUTZdid3E",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            },
-            {
-              "currency": "USD",
-              "issuer": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
-              "type": 48,
-              "type_hex": "0000000000000030"
-            },
-            {
-              "account": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            }
-          ],
-          [
-            {
-              "account": "rGwUWgN5BEg3QGNY3RX2HfYowjUTZdid3E",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            },
-            {
-              "currency": "USD",
-              "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 48,
-              "type_hex": "0000000000000030"
-            },
-            {
-              "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            }
-          ],
-          [
-            {
-              "account": "rGwUWgN5BEg3QGNY3RX2HfYowjUTZdid3E",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            },
-            {
-              "currency": "USD",
-              "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-              "type": 48,
-              "type_hex": "0000000000000030"
-            },
-            {
-              "account": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            }
-          ]
-        ],
-        "source_amount": {
-          "currency": "DYM",
-          "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-          "value": "0.0007157142857142858"
-        }
-      },
-      {
-        "paths_computed": [
-          [
-            {
-              "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            },
-            {
-              "currency": "USD",
-              "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 48,
-              "type_hex": "0000000000000030"
-            },
-            {
-              "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            }
-          ],
-          [
-            {
-              "account": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            },
-            {
-              "currency": "USD",
-              "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 48,
-              "type_hex": "0000000000000030"
-            },
-            {
-              "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            }
-          ],
-          [
-            {
-              "account": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            },
-            {
-              "currency": "USD",
-              "issuer": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
-              "type": 48,
-              "type_hex": "0000000000000030"
-            },
-            {
-              "account": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            }
-          ]
-        ],
-        "source_amount": {
-          "currency": "EUR",
-          "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-          "value": "0.0007409623616236163"
-        }
-      },
-      {
-        "paths_computed": [
-          [
-            {
-              "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            },
-            {
-              "currency": "USD",
-              "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 48,
-              "type_hex": "0000000000000030"
-            },
-            {
-              "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-              "type": 1,
-              "type_hex": "0000000000000001"
-            }
-          ]
-        ],
-        "source_amount": {
-          "currency": "JPY",
-          "issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-          "value": "0.103412412"
-        }
-      }
-    ],
-    "destination_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-    "destination_amount": {
-      "currency": "USD",
-      "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-      "value": "0.001"
-    },
-    "id": 1,
-    "source_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-    "full_reply": false
-  }
-}
-
-
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
alternativesArrayArray of objects with suggested paths to take, as described below. If empty, then no paths were found connecting the source and destination accounts.
destination_accountStringUnique address of the account that would receive a transaction
destination_amountString or ObjectCurrency amount that the destination would receive in a transaction
id(Various)(WebSocket only) The ID provided in the WebSocket request is included again at this level.
source_accountStringUnique address that would send a transaction
full_replyBooleanIf false, this is the result of an incomplete search. A later reply may have a better path. If true, then this is the best path found. (It is still theoretically possible that a better path could exist, but rippled won't find it.) Until you close the pathfinding request, rippled continues to send updates each time a new ledger closes. New in: rippled 0.29.0
-

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

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
paths_computedArrayArray of arrays of objects defining payment paths
source_amountString or ObjectCurrency amount that the source would have to send along this path for the destination to receive the desired amount
-

Possible Errors

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

Asynchronous Follow-ups

-

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

-

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

-

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

-
- -
{
-    "id": 1,
-    "type": "path_find",
-    "alternatives": [
-        /* paths omitted from this example; same format as the initial response */
-    ],
-    "destination_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-    "destination_amount": {
-        "currency": "USD",
-        "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-        "value": "0.001"
-    },
-    "source_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59"
-}
-
-
-

path_find close

-

[Source]

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-  "id": 57,
-  "command": "path_find",
-  "subcommand": "close"
-}
-
-
-

The request includes the following parameters:

- - - - - - - - - - - - - - - -
FieldTypeDescription
subcommandStringUse "close" to send the close subcommand
-

Response Format

-

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

- - - - - - - - - - - - - - - -
FieldTypeDescription
closedBooleanThe value true indicates this reply is in response to a path_find close command.
-

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

-

Possible Errors

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

path_find status

-

[Source]

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-  "id": 58,
-  "command": "path_find",
-  "subcommand": "status"
-}
-
-
-

The request includes the following parameters:

- - - - - - - - - - - - - - - -
FieldTypeDescription
subcommandStringUse "status" to send the status subcommand
-

Response Format

-

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

- - - - - - - - - - - - - - - -
FieldTypeDescription
statusBooleanThe value true indicates this reply is in response to a path_find status command.
-

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

-

Possible Errors

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

ripple_path_find

-

[Source]

-

The ripple_path_find method is a simplified version of path_find that provides a single response with a payment path you can use right away. It is available in both the WebSocket and JSON-RPC APIs. However, the results tend to become outdated as time passes. Instead of making multiple calls to stay updated, you should use path_find instead where possible.

-

Although the rippled server tries to find the cheapest path or combination of paths for making a payment, it is not guaranteed that the paths returned by this method are, in fact, the best paths.

-

Caution: Be careful with the pathfinding results from untrusted servers. A server could be modified to return less-than-optimal paths to earn money for its operators. A server may also return poor results when under heavy load. If you do not have your own server that you can trust with pathfinding, you should compare the results of pathfinding from multiple servers run by different parties, to minimize the risk of a single server returning poor results.

-

Request Format

-

An example of the request format:

-
- -
{
-    "id": 8,
-    "command": "ripple_path_find",
-    "source_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-    "source_currencies": [
-        {
-            "currency": "XRP"
-        },
-        {
-            "currency": "USD"
-        }
-    ],
-    "destination_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-    "destination_amount": {
-        "value": "0.001",
-        "currency": "USD",
-        "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-    }
-}
-
- -
{
-    "method": "ripple_path_find",
-    "params": [
-        {
-            "destination_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-            "destination_amount": {
-                "currency": "USD",
-                "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-                "value": "0.001"
-            },
-            "source_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-            "source_currencies": [
-                {
-                    "currency": "XRP"
-                },
-                {
-                    "currency": "USD"
-                }
-            ]
-        }
-    ]
-}
-
- -
#Syntax ripple_path_find json ledger_index|ledger_hash
-rippled ripple_path_find '{"source_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59", "source_currencies": [ { "currency": "XRP" }, { "currency": "USD" } ], "destination_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59", "destination_amount": { "value": "0.001", "currency": "USD", "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B" } }'
-
-
-

Try it!

-

The request includes the following parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
source_accountStringUnique address of the account that would send funds in a transaction
destination_accountStringUnique address of the account that would receive funds in a transaction
destination_amountString or ObjectCurrency amount that the destination account would receive in a transaction. Special case: New in: rippled 0.30.0 You can specify "-1" (for XRP) or provide -1 as the contents of the value field (for non-XRP currencies). This requests a path to deliver as much as possible, while spending no more than the amount specified in send_max (if provided).
send_maxString or Object(Optional) Currency amount that would be spent in the transaction. Cannot be used with source_currencies. New in: rippled 0.30.0
source_currenciesArray(Optional) 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, like how currency amounts are specified. Cannot contain more than 18 source currencies. By default, uses all source currencies available up to a maximum of 88 different currency/issuer pairs.
ledger_hashString(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger)
ledger_indexString or Unsigned Integer(Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)
-

Response Format

-

An example of a successful response:

-
- -
{
-    "id": 8,
-    "status": "success",
-    "type": "response",
-    "result": {
-        "alternatives": [
-            {
-                "paths_canonical": [],
-                "paths_computed": [
-                    [
-                        {
-                            "currency": "USD",
-                            "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-                            "type": 48,
-                            "type_hex": "0000000000000030"
-                        },
-                        {
-                            "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-                            "type": 1,
-                            "type_hex": "0000000000000001"
-                        }
-                    ],
-                    [
-                        {
-                            "currency": "USD",
-                            "issuer": "rrpNnNLKrartuEqfJGpqyDwPj1AFPg9vn1",
-                            "type": 48,
-                            "type_hex": "0000000000000030"
-                        },
-                        {
-                            "account": "rrpNnNLKrartuEqfJGpqyDwPj1AFPg9vn1",
-                            "type": 1,
-                            "type_hex": "0000000000000001"
-                        },
-                        {
-                            "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-                            "type": 1,
-                            "type_hex": "0000000000000001"
-                        }
-                    ],
-                    [
-                        {
-                            "currency": "USD",
-                            "issuer": "rrpNnNLKrartuEqfJGpqyDwPj1AFPg9vn1",
-                            "type": 48,
-                            "type_hex": "0000000000000030"
-                        },
-                        {
-                            "account": "rrpNnNLKrartuEqfJGpqyDwPj1AFPg9vn1",
-                            "type": 1,
-                            "type_hex": "0000000000000001"
-                        },
-                        {
-                            "account": "rLpq4LgabRfm1xEX5dpWfJovYBH6g7z99q",
-                            "type": 1,
-                            "type_hex": "0000000000000001"
-                        },
-                        {
-                            "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-                            "type": 1,
-                            "type_hex": "0000000000000001"
-                        }
-                    ],
-                    [
-                        {
-                            "currency": "USD",
-                            "issuer": "rrpNnNLKrartuEqfJGpqyDwPj1AFPg9vn1",
-                            "type": 48,
-                            "type_hex": "0000000000000030"
-                        },
-                        {
-                            "account": "rrpNnNLKrartuEqfJGpqyDwPj1AFPg9vn1",
-                            "type": 1,
-                            "type_hex": "0000000000000001"
-                        },
-                        {
-                            "account": "rPuBoajMjFoDjweJBrtZEBwUMkyruxpwwV",
-                            "type": 1,
-                            "type_hex": "0000000000000001"
-                        },
-                        {
-                            "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-                            "type": 1,
-                            "type_hex": "0000000000000001"
-                        }
-                    ]
-                ],
-                "source_amount": "256987"
-            }
-        ],
-        "destination_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-        "destination_currencies": [
-            "015841551A748AD2C1F76FF6ECB0CCCD00000000",
-            "JOE",
-            "DYM",
-            "EUR",
-            "CNY",
-            "MXN",
-            "BTC",
-            "USD",
-            "XRP"
-        ]
-    }
-}
-
- -
200 OK
-{
-    "result": {
-        "alternatives": [
-            {
-                "paths_canonical": [],
-                "paths_computed": [
-                    [
-                        {
-                            "currency": "USD",
-                            "issuer": "rpDMez6pm6dBve2TJsmDpv7Yae6V5Pyvy2",
-                            "type": 48,
-                            "type_hex": "0000000000000030"
-                        },
-                        {
-                            "account": "rpDMez6pm6dBve2TJsmDpv7Yae6V5Pyvy2",
-                            "type": 1,
-                            "type_hex": "0000000000000001"
-                        },
-                        {
-                            "account": "rfDeu7TPUmyvUrffexjMjq3mMcSQHZSYyA",
-                            "type": 1,
-                            "type_hex": "0000000000000001"
-                        },
-                        {
-                            "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-                            "type": 1,
-                            "type_hex": "0000000000000001"
-                        }
-                    ],
-                    [
-                        {
-                            "currency": "USD",
-                            "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-                            "type": 48,
-                            "type_hex": "0000000000000030"
-                        },
-                        {
-                            "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-                            "type": 1,
-                            "type_hex": "0000000000000001"
-                        }
-                    ],
-                    [
-                        {
-                            "currency": "USD",
-                            "issuer": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
-                            "type": 48,
-                            "type_hex": "0000000000000030"
-                        },
-                        {
-                            "account": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
-                            "type": 1,
-                            "type_hex": "0000000000000001"
-                        },
-                        {
-                            "account": "raspZSGNiTKi5jmvFxUYCuYXPv1V8WhL5g",
-                            "type": 1,
-                            "type_hex": "0000000000000001"
-                        },
-                        {
-                            "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-                            "type": 1,
-                            "type_hex": "0000000000000001"
-                        }
-                    ],
-                    [
-                        {
-                            "currency": "USD",
-                            "issuer": "rpHgehzdpfWRXKvSv6duKvVuo1aZVimdaT",
-                            "type": 48,
-                            "type_hex": "0000000000000030"
-                        },
-                        {
-                            "account": "rpHgehzdpfWRXKvSv6duKvVuo1aZVimdaT",
-                            "type": 1,
-                            "type_hex": "0000000000000001"
-                        },
-                        {
-                            "account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-                            "type": 1,
-                            "type_hex": "0000000000000001"
-                        }
-                    ]
-                ],
-                "source_amount": "207414"
-            }
-        ],
-        "destination_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-        "destination_currencies": [
-            "USD",
-            "JOE",
-            "BTC",
-            "DYM",
-            "CNY",
-            "EUR",
-            "015841551A748AD2C1F76FF6ECB0CCCD00000000",
-            "MXN",
-            "XRP"
-        ],
-        "status": "success"
-    }
-}
-
-
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
alternativesArrayArray of objects with possible paths to take, as described below. If empty, then there are no paths connecting the source and destination accounts.
destination_accountStringUnique address of the account that would receive a payment transaction
destination_currenciesArrayArray of strings representing the currencies that the destination accepts, as 3-letter codes like "USD" or as 40-character hex like "015841551A748AD2C1F76FF6ECB0CCCD00000000"
-

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

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
paths_computedArrayArray of arrays of objects defining payment paths
source_amountString or ObjectCurrency amount that the source would have to send along this path for the destination to receive the desired amount
-

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

-

Possible Errors

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

sign

-

[Source]

-

The sign method takes a transaction in JSON format and a secret key, and returns a signed binary representation of the transaction. The result is always different, even when you provide the same transaction JSON and secret key. To contribute one signature to a multi-signed transaction, use the sign_for command instead.

-

Caution: Unless you run the rippled server yourself, you should do local signing with RippleAPI instead of using this command. An untrustworthy server could change the transaction before signing it, or use your secret key to sign additional arbitrary transactions as if they came from you.

-

Request Format

-

An example of the request format:

-
- -
{
-  "id": 2,
-  "command": "sign",
-  "tx_json" : {
-      "TransactionType" : "Payment",
-      "Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-      "Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-      "Amount" : {
-         "currency" : "USD",
-         "value" : "1",
-         "issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
-      }
-   },
-   "secret" : "s████████████████████████████",
-   "offline": false,
-   "fee_mult_max": 1000
-}
-
- -
{
-    "method": "sign",
-    "params": [
-        {
-            "offline": false,
-            "secret": "s████████████████████████████",
-            "tx_json": {
-                "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-                "Amount": {
-                    "currency": "USD",
-                    "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-                    "value": "1"
-                },
-                "Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-                "TransactionType": "Payment"
-            },
-            "fee_mult_max": 1000
-        }
-    ]
-}
-
- -
#Syntax: sign secret tx_json [offline]
-rippled sign s████████████████████████████ '{"TransactionType": "Payment", "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", "Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX", "Amount": { "currency": "USD", "value": "1", "issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn" }, "Sequence": 360, "Fee": "10000"}' offline
-
-
-

Try it!

-

To sign a transaction, you must provide a secret key that can authorize the transaction. You can do this in a few ways:

-
    -
  • Provide a secret value and omit the key_type field. This value can be formatted as 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.)
    • -
-

The request includes the following parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
tx_jsonObjectTransaction definition in JSON format
secretString(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.
seedString(Optional) Secret key of the account supplying the transaction, used to sign it. Must be in base58 format. If provided, you must also specify the key_type. Cannot be used with secret, seed_hex, or passphrase.
seed_hexString(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.
passphraseString(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_typeString(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.
offlineBoolean(Optional, defaults to false) If true, when constructing the transaction, do not try to automatically fill in or validate values.
build_pathBoolean(Optional) If provided for a Payment-type transaction, automatically fill in the Paths field before signing. Caution: The server looks for the presence or absence of this field, not its value. This behavior may change.
fee_mult_maxInteger(Optional, defaults to 10; recommended value 1000) Limits how high the automatically-provided Fee field can be. Signing fails with the error rpcHIGH_FEE if the current load multiplier on the transaction cost is greater than (fee_mult_max ÷ fee_div_max). Ignored if you specify the Fee field of the transaction (transaction cost).
fee_div_maxInteger(Optional, defaults to 1) Signing fails with the error rpcHIGH_FEE if the current load multiplier on the transaction cost is greater than (fee_mult_max ÷ fee_div_max). Ignored if you specify the Fee field of the transaction (transaction cost). New in: rippled 0.30.1
-

Auto-Fillable Fields

-

The server automatically tries to fill in certain fields in tx_json (the Transaction object) automatically if you omit them. The server provides the following fields before signing, unless the request specified offline as true:

-
    -
  • Sequence - The server automatically uses the next Sequence number from the sender's account information.
      -
    • Caution: The next sequence number for the account is not incremented until this transaction is applied. If you sign multiple transactions without submitting and waiting for the response to each one, you must manually provide the correct sequence numbers for each transaction after the first.
      • -
    -
    • -
  • Fee - If you omit the Fee parameter, the server tries to fill in an appropriate transaction cost automatically. On the production XRP Ledger, this fails with rpcHIGH_FEE unless you provide an appropriate fee_mult_max value.
      -
    • The fee_mult_max and fee_div_max parameters limit how high the automatically-provided transaction cost can be, in terms of the load-scaling multiplier that gets applied to the reference transaction cost. The default settings return an error if the automatically-provided value would use greater than a 10× multiplier. However, the production XRP Ledger typically has a 1000× load multiplier.
      • -
    • The commandline syntax does not support fee_mult_max and fee_div_max. For the production XRP Ledger, you must provide a Fee value.
      • -
    • Caution: A malicious server can specify an excessively high transaction cost, ignoring the values of fee_mult_max and fee_div_max.
      • -
    -
    • -
  • Paths - For Payment-type transactions (excluding XRP-to-XRP transfers), the Paths field can be automatically filled, as if you did a ripple_path_find. Only filled if build_path is provided.
    • -
-

Response Format

-

An example of a successful response:

-
- -
{
-  "id": 2,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "tx_blob": "1200002280000000240000016861D4838D7EA4C6800000000000000000000000000055534400000000004B4E9C06F24296074F7BC48F92A97916C6DC5EA9684000000000002710732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB7446304402200E5C2DD81FDF0BE9AB2A8D797885ED49E804DBF28E806604D878756410CA98B102203349581946B0DDA06B36B35DBC20EDA27552C1F167BCF5C6ECFF49C6A46F858081144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143E9D4A2B8AA0780F682D136F7A56D6724EF53754",
-    "tx_json": {
-      "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-      "Amount": {
-        "currency": "USD",
-        "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-        "value": "1"
-      },
-      "Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-      "Fee": "10000",
-      "Flags": 2147483648,
-      "Sequence": 360,
-      "SigningPubKey": "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB",
-      "TransactionType": "Payment",
-      "TxnSignature": "304402200E5C2DD81FDF0BE9AB2A8D797885ED49E804DBF28E806604D878756410CA98B102203349581946B0DDA06B36B35DBC20EDA27552C1F167BCF5C6ECFF49C6A46F8580",
-      "hash": "4D5D90890F8D49519E4151938601EF3D0B30B16CD6A519D9C99102C9FA77F7E0"
-    }
-  }
-}
-
- -
200 OK
-{
-    "result": {
-        "status": "success",
-        "tx_blob": "1200002280000000240000016861D4838D7EA4C6800000000000000000000000000055534400000000004B4E9C06F24296074F7BC48F92A97916C6DC5EA9684000000000002710732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB7446304402200E5C2DD81FDF0BE9AB2A8D797885ED49E804DBF28E806604D878756410CA98B102203349581946B0DDA06B36B35DBC20EDA27552C1F167BCF5C6ECFF49C6A46F858081144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143E9D4A2B8AA0780F682D136F7A56D6724EF53754",
-        "tx_json": {
-            "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-            "Amount": {
-                "currency": "USD",
-                "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-                "value": "1"
-            },
-            "Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-            "Fee": "10000",
-            "Flags": 2147483648,
-            "Sequence": 360,
-            "SigningPubKey": "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB",
-            "TransactionType": "Payment",
-            "TxnSignature": "304402200E5C2DD81FDF0BE9AB2A8D797885ED49E804DBF28E806604D878756410CA98B102203349581946B0DDA06B36B35DBC20EDA27552C1F167BCF5C6ECFF49C6A46F8580",
-            "hash": "4D5D90890F8D49519E4151938601EF3D0B30B16CD6A519D9C99102C9FA77F7E0"
-        }
-    }
-}
-
- -
Loading: "/etc/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "status" : "success",
-      "tx_blob" : "1200002280000000240000016861D4838D7EA4C6800000000000000000000000000055534400000000004B4E9C06F24296074F7BC48F92A97916C6DC5EA9684000000000002710732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB7447304502210094D24C795CFFA8E46FE338AF63421DA5CE5E171ED56F8E4CE70FFABA15D3CFA2022063994C52BF0393C8157EBFFCDE6A7E7EDC7B16A462CA53214F64CC8FCBB5E54A81144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143E9D4A2B8AA0780F682D136F7A56D6724EF53754",
-      "tx_json" : {
-         "Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-         "Amount" : {
-            "currency" : "USD",
-            "issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-            "value" : "1"
-         },
-         "Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-         "Fee" : "10000",
-         "Flags" : 2147483648,
-         "Sequence" : 360,
-         "SigningPubKey" : "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB",
-         "TransactionType" : "Payment",
-         "TxnSignature" : "304502210094D24C795CFFA8E46FE338AF63421DA5CE5E171ED56F8E4CE70FFABA15D3CFA2022063994C52BF0393C8157EBFFCDE6A7E7EDC7B16A462CA53214F64CC8FCBB5E54A",
-         "hash" : "DE80DA6FF9F93FE4CE87C99441F403E0290E35867FF48382204CB89975BF343E"
-      }
-   }
-}
-
-
-

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

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
tx_blobStringBinary representation of the fully-qualified, signed transaction, as hex
tx_jsonObjectJSON specification of the complete transaction as signed, including any fields that were automatically filled in
-

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

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

Possible Errors

-
    -
  • Any of the universal error types.
    • -
  • invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
    • -
  • highFee - The current load-based multiplier to the transaction cost exceeds the limit for an automatically-provided transaction cost. Either specify a higher fee_mult_max (at least 1000) in the request or manually provide a value in the Fee field of the tx_json.
    • -
  • tooBusy - The transaction did not include paths, but the server is too busy to do pathfinding right now. Does not occur if you are connected as an admin.
    • -
  • noPath - The transaction did not include paths, and the server was unable to find a path by which this payment can occur.
    • -
-

sign_for

-

[Source]

-

The sign_for command provides one signature for a multi-signed transaction.

-

This command requires the MultiSign amendment to be enabled. New in: rippled 0.31.0

-

Request Format

-

An example of the request format:

-
- -
{
-    "id": "sign_for_example",
-    "command": "sign_for",
-    "account": "rLFd1FzHMScFhLsXeaxStzv3UC97QHGAbM",
-    "seed": "s████████████████████████████",
-    "key_type": "ed25519",
-    "tx_json": {
-        "TransactionType": "TrustSet",
-        "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
-        "Flags": 262144,
-        "LimitAmount": {
-            "currency": "USD",
-            "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
-            "value": "100"
-        },
-        "Sequence": 2,
-        "SigningPubKey": "",
-        "Fee": "30000"
-    }
-}
-
- -
POST http://localhost:5005/
-{
-    "method": "sign_for",
-    "params": [{
-        "account": "rLFd1FzHMScFhLsXeaxStzv3UC97QHGAbM",
-        "seed": "s████████████████████████████",
-        "key_type": "ed25519",
-        "tx_json": {
-            "TransactionType": "TrustSet",
-            "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
-            "Flags": 262144,
-            "LimitAmount": {
-                "currency": "USD",
-                "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
-                "value": "100"
-            },
-            "Sequence": 2,
-            "SigningPubKey": "",
-            "Fee": "30000"
-        }
-    }]
-}
-
- -
#Syntax: rippled sign_for <signer_address> <signer_secret> [offline]
-rippled sign_for rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW s████████████████████████████ '{
-    "TransactionType": "TrustSet",
-    "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
-    "Flags": 262144,
-    "LimitAmount": {
-        "currency": "USD",
-        "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
-        "value": "100"
-    },
-    "Sequence": 2,
-    "SigningPubKey": "",
-    "Fee": "30000"
-}'
-
-
-

The request includes the following parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
accountString - AddressThe address which is providing the signature.
tx_jsonObjectThe Transaction to sign. Unlike using the sign command, all fields of the transaction must be provided, including Fee and Sequence. The transaction must include the field SigningPubKey with an empty string as the value. The object may optionally contain a Signers array with previously-collected signatures.
secretString(Optional) The secret key to sign with. (Cannot be used with key_type.)
passphraseString(Optional) A passphrase to use as the secret key to sign with.
seedString(Optional) A base58-encoded secret key to sign with.
seed_hexString(Optional) A hexadecimal secret key to sign with.
key_typeString(Optional) The type of key to use for signing. This can be secp256k1 or ed25519. (Ed25519 support is experimental.)
-

You must provide exactly 1 field with the secret key. You can use any of the following fields: secret, passphrase, seed, or seed_hex.

-

Response Format

-

An example of a successful response:

-
- -
{
-  "id": "sign_for_example",
-  "status": "success",
-  "type": "response",
-  "result": {
-    "tx_blob": "1200142200040000240000000263D5038D7EA4C680000000000000000000000000005553440000000000B5F762798A53D543A014CAF8B297CFF8F2F937E868400000000000753073008114A3780F5CB5A44D366520FC44055E8ED44D9A2270F3E0107321EDDF4ECB8F34A168143B928D48EFE625501FB8552403BBBD3FC038A5788951D7707440C3DCA3FEDE6D785398EEAB10A46B44047FF1B0863FC4313051FB292C991D1E3A9878FABB301128FE4F86F3D8BE4706D53FA97F5536DBD31AF14CD83A5ACDEB068114D96CB910955AB40A0E987EEE82BB3CEDD4441AAAE1F1",
-    "tx_json": {
-      "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
-      "Fee": "30000",
-      "Flags": 262144,
-      "LimitAmount": {
-        "currency": "USD",
-        "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
-        "value": "100"
-      },
-      "Sequence": 2,
-      "Signers": [
-        {
-          "Signer": {
-            "Account": "rLFd1FzHMScFhLsXeaxStzv3UC97QHGAbM",
-            "SigningPubKey": "EDDF4ECB8F34A168143B928D48EFE625501FB8552403BBBD3FC038A5788951D770",
-            "TxnSignature": "C3DCA3FEDE6D785398EEAB10A46B44047FF1B0863FC4313051FB292C991D1E3A9878FABB301128FE4F86F3D8BE4706D53FA97F5536DBD31AF14CD83A5ACDEB06"
-          }
-        }
-      ],
-      "SigningPubKey": "",
-      "TransactionType": "TrustSet",
-      "hash": "5216A13A3E3CF662352F0B430C7D82B7450415B6883DD428B5EC1DF1DE45DD8C"
-    }
-  }
-}
-
- -
200 OK
-{
-   "result" : {
-      "status" : "success",
-      "tx_blob" : "1200142200040000240000000263D5038D7EA4C680000000000000000000000000005553440000000000B5F762798A53D543A014CAF8B297CFF8F2F937E868400000000000753073008114A3780F5CB5A44D366520FC44055E8ED44D9A2270F3E010732102B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF744730450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E58114204288D2E47F8EF6C99BCC457966320D12409711E1F1",
-      "tx_json" : {
-         "Account" : "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
-         "Fee" : "30000",
-         "Flags" : 262144,
-         "LimitAmount" : {
-            "currency" : "USD",
-            "issuer" : "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
-            "value" : "100"
-         },
-         "Sequence" : 2,
-         "Signers" : [
-            {
-               "Signer" : {
-                  "Account" : "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-                  "SigningPubKey" : "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
-                  "TxnSignature" : "30450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E5"
-               }
-            }
-         ],
-         "SigningPubKey" : "",
-         "TransactionType" : "TrustSet",
-         "hash" : "A94A6417D1A7AAB059822B894E13D322ED3712F7212CE9257801F96DE6C3F6AE"
-      }
-   }
-}
-
- -
Loading: "/etc/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "status" : "success",
-      "tx_blob" : "1200142200040000240000000263D5038D7EA4C680000000000000000000000000005553440000000000B5F762798A53D543A014CAF8B297CFF8F2F937E868400000000000753073008114A3780F5CB5A44D366520FC44055E8ED44D9A2270F3E010732102B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF744730450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E58114204288D2E47F8EF6C99BCC457966320D12409711E1F1",
-      "tx_json" : {
-         "Account" : "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
-         "Fee" : "30000",
-         "Flags" : 262144,
-         "LimitAmount" : {
-            "currency" : "USD",
-            "issuer" : "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
-            "value" : "100"
-         },
-         "Sequence" : 2,
-         "Signers" : [
-            {
-               "Signer" : {
-                  "Account" : "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-                  "SigningPubKey" : "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
-                  "TxnSignature" : "30450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E5"
-               }
-            }
-         ],
-         "SigningPubKey" : "",
-         "TransactionType" : "TrustSet",
-         "hash" : "A94A6417D1A7AAB059822B894E13D322ED3712F7212CE9257801F96DE6C3F6AE"
-      }
-   }
-}
-
-
-

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

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
tx_blobStringHexadecimal representation of the signed transaction, including the newly-added signature. If it has enough signatures, you can submit this string using the submit command.
tx_jsonObjectThe transaction specification in JSON format, with the newly-added signature in the Signers array. If it has enough signatures, you can submit this object using the submit_multisigned command.
-

Possible Errors

-
    -
  • Any of the universal error types.
    • -
  • invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
    • -
  • srcActNotFound - If the Account from the transaction is not a funded address in the ledger.
    • -
  • srcActMalformed - If the signing address (account field) from the request is not validly formed.
    • -
  • badSeed - The seed value supplied was invalidly-formatted.
    • -
  • badSecret - The secret value supplied was invalidly-formatted.
    • -
-

submit

-

[Source]

-

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 command, and then submits the signed transaction. We recommend only using this mode for testing and development.
    • -
-

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

-

Submit-Only Mode

-

A submit-only request includes the following parameters:

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
tx_blobStringHex representation of the signed transaction to submit. This can be a multi-signed transaction.
fail_hardBoolean(Optional, defaults to false) If true, and the transaction fails locally, do not retry or relay the transaction to other servers
-

Request Format

-
- -
{
-    "id": 3,
-    "command": "submit",
-    "tx_blob": "1200002280000000240000001E61D4838D7EA4C6800000000000000000000000000055534400000000004B4E9C06F24296074F7BC48F92A97916C6DC5EA968400000000000000B732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB7447304502210095D23D8AF107DF50651F266259CC7139D0CD0C64ABBA3A958156352A0D95A21E02207FCF9B77D7510380E49FF250C21B57169E14E9B4ACFD314CEDC79DDD0A38B8A681144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143E9D4A2B8AA0780F682D136F7A56D6724EF53754"
-}
-
- -
{
-    "method": "submit",
-    "params": [
-        {
-            "tx_blob": "1200002280000000240000000361D4838D7EA4C6800000000000000000000000000055534400000000004B4E9C06F24296074F7BC48F92A97916C6DC5EA968400000000000000A732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB74473045022100D184EB4AE5956FF600E7536EE459345C7BBCF097A84CC61A93B9AF7197EDB98702201CEA8009B7BEEBAA2AACC0359B41C427C1C5B550A4CA4B80CF2174AF2D6D5DCE81144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143E9D4A2B8AA0780F682D136F7A56D6724EF53754"
-        }
-    ]
-}
-
- -
#Syntax: submit tx_blob
-submit 1200002280000000240000000361D4838D7EA4C6800000000000000000000000000055534400000000004B4E9C06F24296074F7BC48F92A97916C6DC5EA968400000000000000A732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB74473045022100D184EB4AE5956FF600E7536EE459345C7BBCF097A84CC61A93B9AF7197EDB98702201CEA8009B7BEEBAA2AACC0359B41C427C1C5B550A4CA4B80CF2174AF2D6D5DCE81144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143E9D4A2B8AA0780F682D136F7A56D6724EF53754
-
-
-

Try it!

-

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.

-

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

The request includes the following parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
tx_jsonObjectTransaction definition in JSON format, optionally omitting any auto-fillable fields.
secretString(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.
seedString(Optional) Secret key of the account supplying the transaction, used to sign it. Must be in base58 format. If provided, you must also specify the key_type. Cannot be used with secret, seed_hex, or passphrase.
seed_hexString(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.
passphraseString(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_typeString(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_hardBoolean(Optional, defaults to false) If true, and the transaction fails locally, do not retry or relay the transaction to other servers
offlineBoolean(Optional, defaults to false) If true, when constructing the transaction, do not try to automatically fill in or validate values.
build_pathBoolean(Optional) If provided for a Payment-type transaction, automatically fill in the Paths field before signing. You must omit this field if the transaction is a direct XRP-to-XRP transfer. Caution: The server looks for the presence or absence of this field, not its value. This behavior may change.
fee_mult_maxInteger(Optional, defaults to 10, recommended value 1000) If the Fee parameter is omitted, this field limits the automatically-provided Fee value so that it is less than or equal to the long-term base transaction cost times this value.
fee_div_maxInteger(Optional, defaults to 1) Used with fee_mult_max to create a fractional multiplier for the limit. Specifically, the server multiplies its base transaction cost by fee_mult_max, then divides by this value (rounding down to an integer) to get a limit. If the automatically-provided Fee value would be over the limit, the submit command fails. New in: rippled 0.30.1
-

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

-

Request Format

-

An example of the request format:

-
- -
{
-  "id": 2,
-  "command": "submit",
-  "tx_json" : {
-      "TransactionType" : "Payment",
-      "Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-      "Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-      "Amount" : {
-         "currency" : "USD",
-         "value" : "1",
-         "issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
-      }
-   },
-   "secret" : "s████████████████████████████",
-   "offline": false,
-   "fee_mult_max": 1000
-}
-
- -
{
-    "method": "submit",
-    "params": [
-        {
-            "offline": false,
-            "secret": "s████████████████████████████",
-            "tx_json": {
-                "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-                "Amount": {
-                    "currency": "USD",
-                    "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-                    "value": "1"
-                },
-                "Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-                "TransactionType": "Payment"
-            },
-            "fee_mult_max": 1000
-        }
-    ]
-}
-
- -
#Syntax: submit secret json [offline]
-rippled submit s████████████████████████████ '{"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", "Amount": { "currency": "USD", "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", "value": "1" }, "Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX", "TransactionType": "Payment", "Fee": "10000"}'
-
-
-

Try it!

-

Response Format

-

An example of a successful response:

-
- -
{
-  "id": 1,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "engine_result": "tesSUCCESS",
-    "engine_result_code": 0,
-    "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
-    "tx_blob": "1200002280000000240000016861D4838D7EA4C6800000000000000000000000000055534400000000004B4E9C06F24296074F7BC48F92A97916C6DC5EA9684000000000002710732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB7446304402200E5C2DD81FDF0BE9AB2A8D797885ED49E804DBF28E806604D878756410CA98B102203349581946B0DDA06B36B35DBC20EDA27552C1F167BCF5C6ECFF49C6A46F858081144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143E9D4A2B8AA0780F682D136F7A56D6724EF53754",
-    "tx_json": {
-      "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-      "Amount": {
-        "currency": "USD",
-        "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-        "value": "1"
-      },
-      "Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-      "Fee": "10000",
-      "Flags": 2147483648,
-      "Sequence": 360,
-      "SigningPubKey": "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB",
-      "TransactionType": "Payment",
-      "TxnSignature": "304402200E5C2DD81FDF0BE9AB2A8D797885ED49E804DBF28E806604D878756410CA98B102203349581946B0DDA06B36B35DBC20EDA27552C1F167BCF5C6ECFF49C6A46F8580",
-      "hash": "4D5D90890F8D49519E4151938601EF3D0B30B16CD6A519D9C99102C9FA77F7E0"
-    }
-  }
-}
-
- -
{
-    "result": {
-        "engine_result": "tesSUCCESS",
-        "engine_result_code": 0,
-        "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
-        "status": "success",
-        "tx_blob": "1200002280000000240000016961D4838D7EA4C6800000000000000000000000000055534400000000004B4E9C06F24296074F7BC48F92A97916C6DC5EA9684000000000002710732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB74473045022100A7CCD11455E47547FF617D5BFC15D120D9053DFD0536B044F10CA3631CD609E502203B61DEE4AC027C5743A1B56AF568D1E2B8E79BB9E9E14744AC87F38375C3C2F181144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143E9D4A2B8AA0780F682D136F7A56D6724EF53754",
-        "tx_json": {
-            "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-            "Amount": {
-                "currency": "USD",
-                "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-                "value": "1"
-            },
-            "Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-            "Fee": "10000",
-            "Flags": 2147483648,
-            "Sequence": 361,
-            "SigningPubKey": "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB",
-            "TransactionType": "Payment",
-            "TxnSignature": "3045022100A7CCD11455E47547FF617D5BFC15D120D9053DFD0536B044F10CA3631CD609E502203B61DEE4AC027C5743A1B56AF568D1E2B8E79BB9E9E14744AC87F38375C3C2F1",
-            "hash": "5B31A7518DC304D5327B4887CD1F7DC2C38D5F684170097020C7C9758B973847"
-        }
-    }
-}
-
- -
Loading: "/etc/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "engine_result" : "tesSUCCESS",
-      "engine_result_code" : 0,
-      "engine_result_message" : "The transaction was applied. Only final in a validated ledger.",
-      "status" : "success",
-      "tx_blob" : "1200002280000000240000016A61D4838D7EA4C6800000000000000000000000000055534400000000004B4E9C06F24296074F7BC48F92A97916C6DC5EA9684000000000002710732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB74473045022100FBBF74057359EC31C3647AD3B33D8954730E9879C35034374858A76B7CFA643102200EAA08C61071396E9CF0987FBEA16CF113CBD8068AA221214D165F151285EECD81144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143E9D4A2B8AA0780F682D136F7A56D6724EF53754",
-      "tx_json" : {
-         "Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-         "Amount" : {
-            "currency" : "USD",
-            "issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-            "value" : "1"
-         },
-         "Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-         "Fee" : "10000",
-         "Flags" : 2147483648,
-         "Sequence" : 362,
-         "SigningPubKey" : "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB",
-         "TransactionType" : "Payment",
-         "TxnSignature" : "3045022100FBBF74057359EC31C3647AD3B33D8954730E9879C35034374858A76B7CFA643102200EAA08C61071396E9CF0987FBEA16CF113CBD8068AA221214D165F151285EECD",
-         "hash" : "CB98A6FA1FAC47F9FCC6A233EB46F8F9AF59CC69BD69AE6D06F298F6FF52162A"
-      }
-   }
-}
-
-
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
engine_resultStringCode indicating the preliminary result of the transaction, for example tesSUCCESS
engine_result_codeIntegerNumeric code indicating the preliminary result of the transaction, directly correlated to engine_result
engine_result_messageStringHuman-readable explanation of the transaction's preliminary result
tx_blobStringThe complete transaction in hex string format
tx_jsonObjectThe complete transaction in JSON format
-

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

-

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

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

Possible Errors

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

submit_multisigned

-

[Source]

-

The submit_multisigned command applies a multi-signed transaction and sends it to the network to be included in future ledgers. (You can also submit multi-signed transactions in binary form using the submit command in submit-only mode.)

-

This command requires the MultiSign amendment to be enabled. New in: rippled 0.31.0

-

Request Format

-

An example of the request format:

-
- -
{
-    "id": "submit_multisigned_example"
-    "command": "submit_multisigned",
-    "tx_json": {
-        "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
-        "Fee": "30000",
-        "Flags": 262144,
-        "LimitAmount": {
-            "currency": "USD",
-            "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
-            "value": "100"
-        },
-        "Sequence": 2,
-        "Signers": [{
-            "Signer": {
-                "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-                "SigningPubKey": "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
-                "TxnSignature": "30450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E5"
-            }
-        }, {
-            "Signer": {
-                "Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
-                "SigningPubKey": "028FFB276505F9AC3F57E8D5242B386A597EF6C40A7999F37F1948636FD484E25B",
-                "TxnSignature": "30440220680BBD745004E9CFB6B13A137F505FB92298AD309071D16C7B982825188FD1AE022004200B1F7E4A6A84BB0E4FC09E1E3BA2B66EBD32F0E6D121A34BA3B04AD99BC1"
-            }
-        }],
-        "SigningPubKey": "",
-        "TransactionType": "TrustSet",
-        "hash": "BD636194C48FD7A100DE4C972336534C8E710FD008C0F3CF7BC5BF34DAF3C3E6"
-    }
-}
-
- -
{
-    "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"
-            }
-        }
-    ]
-}
-
- -
#Syntax: submit_multisigned <tx_json>
-rippled submit_multisigned '{
-    "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"
-}'
-
-
-

The request includes the following parameters:

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
tx_jsonObjectTransaction 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_hardBoolean(Optional, defaults to false) If true, and the transaction fails locally, do not retry or relay the transaction to other servers.
-

Response Format

-

An example of a successful response:

-
- -
{
-  "id": "submit_multisigned_example",
-  "status": "success",
-  "type": "response",
-  "result": {
-    "engine_result": "tesSUCCESS",
-    "engine_result_code": 0,
-    "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
-    "tx_blob": "1200142200040000240000000263D5038D7EA4C680000000000000000000000000005553440000000000B5F762798A53D543A014CAF8B297CFF8F2F937E868400000000000753073008114A3780F5CB5A44D366520FC44055E8ED44D9A2270F3E010732102B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF744730450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E58114204288D2E47F8EF6C99BCC457966320D12409711E1E0107321028FFB276505F9AC3F57E8D5242B386A597EF6C40A7999F37F1948636FD484E25B744630440220680BBD745004E9CFB6B13A137F505FB92298AD309071D16C7B982825188FD1AE022004200B1F7E4A6A84BB0E4FC09E1E3BA2B66EBD32F0E6D121A34BA3B04AD99BC181147908A7F0EDD48EA896C3580A399F0EE78611C8E3E1F1",
-    "tx_json": {
-      "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
-      "Fee": "30000",
-      "Flags": 262144,
-      "LimitAmount": {
-        "currency": "USD",
-        "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
-        "value": "100"
-      },
-      "Sequence": 2,
-      "Signers": [
-        {
-          "Signer": {
-            "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-            "SigningPubKey": "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
-            "TxnSignature": "30450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E5"
-          }
-        },
-        {
-          "Signer": {
-            "Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
-            "SigningPubKey": "028FFB276505F9AC3F57E8D5242B386A597EF6C40A7999F37F1948636FD484E25B",
-            "TxnSignature": "30440220680BBD745004E9CFB6B13A137F505FB92298AD309071D16C7B982825188FD1AE022004200B1F7E4A6A84BB0E4FC09E1E3BA2B66EBD32F0E6D121A34BA3B04AD99BC1"
-          }
-        }
-      ],
-      "SigningPubKey": "",
-      "TransactionType": "TrustSet",
-      "hash": "BD636194C48FD7A100DE4C972336534C8E710FD008C0F3CF7BC5BF34DAF3C3E6"
-    }
-  }
-}
-
- -
200 OK
-{
-    "result": {
-        "engine_result": "tesSUCCESS",
-        "engine_result_code": 0,
-        "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
-        "status": "success",
-        "tx_blob": "120014220004000024000000046380000000000000000000000000000000000000005553440000000000B5F762798A53D543A014CAF8B297CFF8F2F937E868400000000000753073008114A3780F5CB5A44D366520FC44055E8ED44D9A2270F3E010732102B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF74473045022100CC9C56DF51251CB04BB047E5F3B5EF01A0F4A8A549D7A20A7402BF54BA744064022061EF8EF1BCCBF144F480B32508B1D10FD4271831D5303F920DE41C64671CB5B78114204288D2E47F8EF6C99BCC457966320D12409711E1E010732103398A4EDAE8EE009A5879113EAA5BA15C7BB0F612A87F4103E793AC919BD1E3C174473045022100FEE8D8FA2D06CE49E9124567DCA265A21A9F5465F4A9279F075E4CE27E4430DE022042D5305777DA1A7801446780308897699412E4EDF0E1AEFDF3C8A0532BDE4D0881143A4C02EA95AD6AC3BED92FA036E0BBFB712C030CE1F1",
-        "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"
-        }
-    }
-}
-
-
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
engine_resultStringCode indicating the preliminary result of the transaction, for example tesSUCCESS
engine_result_codeIntegerNumeric code indicating the preliminary result of the transaction, directly correlated to engine_result
engine_result_messageStringHuman-readable explanation of the preliminary transaction result
tx_blobStringThe complete transaction in hex string format
tx_jsonObjectThe complete transaction in JSON format
-

Possible Errors

-
    -
  • Any of the universal error types.
    • -
  • invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
    • -
  • srcActMalformed - The Account field from the tx_json was invalid or missing.
    • -
  • internal - An internal error occurred. This includes the case where a signature is not valid for the transaction JSON provided.
    • -
-

book_offers

-

[Source]

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-  "id": 4,
-  "command": "book_offers",
-  "taker": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-  "taker_gets": {
-    "currency": "XRP"
-  },
-  "taker_pays": {
-    "currency": "USD",
-    "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
-  },
-  "limit": 10
-}
-
- -
{
-    "method": "book_offers",
-    "params": [
-        {
-            "taker": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
-            "taker_gets": {
-                "currency": "XRP"
-            },
-            "taker_pays": {
-                "currency": "USD",
-                "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-            },
-            "limit": 10
-        }
-    ]
-}
-
- -
#Syntax: book_offers taker_pays taker_gets [taker [ledger [limit] ] ]
-rippled book_offers 'USD/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B' 'EUR/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B'
-
-
-

Try it!

-

The request includes the following parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
ledger_hashString(Optional) A 20-byte hex string for the ledger version to use. (See Specifying a Ledger)
ledger_indexString or Unsigned Integer(Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying a Ledger)
limitUnsigned Integer(Optional) If provided, the server does not provide more than this many offers in the results. The total number of results returned may be fewer than the limit, because the server omits unfunded offers.
takerString(Optional) The Address of an account to use as a perspective. Unfunded offers placed by this account are always included in the response. (You can use this to look up your own orders to cancel them.)
taker_getsObjectSpecification of which currency the account taking the offer would receive, as an object with currency and issuer fields (omit issuer for XRP), like currency amounts.
taker_paysObjectSpecification of which currency the account taking the offer would pay, as an object with currency and issuer fields (omit issuer for XRP), like currency amounts.
-

Response Format

-

An example of a successful response:

-
- -
{
-  "id": 11,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "ledger_current_index": 7035305,
-    "offers": [
-      {
-        "Account": "rM3X3QSr8icjTGpaF52dozhbT2BZSXJQYM",
-        "BookDirectory": "7E5F614417C2D0A7CEFEB73C4AA773ED5B078DE2B5771F6D55055E4C405218EB",
-        "BookNode": "0000000000000000",
-        "Flags": 0,
-        "LedgerEntryType": "Offer",
-        "OwnerNode": "0000000000000AE0",
-        "PreviousTxnID": "6956221794397C25A53647182E5C78A439766D600724074C99D78982E37599F1",
-        "PreviousTxnLgrSeq": 7022646,
-        "Sequence": 264542,
-        "TakerGets": {
-          "currency": "EUR",
-          "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-          "value": "17.90363633316433"
-        },
-        "TakerPays": {
-          "currency": "USD",
-          "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-          "value": "27.05340557506234"
-        },
-        "index": "96A9104BF3137131FF8310B9174F3B37170E2144C813CA2A1695DF2C5677E811",
-        "quality": "1.511056473200875"
-      },
-      {
-        "Account": "rhsxKNyN99q6vyYCTHNTC1TqWCeHr7PNgp",
-        "BookDirectory": "7E5F614417C2D0A7CEFEB73C4AA773ED5B078DE2B5771F6D5505DCAA8FE12000",
-        "BookNode": "0000000000000000",
-        "Flags": 131072,
-        "LedgerEntryType": "Offer",
-        "OwnerNode": "0000000000000001",
-        "PreviousTxnID": "8AD748CD489F7FF34FCD4FB73F77F1901E27A6EFA52CCBB0CCDAAB934E5E754D",
-        "PreviousTxnLgrSeq": 7007546,
-        "Sequence": 265,
-        "TakerGets": {
-          "currency": "EUR",
-          "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-          "value": "2.542743233917848"
-        },
-        "TakerPays": {
-          "currency": "USD",
-          "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
-          "value": "4.19552633596446"
-        },
-        "index": "7001797678E886E22D6DE11AF90DF1E08F4ADC21D763FAFB36AF66894D695235",
-        "quality": "1.65"
-      }
-    ]
-  }
-}
-
- -
200 OK
-{
-    "result": {
-        "ledger_current_index": 8696243,
-        "offers": [],
-        "status": "success",
-        "validated": false
-    }
-}
-
-
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
ledger_current_indexInteger(Omitted if ledger version provided) Sequence number of the ledger version used when retrieving this data.
ledger_indexInteger(Omitted if ledger_current_index provided instead) Sequence number, provided in the request, of the ledger version that was used when retrieving this data.
ledger_hashString(May be omitted) Hex hash, provided in the request, of the ledger version that was used when retrieving this data.
offersArrayArray of offer objects, each of which has the fields of an OfferCreate transaction
-

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

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

Possible Errors

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

channel_authorize

-

[Source]

-

(Requires the PayChan amendment to be enabled. New in: rippled 0.33.0)

-

The channel_authorize method creates a signature that can be used to redeem a specific amount of XRP from a payment channel.

-

Request Format

-

An example of the request format:

-
- -
{
-    "id": "channel_authorize_example_id1",
-    "command": "channel_authorize",
-    "channel_id": "5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3",
-    "secret": "s████████████████████████████",
-    "amount": "1000000"
-}
-
- -
POST http://localhost:5005/
-Content-Type: application/json
-
-{
-    "method": "channel_authorize",
-    "params": [{
-        "channel_id": "5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3",
-        "secret": "s████████████████████████████",
-        "amount": "1000000"
-    }]
-}
-
- -
#Syntax: channel_authorize <private_key> <channel_id> <drops>
-rippled channel_authorize s████████████████████████████ 5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3 1000000
-
-
-

The request includes the following parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
channel_idStringThe unique ID of the payment channel to use.
secretStringThe secret key to use to sign the claim. This must be the same key pair as the public key specified in the channel.
amountStringCumulative amount of XRP, in drops, to authorize. If the destination has already received a lesser amount of XRP from this channel, the signature created by this method can be redeemed for the difference.
-

Note: You cannot use Ed25519 keys to sign claims with this method. This is a known bug.

-

Response Format

-

An example of a successful response:

-
- -
{
-    "id": "channel_authorize_example_id1",
-    "status": "success"
-    "result": {
-        "signature": "304402204EF0AFB78AC23ED1C472E74F4299C0C21F1B21D07EFC0A3838A420F76D783A400220154FB11B6F54320666E4C36CA7F686C16A3A0456800BBC43746F34AF50290064",
-    }
-}
-
- -
200 OK
-
-{
-    "result": {
-        "signature": "304402204EF0AFB78AC23ED1C472E74F4299C0C21F1B21D07EFC0A3838A420F76D783A400220154FB11B6F54320666E4C36CA7F686C16A3A0456800BBC43746F34AF50290064",
-        "status": "success"
-    }
-}
-
- -
{
-    "result": {
-        "signature": "304402204EF0AFB78AC23ED1C472E74F4299C0C21F1B21D07EFC0A3838A420F76D783A400220154FB11B6F54320666E4C36CA7F686C16A3A0456800BBC43746F34AF50290064",
-        "status": "success"
-    }
-}
-
-
-

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

- - - - - - - - - - - - - - - -
FieldTypeDescription
signatureStringThe signature for this claim, as a hexadecimal value. To process the claim, the destination account of the payment channel must send a PaymentChannelClaim transaction with this signature, the exact Channel ID, XRP amount, and public key of the channel.
-

Possible Errors

-
    -
  • Any of the universal error types.
    • -
  • badSeed - The secret in the request is not a valid secret key.
    • -
  • channelAmtMalformed - The amount in the request is not a valid XRP amount.
    • -
  • channelMalformed - The channel_id in the request is not a valid Channel ID. The Channel ID should be a 256-bit (64-character) hexadecimal string.
    • -
-

channel_verify

-

[Source]

-

(Requires the PayChan amendment to be enabled. New in: rippled 0.33.0)

-

The channel_verify method checks the validity of a signature that can be used to redeem a specific amount of XRP from a payment channel.

-

Request Format

-

An example of the request format:

-
- -
{
-    "id": 1,
-    "command": "channel_verify",
-    "channel_id": "5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3",
-    "signature": "304402204EF0AFB78AC23ED1C472E74F4299C0C21F1B21D07EFC0A3838A420F76D783A400220154FB11B6F54320666E4C36CA7F686C16A3A0456800BBC43746F34AF50290064",
-    "public_key": "aB44YfzW24VDEJQ2UuLPV2PvqcPCSoLnL7y5M1EzhdW4LnK5xMS3",
-    "amount": "1000000"
-}
-
- -
POST http://localhost:5005/
-Content-Type: application/json
-
-{
-    "method": "channel_verify",
-    "params": [{
-        "channel_id": "5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3",
-        "signature": "304402204EF0AFB78AC23ED1C472E74F4299C0C21F1B21D07EFC0A3838A420F76D783A400220154FB11B6F54320666E4C36CA7F686C16A3A0456800BBC43746F34AF50290064",
-        "public_key": "aB44YfzW24VDEJQ2UuLPV2PvqcPCSoLnL7y5M1EzhdW4LnK5xMS3",
-        "amount": "1000000"
-    }]
-}
-
- -
#Syntax: channel_verify <public_key> <channel_id> <amount> <signature>
-rippled channel_verify aB44YfzW24VDEJQ2UuLPV2PvqcPCSoLnL7y5M1EzhdW4LnK5xMS3 5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3 1000000 304402204EF0AFB78AC23ED1C472E74F4299C0C21F1B21D07EFC0A3838A420F76D783A400220154FB11B6F54320666E4C36CA7F686C16A3A0456800BBC43746F34AF50290064
-
-
-

The request includes the following parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
amountStringThe amount of XRP, in drops, the provided signature authorizes.
channel_idStringThe Channel ID of the channel that provides the XRP. This is a 64-character hexadecimal string.
public_keyStringThe public key of the channel and the key pair that was used to create the signature, in base58 format. (One way to get the public key in base58 format is to use the wallet_propose command.)
signatureStringThe signature to verify, in hexadecimal.
-

Response Format

-

An example of a successful response:

-
- -
{
-    "id": 1,
-    "status": "success",
-    "type": "response",
-    "result": {
-        "signature_verified":true
-    }
-}
-
- -
200 OK
-
-{
-    "result": {
-        "signature_verified":true,
-        "status":"success"
-    }
-}
-
- -
{
-    "result": {
-        "signature_verified":true,
-        "status":"success"
-    }
-}
-
-
-

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

- - - - - - - - - - - - - - - -
FieldTypeDescription
signature_verifiedBooleanIf true, the signature is valid for the stated amount, channel, and public key.
-

Caution: This does not indicate check that the channel has sufficient XRP allocated to it. Before considering a claim valid, you should look up the channel in the latest validated ledger and confirm that the channel is open and its amount value is equal or greater than the amount of the claim. To do so, use the account_channels method.

-

Possible Errors

-
    -
  • Any of the universal error types.
    • -
  • invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
    • -
  • publicMalformed - The public_key field of the request is not a valid public key in the correct format. Public keys are 33 bytes and must be represented in base58. The base58 representation of account public keys starts with the letter a.
    • -
  • channelMalformed - The channel_id field of the request is not a valid Channel ID. The Channel ID must be a 256-bit (64-character) hexadecimal string.
    • -
  • channelAmtMalformed - The value specified in the amount field was not a valid XRP amount.
    • -
-

Subscriptions

-

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

-

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

-

subscribe

-

[Source]

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-  "id": "Example watch Bitstamp's hot wallet",
-  "command": "subscribe",
-  "accounts": ["rrpNnNLKrartuEqfJGpqyDwPj1AFPg9vn1"]
-}
-
- -
{
-    "id": "Example subscribe to XRP/GateHub USD order book",
-    "command": "subscribe",
-    "books": [
-        {
-            "taker_pays": {
-                "currency": "XRP"
-            },
-            "taker_gets": {
-                "currency": "USD",
-                "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq"
-            },
-            "snapshot": true
-        }
-    ]
-}
-
- -
{
-  "id": "Example watch for new validated ledgers",
-  "command": "subscribe",
-  "streams": ["ledger"]
-}
-
-
-

Try it!

-

The request includes the following parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
streamsArray(Optional) Array of string names of generic streams to subscribe to, as explained below
accountsArray(Optional) Array with the unique base58 addresses of accounts to monitor for validated transactions. The server sends a notification for any transaction that affects at least one of these accounts.
accounts_proposedArray(Optional) Like accounts, but include transactions that are not yet finalized.
booksArray(Optional) Array of objects defining order books to monitor for updates, as detailed below.
urlString(Optional for Websocket; Required otherwise) URL where the server sends a JSON-RPC callbacks for each event. Admin-only.
url_usernameString(Optional) Username to provide for basic authentication at the callback URL.
url_passwordString(Optional) Password to provide for basic authentication at the callback URL.
-

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

-

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

-
    -
  • server - Sends a message whenever the status of the rippled server (for example, network connectivity) changes
    • -
  • ledger - Sends a message whenever the consensus process declares a new validated ledger
    • -
  • transactions - Sends a message whenever a transaction is included in a closed ledger
    • -
  • transactions_proposed - Sends a message whenever a transaction is included in a closed ledger, as well as some transactions that have not yet been included in a validated ledger and may never be. Not all proposed transactions appear before validation. - Note: Even some transactions that don't succeed are included in validated ledgers, because they take the anti-spam transaction fee.
    • -
  • validations - Sends a message whenever the server receives a validation message from a server it trusts. (An individual rippled declares a ledger validated when the server receives validation messages from at least a quorum of trusted validators.)
    • -
  • peer_status - (Admin only) Information about connected peer rippled servers, especially with regards to the consensus process.
    • -
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
taker_getsObjectSpecification of which currency the account taking the offer would receive, as a currency object with no amount.
taker_paysObjectSpecification of which currency the account taking the offer would pay, as a currency object with no amount.
takerStringUnique base58 account address to use as a perspective for viewing offers. (This affects the funding status and fees of offers.)
snapshotBoolean(Optional, defaults to false) If true, return the current state of the order book once when you subscribe before sending updates
bothBoolean(Optional, defaults to false) If true, return both sides of the order book.
-

Response Format

-

An example of a successful response:

-
- -
{
-  "id": "Example watch Bitstamp's hot wallet",
-  "status": "success",
-  "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.

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

Possible Errors

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

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

-

Ledger Stream

-

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

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

The fields from a ledger stream message are as follows:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
typeStringledgerClosed indicates this is from the ledger stream
fee_baseUnsigned IntegerCost of the 'reference transaction' in drops of XRP. (See Transaction Cost If the ledger includes a SetFee pseudo-transaction the new transaction cost applies to all transactions after this ledger.
fee_refUnsigned IntegerCost of the 'reference transaction' in 'fee units'.
ledger_hashStringUnique hash of the ledger that was closed, as hex
ledger_indexUnsigned IntegerSequence number of the ledger that was closed
ledger_timeUnsigned IntegerThe time this ledger was closed, in seconds since the Ripple Epoch
reserve_baseUnsigned IntegerThe minimum reserve, in drops of XRP, that is required for an account. If the ledger includes a SetFee pseudo-transaction the new base reserve applies after this ledger.
reserve_incUnsigned IntegerThe increase in account reserve that is added for each item the account owns, such as offers or trust lines. If the ledger includes a SetFee pseudo-transaction the new owner reserve applies after this ledger.
txn_countUnsigned IntegerNumber of new transactions included in this ledger
validated_ledgersString(May be omitted) Range of ledgers that the server has available. This may be discontiguous. This field is not returned if the server is not connected to the network, or if it is connected but has not yet obtained a ledger from the network.
-

Validations Stream

-

New in: rippled 0.29.0

-

The validations stream sends messages whenever it receives validation messages, also called validation votes, from validators it trusts. The message looks like the following:

-
{
-    "type": "validationReceived",
-    "amendments":[
-        "42426C4D4F1009EE67080A9B7965B44656D7714D104A72F9B4369F97ABF044EE",
-        "4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373",
-        "6781F8368C4771B83E8B821D88F580202BCB4228075297B19E4FDC5233F1EFDC",
-        "C1B8D934087225F509BEB5A8EC24447854713EE447D277F69545ABFA0E0FD490",
-        "DA1BD556B42D85EA9C84066D028D355B52416734D3283F85E216EA5DA6DB7E13"
-    ],
-    "base_fee":10,
-    "flags":2147483649,
-    "full":true,
-    "ledger_hash":"EC02890710AAA2B71221B0D560CFB22D64317C07B7406B02959AD84BAD33E602",
-    "ledger_index":"6",
-    "load_fee":256000,
-    "reserve_base":20000000,
-    "reserve_inc":5000000,
-    "signature":"3045022100E199B55643F66BC6B37DBC5E185321CF952FD35D13D9E8001EB2564FFB94A07602201746C9A4F7A93647131A2DEB03B76F05E426EC67A5A27D77F4FF2603B9A528E6",
-    "signing_time":515115322,
-    "validation_public_key":"n94Gnc6svmaPPRHUAyyib1gQUov8sYbjLoEwUBYPH39qHZXuo8ZT"
-}
-
-

The fields from a validations stream message are as follows:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
typeStringThe value validationReceived indicates this is from the validations stream.
amendmentsArray of Strings(May be omitted) The amendments this server wants to be added to the protocol. New in: rippled 0.32.0
base_feeInteger(May be omitted) The unscaled transaction cost (reference_fee value) this server wants to set by Fee Voting. New in: rippled 0.32.0
flagsNumberBit-mask of flags added to this validation message. The flag 0x80000000 indicates that the validation signature is fully-canonical. The flag 0x00000001 indicates that this is a full validation; otherwise it's a partial validation. Partial validations are not meant to vote for any particular ledger. A partial validation indicates that the validator is still online but not keeping up with consensus. New in: rippled 0.32.0
fullBooleanIf true, this is a full validation. Otherwise, this is a partial validation. Partial validations are not meant to vote for any particular ledger. A partial validation indicates that the validator is still online but not keeping up with consensus. New in: rippled 0.32.0
ledger_hashStringThe identifying hash of the proposed ledger is being validated.
ledger_indexString - IntegerThe Ledger Index of the proposed ledger. New in: rippled 0.31.0
load_feeInteger(May be omitted) The local load-scaled transaction cost this validator is currently enforcing, in fee units. New in: rippled 0.32.0
reserve_baseInteger(May be omitted) The minimum reserve requirement (account_reserve value) this validator wants to set by Fee Voting. New in: rippled 0.32.0
reserve_incInteger(May be omitted) The increment in the reserve requirement (owner_reserve value) this validator wants to set by Fee Voting. New in: rippled 0.32.0
signatureStringThe signature that the validator used to sign its vote for this ledger.
signing_timeNumberWhen this validation vote was signed, in seconds since the Ripple Epoch. New in: rippled 0.32.0
validation_public_keyStringThe base58 encoded public key from the key-pair that the validator used to sign the message. This identifies the validator sending the message and can also be used to verify the signature.
-

Transaction Streams

-

Many subscriptions result in messages about transactions, including the following:

-
    -
  • The transactions stream
    • -
  • The transactions_proposed stream
    • -
  • accounts subscriptions
    • -
  • accounts_proposed subscriptions
    • -
  • book (Order Book) subscriptions
    • -
-

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

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

Otherwise, the messages from the transactions_proposed stream are the same as ones from the transactions stream.

-

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

-

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

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

Transaction stream messages have the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
typeStringtransaction indicates this is the notification of a transaction, which could come from several possible streams.
engine_resultStringString Transaction result code
engine_result_codeNumberNumeric transaction response code, if applicable.
engine_result_messageStringHuman-readable explanation for the transaction response
ledger_current_indexUnsigned Integer(Omitted for validated transactions) Sequence number of the current ledger version for which this transaction is currently proposed
ledger_hashString(Omitted for unvalidated transactions) Unique hash of the ledger version that includes this transaction, as hex
ledger_indexUnsigned Integer(Omitted for unvalidated transactions) Sequence number of the ledger version that includes this transaction
metaObject(Omitted for unvalidated transactions) Various metadata about the transaction, including which ledger entries it affected
transactionObjectThe definition of the transaction in JSON format
validatedBooleanIf true, this transaction is included in a validated ledger. Responses from the transaction stream should always be validated.
-

Peer Status Stream

-

The admin-only peer_status stream reports a large amount of information on the activities of other rippled servers to which this server is connected, in particular their status in the consensus process.

-

Example of a Peer Status stream message:

-
{
-    "action": "CLOSING_LEDGER",
-    "date": 508546525,
-    "ledger_hash": "4D4CD9CD543F0C1EF023CC457F5BEFEA59EEF73E4552542D40E7C4FA08D3C320",
-    "ledger_index": 18853106,
-    "ledger_index_max": 18853106,
-    "ledger_index_min": 18852082,
-    "type": "peerStatusChange"
-}
-
-

Peer Status stream messages represent some event where the status of the peer rippled server changed. These messages are JSON objects with the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
typeStringpeerStatusChange indicates this comes from the Peer Status stream.
actionStringThe type of event that prompted this message. See Peer Status Events for possible values.
dateNumberThe time this event occurred, in seconds since the Ripple Epoch.
ledger_hashString(May be omitted) The identifying Hash of a ledger version to which this message pertains.
ledger_indexNumber(May be omitted) The Ledger Index of a ledger version to which this message pertains.
ledger_index_maxNumber(May be omitted) The largest Ledger Index the peer has currently available.
ledger_index_minNumber(May be omitted) The smallest Ledger Index the peer has currently available.
-

Peer Status Events

-

The action field of a Peer Status stream message can have the following values:

- - - - - - - - - - - - - - - - - - - - - - - - - -
ValueMeaning
CLOSING_LEDGERThe peer closed a ledger version with this Ledger Index, which usually means it is about to start consensus.
ACCEPTED_LEDGERThe peer built this ledger version as the result of a consensus round. Note: This ledger is still not certain to become immutably validated.
SWITCHED_LEDGERThe peer concluded it was not following the rest of the network and switched to a different ledger version.
LOST_SYNCThe peer fell behind the rest of the network in tracking which ledger versions are validated and which are undergoing consensus.
-

Order Book Streams

-

When you subscribe to one or more order books with the books field, you get back any transactions that affect those order books.

-

Example order book stream message:

-
{
-    "engine_result": "tesSUCCESS",
-    "engine_result_code": 0,
-    "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
-    "ledger_hash": "08547DD866F099CCB3666F113116B7AA2DF520FA2E3011DD1FF9C9C04A6C7C3E",
-    "ledger_index": 18852105,
-    "meta": {
-        "AffectedNodes": [{
-            "ModifiedNode": {
-                "FinalFields": {
-                    "Account": "rfCFLzNJYvvnoGHWQYACmJpTgkLUaugLEw",
-                    "AccountTxnID": "D295E2BE50E3B78AED24790D7B9096996DAF43F095BF17DB83EEACC283D14050",
-                    "Balance": "3070332374272",
-                    "Flags": 0,
-                    "OwnerCount": 23,
-                    "RegularKey": "r9S56zu6QeJD5d8A7QMfLAeYavgB9dhaX4",
-                    "Sequence": 12142921
-                },
-                "LedgerEntryType": "AccountRoot",
-                "LedgerIndex": "2880A9B4FB90A306B576C2D532BFE390AB3904642647DCF739492AA244EF46D1",
-                "PreviousFields": {
-                    "AccountTxnID": "3CA3422B0E42D76A7A677B0BA0BE72DFCD93676E0C80F8D2EB27C04BD8457A0F",
-                    "Balance": "3070332385272",
-                    "Sequence": 12142920
-                },
-                "PreviousTxnID": "3CA3422B0E42D76A7A677B0BA0BE72DFCD93676E0C80F8D2EB27C04BD8457A0F",
-                "PreviousTxnLgrSeq": 18852102
-            }
-        }, {
-            "ModifiedNode": {
-                "FinalFields": {
-                    "Flags": 0,
-                    "IndexPrevious": "00000000000022D2",
-                    "Owner": "rfCFLzNJYvvnoGHWQYACmJpTgkLUaugLEw",
-                    "RootIndex": "F435FBBEC9654204D7151A01E686BAA8CB325A472D7B61C7916EA58B59355767"
-                },
-                "LedgerEntryType": "DirectoryNode",
-                "LedgerIndex": "29A543B6681AD7FC8AFBD1386DAE7385F02F9B8C4756A467DF6834AB54BBC9DB"
-            }
-        }, {
-            "ModifiedNode": {
-                "FinalFields": {
-                    "ExchangeRate": "4C1BA999A513EF78",
-                    "Flags": 0,
-                    "RootIndex": "79C54A4EBD69AB2EADCE313042F36092BE432423CC6A4F784C1BA999A513EF78",
-                    "TakerGetsCurrency": "0000000000000000000000000000000000000000",
-                    "TakerGetsIssuer": "0000000000000000000000000000000000000000",
-                    "TakerPaysCurrency": "0000000000000000000000005553440000000000",
-                    "TakerPaysIssuer": "2ADB0B3959D60A6E6991F729E1918B7163925230"
-                },
-                "LedgerEntryType": "DirectoryNode",
-                "LedgerIndex": "79C54A4EBD69AB2EADCE313042F36092BE432423CC6A4F784C1BA999A513EF78"
-            }
-        }, {
-            "CreatedNode": {
-                "LedgerEntryType": "Offer",
-                "LedgerIndex": "92E235EE80D2B28A89BEE2C905D4545C2A004FD5D4097679C8A3FB25507FD9EB",
-                "NewFields": {
-                    "Account": "rfCFLzNJYvvnoGHWQYACmJpTgkLUaugLEw",
-                    "BookDirectory": "79C54A4EBD69AB2EADCE313042F36092BE432423CC6A4F784C1BA999A513EF78",
-                    "Expiration": 508543674,
-                    "OwnerNode": "00000000000022F4",
-                    "Sequence": 12142920,
-                    "TakerGets": "6537121438",
-                    "TakerPays": {
-                        "currency": "USD",
-                        "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
-                        "value": "50.9"
-                    }
-                }
-            }
-        }, {
-            "DeletedNode": {
-                "FinalFields": {
-                    "Account": "rfCFLzNJYvvnoGHWQYACmJpTgkLUaugLEw",
-                    "BookDirectory": "79C54A4EBD69AB2EADCE313042F36092BE432423CC6A4F784C1BA999A513EF78",
-                    "BookNode": "0000000000000000",
-                    "Expiration": 508543133,
-                    "Flags": 0,
-                    "OwnerNode": "00000000000022F4",
-                    "PreviousTxnID": "58B3279C2D56AAC3D9B06106E637C01E3D911E9D31E2FE4EA0D886AC9F4DEE1E",
-                    "PreviousTxnLgrSeq": 18851945,
-                    "Sequence": 12142889,
-                    "TakerGets": "6537121438",
-                    "TakerPays": {
-                        "currency": "USD",
-                        "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
-                        "value": "50.9"
-                    }
-                },
-                "LedgerEntryType": "Offer",
-                "LedgerIndex": "D3436CE21925E1CB12C5C444963B47D7EA0CD9A0E387926DC76B23FE5CD1C15F"
-            }
-        }],
-        "TransactionIndex": 26,
-        "TransactionResult": "tesSUCCESS"
-    },
-    "status": "closed",
-    "transaction": {
-        "Account": "rfCFLzNJYvvnoGHWQYACmJpTgkLUaugLEw",
-        "Expiration": 508543674,
-        "Fee": "11000",
-        "Flags": 2147483648,
-        "LastLedgerSequence": 18852106,
-        "OfferSequence": 12142889,
-        "Sequence": 12142920,
-        "SigningPubKey": "034841BF24BD72C7CC371EBD87CCBF258D8ADB05C18DE207130364A97D8A3EA524",
-        "TakerGets": "6537121438",
-        "TakerPays": {
-            "currency": "USD",
-            "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
-            "value": "50.9"
-        },
-        "TransactionType": "OfferCreate",
-        "TxnSignature": "3045022100B9AD678A773FB61F8F9B565713C80CBF187A2F9EB8E9CE0DAC7B839CA6F4B04C02200613D173A0636CD9BE13F2E3EBD13A16932B5B7D8A96BB5F6D561CA5CDBC4AD3",
-        "date": 508543090,
-        "hash": "D295E2BE50E3B78AED24790D7B9096996DAF43F095BF17DB83EEACC283D14050",
-        "owner_funds": "3070197374272"
-    },
-    "type": "transaction",
-    "validated": true
-}
-
-

The format of an order book stream message is the same as that of transaction stream messages, except that OfferCreate transactions also contain the following field:

- - - - - - - - - - - - - - - -
FieldValueDescription
transaction.owner_fundsStringNumeric amount of the TakerGets currency that the Account sending this OfferCreate transaction has after executing this transaction. This does not check whether the currency amount is frozen.
-

unsubscribe

-

[Source]

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-    "id": "Unsubscribe a lot of stuff",
-    "command": "unsubscribe",
-    "streams": ["ledger","server","transactions","transactions_proposed"],
-    "accounts": ["rrpNnNLKrartuEqfJGpqyDwPj1AFPg9vn1"],
-    "accounts_proposed": ["rrpNnNLKrartuEqfJGpqyDwPj1AFPg9vn1"],
-    "books": [
-        {
-            "taker_pays": {
-                "currency": "XRP"
-            },
-            "taker_gets": {
-                "currency": "USD",
-                "issuer": "rUQTpMqAF5jhykj4FExVeXakrZpiKF6cQV"
-            },
-            "both": true
-        }
-    ]
-}
-
-
-

Try it!

-

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

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

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

-

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

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
taker_getsObjectSpecification of which currency the account taking the offer would receive, as an object with currency and issuer fields (omit issuer for XRP), like currency amounts.
taker_paysObjectSpecification of which currency the account taking the offer would pay, as an object with currency and issuer fields (omit issuer for XRP), like currency amounts.
bothBoolean(Optional, defaults to false) If true, remove a subscription for both sides of the order book.
-

Response Format

-

An example of a successful response:

-
- -
{
-    "id": "Unsubscribe a lot of stuff",
-    "result": {},
-    "status": "success",
-    "type": "response"
-}
-
-
-

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

-

Possible Errors

-
    -
  • Any of the universal error types.
    • -
  • invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.
    • -
  • noPermission - The request included the url field, but you are not connected as an admin.
    • -
  • malformedStream - The streams field of the request is not formatted properly.
    • -
  • malformedAccount - One of the addresses in the accounts or accounts_proposed fields of the request is not a properly-formatted XRP Ledger address.
      -
    • Note:: You can subscribe to the stream of an address that does not yet have an entry in the global ledger to get a message when that address becomes funded.
      • -
    -
    • -
  • srcCurMalformed - One or more taker_pays sub-fields of the books field in the request is not formatted properly.
    • -
  • dstAmtMalformed - One or more taker_gets sub-fields of the books field in the request is not formatted properly.
    • -
  • srcIsrMalformed - The issuer field of one or more taker_pays sub-fields of the books field in the request is not valid.
    • -
  • dstIsrMalformed - The issuer field of one or more taker_gets sub-fields of the books field in the request is not valid.
    • -
  • badMarket - One or more desired order books in the books field does not exist; for example, offers to exchange a currency for itself.
    • -
-

Server Information

-

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

-

server_info

-

[Source]

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-  "id": 1,
-  "command": "server_info"
-}
-
- -
{
-    "method": "server_info",
-    "params": [
-        {}
-    ]
-}
-
- -
#Syntax: server_info
-rippled server_info
-
-
-

Try it!

-

The request does not takes any parameters.

-

Response Format

-

An example of a successful response:

-
- -
{
-  "id": 1,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "info": {
-      "build_version": "0.30.1-rc3",
-      "complete_ledgers": "18611104-18614732",
-      "hostid": "trace",
-      "io_latency_ms": 1,
-      "last_close": {
-        "converge_time_s": 4.003,
-        "proposers": 5
-      },
-      "load": {
-        "job_types": [
-          {
-            "job_type": "untrustedProposal",
-            "per_second": 2
-          },
-          {
-            "in_progress": 1,
-            "job_type": "clientCommand"
-          },
-          {
-            "job_type": "transaction",
-            "per_second": 4
-          },
-          {
-            "job_type": "batch",
-            "per_second": 3
-          },
-          {
-            "job_type": "writeObjects",
-            "per_second": 2
-          },
-          {
-            "job_type": "trustedProposal",
-            "per_second": 1
-          },
-          {
-            "job_type": "peerCommand",
-            "per_second": 108
-          },
-          {
-            "job_type": "diskAccess",
-            "per_second": 1
-          },
-          {
-            "job_type": "processTransaction",
-            "per_second": 4
-          },
-          {
-            "job_type": "WriteNode",
-            "per_second": 63
-          }
-        ],
-        "threads": 6
-      },
-      "load_factor": 1000,
-      "load_factor_net": 1000,
-      "peers": 10,
-      "pubkey_node": "n94UE1ukbq6pfZY9j54sv2A1UrEeHZXLbns3xK5CzU9NbNREytaa",
-      "pubkey_validator": "n9KM73uq5BM3Fc6cxG3k5TruvbLc8Ffq17JZBmWC4uP4csL4rFST",
-      "server_state": "proposing",
-      "state_accounting": {
-        "connected": {
-          "duration_us": "150510079",
-          "transitions": 1
-        },
-        "disconnected": {
-          "duration_us": "1827731",
-          "transitions": 1
-        },
-        "full": {
-          "duration_us": "166972201508",
-          "transitions": 1853
-        },
-        "syncing": {
-          "duration_us": "6249156726",
-          "transitions": 1854
-        },
-        "tracking": {
-          "duration_us": "13035222",
-          "transitions": 1854
-        }
-      },
-      "uptime": 173379,
-      "validated_ledger": {
-        "age": 3,
-        "base_fee_xrp": 0.00001,
-        "hash": "04F7CF4EACC57140C8088F6BFDC8A824BB3ED5717C3DAA6642101F9FB446226C",
-        "reserve_base_xrp": 20,
-        "reserve_inc_xrp": 5,
-        "seq": 18614732
-      },
-      "validation_quorum": 4
-    }
-  }
-}
-
- -
200 OK
-{
-   "result" : {
-      "info" : {
-         "build_version" : "0.33.0-hf1",
-         "complete_ledgers" : "24900901-24900984,24901116-24901158",
-         "hostid" : "trace",
-         "io_latency_ms" : 1,
-         "last_close" : {
-            "converge_time_s" : 2.001,
-            "proposers" : 5
-         },
-         "load" : {
-            "job_types" : [
-               {
-                  "in_progress" : 1,
-                  "job_type" : "clientCommand"
-               },
-               {
-                  "job_type" : "transaction",
-                  "per_second" : 6
-               },
-               {
-                  "job_type" : "batch",
-                  "per_second" : 6
-               },
-               {
-                  "in_progress" : 1,
-                  "job_type" : "advanceLedger"
-               },
-               {
-                  "job_type" : "trustedValidation",
-                  "per_second" : 1
-               },
-               {
-                  "avg_time" : 77,
-                  "job_type" : "writeObjects",
-                  "over_target" : true,
-                  "peak_time" : 2990,
-                  "per_second" : 2
-               },
-               {
-                  "job_type" : "trustedProposal",
-                  "per_second" : 2
-               },
-               {
-                  "job_type" : "peerCommand",
-                  "per_second" : 205
-               },
-               {
-                  "avg_time" : 771,
-                  "job_type" : "diskAccess",
-                  "over_target" : true,
-                  "peak_time" : 1934
-               },
-               {
-                  "job_type" : "processTransaction",
-                  "per_second" : 6
-               },
-               {
-                  "job_type" : "SyncReadNode",
-                  "per_second" : 4
-               },
-               {
-                  "job_type" : "WriteNode",
-                  "per_second" : 235
-               }
-            ],
-            "threads" : 6
-         },
-         "load_factor" : 4.765625,
-         "load_factor_local" : 4.765625,
-         "peers" : 10,
-         "pubkey_node" : "n9McNsnzzXQPbg96PEUrrQ6z3wrvgtU4M7c97tncMpSoDzaQvPar",
-         "pubkey_validator" : "n9KM73uq5BM3Fc6cxG3k5TruvbLc8Ffq17JZBmWC4uP4csL4rFST",
-         "published_ledger" : 24901158,
-         "server_state" : "proposing",
-         "state_accounting" : {
-            "connected" : {
-               "duration_us" : "854824665",
-               "transitions" : 2
-            },
-            "disconnected" : {
-               "duration_us" : "2183055",
-               "transitions" : 1
-            },
-            "full" : {
-               "duration_us" : "944104343",
-               "transitions" : 2
-            },
-            "syncing" : {
-               "duration_us" : "9233178",
-               "transitions" : 1
-            },
-            "tracking" : {
-               "duration_us" : "0",
-               "transitions" : 2
-            }
-         },
-         "uptime" : 1792,
-         "validated_ledger" : {
-            "age" : 1,
-            "base_fee_xrp" : 1e-05,
-            "hash" : "D2C122281EB72E64D19B9654A8D3D0FC4207373D3FE5D91AE516685A58874621",
-            "reserve_base_xrp" : 20,
-            "reserve_inc_xrp" : 5,
-            "seq" : 24901185
-         },
-         "validation_quorum" : 4
-      },
-      "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:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
build_versionStringThe version number of the running rippled version.
closed_ledgerObject(May be omitted) Information on the most recently closed ledger that has not been validated by consensus. If the most recently validated ledger is available, the response omits this field and includes validated_ledger instead. The member fields are the same as the validated_ledger field.
complete_ledgersStringRange expression indicating the sequence numbers of the ledger versions the local rippled has in its database. This may be a disjoint sequence, for example 24900901-24900984,24901116-24901158.
hostidStringOn an admin request, returns the hostname of the server running the rippled instance; otherwise, returns a unique four letter word.
io_latency_msNumberAmount of time spent waiting for I/O operations, in milliseconds. If this number is not very, very low, then the rippled server is probably having serious load issues.
last_closeObjectInformation about the last time the server closed a ledger, including the amount of time it took to reach a consensus and the number of trusted validators participating.
loadObjectAdmin only Detailed information about the current load state of the server
load.job_typesArrayAdmin only Information about the rate of different types of jobs the server is doing and how much time it spends on each.
load.threadsNumberAdmin only The number of threads in the server's main job pool.
load_factorNumberThe load-scaled open ledger transaction cost the server is currently enforcing, as a multiplier on the base transaction cost. For example, at 1000 load factor and a reference transaction cost of 10 drops of XRP, the load-scaled transaction cost is 10,000 drops (0.01 XRP). The load factor is determined by the highest of the individual server's load factor, the cluster's load factor, the open ledger cost and the overall network's load factor. Updated in: rippled 0.33.0
load_factor_localNumber(May be omitted) Current multiplier to the transaction cost based on load to this server.
load_factor_netNumber(May be omitted) Current multiplier to the transaction cost being used by the rest of the network (estimated from other servers' reported load values).
load_factor_clusterNumber(May be omitted) Current multiplier to the transaction cost based on load to servers in this cluster.
load_factor_fee_escalationNumber(May be omitted) The current multiplier to the transaction cost that a transaction must pay to get into the open ledger. New in: rippled 0.32.0
load_factor_fee_queueNumber(May be omitted) The current multiplier to the transaction cost that a transaction must pay to get into the queue, if the queue is full. New in: rippled 0.32.0
load_factor_serverNumber(May be omitted) The load factor the server is enforcing, not including the open ledger cost. New in: rippled 0.33.0
peersNumberHow many other rippled servers the node is currently connected to.
pubkey_nodeStringPublic key used to verify this node for internal communications; this key is automatically generated by the server the first time it starts up. (If deleted, the node can create a new pair of keys.)
pubkey_validatorStringAdmin only Public key used by this node to sign ledger validations.
server_stateStringA string indicating to what extent the server is participating in the network. See Possible Server States for more details.
state_accountingObjectA map of various server states with information about the time the server spends in each. This can be useful for tracking the long-term health of your server's connectivity to the network. New in: rippled 0.30.1
state_accounting.*.duration_usStringThe number of microseconds the server has spent in this state. (This is updated whenever the server transitions into another state.) New in: rippled 0.30.1
state_accounting.*.transitionsNumberThe number of times the server has transitioned into this state. New in: rippled 0.30.1
uptimeNumberNumber of consecutive seconds that the server has been operational. New in: rippled 0.30.1
validated_ledgerObject(May be omitted) Information about the most recent fully-validated ledger. If the most recent validated ledger is not available, the response omits this field and includes closed_ledger instead.
validated_ledger.ageNumberThe time since the ledger was closed, in seconds.
validated_ledger.base_fee_xrpNumberBase fee, in XRP. This may be represented in scientific notation such as 1e-05 for 0.00005.
validated_ledger.hashStringUnique hash for the ledger, as hex
validated_ledger.reserve_base_xrpUnsigned IntegerMinimum amount of XRP (not drops) necessary for every account to keep in reserve
validated_ledger.reserve_inc_xrpUnsigned IntegerAmount of XRP (not drops) added to the account reserve for each object an account owns in the ledger
validated_ledger.seqNumber - Ledger IndexThe ledger index of the latest validate ledger
validation_quorumNumberMinimum number of trusted validations required to validate a ledger version. Some circumstances may cause the server to require more validations.
-

Note: If the closed_ledger field is present and has a small seq value (less than 8 digits), that indicates rippled does not currently have a copy of the validated ledger from the peer-to-peer network. This could mean your server is still syncing. Typically, it takes about 5 minutes to sync with the network, depending on your connection speed and hardware specs.

-

Possible Errors

- -

server_state

-

[Source]

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-  "id": 2,
-  "command": "server_state"
-}
-
- -
{
-    "method": "server_state",
-    "params": [
-        {}
-    ]
-}
-
- -
#Syntax: server_state
-rippled server_state
-
-
-

Try it!

-

The request does not takes any parameters.

-

Response Format

-

An example of a successful response:

-
- -
{
-  "id": 2,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "state": {
-      "build_version": "0.30.1-rc3",
-      "complete_ledgers": "18611104-18615049",
-      "io_latency_ms": 1,
-      "last_close": {
-        "converge_time": 3003,
-        "proposers": 5
-      },
-      "load": {
-        "job_types": [
-          {
-            "job_type": "untrustedProposal",
-            "peak_time": 1,
-            "per_second": 3
-          },
-          {
-            "in_progress": 1,
-            "job_type": "clientCommand"
-          },
-          {
-            "avg_time": 12,
-            "job_type": "writeObjects",
-            "peak_time": 345,
-            "per_second": 2
-          },
-          {
-            "job_type": "trustedProposal",
-            "per_second": 1
-          },
-          {
-            "job_type": "peerCommand",
-            "per_second": 64
-          },
-          {
-            "avg_time": 33,
-            "job_type": "diskAccess",
-            "peak_time": 526
-          },
-          {
-            "job_type": "WriteNode",
-            "per_second": 55
-          }
-        ],
-        "threads": 6
-      },
-      "load_base": 256,
-      "load_factor": 256000,
-      "peers": 10,
-      "pubkey_node": "n94UE1ukbq6pfZY9j54sv2A1UrEeHZXLbns3xK5CzU9NbNREytaa",
-      "pubkey_validator": "n9KM73uq5BM3Fc6cxG3k5TruvbLc8Ffq17JZBmWC4uP4csL4rFST",
-      "server_state": "proposing",
-      "state_accounting": {
-        "connected": {
-          "duration_us": "150510079",
-          "transitions": 1
-        },
-        "disconnected": {
-          "duration_us": "1827731",
-          "transitions": 1
-        },
-        "full": {
-          "duration_us": "168295542987",
-          "transitions": 1865
-        },
-        "syncing": {
-          "duration_us": "6294237352",
-          "transitions": 1866
-        },
-        "tracking": {
-          "duration_us": "13035524",
-          "transitions": 1866
-        }
-      },
-      "uptime": 174748,
-      "validated_ledger": {
-        "base_fee": 10,
-        "close_time": 507693650,
-        "hash": "FEB17B15FB64E3AF8D371E6AAFCFD8B92775BB80AB953803BD73EA8EC75ECA34",
-        "reserve_base": 20000000,
-        "reserve_inc": 5000000,
-        "seq": 18615049
-      },
-      "validation_quorum": 4
-    }
-  }
-}
-
- -
200 OK
-{
-   "result" : {
-      "state" : {
-         "build_version" : "0.30.1-rc3",
-         "complete_ledgers" : "18611104-18615037",
-         "io_latency_ms" : 1,
-         "last_close" : {
-            "converge_time" : 2001,
-            "proposers" : 5
-         },
-         "load" : {
-            "job_types" : [
-               {
-                  "job_type" : "untrustedProposal",
-                  "per_second" : 2
-               },
-               {
-                  "in_progress" : 1,
-                  "job_type" : "clientCommand"
-               },
-               {
-                  "job_type" : "writeObjects",
-                  "per_second" : 2
-               },
-               {
-                  "avg_time" : 2,
-                  "job_type" : "acceptLedger",
-                  "peak_time" : 6
-               },
-               {
-                  "job_type" : "trustedProposal",
-                  "per_second" : 1
-               },
-               {
-                  "job_type" : "peerCommand",
-                  "per_second" : 80
-               },
-               {
-                  "job_type" : "diskAccess",
-                  "per_second" : 1
-               },
-               {
-                  "job_type" : "WriteNode",
-                  "per_second" : 91
-               }
-            ],
-            "threads" : 6
-         },
-         "load_base" : 256,
-         "load_factor" : 256000,
-         "peers" : 10,
-         "pubkey_node" : "n94UE1ukbq6pfZY9j54sv2A1UrEeHZXLbns3xK5CzU9NbNREytaa",
-         "pubkey_validator" : "n9KM73uq5BM3Fc6cxG3k5TruvbLc8Ffq17JZBmWC4uP4csL4rFST",
-         "server_state" : "proposing",
-         "state_accounting" : {
-            "connected" : {
-               "duration_us" : "150510079",
-               "transitions" : 1
-            },
-            "disconnected" : {
-               "duration_us" : "1827731",
-               "transitions" : 1
-            },
-            "full" : {
-               "duration_us" : "168241260112",
-               "transitions" : 1865
-            },
-            "syncing" : {
-               "duration_us" : "6294237352",
-               "transitions" : 1866
-            },
-            "tracking" : {
-               "duration_us" : "13035524",
-               "transitions" : 1866
-            }
-         },
-         "uptime" : 174693,
-         "validated_ledger" : {
-            "base_fee" : 10,
-            "close_time" : 507693592,
-            "hash" : "1C26209AE593C7EB5123363B3152D86514845FBD42CC6B05111D57F62D02B113",
-            "reserve_base" : 20000000,
-            "reserve_inc" : 5000000,
-            "seq" : 18615037
-         },
-         "validation_quorum" : 4
-      },
-      "status" : "success"
-   }
-}
-
-
-
-

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:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
build_versionStringThe version number of the running rippled version.
complete_ledgersStringRange expression indicating the sequence numbers of the ledger versions the local rippled has in its database. It is possible to be a disjoint sequence, e.g. "2500-5000,32570-7695432".
closed_ledgerObject(May be omitted) Information on the most recently closed ledger that has not been validated by consensus. If the most recently validated ledger is available, the response omits this field and includes validated_ledger instead. The member fields are the same as the validated_ledger field.
io_latency_msNumberAmount of time spent waiting for I/O operations, in milliseconds. If this number is not very, very low, then the rippled server is probably having serious load issues.
loadObjectAdmin only Detailed information about the current load state of the server
load.job_typesArrayAdmin only Information about the rate of different types of jobs the server is doing and how much time it spends on each.
load.threadsNumberAdmin only The number of threads in the server's main job pool.
load_baseIntegerThis is the baseline amount of server load used in transaction cost calculations. If the load_factor is equal to the load_base then only the base transaction cost is enforced. If the load_factor is higher than the load_base, then transaction costs are multiplied by the ratio between them. For example, if the load_factor is double the load_base, then transaction costs are doubled.
load_factorNumberThe load factor the server is currently enforcing. The ratio between this value and the load_base determines the multiplier for transaction costs. The load factor is determined by the highest of the individual server's load factor, cluster's load factor, the open ledger cost, and the overall network's load factor. Updated in: rippled 0.33.0
load_factor_fee_escalationInteger(May be omitted) The current multiplier to the transaction cost to get into the open ledger, in fee levels. New in: rippled 0.32.0
load_factor_fee_queueInteger(May be omitted) The current multiplier to the transaction cost to get into the queue, if the queue is full, in fee levels. New in: rippled 0.32.0
load_factor_fee_referenceInteger(May be omitted) The transaction cost with no load scaling, in fee levels. New in: rippled 0.32.0
load_factor_serverNumber(May be omitted) The load factor the server is enforcing, not including the open ledger cost. New in: rippled 0.33.0
peersNumberHow many other rippled servers the node is currently connected to.
pubkey_nodeStringPublic key used by this server (along with the corresponding private key) for secure communications between nodes. This key pair is automatically created and stored in rippled's local database the first time it starts up; if lost or deleted, a new key pair can be generated with no ill effects.
pubkey_validatorStringAdmin only Public key of the keypair used by this server to sign proposed ledgers for validation.
server_stateStringA string indicating to what extent the server is participating in the network. See Possible Server States for more details.
state_accountingObjectA map of various server states with information about the time the server spends in each. This can be useful for tracking the long-term health of your server's connectivity to the network. New in: rippled 0.30.1
state_accounting.*.duration_usStringThe number of microseconds the server has spent in this state. (This is updated whenever the server transitions into another state.) New in: rippled 0.30.1
state_accounting.*.transitionsNumberThe number of times the server has transitioned into this state. New in: rippled 0.30.1
uptimeNumberNumber of consecutive seconds that the server has been operational. New in: rippled 0.30.1
validated_ledgerObject(May be omitted) Information about the most recent fully-validated ledger. If the most recent validated ledger is not available, the response omits this field and includes closed_ledger instead.
validated_ledger.base_feeUnsigned IntegerBase fee, in drops of XRP, for propagating a transaction to the network.
validated_ledger.close_timeNumberTime this ledger was closed, in seconds since the Ripple Epoch
validated_ledger.hashStringUnique hash of this ledger version, as hex
validated_ledger.reserve_baseUnsigned IntegerMinimum amount, in drops of XRP, necessary for every account to keep in reserve
validated_ledger.reserve_incUnsigned IntegerAmount, in drops of XRP, that is added to the account reserve for each item the account owns in the ledger.
validated_ledger.seqUnsigned IntegerUnique sequence number of this ledger
validation_quorumNumberMinimum number of trusted validations required to validate a ledger version. Some circumstances may cause the server to require more validations.
-

Possible Errors

- -

can_delete

-

[Source]

-

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

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-  "id": 2,
-  "command": "can_delete",
-  "can_delete": 11320417
-}
-
- -
{
-    "method": "can_delete",
-    "params": [
-        {
-            "can_delete": 11320417
-        }
-    ]
-}
-
- -
#Syntax can_delete [<ledger_index>|<ledger_hash>|now|always|never]
-rippled can_delete 11320417
-
-
-

The request includes the following optional parameter:

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

If no parameter is specified, no change is made.

-

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

- - - - - - - - - - - - - - - -
FieldTypeDescription
can_deleteIntegerThe maximum ledger index that may be removed by the online deletion routine.
-

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

-

Possible Errors

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

consensus_info

-

[Source]

-

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

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-    "id": 99,
-    "command": "consensus_info"
-}
-
- -
{
-    "method": "consensus_info",
-    "params": [
-        {}
-    ]
-}
-
- -
#Syntax: consensus_info
-rippled consensus_info
-
-
-

The request has no parameters.

-

Response Format

-

An example of a successful response:

-
- -
{
-   "result" : {
-      "info" : {
-         "acquired" : {
-            "4BC2CE596CBD1321775320E2067F9C06D3862826212C16EF42ABB6A2B0414306" : "acquired"
-         },
-         "close_granularity" : 10,
-         "close_percent" : 50,
-         "close_resolution" : 10,
-         "close_times" : {
-            "486082972" : 1,
-            "486082973" : 4
-         },
-         "current_ms" : 1003,
-         "have_time_consensus" : false,
-         "ledger_seq" : 13701086,
-         "our_position" : {
-            "close_time" : 486082973,
-            "previous_ledger" : "0BB01379B51234BAAF501A71C7AB147F595460B689BB9E8252A0B87B5A483623",
-            "propose_seq" : 0,
-            "transaction_hash" : "4BC2CE596CBD1321775320E2067F9C06D3862826212C16EF42ABB6A2B0414306"
-         },
-         "peer_positions" : {
-            "0A2EAF919033A036D363D4E5610A66209DDBE8EE" : {
-               "close_time" : 486082972,
-               "peer_id" : "n9KiYM9CgngLvtRCQHZwgC2gjpdaZcCcbt3VboxiNFcKuwFVujzS",
-               "previous_ledger" : "0BB01379B51234BAAF501A71C7AB147F595460B689BB9E8252A0B87B5A483623",
-               "propose_seq" : 0,
-               "transaction_hash" : "4BC2CE596CBD1321775320E2067F9C06D3862826212C16EF42ABB6A2B0414306"
-            },
-            "1567A8C953A86F8428C7B01641D79BBF2FD508F3" : {
-               "close_time" : 486082973,
-               "peer_id" : "n9LdgEtkmGB9E2h3K4Vp7iGUaKuq23Zr32ehxiU8FWY7xoxbWTSA",
-               "previous_ledger" : "0BB01379B51234BAAF501A71C7AB147F595460B689BB9E8252A0B87B5A483623",
-               "propose_seq" : 0,
-               "transaction_hash" : "4BC2CE596CBD1321775320E2067F9C06D3862826212C16EF42ABB6A2B0414306"
-            },
-            "202397A81F20B44CF44EA99AF761295E5A8397D2" : {
-               "close_time" : 486082973,
-               "peer_id" : "n9MD5h24qrQqiyBC8aeqqCWvpiBiYQ3jxSr91uiDvmrkyHRdYLUj",
-               "previous_ledger" : "0BB01379B51234BAAF501A71C7AB147F595460B689BB9E8252A0B87B5A483623",
-               "propose_seq" : 0,
-               "transaction_hash" : "4BC2CE596CBD1321775320E2067F9C06D3862826212C16EF42ABB6A2B0414306"
-            },
-            "5C29005CF4FB479FC49EEFB4A5B075C86DD963CC" : {
-               "close_time" : 486082973,
-               "peer_id" : "n9L81uNCaPgtUJfaHh89gmdvXKAmSt5Gdsw2g1iPWaPkAHW5Nm4C",
-               "previous_ledger" : "0BB01379B51234BAAF501A71C7AB147F595460B689BB9E8252A0B87B5A483623",
-               "propose_seq" : 0,
-               "transaction_hash" : "4BC2CE596CBD1321775320E2067F9C06D3862826212C16EF42ABB6A2B0414306"
-            },
-            "EFC49EB648E557CC50A72D715249B80E071F7705" : {
-               "close_time" : 486082973,
-               "peer_id" : "n949f75evCHwgyP4fPVgaHqNHxUVN15PsJEZ3B3HnXPcPjcZAoy7",
-               "previous_ledger" : "0BB01379B51234BAAF501A71C7AB147F595460B689BB9E8252A0B87B5A483623",
-               "propose_seq" : 0,
-               "transaction_hash" : "4BC2CE596CBD1321775320E2067F9C06D3862826212C16EF42ABB6A2B0414306"
-            }
-         },
-         "previous_mseconds" : 2005,
-         "previous_proposers" : 5,
-         "proposers" : 5,
-         "proposing" : false,
-         "state" : "consensus",
-         "synched" : true,
-         "validating" : false
-      },
-      "status" : "success"
-   }
-}
-
- -
Loading: "/etc/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "info" : {
-         "acquired" : {
-            "4BC2CE596CBD1321775320E2067F9C06D3862826212C16EF42ABB6A2B0414306" : "acquired"
-         },
-         "close_granularity" : 10,
-         "close_percent" : 50,
-         "close_resolution" : 10,
-         "close_times" : {
-            "486082972" : 1,
-            "486082973" : 4
-         },
-         "current_ms" : 1003,
-         "have_time_consensus" : false,
-         "ledger_seq" : 13701086,
-         "our_position" : {
-            "close_time" : 486082973,
-            "previous_ledger" : "0BB01379B51234BAAF501A71C7AB147F595460B689BB9E8252A0B87B5A483623",
-            "propose_seq" : 0,
-            "transaction_hash" : "4BC2CE596CBD1321775320E2067F9C06D3862826212C16EF42ABB6A2B0414306"
-         },
-         "peer_positions" : {
-            "0A2EAF919033A036D363D4E5610A66209DDBE8EE" : {
-               "close_time" : 486082972,
-               "peer_id" : "n9KiYM9CgngLvtRCQHZwgC2gjpdaZcCcbt3VboxiNFcKuwFVujzS",
-               "previous_ledger" : "0BB01379B51234BAAF501A71C7AB147F595460B689BB9E8252A0B87B5A483623",
-               "propose_seq" : 0,
-               "transaction_hash" : "4BC2CE596CBD1321775320E2067F9C06D3862826212C16EF42ABB6A2B0414306"
-            },
-            "1567A8C953A86F8428C7B01641D79BBF2FD508F3" : {
-               "close_time" : 486082973,
-               "peer_id" : "n9LdgEtkmGB9E2h3K4Vp7iGUaKuq23Zr32ehxiU8FWY7xoxbWTSA",
-               "previous_ledger" : "0BB01379B51234BAAF501A71C7AB147F595460B689BB9E8252A0B87B5A483623",
-               "propose_seq" : 0,
-               "transaction_hash" : "4BC2CE596CBD1321775320E2067F9C06D3862826212C16EF42ABB6A2B0414306"
-            },
-            "202397A81F20B44CF44EA99AF761295E5A8397D2" : {
-               "close_time" : 486082973,
-               "peer_id" : "n9MD5h24qrQqiyBC8aeqqCWvpiBiYQ3jxSr91uiDvmrkyHRdYLUj",
-               "previous_ledger" : "0BB01379B51234BAAF501A71C7AB147F595460B689BB9E8252A0B87B5A483623",
-               "propose_seq" : 0,
-               "transaction_hash" : "4BC2CE596CBD1321775320E2067F9C06D3862826212C16EF42ABB6A2B0414306"
-            },
-            "5C29005CF4FB479FC49EEFB4A5B075C86DD963CC" : {
-               "close_time" : 486082973,
-               "peer_id" : "n9L81uNCaPgtUJfaHh89gmdvXKAmSt5Gdsw2g1iPWaPkAHW5Nm4C",
-               "previous_ledger" : "0BB01379B51234BAAF501A71C7AB147F595460B689BB9E8252A0B87B5A483623",
-               "propose_seq" : 0,
-               "transaction_hash" : "4BC2CE596CBD1321775320E2067F9C06D3862826212C16EF42ABB6A2B0414306"
-            },
-            "EFC49EB648E557CC50A72D715249B80E071F7705" : {
-               "close_time" : 486082973,
-               "peer_id" : "n949f75evCHwgyP4fPVgaHqNHxUVN15PsJEZ3B3HnXPcPjcZAoy7",
-               "previous_ledger" : "0BB01379B51234BAAF501A71C7AB147F595460B689BB9E8252A0B87B5A483623",
-               "propose_seq" : 0,
-               "transaction_hash" : "4BC2CE596CBD1321775320E2067F9C06D3862826212C16EF42ABB6A2B0414306"
-            }
-         },
-         "previous_mseconds" : 2005,
-         "previous_proposers" : 5,
-         "proposers" : 5,
-         "proposing" : false,
-         "state" : "consensus",
-         "synched" : true,
-         "validating" : false
-      },
-      "status" : "success"
-   }
-}
-
-
-

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

- - - - - - - - - - - - - - - -
FieldTypeDescription
infoObjectInformation that may be useful for debugging consensus. This output is subject to change without notice.
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
ledger_seqNumberThe sequence number of the ledger currently in the consensus process
our_positionObjectThis server's expectation for the ledger in the consensus process.
peer_positionsObjectMap of peers and their proposed versions of the ledger in the consensus process.
proposersNumberThe number of trusted validators participating in this consensus process. Which validators are trusted depends on this server's configuration.
synchedBooleanWhether this server considers itself in sync with the network.
stateStringWhat part of the consensus process is currently in progress: open, consensus, finished, or accepted.
-

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

-

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

-

Possible Errors

- -

fetch_info

-

[Source]

-

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

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-    "id": 91,
-    "command": "fetch_info",
-    "clear": false
-}
-
- -
{
-    "method": "fetch_info",
-    "params": [
-        {
-            "clear": false
-        }
-    ]
-}
-
- -
#Syntax: fetch_info [clear]
-rippled fetch_info
-
-
-

The request includes the following parameters:

- - - - - - - - - - - - - - - -
FieldTypeDescription
clearBooleanIf true, reset current fetches. Otherwise, only get status of fetches in progress.
-

Response Format

-

An example of a successful response:

-
- -
{
-   "result" : {
-      "info" : {
-         "348928" : {
-            "hash" : "C26D432B06F84861BCACD7942EDC3FE0B2E1DEB966A9E516A0FD275A375C2010",
-            "have_header" : true,
-            "have_state" : false,
-            "have_transactions" : true,
-            "needed_state_hashes" : [
-               "BF8DC6B1E10D1D3565BF0649075D22EBFD34F751AFCC0E53E81D74786BC88922",
-               "34E37A71CB51A12C73A435250E6A6349F7884C7EEBA6B88FA31F0244E967E88F",
-               "BFB7D3008A7D61FD6A0538D1C2E70CFB94CE8DC66606319C372F278A48629765",
-               "41C0C61D701FB1EA586F0EF1FC7A91FEC476D979589DA60507F05C13F7C21975",
-               "6DDE8840A2C3C7FF05E5FFEE4D06408694C16A8357338FE0C4581DC3D8A00BBA",
-               "6C69D833B582C849917806FA009518832BB50E900E43716FD7CC1966428DD0CF",
-               "1EDC020CFC4AF19B625C52E20B66D6AE672821CCC461E8A9C457A3B2955657F7",
-               "FC0616A66A2B0589CA513F3341D4EA51E782C4601E5072308478E3CC19264640",
-               "19FC607B5DE1B64681A676EC1ED5507B9555B0E098CD9D898320297DE1A64033",
-               "5E128D3FC990074E35687387A14AA12D9FD287E5AB57CB9B2FD83DE635DF5CA9",
-               "DE72820F3981770F2AA8770BC233B80661F1A452819D8529008875FF8DED87A9",
-               "3ACB84BEE2C45556351FF60FD787D235C9CF5623FB8A35B01446B773598E7CC0",
-               "0DD3A8DF69874148057F1F2BF305442FF2E89A76A08B4CC8C051E2ED69B874F3",
-               "4AE9A9C4F12A5BD0355037DA40A0B145420A2168A9FEDE43E643BD13062F8ECE",
-               "08CBF8CFFEC207F5AC4E4F24BC447011FD8C79D25B344281FBFB4732D7058ED4",
-               "779B2577C5C4BAED6657421448EA506BBF50F86BE363E0924127C4EA17A58BBE"
-            ],
-            "peers" : 2,
-            "timeouts" : 0
-         }
-      },
-      "status" : "success"
-   }
-}
-
- -
Loading: "/etc/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "info" : {
-         "348928" : {
-            "hash" : "C26D432B06F84861BCACD7942EDC3FE0B2E1DEB966A9E516A0FD275A375C2010",
-            "have_header" : true,
-            "have_state" : false,
-            "have_transactions" : true,
-            "needed_state_hashes" : [
-               "BF8DC6B1E10D1D3565BF0649075D22EBFD34F751AFCC0E53E81D74786BC88922",
-               "34E37A71CB51A12C73A435250E6A6349F7884C7EEBA6B88FA31F0244E967E88F",
-               "BFB7D3008A7D61FD6A0538D1C2E70CFB94CE8DC66606319C372F278A48629765",
-               "41C0C61D701FB1EA586F0EF1FC7A91FEC476D979589DA60507F05C13F7C21975",
-               "6DDE8840A2C3C7FF05E5FFEE4D06408694C16A8357338FE0C4581DC3D8A00BBA",
-               "6C69D833B582C849917806FA009518832BB50E900E43716FD7CC1966428DD0CF",
-               "1EDC020CFC4AF19B625C52E20B66D6AE672821CCC461E8A9C457A3B2955657F7",
-               "FC0616A66A2B0589CA513F3341D4EA51E782C4601E5072308478E3CC19264640",
-               "19FC607B5DE1B64681A676EC1ED5507B9555B0E098CD9D898320297DE1A64033",
-               "5E128D3FC990074E35687387A14AA12D9FD287E5AB57CB9B2FD83DE635DF5CA9",
-               "DE72820F3981770F2AA8770BC233B80661F1A452819D8529008875FF8DED87A9",
-               "3ACB84BEE2C45556351FF60FD787D235C9CF5623FB8A35B01446B773598E7CC0",
-               "0DD3A8DF69874148057F1F2BF305442FF2E89A76A08B4CC8C051E2ED69B874F3",
-               "4AE9A9C4F12A5BD0355037DA40A0B145420A2168A9FEDE43E643BD13062F8ECE",
-               "08CBF8CFFEC207F5AC4E4F24BC447011FD8C79D25B344281FBFB4732D7058ED4",
-               "779B2577C5C4BAED6657421448EA506BBF50F86BE363E0924127C4EA17A58BBE"
-            ],
-            "peers" : 2,
-            "timeouts" : 0
-         }
-      },
-      "status" : "success"
-   }
-}
-
-
-

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

- - - - - - - - - - - - - - - -
FieldTypeDescription
infoObjectMap of objects being fetched and the status of that object being fetched. A ledger being fetched may be identified by its sequence number; ledgers and other objects being fetched may also be identified by their hashes.
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
hashStringThe hash of the object being fetched.
have_headerBooleanFor a ledger, whether this server has already obtained the ledger's header section.
have_transactionsBooleanFor a ledger, whether this server has already obtained the transaction section of that ledger.
needed_state_hashesArray of (Hash) StringsThe hash values of state nodes still needed from this object. If more than 16 are needed, the response contains only the first 16.
peersNumberThe number of peers who have this object available.
timeoutsNumberThe number of times that fetching this object has resulted in a timeout (2.5 seconds).
-

Possible Errors

- -

feature

-

[Source]

-

The feature command returns information about amendments this server knows about, including whether they are enabled and whether the server is voting in favor of those amendments in the amendment process. New in: rippled 0.31.0

-

You can use the feature command to temporarily configure the server to vote against or in favor of an amendment. This change does not persist if you restart the server. To make lasting changes in amendment voting, use the rippled.cfg file. See Configuring Amendment Voting for more information.

-

The feature method is an admin command that cannot be run by unprivileged users.

-

Request Format

-

An example of the request format:

-
- -
{
-  "id": "list_all_features",
-  "command": "feature"
-}
-
- -
{
-  "id": "reject_multi_sign",
-  "command": "feature",
-  "feature": "4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373",
-  "vetoed": true
-}
-
- -
{
-    "method": "feature",
-    "params": [
-        {
-            "feature": "4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373",
-            "vetoed": false
-        }
-    ]
-}
-
- -
#Syntax: feature [<feature_id> [accept|reject]]
-rippled feature 4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373 accept
-
-
-

The request includes the following parameters:

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
featureString(Optional) The unique ID of an amendment, as hexadecimal; or the short name of the amendment. If provided, limits the response to one amendment. Otherwise, the response lists all amendments.
vetoedBoolean(Optional; ignored unless feature also specified) If true, instructs the server to vote against the amendment specified by feature. If false, instructs the server to vote in favor of the amendment.
-

Note: You can configure your server to vote in favor of a new amendment, even if the server does not currently know how to apply that amendment, by specifying the amendment ID in the feature field. For example, you might want to do this if you plan to upgrade soon to a new rippled version that does support the amendment.

-

Response Format

-

An example of a successful response:

-
- -
{
-  "id": "list_all_features",
-  "status": "success",
-  "type": "response",
-  "result": {
-    "features": {
-      "42426C4D4F1009EE67080A9B7965B44656D7714D104A72F9B4369F97ABF044EE": {
-        "enabled": false,
-        "name": "FeeEscalation",
-        "supported": true,
-        "vetoed": false
-      },
-      "4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373": {
-        "enabled": false,
-        "name": "MultiSign",
-        "supported": true,
-        "vetoed": false
-      },
-      "6781F8368C4771B83E8B821D88F580202BCB4228075297B19E4FDC5233F1EFDC": {
-        "enabled": false,
-        "name": "TrustSetAuth",
-        "supported": true,
-        "vetoed": false
-      },
-      "C1B8D934087225F509BEB5A8EC24447854713EE447D277F69545ABFA0E0FD490": {
-        "enabled": false,
-        "name": "Tickets",
-        "supported": true,
-        "vetoed": false
-      },
-      "DA1BD556B42D85EA9C84066D028D355B52416734D3283F85E216EA5DA6DB7E13": {
-        "enabled": false,
-        "name": "SusPay",
-        "supported": true,
-        "vetoed": false
-      }
-    }
-  }
-}
-
- -
{
-    "id": "reject_multi_sign",
-    "status": "success",
-    "type": "response",
-    "result": {
-        "features": {
-            "4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373": {
-                "enabled": false,
-                "name": "MultiSign",
-                "supported": true,
-                "vetoed": true
-            }
-        }
-    }
-}
-
- -
200 OK
-{
-    "result": {
-        "4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373": {
-            "enabled": false,
-            "name": "MultiSign",
-            "supported": true,
-            "vetoed": false
-        },
-        "status": "success"
-    }
-}
-
- -
Loading: "/etc/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-    "result": {
-        "4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373": {
-            "enabled": false,
-            "name": "MultiSign",
-            "supported": true,
-            "vetoed": false
-        },
-        "status": "success"
-    }
-}
-
-
-

The response follows the standard format, with a successful result containing a map of amendments as a JSON object. The keys of the object are amendment IDs. The values for each key are amendment objects that describe the status of the amendment with that ID. If the request specified a feature, the map contains only the requested amendment object, after applying any changes from the request. Each amendment object has the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
enabledBooleanWhether this amendment is currently enabled in the latest ledger.
nameString(May be omitted) The human-readable name for this amendment, if known.
supportedBooleanWhether this server knows how to apply this amendment.
vetoedBooleanWhether the server has been instructed to vote against this amendment.
-

Caution: The name for an amendment does not strictly indicate what that amendment does. The name is not guaranteed to be unique or consistent across servers.

-

Possible Errors

-
    -
  • Any of the universal error types.
    • -
  • badFeature - The feature specified was invalidly formatted, or the server does not know an amendment with that name.
    • -
-

fee

-

[Source]

-

The fee command reports the current state of the open-ledger requirements for the transaction cost. This requires the FeeEscalation amendment to be enabled. New in: rippled 0.31.0

-

This is a public command available to unprivileged users. Updated in: rippled 0.32.0

-

Request Format

-

An example of the request format:

-
- -
{
-  "id": "fee_websocket_example",
-  "command": "fee"
-}
-
- -
{
-    "method": "fee",
-    "params": [{}]
-}
-
- -
#Syntax: fee
-rippled fee
-
-
-

The request does not include any parameters.

-

Response Format

-

An example of a successful response:

-
- -
{
-  "id": "fee_websocket_example",
-  "status": "success",
-  "type": "response",
-  "result": {
-    "current_ledger_size": "14",
-    "current_queue_size": "0",
-    "drops": {
-      "base_fee": "10",
-      "median_fee": "11000",
-      "minimum_fee": "10",
-      "open_ledger_fee": "10"
-    },
-    "expected_ledger_size": "24",
-    "ledger_current_index": 26575101,
-    "levels": {
-      "median_level": "281600",
-      "minimum_level": "256",
-      "open_ledger_level": "256",
-      "reference_level": "256"
-    },
-    "max_queue_size": "480"
-  }
-}
-
- -
200 OK
-{
-    "result": {
-        "current_ledger_size": "56",
-        "current_queue_size": "11",
-        "drops": {
-            "base_fee": "10",
-            "median_fee": "10000",
-            "minimum_fee": "10",
-            "open_ledger_fee": "2653937"
-        },
-        "expected_ledger_size": "55",
-        "ledger_current_index": 26575101,
-        "levels": {
-            "median_level": "256000",
-            "minimum_level": "256",
-            "open_ledger_level": "67940792",
-            "reference_level": "256"
-        },
-        "max_queue_size": "1100",
-        "status": "success"
-    }
-}
-
- -
Loading: "/etc/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "current_ledger_size" : "16",
-      "current_queue_size" : "2",
-      "drops" : {
-         "base_fee" : "10",
-         "median_fee" : "11000",
-         "minimum_fee" : "10",
-         "open_ledger_fee" : "3203982"
-      },
-      "expected_ledger_size" : "15",
-      "ledger_current_index": 26575101,
-      "levels" : {
-         "median_level" : "281600",
-         "minimum_level" : "256",
-         "open_ledger_level" : "82021944",
-         "reference_level" : "256"
-      },
-      "max_queue_size" : "300",
-      "status" : "success"
-   }
-}
-
-
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
current_ledger_sizeString (Integer)Number of transactions provisionally included in the in-progress ledger.
current_queue_sizeString (Integer)Number of transactions currently queued for the next ledger.
dropsObjectVarious information about the transaction cost (the Fee field of a transaction), in drops of xrp.
drops.base_feeString (Integer)The transaction cost required for a reference transaction to be included in a ledger under minimum load, represented in drops of XRP.
drops.median_feeString (Integer)An approximation of the median transaction cost among transactions included in the previous validated ledger, represented in drops of XRP.
drops.minimum_feeString (Integer)The minimum transaction cost for a reference transaction to be queued for a later ledger, represented in drops of XRP. If greater than base_fee, the transaction queue is full.
drops.open_ledger_feeString (Integer)The minimum transaction cost that a reference transaction must pay to be included in the current open ledger, represented in drops of XRP.
expected_ledger_sizeString (Integer)The approximate number of transactions expected to be included in the current ledger. This is based on the number of transactions in the previous ledger.
ledger_current_indexNumberThe Ledger Index of the current open ledger these stats describe. New in: rippled 0.50.0
levelsObjectVarious information about the transaction cost, in fee levels. The ratio in fee levels applies to any transaction relative to the minimum cost of that particular transaction.
levels.median_levelString (Integer)The median transaction cost among transactions in the previous validated ledger, represented in fee levels.
levels.minimum_levelString (Integer)The minimum transaction cost required to be queued for a future ledger, represented in fee levels.
levels.open_ledger_levelString (Integer)The minimum transaction cost required to be included in the current open ledger, represented in fee levels.
levels.reference_levelString (Integer)The equivalent of the minimum transaction cost, represented in fee levels.
max_queue_sizeString (Integer)The maximum number of transactions that the transaction queue can currently hold.
-

Possible Errors

- -

get_counts

-

[Source]

-

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

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-    "id": 90,
-    "command": "get_counts",
-    "min_count": 100
-}
-
- -
{
-    "method": "get_counts",
-    "params": [
-        {
-            "min_count": 100
-        }
-    ]
-}
-
- -
#Syntax: get_counts [min_count]
-rippled get_counts 100
-
-
-

The request includes the following parameters:

- - - - - - - - - - - - - - - -
FieldTypeDescription
min_countNumber (Unsigned Integer)Only return fields with a value at least this high.
-

Response Format

-

An example of a successful response:

-
- -
{
-   "result" : {
-      "AL_hit_rate" : 48.36725616455078,
-      "HashRouterEntry" : 3048,
-      "Ledger" : 46,
-      "NodeObject" : 10417,
-      "SLE_hit_rate" : 64.62035369873047,
-      "STArray" : 1299,
-      "STLedgerEntry" : 646,
-      "STObject" : 6987,
-      "STTx" : 4104,
-      "STValidation" : 610,
-      "Transaction" : 4069,
-      "dbKBLedger" : 10733,
-      "dbKBTotal" : 39069,
-      "dbKBTransaction" : 26982,
-      "fullbelow_size" : 0,
-      "historical_perminute" : 0,
-      "ledger_hit_rate" : 71.0565185546875,
-      "node_hit_rate" : 3.808214902877808,
-      "node_read_bytes" : 393611911,
-      "node_reads_hit" : 1283098,
-      "node_reads_total" : 679410,
-      "node_writes" : 1744285,
-      "node_written_bytes" : 794368909,
-      "status" : "success",
-      "treenode_cache_size" : 6650,
-      "treenode_track_size" : 598631,
-      "uptime" : "3 hours, 50 minutes, 27 seconds",
-      "write_load" : 0
-   }
-}
-
- -
Loading: "/etc/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "AL_hit_rate" : 48.36725616455078,
-      "HashRouterEntry" : 3048,
-      "Ledger" : 46,
-      "NodeObject" : 10417,
-      "SLE_hit_rate" : 64.62035369873047,
-      "STArray" : 1299,
-      "STLedgerEntry" : 646,
-      "STObject" : 6987,
-      "STTx" : 4104,
-      "STValidation" : 610,
-      "Transaction" : 4069,
-      "dbKBLedger" : 10733,
-      "dbKBTotal" : 39069,
-      "dbKBTransaction" : 26982,
-      "fullbelow_size" : 0,
-      "historical_perminute" : 0,
-      "ledger_hit_rate" : 71.0565185546875,
-      "node_hit_rate" : 3.808214902877808,
-      "node_read_bytes" : 393611911,
-      "node_reads_hit" : 1283098,
-      "node_reads_total" : 679410,
-      "node_writes" : 1744285,
-      "node_written_bytes" : 794368909,
-      "status" : "success",
-      "treenode_cache_size" : 6650,
-      "treenode_track_size" : 598631,
-      "uptime" : "3 hours, 50 minutes, 27 seconds",
-      "write_load" : 0
-   }
-}
-
-
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
TransactionNumberThe number of Transaction objects in memory
LedgerNumberThe number of ledgers in memory
uptimeStringThe amount of time this server has been running uninterrupted.
-

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

-

Possible Errors

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

ledger_cleaner

-

[Source]

-

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

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-    "command": "ledger_cleaner",
-    "max_ledger": 13818756,
-    "min_ledger": 13818000,
-    "stop": false
-}
-
-
-

The request includes the following parameters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
ledgerNumber (Ledger Sequence Number)(Optional) If provided, check and correct this specific ledger only.
max_ledgerNumber (Ledger Sequence Number)(Optional) Configure the ledger cleaner to check ledgers with sequence numbers equal or lower than this.
min_ledgerNumber (Ledger Sequence Number)(Optional) Configure the ledger cleaner to check ledgers with sequence numbers equal or higher than this.
fullBoolean(Optional) If true, fix ledger state nodes and transations in the specified ledger(s). Defaults to false. Automatically set to true if ledger is provided.
fix_txnsBoolean(Optional) If true, correct transaction in the specified ledger(s). Overrides full if provided.
check_nodesBoolean(Optional) If true, correct ledger state nodes in the specified ledger(s). Overrides full if provided.
stopBoolean(Optional) If true, disable the ledger cleaner.
-

Response Format

-

An example of a successful response:

-
- -
200 OK
-{
-   "result" : {
-      "message" : "Cleaner configured",
-      "status" : "success"
-   }
-}
-
-
-
-

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

- - - - - - - - - - - - - - - -
FieldTypeDescription
messageStringCleaner configured on success.
-

Possible Errors

-
    -
  • Any of the universal error types.
    • -
  • internal if one the parameters is specified incorrectly. (This is a bug; the intended error code is invalidParams.)
    • -
-

log_level

-

[Source]

-

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

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-    "id": "ll1",
-    "command": "log_level",
-    "severity": "debug",
-    "partition": "PathRequest"
-}
-
- -
#Syntax: log_level [[partition] severity]
-rippled log_level PathRequest debug
-
-
-

The request includes the following parameters:

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

Response Format

-

Examples of successful responses:

-
- -
Loading: "/etc/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "status" : "success"
-   }
-}
-
- -
Loading: "/etc/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "levels" : {
-         "AmendmentTable" : "Error",
-         "Application" : "Error",
-         "CancelOffer" : "Error",
-         "Collector" : "Error",
-         "CreateOffer" : "Error",
-         "DeferredCredits" : "Error",
-         "FeeVote" : "Error",
-         "InboundLedger" : "Error",
-         "JobQueue" : "Error",
-         "Ledger" : "Error",
-         "LedgerCleaner" : "Error",
-         "LedgerConsensus" : "Error",
-         "LedgerEntrySet" : "Error",
-         "LedgerMaster" : "Error",
-         "LedgerTiming" : "Error",
-         "LoadManager" : "Error",
-         "LoadMonitor" : "Error",
-         "NetworkOPs" : "Error",
-         "NodeObject" : "Error",
-         "OrderBookDB" : "Error",
-         "Overlay" : "Error",
-         "PathRequest" : "Debug",
-         "Payment" : "Error",
-         "Peer" : "Error",
-         "PeerFinder" : "Error",
-         "Protocol" : "Error",
-         "RPC" : "Error",
-         "RPCErr" : "Error",
-         "RPCHandler" : "Error",
-         "RPCManager" : "Error",
-         "Resolver" : "Error",
-         "Resource" : "Error",
-         "RippleCalc" : "Error",
-         "SHAMap" : "Error",
-         "SHAMapStore" : "Error",
-         "SNTPClient" : "Error",
-         "STAmount" : "Error",
-         "SerializedLedger" : "Error",
-         "Server" : "Error",
-         "SetAccount" : "Error",
-         "SetTrust" : "Error",
-         "TaggedCache" : "Error",
-         "TransactionAcquire" : "Error",
-         "TransactionEngine" : "Error",
-         "UVL" : "Error",
-         "UniqueNodeList" : "Error",
-         "Validations" : "Error",
-         "WALCheckpointer" : "Error",
-         "WebSocket" : "Trace",
-         "base" : "Error"
-      },
-      "status" : "success"
-   }
-}
-
-
-

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

-

Otherwise, the request contains the following field:

- - - - - - - - - - - - - - - -
FieldTypeDescription
levelObjectThe current log levels of each category. This list of categories is subject to change without notice in future releases. You can use the field names as values to partition in requests to this command.
-

Possible Errors

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

logrotate

-

[Source]

-

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

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-    "id": "lr1",
-    "command": "logrotate"
-}
-
- -
rippled logrotate
-
-
-

The request includes no parameters.

-

Response Format

-

An example of a successful response:

-
- -
200 OK
-{
-   "result" : {
-      "message" : "The log file was closed and reopened.",
-      "status" : "success"
-   }
-}
-
-
- -
Loading: "/etc/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "message" : "The log file was closed and reopened.",
-      "status" : "success"
-   }
-}
-
-
-
-

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

- - - - - - - - - - - - - - - -
FieldTypeDescription
messageStringOn success, contains the message The log file was closed and reopened.
-

Possible Errors

- -

validation_create

-

[Source]

-

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

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-    "id": 0,
-    "command": "validation_create",
-    "secret": "BAWL MAN JADE MOON DOVE GEM SON NOW HAD ADEN GLOW TIRE"
-}
-
- -
{
-    "method": "validation_create",
-    "params": [
-        {
-            "secret": "BAWL MAN JADE MOON DOVE GEM SON NOW HAD ADEN GLOW TIRE"
-        }
-    ]
-}
-
- -
#Syntax: validation_create [secret]
-rippled validation_create "BAWL MAN JADE MOON DOVE GEM SON NOW HAD ADEN GLOW TIRE"
-
-
-

The request includes the following parameters:

- - - - - - - - - - - - - - - -
FieldTypeDescription
secretString(Optional) Use this value as a seed to generate the credentials. The same secret always generates the same credentials. You can provide the seed in RFC-1751 format or Ripple's base58 format. If omitted, generate a random seed.
-

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

-

Response Format

-

An example of a successful response:

-
- -
{
-   "result" : {
-      "status" : "success",
-      "validation_key" : "FAWN JAVA JADE HEAL VARY HER REEL SHAW GAIL ARCH BEN IRMA",
-      "validation_public_key" : "n9Mxf6qD4J55XeLSCEpqaePW4GjoCR5U1ZeGZGJUCNe3bQa4yQbG",
-      "validation_seed" : "ssZkdwURFMBXenJPbrpE14b6noJSu"
-   }
-}
-
- -
Loading: "/etc/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "status" : "success",
-      "validation_key" : "FAWN JAVA JADE HEAL VARY HER REEL SHAW GAIL ARCH BEN IRMA",
-      "validation_public_key" : "n9Mxf6qD4J55XeLSCEpqaePW4GjoCR5U1ZeGZGJUCNe3bQa4yQbG",
-      "validation_seed" : "ssZkdwURFMBXenJPbrpE14b6noJSu"
-   }
-}
-
-
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
validation_keyStringThe secret key for these validation credentials, in RFC-1751 format.
validation_public_keyStringThe public key for these validation credentials, in Ripple's base58 encoded string format.
validation_seedStringThe secret key for these validation credentials, in Ripple's base58 encoded string format.
-

Possible Errors

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

validation_seed

-

[Source]

-

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

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-    "id": "set_seed_1",
-    "command": "validation_seed",
-    "secret": "BAWL MAN JADE MOON DOVE GEM SON NOW HAD ADEN GLOW TIRE"
-}
-
- -
#Syntax: validation_seed [secret]
-rippled validation_seed 'BAWL MAN JADE MOON DOVE GEM SON NOW HAD ADEN GLOW TIRE'
-
-
-

The request includes the following parameters:

- - - - - - - - - - - - - - - -
FieldTypeDescription
secretString(Optional) If present, use this value as the secret value for the validating key pair. Valid formats include base58, RFC-1751, or as a passphrase. If omitted, disables proposing validations to the network.
-

Response Format

-

An example of a successful response:

-
- -
200 OK
-{
-   "result" : {
-      "status" : "success",
-      "validation_key" : "BAWL MAN JADE MOON DOVE GEM SON NOW HAD ADEN GLOW TIRE",
-      "validation_public_key" : "n9Jx6RS6zSgqsgnuWJifNA9EqgjTKAywqYNReK5NRd1yLBbfC3ng",
-      "validation_seed" : "snjJkyBGogTem5dFGbcRaThKq2Rt3"
-   }
-}
-
- -
Loading: "/etc/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "status" : "success",
-      "validation_key" : "BAWL MAN JADE MOON DOVE GEM SON NOW HAD ADEN GLOW TIRE",
-      "validation_public_key" : "n9Jx6RS6zSgqsgnuWJifNA9EqgjTKAywqYNReK5NRd1yLBbfC3ng",
-      "validation_seed" : "snjJkyBGogTem5dFGbcRaThKq2Rt3"
-   }
-}
-
-
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
validation_keyString(Omitted if proposing disabled) The secret key for these validation credentials, in RFC-1751 format.
validation_public_keyString(Omitted if proposing disabled) The public key for these validation credentials, in Ripple's base58 encoded string format.
validation_seedString(Omitted if proposing disabled) The secret key for these validation credentials, in Ripple's base58 encoded string format.
-

Possible Errors

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

peers

-

[Source]

-

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

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-    "id": 2,
-    "command": "peers"
-}
-
- -
rippled peers
-
-
-

The request includes no additional parameters.

-

Response Format

-

An example of a successful response:

-
- -
{
-  "id": 2,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "cluster": {},
-    "peers": [
-      {
-        "address": "184.172.237.226:51235",
-        "complete_ledgers": "14534883 - 18828973",
-        "latency": 117,
-        "ledger": "50A2577CE6EB8A92847C443BDA45F5C5F0A22B9C6F4B47DBA0C12BDA75001D01",
-        "load": 54,
-        "public_key": "n9KNYm52mgcUQ7R2RA4kyw9Nk1yc6S35PaiuyqjYsy6UjhCXpw12",
-        "uptime": 55036,
-        "version": "rippled-0.30.0-hf1"
-      },
-      {
-        "address": "54.186.248.91:51235",
-        "complete_ledgers": "18827949 - 18828973",
-        "latency": 91,
-        "ledger": "50A2577CE6EB8A92847C443BDA45F5C5F0A22B9C6F4B47DBA0C12BDA75001D01",
-        "load": 62,
-        "public_key": "n9MT5EjnV912KGuBUqPs4tpdhzMPGcnDBrTuWkD9sWQHJ1kDcUcz",
-        "uptime": 83814,
-        "version": "rippled-0.30.1"
-      },
-      {
-        "address": "54.84.21.230:51235",
-        "complete_ledgers": "18827949 - 18828973",
-        "latency": 202,
-        "ledger": "50A2577CE6EB8A92847C443BDA45F5C5F0A22B9C6F4B47DBA0C12BDA75001D01",
-        "load": 60,
-        "public_key": "n9KJb7NMxGySRcjCqh69xEPMUhwJx22qntYYXsnUqYgjsJhNoW7g",
-        "uptime": 99625,
-        "version": "rippled-0.30.1"
-      },
-      {
-        "address": "72.251.233.162:51235",
-        "complete_ledgers": "18827949 - 18828973",
-        "latency": 36,
-        "ledger": "50A2577CE6EB8A92847C443BDA45F5C5F0A22B9C6F4B47DBA0C12BDA75001D01",
-        "load": 66,
-        "public_key": "n9M8RSk6hrvXZKFQ6CxPbJsjt73xW1xsnjn7G69VAMbE2j4sBQNQ",
-        "uptime": 99619,
-        "version": "rippled-0.30.1"
-      },
-      {
-        "address": "162.217.98.136:51235",
-        "complete_ledgers": "32570 - 18828973",
-        "latency": 118,
-        "ledger": "50A2577CE6EB8A92847C443BDA45F5C5F0A22B9C6F4B47DBA0C12BDA75001D01",
-        "load": 69,
-        "public_key": "n944PcXEoZaiEHnwFD92xA4bxsS7jjYb27WcdDQwkHYyk1MWTEsX",
-        "uptime": 99625,
-        "version": "rippled-0.30.1"
-      },
-      {
-        "address": "72.251.233.163:51235",
-        "complete_ledgers": "18827949 - 18828973",
-        "latency": 51,
-        "ledger": "50A2577CE6EB8A92847C443BDA45F5C5F0A22B9C6F4B47DBA0C12BDA75001D01",
-        "load": 61,
-        "public_key": "n94ne2Z5dX8qcJNa8cPtAbtn21gEaCoEduS8TwdGAhi1iLfCUMDm",
-        "uptime": 99625,
-        "version": "rippled-0.30.1"
-      },
-      {
-        "address": "54.186.73.52:51235",
-        "complete_ledgers": "18827949 - 18828973",
-        "latency": 72,
-        "ledger": "50A2577CE6EB8A92847C443BDA45F5C5F0A22B9C6F4B47DBA0C12BDA75001D01",
-        "load": 60,
-        "public_key": "n9JySgyBVcQKvyDoeRKg7s2Mm6ZcFHk22vUZb3o1HSosWxcj9xPt",
-        "uptime": 99625,
-        "version": "rippled-0.30.1"
-      },
-      {
-        "address": "72.251.233.165:51235",
-        "complete_ledgers": "18827949 - 18828973",
-        "latency": 40,
-        "ledger": "50A2577CE6EB8A92847C443BDA45F5C5F0A22B9C6F4B47DBA0C12BDA75001D01",
-        "load": 63,
-        "public_key": "n9M77Uc9CSaSFZqt5V7sxPR4kFwbha7hwUFBD5v5kZt2SQjBeoDs",
-        "uptime": 99625,
-        "version": "rippled-0.30.1"
-      },
-      {
-        "address": "72.251.232.173:51235",
-        "complete_ledgers": "32570 - 18828973",
-        "latency": 40,
-        "ledger": "50A2577CE6EB8A92847C443BDA45F5C5F0A22B9C6F4B47DBA0C12BDA75001D01",
-        "load": 71,
-        "public_key": "n9JveA1hHDGjZECaYC7KM4JP8NXXzNXAxixbzcLTGnrsFZsA9AD1",
-        "uptime": 99625,
-        "version": "rippled-0.31.0-b6"
-      },
-      {
-        "address": "98.167.120.212:51235",
-        "complete_ledgers": "18828845 - 18828973",
-        "latency": 99,
-        "ledger": "50A2577CE6EB8A92847C443BDA45F5C5F0A22B9C6F4B47DBA0C12BDA75001D01",
-        "load": 60,
-        "public_key": "n9LDBRoqPYY7RdkNXbX1dqZXVtUKcSqzs2CZPhTH7ymA9X7Xzmpj",
-        "uptime": 99625,
-        "version": "rippled-0.30.1-rc4"
-      }
-    ]
-  }
-}
-
- -
{
-   "result" : {
-      "cluster" : {},
-      "peers" : [
-         {
-            "address" : "184.172.237.226:51235",
-            "complete_ledgers" : "14535005 - 18828957",
-            "latency" : 114,
-            "ledger" : "80FCB89BC5B90D2B9C2CE33786738809796F04FB9CB1E5EEE768DD9A9C399FB0",
-            "load" : 47,
-            "public_key" : "n9KNYm52mgcUQ7R2RA4kyw9Nk1yc6S35PaiuyqjYsy6UjhCXpw12",
-            "uptime" : 54976,
-            "version" : "rippled-0.30.0-hf1"
-         },
-         {
-            "address" : "54.186.248.91:51235",
-            "complete_ledgers" : "18827934 - 18828958",
-            "latency" : 68,
-            "ledger" : "9447480E351221123B1A454356435A66C188D9794B0197A060637E19F074B421",
-            "load" : 56,
-            "public_key" : "n9MT5EjnV912KGuBUqPs4tpdhzMPGcnDBrTuWkD9sWQHJ1kDcUcz",
-            "uptime" : 83754,
-            "version" : "rippled-0.30.1"
-         },
-         {
-            "address" : "54.84.21.230:51235",
-            "complete_ledgers" : "18827934 - 18828958",
-            "latency" : 135,
-            "ledger" : "9447480E351221123B1A454356435A66C188D9794B0197A060637E19F074B421",
-            "load" : 54,
-            "public_key" : "n9KJb7NMxGySRcjCqh69xEPMUhwJx22qntYYXsnUqYgjsJhNoW7g",
-            "uptime" : 99565,
-            "version" : "rippled-0.30.1"
-         },
-         {
-            "address" : "72.251.233.162:51235",
-            "complete_ledgers" : "18827934 - 18828958",
-            "latency" : 24,
-            "ledger" : "9447480E351221123B1A454356435A66C188D9794B0197A060637E19F074B421",
-            "load" : 61,
-            "public_key" : "n9M8RSk6hrvXZKFQ6CxPbJsjt73xW1xsnjn7G69VAMbE2j4sBQNQ",
-            "uptime" : 99560,
-            "version" : "rippled-0.30.1"
-         },
-         {
-            "address" : "162.217.98.136:51235",
-            "complete_ledgers" : "32570 - 18828958",
-            "latency" : 88,
-            "ledger" : "9447480E351221123B1A454356435A66C188D9794B0197A060637E19F074B421",
-            "load" : 55,
-            "public_key" : "n944PcXEoZaiEHnwFD92xA4bxsS7jjYb27WcdDQwkHYyk1MWTEsX",
-            "uptime" : 99566,
-            "version" : "rippled-0.30.1"
-         },
-         {
-            "address" : "72.251.233.163:51235",
-            "complete_ledgers" : "18827934 - 18828958",
-            "latency" : 24,
-            "ledger" : "9447480E351221123B1A454356435A66C188D9794B0197A060637E19F074B421",
-            "load" : 56,
-            "public_key" : "n94ne2Z5dX8qcJNa8cPtAbtn21gEaCoEduS8TwdGAhi1iLfCUMDm",
-            "uptime" : 99566,
-            "version" : "rippled-0.30.1"
-         },
-         {
-            "address" : "54.186.73.52:51235",
-            "complete_ledgers" : "18827934 - 18828958",
-            "latency" : 51,
-            "ledger" : "9447480E351221123B1A454356435A66C188D9794B0197A060637E19F074B421",
-            "load" : 56,
-            "public_key" : "n9JySgyBVcQKvyDoeRKg7s2Mm6ZcFHk22vUZb3o1HSosWxcj9xPt",
-            "uptime" : 99566,
-            "version" : "rippled-0.30.1"
-         },
-         {
-            "address" : "72.251.233.165:51235",
-            "complete_ledgers" : "18827934 - 18828958",
-            "latency" : 25,
-            "ledger" : "9447480E351221123B1A454356435A66C188D9794B0197A060637E19F074B421",
-            "load" : 56,
-            "public_key" : "n9M77Uc9CSaSFZqt5V7sxPR4kFwbha7hwUFBD5v5kZt2SQjBeoDs",
-            "uptime" : 99566,
-            "version" : "rippled-0.30.1"
-         },
-         {
-            "address" : "72.251.232.173:51235",
-            "complete_ledgers" : "32570 - 18828958",
-            "latency" : 24,
-            "ledger" : "9447480E351221123B1A454356435A66C188D9794B0197A060637E19F074B421",
-            "load" : 81,
-            "public_key" : "n9JveA1hHDGjZECaYC7KM4JP8NXXzNXAxixbzcLTGnrsFZsA9AD1",
-            "uptime" : 99566,
-            "version" : "rippled-0.31.0-b6"
-         },
-         {
-            "address" : "98.167.120.212:51235",
-            "complete_ledgers" : "18828830 - 18828957",
-            "latency" : 137,
-            "ledger" : "9447480E351221123B1A454356435A66C188D9794B0197A060637E19F074B421",
-            "load" : 54,
-            "public_key" : "n9LDBRoqPYY7RdkNXbX1dqZXVtUKcSqzs2CZPhTH7ymA9X7Xzmpj",
-            "uptime" : 99566,
-            "version" : "rippled-0.30.1-rc4"
-         }
-      ],
-      "status" : "success"
-   }
-}
-
- -
Loading: "/etc/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "cluster" : {},
-      "peers" : [
-         {
-            "address" : "72.251.232.173:51235",
-            "complete_ledgers" : "32570 - 18851276",
-            "latency" : 22,
-            "ledger" : "592C723DDBB1C5119F0D8288894060C83C8C2975A061D7C9971427D6798098F5",
-            "load" : 20,
-            "public_key" : "n9JveA1hHDGjZECaYC7KM4JP8NXXzNXAxixbzcLTGnrsFZsA9AD1",
-            "uptime" : 26,
-            "version" : "rippled-0.31.0-b6"
-         },
-         {
-            "address" : "169.53.155.36:51235",
-            "complete_ledgers" : "12920801 - 18851275",
-            "latency" : 127,
-            "load" : 16,
-            "public_key" : "n9L42gouyppsmsMXXUdByXnVDUZv1eu6KLZUWUkNHsukzv3pr7po",
-            "uptime" : 18,
-            "version" : "rippled-0.30.0-hf1"
-         },
-         {
-            "address" : "169.53.155.44:51235",
-            "complete_ledgers" : "12920779 - 18851276",
-            "latency" : 20,
-            "ledger" : "592C723DDBB1C5119F0D8288894060C83C8C2975A061D7C9971427D6798098F5",
-            "load" : 49,
-            "public_key" : "n94BpoEqEf1PxpAv3Bmyy2WoKHyeMpHPH4tcj6P9NW98zdzEyRhi",
-            "uptime" : 50,
-            "version" : "rippled-0.30.0-hf1"
-         },
-         {
-            "address" : "192.170.145.77:51235",
-            "complete_ledgers" : "32570 - 18851277",
-            "latency" : 145,
-            "ledger" : "592C723DDBB1C5119F0D8288894060C83C8C2975A061D7C9971427D6798098F5",
-            "load" : 29,
-            "public_key" : "n9LwcmtjDAJQz4u8DZCMGQ9GXHuMEV4Cf8KpPL9NgqAV2puxdYc2",
-            "uptime" : 51,
-            "version" : "rippled-0.30.1"
-         },
-         {
-            "address" : "162.217.98.136:51235",
-            "complete_ledgers" : "32570 - 18851277",
-            "latency" : 83,
-            "ledger" : "592C723DDBB1C5119F0D8288894060C83C8C2975A061D7C9971427D6798098F5",
-            "load" : 30,
-            "public_key" : "n944PcXEoZaiEHnwFD92xA4bxsS7jjYb27WcdDQwkHYyk1MWTEsX",
-            "uptime" : 50,
-            "version" : "rippled-0.30.1"
-         },
-         {
-            "address" : "184.172.237.241:51235",
-            "complete_ledgers" : "14153089 - 18851277",
-            "latency" : 104,
-            "ledger" : "592C723DDBB1C5119F0D8288894060C83C8C2975A061D7C9971427D6798098F5",
-            "load" : 29,
-            "public_key" : "n9L3LdCTVYUhCKtQtxiHrQ5ocNXVqZFiEJpF5pX9DXahYLrvi5R7",
-            "uptime" : 51,
-            "version" : "rippled-0.30.0-hf1"
-         },
-         {
-            "address" : "99.110.49.91:51301",
-            "complete_ledgers" : "32570 - 18851277",
-            "latency" : 152,
-            "ledger" : "592C723DDBB1C5119F0D8288894060C83C8C2975A061D7C9971427D6798098F5",
-            "load" : 55,
-            "public_key" : "n9LGv3xKVqhxq6vcTfmJZhxyhjywsZbvJvpFbZRXzzz5uQ64xTLy",
-            "uptime" : 51,
-            "version" : "rippled-0.31.0-b6"
-         },
-         {
-            "address" : "169.53.155.45:51235",
-            "complete_ledgers" : "12920779 - 18851277",
-            "latency" : 15,
-            "ledger" : "592C723DDBB1C5119F0D8288894060C83C8C2975A061D7C9971427D6798098F5",
-            "load" : 30,
-            "public_key" : "n9MRiHyMk43YpqATWeT8Zyu4HJq1btb5oNKmnHTkLJKQg9LQQq3v",
-            "uptime" : 51,
-            "version" : "rippled-0.30.0-hf1"
-         },
-         {
-            "address" : "54.186.248.91:51235",
-            "complete_ledgers" : "18850253 - 18851277",
-            "latency" : 63,
-            "ledger" : "592C723DDBB1C5119F0D8288894060C83C8C2975A061D7C9971427D6798098F5",
-            "load" : 36,
-            "public_key" : "n9MT5EjnV912KGuBUqPs4tpdhzMPGcnDBrTuWkD9sWQHJ1kDcUcz",
-            "uptime" : 51,
-            "version" : "rippled-0.30.1"
-         }
-      ],
-      "status" : "success"
-   }
-}
-
-
-
-

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

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
clusterObjectSummary of other rippled servers in the same cluster, if configured as a cluster. New in: rippled 0.30.1
peersArrayArray of peer objects.
-

Each field of the cluster object is the public key of that rippled server's identifying keypair. (This is the same value that that server returns as pubkey_node in the server_info command.) The contents of that field are an object with the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
tagStringThe display name for this cluster member as defined in the config file.
feeNumber(May be omitted) The load multiplier this cluster member is applying to the transaction cost
ageNumberThe number of seconds since the last cluster report from this cluster member.
-

Each member of the peers array is a peer object with the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
addressStringThe IP address and port where this peer is connected
clusterBoolean(May be omitted) If true, the current server and the peer server are part of the same rippled cluster.
nameString(May be omitted) If the peer is part of the same cluster, this is the display name for that node as defined in the config file.
complete_ledgersStringRange expression indicating the sequence numbers of the ledger versions the peer rippled has available
inboundBoolean(May be omitted) If true, the peer is connecting to the local server.
latencyNumberThe network latency to the peer (in milliseconds)
ledgerStringThe hash of the peer's most recently closed ledger
loadNumberA measure of the amount of load the peer server is putting on the local server. Larger numbers indicate more load. (The units by which load is measured are not formally defined.)
protocolString(May be omitted) The protocol version that the peer is using, if not the same as the local server.
public_keyString(May be omitted) A public key that can be used to verify the integrity of the peer's messages. This is not the same key that is used for validations, but it follows the same format.
sanityString(May be omitted) Whether this peer is following the same rules and ledger sequence as the current server. A value of insane probably indicates that the peer is part of a parallel network. The value unknown indicates that the current server is unsure whether the peer is compatible.
statusString(May be omitted) The most recent status message from the peer. Could be connecting, connected, monitoring, validating, or shutting.
uptimeNumberThe number of seconds that your rippled server has been continuously connected to this peer. New in: rippled 0.30.1
versionstring(May be omitted) The rippled version number of the peer server
-

Possible Errors

- -

print

-

[Source]

-

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

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-    "id": "print_req_1",
-    "command": "print"
-}
-
- -
rippled print
-
-
-

The request includes no parameters.

-

Response Format

-

An example of a successful response:

-
- -
Loading: "/etc/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "app" : {
-         "ledgercleaner" : {
-            "status" : "idle"
-         },
-         "peers" : {
-            "peerfinder" : {
-               "bootcache" : {
-                  "entries" : 109
-               },
-               "config" : {
-                  "auto_connect" : "true",
-                  "features" : "",
-                  "max_peers" : 21,
-                  "out_peers" : 10,
-                  "port" : 51235,
-                  "want_incoming" : "true"
-               },
-               "counts" : {
-                  "accept" : 0,
-                  "close" : 0,
-                  "cluster" : "0",
-                  "connect" : 0,
-                  "fixed" : "0",
-                  "in" : "0/11",
-                  "out" : "10/10",
-                  "total" : "10"
-               },
-               "fixed" : 0,
-               "livecache" : {
-                  "entries" : [
-                     {
-                        "address" : "23.239.3.247:51235",
-                        "expires" : "30000000000 nanoseconds",
-                        "hops" : 2
-                     },
-                     {
-                        "address" : "192.170.145.88:51235",
-                        "expires" : "30000000000 nanoseconds",
-                        "hops" : 1
-                     },
-                     {
-                        "address" : "198.204.238.130:51235",
-                        "expires" : "26000024558 nanoseconds",
-                        "hops" : 1
-                     },
-                     {
-                        "address" : "203.127.12.115:51235",
-                        "expires" : "26000024558 nanoseconds",
-                        "hops" : 2
-                     },
-                     {
-                        "address" : "212.83.147.67:51235",
-                        "expires" : "26000024558 nanoseconds",
-                        "hops" : 2
-                     }
-                  ],
-                  "hist" : "0, 10, 74, 10, 0, 0, 0, 0",
-                  "size" : "94"
-               },
-               "peers" : [
-                  {
-                     "local_address" : "10.1.10.78:48923",
-                     "remote_address" : "52.24.43.83:51235",
-                     "state" : "active"
-                  },
-                  {
-                     "local_address" : "10.1.10.78:50004",
-                     "remote_address" : "52.26.205.197:51235",
-                     "state" : "active"
-                  },
-                  {
-                     "local_address" : "10.1.10.78:37019",
-                     "remote_address" : "168.1.60.132:51235",
-                     "state" : "active"
-                  },
-                  {
-                     "local_address" : "10.1.10.78:38775",
-                     "remote_address" : "192.170.145.88:51235",
-                     "state" : "active"
-                  },
-                  {
-                     "local_address" : "10.1.10.78:34793",
-                     "remote_address" : "198.204.238.130:51235",
-                     "state" : "active"
-                  }
-               ]
-            }
-         },
-         "resource" : {
-            "admin" : [
-               {
-                  "balance" : 0,
-                  "count" : 1,
-                  "name" : "\"127.0.0.1\""
-               }
-            ],
-            "inactive" : [],
-            "inbound" : [],
-            "outbound" : [
-               {
-                  "balance" : 23,
-                  "count" : 1,
-                  "name" : "93.190.138.234:51235"
-               },
-               {
-                  "balance" : 35,
-                  "count" : 1,
-                  "name" : "198.204.238.130:51235"
-               },
-               {
-                  "balance" : 31,
-                  "count" : 1,
-                  "name" : "52.26.205.197:51235"
-               },
-               {
-                  "balance" : 32,
-                  "count" : 1,
-                  "name" : "54.186.73.52:51235"
-               },
-               {
-                  "balance" : 15,
-                  "count" : 1,
-                  "name" : "72.251.233.164:51235"
-               }
-            ]
-         },
-         "server" : {
-            "active" : "2",
-            "hist" : "16",
-            "history" : [
-               {
-                  "bytes_in" : "214",
-                  "bytes_out" : "11688",
-                  "elapsed" : "0 seconds",
-                  "id" : "16",
-                  "requests" : 1,
-                  "when" : "2015-Jun-16 16:33:50"
-               },
-               {
-                  "bytes_in" : "214",
-                  "bytes_out" : "11431",
-                  "elapsed" : "0 seconds",
-                  "id" : "15",
-                  "requests" : 1,
-                  "when" : "2015-Jun-16 16:11:59"
-               },
-               {
-                  "bytes_in" : "227",
-                  "bytes_out" : "337",
-                  "elapsed" : "0 seconds",
-                  "id" : "3",
-                  "requests" : 1,
-                  "when" : "2015-Jun-16 14:57:23"
-               },
-               {
-                  "bytes_in" : "214",
-                  "bytes_out" : "2917",
-                  "elapsed" : "0 seconds",
-                  "id" : "2",
-                  "requests" : 1,
-                  "when" : "2015-Jun-16 12:39:29"
-               },
-               {
-                  "bytes_in" : "220",
-                  "bytes_out" : "1426",
-                  "elapsed" : "0 seconds",
-                  "id" : "1",
-                  "requests" : 1,
-                  "when" : "2015-Jun-16 12:39:13"
-               }
-            ]
-         },
-         "validators" : {}
-      },
-      "status" : "success"
-   }
-}
-
-
-
-

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

-

Possible Errors

- -

Convenience Functions

-

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

-

ping

-

[Source]

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-    "id": 1,
-    "command": "ping"
-}
-
- -
{
-    "method": "ping",
-    "params": [
-        {}
-    ]
-}
-
- -
#Syntax: ping
-rippled ping
-
-
-

Try it!

-

The request includes no parameters.

-

Response Format

-

An example of a successful response:

-
- -
{
-    "id": 1,
-    "result": {},
-    "status": "success",
-    "type": "response"
-}
-
- -
200 OK
-{
-    "result": {
-        "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.

-

Possible Errors

- -

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,
-    "command": "random"
-}
-
- -
{
-    "method": "random",
-    "params": [
-        {}
-    ]
-}
-
- -
#Syntax: random
-rippled random
-
-
-

The request includes no parameters.

-

Response Format

-

An example of a successful response:

-
- -
{
-    "id": 1,
-    "result": {
-        "random": "8ED765AEBBD6767603C2C9375B2679AEC76E6A8133EF59F04F9FC1AAA70E41AF"
-    },
-    "status": "success",
-    "type": "response"
-}
-
- -
200 OK
-{
-    "result": {
-        "random": "4E57146AA47BC6E88FDFE8BAA235B900126C916B6CC521550996F590487B837A",
-        "status": "success"
-    }
-}
-
-
-

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

- - - - - - - - - - - - - - - -
FieldTypeDescription
randomStringRandom 256-bit hex value.
-

Possible Errors

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

json

-

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

-

Request Format

-

An example of the request format:

-
- -
# Syntax: json method json_stanza
-rippled -q json ledger_closed '{}'
-
-
-

Response Format

-

An example of a successful response:

-
- -
{
-   "result" : {
-      "ledger_hash" : "8047C3ECF1FA66326C1E57694F6814A1C32867C04D3D68A851367EE2F89BBEF3",
-      "ledger_index" : 390308,
-      "status" : "success"
-   }
-}
-
-
-

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

-

connect

-

[Source]

-

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

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-    "command": "connect",
-    "ip": "192.170.145.88",
-    "port": 51235
-}
-
- -
{
-    "method": "connect",
-    "params": [
-        {
-            "ip": "192.170.145.88",
-            "port": 51235
-        }
-    ]
-}
-
- -
#Syntax: connect ip [port]
-rippled connect 192.170.145.88 51235
-
-
-

The request includes the following parameters:

- - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
ipStringIP address of the server to connect to
portNumber(Optional) Port number to use when connecting. Defaults to 6561.
-

Response Format

-

An example of a successful response:

-
- -
{
-   "result" : {
-      "message" : "connecting",
-      "status" : "success"
-   }
-}
-
- -
Loading: "/etc/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "message" : "connecting",
-      "status" : "success"
-   }
-}
-
-
-

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

- - - - - - - - - - - - - - - -
FieldTypeDescription
messageStringThe value connecting, if the command was successful.
-

Possible Errors

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

stop

-

[Source]

-

Gracefully shuts down the server.

-

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

-

Request Format

-

An example of the request format:

-
- -
{
-    "id": 0,
-    "command": "stop"
-}
-
- -
{
-    "method": "stop",
-    "params": [
-        {}
-    ]
-}
-
- -
rippled stop
-
-
-

The request includes no parameters.

-

Response Format

-

An example of a successful response:

-
- -
{
-   "result" : {
-      "message" : "ripple server stopping",
-      "status" : "success"
-   }
-}
-
- -
Loading: "/etc/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "message" : "ripple server stopping",
-      "status" : "success"
-   }
-}
-
-
-

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

- - - - - - - - - - - - - - - -
FieldTypeDescription
messageStringripple server stopping on success.
-

Possible Errors

- -

Peer Protocol

-

Servers in the XRP Ledger communicate to each other using the XRP Ledger peer protocol, also known as RTXP. Peer servers connect via HTTPS and then perform an HTTP upgrade to RTXP. (For more information, see the Overlay Network article in the rippled repository.)

-

Configuring the Peer Protocol

-

In order to participate in the XRP Ledger, rippled servers connects to arbitrary peers using the peer protocol. (All such peers are treated as untrusted, unless they are clustered with the current server.)

-

Ideally, the server should be able to send and receive connections on the peer port. You should forward the port used for the peer protocol through your firewall to the rippled server. The default rippled configuration file listens for incoming peer protocol connections on port 51235 on all network interfaces. You can change the port used by editing the appropriate stanza in your rippled.cfg file.

-

Example:

-
[port_peer]
-port = 51235
-ip = 0.0.0.0
-protocol = peer
-
-

Peer Crawler

-

The Peer Crawler asks a rippled server to report information about the other rippled servers it is connected to as peers. The peers command in the WebSocket and JSON-RPC APIs also returns a similar, more comprehensive set of information, but requires administrative access to the server. The Peer Crawler response is available to other servers on a non-privileged basis through the Peer Protocol (RTXP) port.

-

Request Format

-

To request the Peer Crawler information, make the following HTTP request:

-
    -
  • Protocol: https
    • -
  • HTTP Method: GET
    • -
  • Host: (any rippled server, by hostname or IP address)
    • -
  • Port: (port number where the rippled server uses the Peer Protocol, typically 51235)
    • -
  • Path: /crawl
    • -
  • Notes: Most rippled servers use a self-signed certificate to respond to the request. By default, most tools (including web browsers) flag or block such responses for being untrusted. You must ignore the certificate checking (for example, if using cURL, add the --insecure flag) to display a response from those servers.
    • -
-

Response Format

-

The response has the status code 200 OK and a JSON object in the message body.

-

The JSON object has the following fields:

- - - - - - - - - - - - - - - -
FieldValueDescription
overlay.activeArrayArray of Peer Objects, where each member is a peer that is connected to this server.
-

Each member of the active array is a Peer Object with the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
ipString (IPv4 Address)The IP address of this connected peer.
portString (Number)The port number on the peer server that serves RTXP. Typically 51235.
public_keyString (Base-64 Encoded)The public key of the ECDSA key pair used by this peer to sign RTXP messages. (This is the same data as the pubkey_node reported in the peer server's server_info command.)
typeStringThe value in or out, indicating whether the TCP connection to the peer is incoming or outgoing.
uptimeNumberThe number of seconds the server has been has been connected to this peer.
versionStringThe rippled version number the peer reports to be using.
-

Example

-

Request:

-
- -
GET https://s1.ripple.com:51235/crawl
-
- -
curl -k https://s1.ripple.com:51235/crawl
-
-
-

Response:

-
200 OK
-{
-    "overlay": {
-        "active": [{
-            "ip": "208.43.252.243",
-            "port": "51235",
-            "public_key": "A2GayQNaj7qbqLFiCFW2UXtAnEPghP/KWVqix2gUa6dM",
-            "type": "out",
-            "uptime": 107926,
-            "version": "rippled-0.31.0-rc1"
-        }, {
-            "ip": "184.172.237.226",
-            "port": "51235",
-            "public_key": "Asv/wKq/dqMWbP2M4eR+QvkuojYMLRXhKhIPnW40bsaF",
-            "type": "out",
-            "uptime": 247376,
-            "version": "rippled-0.31.0-rc1"
-        }, {
-            "ip": "54.186.73.52",
-            "port": "51235",
-            "public_key": "AjikFnq0P2XybCyREr2KPiqXqJteqwPwVRVbVK+93+3o",
-            "type": "out",
-            "uptime": 328776,
-            "version": "rippled-0.31.0-rc1"
-        }, {
-            "ip": "169.53.155.59",
-            "port": "51235",
-            "public_key": "AyIcVhAhOGnP0vtfCt+HKUrx9B2fDvP/4XUkOtVQ37g/",
-            "type": "out",
-            "uptime": 328776,
-            "version": "rippled-0.31.1"
-        }, {
-            "ip": "169.53.155.44",
-            "port": "51235",
-            "public_key": "AuVZszWXgMgM8YuTVhQsGE9OciEeBD8aMVe1mFid3n63",
-            "type": "out",
-            "uptime": 328776,
-            "version": "rippled-0.32.0-b12"
-        }, {
-            "ip": "184.173.45.39",
-            "port": "51235",
-            "public_key": "Ao2GbGbp2QYQ2B4S9ckCtON7CsZdXqdK5Yon4x7qmWFm",
-            "type": "out",
-            "uptime": 63336,
-            "version": "rippled-0.31.0-rc1"
-        }, {
-            "ip": "169.53.155.34",
-            "port": "51235",
-            "public_key": "A3inNJsIQzO7z7SS7uB9DyvN0wsiS9it/RGY/kNx6KEG",
-            "type": "out",
-            "uptime": 328776,
-            "version": "rippled-0.31.0-rc1"
-        }, {
-            "ip": "169.53.155.45",
-            "port": "51235",
-            "public_key": "AglUUjwXTC2kUlK41WjDs2eAVN0SnlMpzYA9lEgB0UGP",
-            "type": "out",
-            "uptime": 65443,
-            "version": "rippled-0.31.0-rc1"
-        }, {
-            "ip": "99.110.49.91",
-            "port": "51301",
-            "public_key": "AuQDH0o+4fpl2n+pR5U0Y4FTj0oGr4iEKe0MObPcSYj9",
-            "type": "out",
-            "uptime": 328776,
-            "version": "rippled-0.32.0-b9"
-        }, {
-            "ip": "169.53.155.36",
-            "port": "51235",
-            "public_key": "AsR4xub7MLg2Zl5Fwd/n7dTz7mhbBoSyCc/v9bnubrVy",
-            "type": "out",
-            "uptime": 328776,
-            "version": "rippled-0.31.0-rc1"
-        }]
-    }
-}
-
-

Concealing Peer Information

-

You can use the [peer_private] stanza of the rippled config file to request that peer servers do not report your IP address in the Peer Crawler response. You cannot force peers you do not control to follow this request, if they run custom software. However, you can use this to hide the IP addresses of rippled servers you control that only connect to peers you control (using [ips_fixed] and a firewall). This can help to protect important validating servers.

-

Example:

-
# Configuration on a private server that only connects through
-# a second rippled server at IP address 10.1.10.55
-[ips_fixed]
-10.1.10.55
-
-[peer_private]
-1
-
- -
-
-
- - - - \ No newline at end of file diff --git a/reference-transaction-format.html b/reference-transaction-format.html deleted file mode 100644 index 30ca166937..0000000000 --- a/reference-transaction-format.html +++ /dev/null @@ -1,2673 +0,0 @@ - - - - - - - - Transaction Format - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

Transactions Overview

-

A Transaction is the only way to modify the XRP Ledger. Transactions are only valid if signed, submitted, and accepted into a validated ledger version following the consensus process. Some ledger rules also generate pseudo-transactions, which aren't signed or submitted, but still must be accepted by consensus. Transactions that fail are also included in ledgers because they modify balances of XRP to pay for the anti-spam transaction cost.

- -

Authorizing Transactions

-

In the decentralized XRP Ledger, a digital signature proves that a transaction is authorized to do a specific set of actions. Only signed transactions can be submitted to the network and included in a validated ledger. A signed transaction is immutable: its contents cannot change, and the signature is not valid for any other transaction.

-

A transaction can be authorized by any of the following types of signatures:

-
    -
  • A single signature from the master secret key that is mathematically associated with the sending address. You can disable or enable the master key using an AccountSet transaction.
    • -
  • A single signature that matches a regular key associated with the address. You can add, remove, or replace a regular key using a SetRegularKey transaction.
    • -
  • A multi-signature that matches a list of signers owned by the address. You can add, remove, or replace a list of signers using a SignerListSet transaction.
    • -
-

Any signature type can authorize any type of transaction, with the following exceptions:

- -

Signing and Submitting Transactions

-

Sending a transaction to the XRP Ledger involves several steps:

-
    -
  1. Create an unsigned transaction in JSON format.
    2. -
  2. Use one or more signatures to authorize the transaction.
    3. -
  3. Submit a transaction to a rippled server. If the transaction is properly formed, the server provisionally applies the transaction to its current version of the ledger and relays the transaction to other members of the peer-to-peer network.
    4. -
  4. The consensus process determines which provisional transactions get included in the next validated ledger.
    5. -
  5. The rippled servers apply those transactions to the previous ledger in a canonical order and share their results.
    6. -
  6. If enough trusted validators created the exact same ledger, that ledger is declared validated and the results of the transactions in that ledger are immutable.
    7. -
-

Unsigned Transaction Format

-

Here is an example of an unsigned Payment transaction in JSON:

-
{
-  "TransactionType" : "Payment",
-  "Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-  "Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-  "Amount" : {
-     "currency" : "USD",
-     "value" : "1",
-     "issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
-  },
-  "Fee": "10",
-  "Flags": 2147483648,
-  "Sequence": 2,
-}
-
-

The XRP Ledger only relays and executes a transaction if the transaction object has been authorized by the sending address (in the Account) field. For transactions authorized by only a single signature, you have two options:

-
    -
  1. Convert it to a binary blob and sign it offline. This is preferable, since it means that the account secret used for signing the transaction is never transmitted over any network connection.
      -
    • You can use RippleAPI for offline signing.
      • -
    -
    2. -
  2. Have a rippled server sign the transaction for you. The sign command takes a JSON-format transaction and secret and returns the signed binary transaction format ready for submission. (Transmitting your account secret is dangerous, so you should only do this from within a trusted and encrypted connection, or through a local connection, and only to a server you control.)
      -
    • As a shortcut, you can use the submit command with a tx_json object to sign and submit a transaction all at once. This is only recommended for testing and development purposes.
      • -
    -
    3. -
-

In either case, signing a transaction generates a binary blob that can be submitted to the network. This means using rippled's submit command. Here is an example of the same transaction, as a signed blob, being submitted with the WebSocket API:

-
{
-  "id": 2,
-  "command": "submit",
-  "tx_blob" : "120000240000000461D4838D7EA4C6800000000000000000000000000055534400000000004B4E9C06F24296074F7BC48F92A97916C6DC5EA968400000000000000F732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB74483046022100982064CDD3F052D22788DB30B52EEA8956A32A51375E72274E417328EBA31E480221008F522C9DB4B0F31E695AA013843958A10DE8F6BA7D6759BEE645F71A7EB240BE81144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143E9D4A2B8AA0780F682D136F7A56D6724EF53754"
-}
-
-

After a transaction has been submitted, you can check its status using the API, for example using the tx command.

-

Caution: The success of a transaction is not final unless the transaction appears in a validated ledger with the result code tesSUCCESS. See also: Finality of Results.

-

Example response from the tx command:

-
{
-  "id": 6,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-    "Amount": {
-      "currency": "USD",
-      "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-      "value": "1"
-    },
-    "Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-    "Fee": "10",
-    "Flags": 2147483648,
-    "Sequence": 2,
-    "SigningPubKey": "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB",
-    "TransactionType": "Payment",
-    "TxnSignature": "3045022100D64A32A506B86E880480CCB846EFA3F9665C9B11FDCA35D7124F53C486CC1D0402206EC8663308D91C928D1FDA498C3A2F8DD105211B9D90F4ECFD75172BAE733340",
-    "date": 455224610,
-    "hash": "33EA42FC7A06F062A7B843AF4DC7C0AB00D6644DFDF4C5D354A87C035813D321",
-    "inLedger": 7013674,
-    "ledger_index": 7013674,
-    "meta": {
-      "AffectedNodes": [
-        {
-          "ModifiedNode": {
-            "FinalFields": {
-              "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-              "Balance": "99999980",
-              "Flags": 0,
-              "OwnerCount": 0,
-              "Sequence": 3
-            },
-            "LedgerEntryType": "AccountRoot",
-            "LedgerIndex": "13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8",
-            "PreviousFields": {
-              "Balance": "99999990",
-              "Sequence": 2
-            },
-            "PreviousTxnID": "7BF105CFE4EFE78ADB63FE4E03A851440551FE189FD4B51CAAD9279C9F534F0E",
-            "PreviousTxnLgrSeq": 6979192
-          }
-        },
-        {
-          "ModifiedNode": {
-            "FinalFields": {
-              "Balance": {
-                "currency": "USD",
-                "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                "value": "2"
-              },
-              "Flags": 65536,
-              "HighLimit": {
-                "currency": "USD",
-                "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-                "value": "0"
-              },
-              "HighNode": "0000000000000000",
-              "LowLimit": {
-                "currency": "USD",
-                "issuer": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-                "value": "100"
-              },
-              "LowNode": "0000000000000000"
-            },
-            "LedgerEntryType": "RippleState",
-            "LedgerIndex": "96D2F43BA7AE7193EC59E5E7DDB26A9D786AB1F7C580E030E7D2FF5233DA01E9",
-            "PreviousFields": {
-              "Balance": {
-                "currency": "USD",
-                "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                "value": "1"
-              }
-            },
-            "PreviousTxnID": "7BF105CFE4EFE78ADB63FE4E03A851440551FE189FD4B51CAAD9279C9F534F0E",
-            "PreviousTxnLgrSeq": 6979192
-          }
-        }
-      ],
-      "TransactionIndex": 0,
-      "TransactionResult": "tesSUCCESS"
-    },
-    "validated": true
-  }
-}
-
-

Multi-Signing

-

Multi-signing in the XRP Ledger is the act of authorizing transactions for the XRP Ledger by using a combination of multiple secret keys. You can have any combination of authorization methods enabled for your address, including multi-signing, a master key, and a regular key. (The only requirement is that at least one method must be enabled.)

-

The SignerListSet transaction defines which addresses can authorize transactions from your address. You can include up to 8 addresses in a SignerList. You can control how many signatures are needed, in which combinations, by using the quorum and weight values of the SignerList.

-

To successfully submit a multi-signed transaction, you must do all of the following:

-
    -
  • The address sending the transaction (specified in the Account field) must own a SignerList in the ledger.
    • -
  • The transaction must include the SigningPubKey field as an empty string.
    • -
  • The transaction must include a Signers field containing an array of signatures.
    • -
  • The signatures present in the Signers array must match signers defined in the SignerList.
    • -
  • For the provided signatures, the total weight associated with those signers must be equal or greater than the quorum for the SignerList.
    • -
  • The transaction cost (specified in the Fee field) must be at least (N+1) times the normal transaction cost, where N is the number of signatures provided.
    • -
  • All fields of the transaction must be defined before collecting signatures. You cannot auto-fill any fields.
    • -
  • If presented in binary form, the Signers array must be sorted based on the numeric value of the signer addresses, with the lowest value first. (If submitted as JSON, the submit_multisigned command handles this automatically.)
    • -
-

For more information, see How to Multi-Sign.

-

Reliable Transaction Submission

-

Reliably submitting transactions is the process of achieving both of the following:

-
    -
  • Idempotency - A transaction should be processed once and only once, or not at all.
    • -
  • Verifiability - Applications can determine the final result of a transaction.
    • -
-

To have both qualities when submitting a transaction, an application should:

-
    -
  1. Construct and sign the transaction first, including a LastLedgerSequence parameter that gives the transaction a limited lifespan.
    2. -
  2. Persist details of the transaction before submitting.
    3. -
  3. Submit the transaction.
    4. -
  4. Confirm that the transaction was either included in a validated ledger, or that it has expired due to LastLedgerSequence.
    5. -
  5. If a transaction fails or expires, you can modify and resubmit it.
    6. -
-

Main article: Reliable Transaction Submission

-

Identifying Transactions

-

The "hash" is the unique value that identifies a particular transaction. The server provides the hash in the response when you submit the transaction; you can also look up a transaction in an account's transaction history with the account_tx command.

-

The transaction hash can be used as a "proof of payment" since anyone can look up the transaction by its hash to verify its final status.

-

Common Fields

-

Every transaction type has the same set of fundamental fields. Field names are case-sensitive. The common fields for all transactions are:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldJSON TypeInternal TypeDescription
AccountStringAccountThe unique address of the account that initiated the transaction.
AccountTxnIDStringHash256(Optional) Hash value identifying another transaction. This transaction is only valid if the sending account's previously-sent transaction matches the provided hash.
FeeStringAmount(Required, but auto-fillable) Integer amount of XRP, in drops, to be destroyed as a cost for distributing this transaction to the network.
FlagsUnsigned IntegerUInt32(Optional) Set of bit-flags for this transaction.
LastLedgerSequenceNumberUInt32(Optional, but strongly recommended) Highest ledger sequence number that a transaction can appear in.
MemosArray of ObjectsArray(Optional) Additional arbitrary information used to identify this transaction.
PreviousTxnIDStringHash256Removed in: rippled 0.28.0 Use AccountTxnID instead.
SequenceUnsigned IntegerUInt32(Required, but auto-fillable) The sequence number, relative to the initiating account, of this transaction. A transaction is only valid if the Sequence number is exactly 1 greater than the last-valided transaction from the same account.
SigningPubKeyStringPubKey(Automatically added when signing) Hex representation of the public key that corresponds to the private key used to sign this transaction. If an empty string, indicates a multi-signature is present in the Signers field instead.
SignersArrayArray(Optional) Array of objects that represent a multi-signature which authorizes this transaction.
SourceTagUnsigned IntegerUInt32(Optional) Arbitrary integer used to identify the reason for this payment, or a sender on whose behalf this transaction is made. Conventionally, a refund should specify the initial payment's SourceTag as the refund payment's DestinationTag.
TransactionTypeStringUInt16The type of transaction. Valid types include: Payment, OfferCreate, OfferCancel, TrustSet, AccountSet, SetRegularKey, SignerListSet, EscrowCreate, EscrowFinish, EscrowCancel, PaymentChannelCreate, PaymentChannelFund, and PaymentChannelClaim.
TxnSignatureStringVariableLength(Automatically added when signing) The signature that verifies this transaction as originating from the account it says it is from.
-

Auto-fillable Fields

-

Some fields can be automatically filled in before the transaction is signed, either by a rippled server or by the library used for offline signing. Both ripple-lib and rippled can automatically provide the following values:

-
    -
  • Fee - Automatically fill in the transaction cost based on the network. (Note: rippled's sign command supports limits on how high the filled-in-value is, using the fee_mult_max parameter.)
    • -
  • Sequence - Automatically use the next sequence number for the account sending the transaction.
    • -
-

For a production system, we recommend not leaving these fields to be filled by the server. For example, if transaction costs become high due to a temporary spike in network load, you may want to wait for the cost to decrease before sending some transactions, instead of paying the temporarily-high cost.

-

The Paths field of the Payment transaction type can also be automatically filled in.

-

Transaction Cost

-

To protect the XRP Ledger from being disrupted by spam and denial-of-service attacks, each transaction must destroy a small amount of XRP. This transaction cost is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network.

-

The Fee field specifies an amount, in drops of XRP, to destroy as the cost for relaying this transaction. If the transaction is included in a validated ledger (whether or not it achieves its intended purpose), then the amount of XRP specified in the Fee parameter is destroyed forever. You can look up the transaction cost in advance, or let rippled set it automatically when you sign a transaction.

-

Note: Multi-signed transactions require additional fees to relay to the network.

-

Canceling or Skipping a Transaction

-

An important and intentional feature of the XRP Ledger is that a transaction is final as soon as it has been incorporated in a validated ledger.

-

However, if a transaction has not yet been included in a validated ledger, you can effectively cancel it by rendering it invalid. Typically, this means sending another transaction with the same Sequence value from the same account. If you do not want the replacement transaction to do anything, send an AccountSet transaction with no options.

-

For example, if you try to submit 3 transactions with sequence numbers 11, 12, and 13, but transaction 11 gets lost somehow or does not have a high enough transaction cost to be propagated to the network, then you can cancel transaction 11 by submitting an AccountSet transaction with no options and sequence number 11. This does nothing (except destroying the transaction cost for the new transaction 11), but it allows transactions 12 and 13 to become valid.

-

This approach is preferable to renumbering and resubmitting transactions 12 and 13, because it prevents transactions from being effectively duplicated under different sequence numbers.

-

In this way, an AccountSet transaction with no options is the canonical "no-op" transaction.

-

LastLedgerSequence

-

We strongly recommend that you specify the LastLedgerSequence parameter on every transaction. Provide a value of about 3 higher than the most recent ledger index to ensure that your transaction is either validated or rejected within a matter of seconds.

-

Without the LastLedgerSequence parameter, a transaction can become stuck in an undesirable state where it is neither validated nor rejected for a long time. Specifically, if the load-based transaction cost of the network increases after you send a transaction, your transaction may not get propagated enough to be included in a validated ledger, but you would have to pay the (increased) transaction cost to send another transaction canceling it. Later, if the transaction cost decreases again, the transaction can become included in a future ledger. The LastLedgerSequence places a hard upper limit on how long the transaction can wait to be validated or rejected.

-

AccountTxnID

-

The AccountTxnID field lets you chain your transactions together, so that a current transaction is not valid unless the previous one (by Sequence Number) is also valid and matches the transaction you expected.

-

One situation in which this is useful is if you have a primary system for submitting transactions and a passive backup system. If the passive backup system becomes disconnected from the primary, but the primary is not fully dead, and they both begin operating at the same time, you could potentially have serious problems like some transactions sending twice and others not at all. Chaining your transactions together with AccountTxnID ensures that, even if both systems are active, only one of them can submit valid transactions at a time.

-

To use AccountTxnID, you must first set the asfAccountTxnID flag, so that the ledger keeps track of the ID for the account's previous transaction.

-

Memos

-

The Memos field includes arbitrary messaging data with the transaction. It is presented as an array of objects. Each object has only one field, Memo, which in turn contains another object with one or more of the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeInternal TypeDescription
MemoDataStringVariableLengthArbitrary hex value, conventionally containing the content of the memo.
MemoFormatStringVariableLengthHex value representing characters allowed in URLs. Conventionally containing information on how the memo is encoded, for example as a MIME type.
MemoTypeStringVariableLengthHex value representing characters allowed in URLs. Conventionally, a unique relation (according to RFC 5988) that defines the format of this memo.
-

The MemoType and MemoFormat fields should only consist of the following characters: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~:/?#[]@!$&'()*+,;=%

-

The Memos field is limited to no more than 1KB in size (when serialized in binary format).

-

Example of a transaction with a Memos field:

-
{
-    "TransactionType": "Payment",
-    "Account": "rMmTCjGFRWPz8S2zAUUoNVSQHxtRQD4eCx",
-    "Destination": "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV",
-    "Memos": [
-        {
-            "Memo": {
-                "MemoType": "687474703a2f2f6578616d706c652e636f6d2f6d656d6f2f67656e65726963",
-                "MemoData": "72656e74"
-            }
-        }
-    ],
-    "Amount": "1"
-}
-
-

Signers Field

-

The Signers field contains a multi-signature, which has signatures from up to 8 key pairs, that together should authorize the transaction. The Signers list is an array of objects, each with one field, Signer. The Signer field has the following nested fields:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeInternal TypeDescription
AccountStringAccountIDThe address associated with this signature, as it appears in the SignerList.
TxnSignatureStringBlobA signature for this transaction, verifiable using the SigningPubKey.
SigningPubKeyStringPubKeyThe public key used to create this signature.
-

The SigningPubKey must be a key that is associated with the Account address. If the referenced Account is a funded account in the ledger, then the SigningPubKey can be that account's current Regular Key if one is set. It could also be that account's Master Key, unless the lsfDisableMaster flag is enabled. If the referenced Account address is not a funded account in the ledger, then the SigningPubKey must be the master key associated with that address.

-

Because signature verification is a compute-intensive task, multi-signed transactions cost additional XRP to relay to the network. Each signature included in the multi-signature increases the transaction cost required for the transaction. For example, if the current minimum transaction cost to relay a transaction to the network is 10000 drops, then a multi-signed transaction with 3 entries in the Signers array would need a Fee value of at least 40000 drops to relay.

-

Flags

-

The Flags field can contain various options that affect how a transaction should behave. The options are represented as binary values that can be combined with bitwise-or operations to set multiple flags at once.

-

Most flags only have meaning for a specific transaction type. The same bitwise value may be reused for flags on different transaction types, so it is important to pay attention to the TransactionType field when setting and reading flags.

-

The only flag that applies globally to all transactions is as follows:

- - - - - - - - - - - - - - - - - -
Flag NameHex ValueDecimal ValueDescription
tfFullyCanonicalSig0x800000002147483648Require a fully-canonical signature, to protect a transaction from transaction malleability exploits.
-

Transaction Types

-

The type of a transaction (TransactionType field) is the most fundamental information about a transaction. This indicates what operations it can or is supposed to perform.

-

All transactions have certain fields in common:

- -

Each transaction type has additional fields relevant to the type of action it causes:

- -

Pseudo-Transactions that are not created and submitted in the usual way, but may be added to open ledgers according to ledger rules. They still must be approved by consensus to be included in a validated ledger. Pseudo-transactions have their own unique transaction types:

- -

AccountSet

-

[Source]

-

An AccountSet transaction modifies the properties of an account in the XRP Ledger.

-

Example AccountSet:

-
{
-    "TransactionType": "AccountSet",
-    "Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-    "Fee": "10000",
-    "Sequence": 5,
-    "Domain": "6D64756F31332E636F6D",
-    "SetFlag": 5,
-    "MessageKey": "rQD4SqHJtDxn5DDL7xNnojNa3vxS1Jx5gv"
-}
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldJSON TypeInternal TypeDescription
ClearFlagUnsigned IntegerUInt32(Optional) Unique identifier of a flag to disable for this account.
DomainStringVariableLength(Optional) The domain that owns this account, as a string of hex representing the ASCII for the domain in lowercase.
EmailHashStringHash128(Optional) Hash of an email address to be used for generating an avatar image. Conventionally, clients use Gravatar to display this image.
MessageKeyStringPubKey(Optional) Public key for sending encrypted messages to this account.
SetFlagUnsigned IntegerUInt32(Optional) Integer flag to enable for this account.
TransferRateUnsigned IntegerUInt32(Optional) The fee to charge when users transfer this account's issuances, represented as billionths of a unit. Use 0 to set no fee.
TickSizeUnsigned IntegerUInt8(Optional) Tick size to use for offers involving a currency issued by this address. The exchange rates of those offers is rounded to this many significant digits. Valid values are 3 to 15 inclusive, or 0 to disable. (Requires the TickSize amendment.)
WalletLocatorStringHash256(Optional) Not used.
WalletSizeUnsigned IntegerUInt32(Optional) Not used.
-

If none of these options are provided, then the AccountSet transaction has no effect (beyond destroying the transaction cost). See Canceling or Skipping a Transaction for more details.

-

Domain

-

The Domain field is represented as the hex string of the lowercase ASCII of the domain. For example, the domain example.com would be represented as "6578616d706c652e636f6d".

-

To remove the Domain field from an account, send an AccountSet with the Domain set to an empty string.

-

Client applications can use the ripple.txt file hosted by the domain to confirm that the account is actually operated by that domain.

-

AccountSet Flags

-

There are several options which can be either enabled or disabled for an account. Account options are represented by different types of flags depending on the situation:

-
    -
  • The AccountSet transaction type has several "AccountSet Flags" (prefixed asf) that can enable an option when passed as the SetFlag parameter, or disable an option when passed as the ClearFlag parameter.
    • -
  • The AccountSet transaction type has several transaction flags (prefixed tf) that can be used to enable or disable specific account options when passed in the Flags parameter. This style is discouraged. New account options do not have corresponding transaction (tf) flags.
    • -
  • The AccountRoot ledger node type has several ledger-specific-flags (prefixed lsf) which represent the state of particular account options within a particular ledger. Naturally, the values apply until a later ledger version changes them.
    • -
-

The preferred way to enable and disable Account Flags is using the SetFlag and ClearFlag parameters of an AccountSet transaction. AccountSet flags have names that begin with asf.

-

All flags are off by default.

-

The available AccountSet flags are:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Flag NameDecimal ValueCorresponding Ledger FlagDescription
asfRequireDest1lsfRequireDestTagRequire a destination tag to send transactions to this account.
asfRequireAuth2lsfRequireAuthRequire authorization for users to hold balances issued by this address. Can only be enabled if the address has no trust lines connected to it.
asfDisallowXRP3lsfDisallowXRPXRP should not be sent to this account. (Enforced by client applications, not by rippled)
asfDisableMaster4lsfDisableMasterDisallow use of the master key. Can only be enabled if the account has configured another way to sign transactions, such as a Regular Key or a Signer List.
asfAccountTxnID5(None)Track the ID of this account's most recent transaction. Required for AccountTxnID
asfNoFreeze6lsfNoFreezePermanently give up the ability to freeze individual trust lines or disable Global Freeze. This flag can never be disabled after being enabled.
asfGlobalFreeze7lsfGlobalFreezeFreeze all assets issued by this account.
asfDefaultRipple8lsfDefaultRippleEnable rippling on this account's trust lines by default. New in: rippled 0.27.3
-

To enable the asfDisableMaster or asfNoFreeze flags, you must authorize the transaction by signing it with the master key. You cannot use a regular key or a multi-signature. New in: rippled 0.28.0

-

The following Transaction flags, specific to the AccountSet transaction type, serve the same purpose, but are discouraged:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Flag NameHex ValueDecimal ValueReplaced by AccountSet Flag
tfRequireDestTag0x0001000065536asfRequireDest (SetFlag)
tfOptionalDestTag0x00020000131072asfRequireDest (ClearFlag)
tfRequireAuth0x00040000262144asfRequireAuth (SetFlag)
tfOptionalAuth0x00080000524288asfRequireAuth (ClearFlag)
tfDisallowXRP0x001000001048576asfDisallowXRP (SetFlag)
tfAllowXRP0x002000002097152asfDisallowXRP (ClearFlag)
-

Blocking Incoming Transactions

-

Incoming transactions with unclear purposes may be an inconvenience for financial institutions, who would have to recognize when a customer made a mistake, and then potentially refund accounts or adjust balances depending on the mistake. The asfRequireDest and asfDisallowXRP flags are intended to protect users from accidentally sending funds in a way that is unclear about the reason the funds were sent.

-

For example, a destination tag is typically used to identify which hosted balance should be credited when a financial institution receives a payment. If the destination tag is omitted, it may be unclear which account should be credited, creating a need for refunds, among other problems. By using the asfRequireDest tag, you can ensure that every incoming payment has a destination tag, which makes it harder for others to send you an ambiguous payment by accident.

-

You can protect against unwanted incoming payments for non-XRP currencies by not creating trust lines in those currencies. Since XRP does not require trust, the asfDisallowXRP flag is used to discourage users from sending XRP to an account. However, this flag is not enforced in rippled because it could potentially cause accounts to become unusable. (If an account did not have enough XRP to send a transaction that disabled the flag, the account would be completely unusable.) Instead, client applications should disallow or discourage XRP payments to accounts with the asfDisallowXRP flag enabled.

-

TransferRate

-

The TransferRate field specifies a fee to charge whenever counterparties transfer the currency you issue. See Transfer Fees for more information.

-

In rippled's WebSocket and JSON-RPC APIs, the TransferRate is represented as an integer, the amount that must be sent for 1 billion units to arrive. For example, a 20% transfer fee is represented as the value 1200000000. The value cannot be less than 1000000000. (Less than that would indicate giving away money for sending transactions, which is exploitable.) You can specify 0 as a shortcut for 1000000000, meaning no fee.

-

EscrowCancel

-

[Source]

-

Requires the Escrow Amendment.

-

Return escrowed XRP to the sender.

-

Example EscrowCancel:

-
{
-    "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-    "TransactionType": "EscrowCancel",
-    "Owner": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-    "OfferSequence": 7,
-}
-
- - - - - - - - - - - - - - - - - - - - - - - -
FieldJSON TypeInternal TypeDescription
OwnerStringAccountIDAddress of the source account that funded the escrow payment.
OfferSequenceUnsigned IntegerUInt32Transaction sequence of EscrowCreate transaction that created the escrow to cancel.
-

Any account may submit an EscrowCancel transaction.

-
    -
  • If the corresponding EscrowCreate transaction did not specify a CancelAfter time, the EscrowCancel transaction fails.
    • -
  • Otherwise the EscrowCancel transaction fails if the CancelAfter time is after the close time of the most recently-closed ledger.
    • -
-

EscrowCreate

-

[Source]

-

Requires the Escrow Amendment.

-

Sequester XRP until the escrow process either finishes or is canceled.

-

Example EscrowCreate:

-
{
-    "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-    "TransactionType": "EscrowCreate",
-    "Amount": "10000",
-    "Destination": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-    "CancelAfter": 533257958,
-    "FinishAfter": 533171558,
-    "Condition": "A0258020E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855810100",
-    "DestinationTag": 23480,
-    "SourceTag": 11747
-}
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldJSON TypeInternal TypeDescription
AmountStringAmountAmount of XRP, in drops, to deduct from the sender's balance and escrow. Once escrowed, the XRP can either go to the Destination address (after the FinishAfter time) or returned to the sender (after the CancelAfter time).
DestinationStringAccountIDAddress to receive escrowed XRP.
CancelAfterNumberUInt32(Optional) The time, in seconds since the Ripple Epoch, when this escrow expires. This value is immutable; the funds can only be returned the sender after this time.
FinishAfterNumberUInt32(Optional) The time, in seconds since the Ripple Epoch, when the escrowed XRP can be released to the recipient. This value is immutable; the funds cannot move until this time is reached.
ConditionStringVariableLength(Optional) Hex value representing a PREIMAGE-SHA-256 crypto-condition. The funds can only be delivered to the recipient if this condition is fulfilled.
DestinationTagNumberUInt32(Optional) Arbitrary tag to further specify the destination for this escrowed payment, such as a hosted recipient at the destination address.
SourceTagNumberUInt32(Optional) Arbitrary tag to further specify the source for this escrowed payment, such as a hosted sender at the source address.
-

Either CancelAfter or FinishAfter must be specified. If both are included, the FinishAfter time must precede that of CancelAfter.

-

EscrowFinish

-

[Source]

-

Requires the Escrow Amendment.

-

Deliver XRP from a held payment to the recipient.

-

Example EscrowFinish:

-
{
-    "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-    "TransactionType": "EscrowFinish",
-    "Owner": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-    "OfferSequence": 7,
-    "Condition": "A0258020E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855810100",
-    "Fulfillment": "A0028000"
-}
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldJSON TypeInternal TypeDescription
OwnerStringAccountIDAddress of the source account that funded the held payment.
OfferSequenceUnsigned IntegerUInt32Transaction sequence of EscrowCreate transaction that created the held payment to finish.
ConditionStringVariableLength(Optional) Hex value matching the previously-supplied PREIMAGE-SHA-256 crypto-condition of the held payment.
FulfillmentStringVariableLength(Optional) Hex value of the PREIMAGE-SHA-256 crypto-condition fulfillment matching the held payment's Condition.
-

Any account may submit an EscrowFinish transaction.

-
    -
  • If the held payment has a FinishAfter time, you cannot execute it before this time. Specifically, if the corresponding EscrowCreate transaction specified a FinishAfter time that is after the close time of the most recently-closed ledger, the EscrowFinish transaction fails.
    • -
  • If the held payment has a Condition, you cannot execute it unless you provide a matching Fulfillment for the condition.
    • -
  • You cannot execute a held payment after it has expired. Specifically, if the corresponding EscrowCreate transaction specified a CancelAfter time that is before the close time of the most recently-closed ledger, the EscrowFinish transaction fails.
    • -
-

Note: The minimum transaction cost to submit an EscrowFinish transaction increases if it contains a fulfillment. If the transaction has no fulfillment, the transaction cost is the standard 10 drops. If the transaction contains a fulfillment, the transaction cost is 330 drops of XRP plus another 10 drops for every 16 bytes in size of the preimage.

-

OfferCancel

-

[Source]

-

An OfferCancel transaction removes an Offer node from the XRP Ledger.

-
{
-    "TransactionType": "OfferCancel",
-    "Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-    "Fee": "12",
-    "Flags": 0,
-    "LastLedgerSequence": 7108629,
-    "OfferSequence": 6,
-    "Sequence": 7
-}
-
- - - - - - - - - - - - - - - - - -
FieldJSON TypeInternal TypeDescription
OfferSequenceUnsigned IntegerUInt32The sequence number of a previous OfferCreate transaction. If specified, cancel any offer node in the ledger that was created by that transaction. It is not considered an error if the offer specified does not exist.
-

Tip: To remove an old offer and replace it with a new one, you can use an OfferCreate transaction with an OfferSequence parameter, instead of using OfferCancel and another OfferCreate.

-

The OfferCancel method returns tesSUCCESS even if it did not find an offer with the matching sequence number.

-

OfferCreate

-

[Source]

-

An OfferCreate transaction is effectively a limit order. It defines an intent to exchange currencies, and creates an Offer node in the XRP Ledger if not completely fulfilled when placed. Offers can be partially fulfilled.

-
{
-    "TransactionType": "OfferCreate",
-    "Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-    "Fee": "12",
-    "Flags": 0,
-    "LastLedgerSequence": 7108682,
-    "Sequence": 8,
-    "TakerGets": "6000000",
-    "TakerPays": {
-      "currency": "GKO",
-      "issuer": "ruazs5h1qEsqpke88pcqnaseXdm6od2xc",
-      "value": "2"
-    }
-}
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldJSON TypeInternal TypeDescription
ExpirationUnsigned IntegerUInt32(Optional) Time after which the offer is no longer active, in seconds since the Ripple Epoch.
OfferSequenceUnsigned IntegerUInt32(Optional) An offer to delete first, specified in the same way as OfferCancel.
TakerGetsCurrency AmountAmountThe amount and type of currency being provided by the offer creator.
TakerPaysCurrency AmountAmountThe amount and type of currency being requested by the offer creator.
-

Lifecycle of an Offer

-

When an OfferCreate transaction is processed, it automatically consumes matching or crossing offers to the extent possible. (If existing offers provide a better rate than requested, the offer creator could pay less than the full TakerGets amount to receive the entire TakerPays amount.) If that does not completely fulfill the TakerPays amount, then the offer becomes an Offer node in the ledger. (You can use OfferCreate Flags to modify this behavior.)

-

An offer in the ledger can be fulfilled either by additional OfferCreate transactions that match up with the existing offers, or by Payments that use the offer to connect the payment path. Offers can be partially fulfilled and partially funded. A single transaction can consume up to 850 Offers from the ledger. (Any more than that, and the metadata becomes too large, resulting in tecOVERSIZE.)

-

You can create an offer so long as you have at least some (any positive, nonzero amount) of the currency specified by the TakerGets parameter of the offer. The offer sells as much of the currency as you have, up to the TakerGets amount, until the TakerPays amount is satisfied. An offer cannot place anyone in debt.

-

It is possible for an offer to become temporarily or permanently unfunded:

-
    -
  • If the creator no longer has any of the TakerGets currency.
      -
    • The offer becomes funded again when the creator obtains more of that currency.
      • -
    -
    • -
  • If the currency required to fund the offer is held in a frozen trust line.
      -
    • The offer becomes funded again when the trust line is no longer frozen.
      • -
    -
    • -
  • If the creator does not have enough XRP for the reserve amount of a new trust line required by the offer. (See Offers and Trust.)
      -
    • The offer becomes funded again when the creator obtains more XRP, or the reserve requirements decrease.
      • -
    -
    • -
  • If the Expiration time included in the offer is before the close time of the most recently-closed ledger. (See Expiration.)
    • -
-

An unfunded offer can stay on the ledger indefinitely, but it does not have any effect. The only ways an offer can be permanently removed from the ledger are:

-
    -
  • It becomes fully claimed by a Payment or a matching OfferCreate transaction.
    • -
  • An OfferCancel or OfferCreate transaction explicitly cancels the offer.
    • -
  • An OfferCreate transaction from the same account crosses the earlier offer. (In this case, the older offer is automatically canceled.)
    • -
  • An offer is found to be unfunded during transaction processing, typically because it was at the tip of the orderbook.
      -
    • This includes cases where one side or the other of an offer is found to be closer to 0 than rippled's precision supports.
      • -
    -
    • -
-

Tracking Unfunded Offers

-

Tracking the funding status of all offers can be computationally taxing. In particular, addresses that are actively trading may have a large number of offers open. A single balance can affect the funding status of many offers to buy different currencies. Because of this, rippled does not proactively find and remove offers.

-

A client application can locally track the funding status of offers. To do this, first retreive an order book using the book_offers command and check the taker_gets_funded field of offers. Then, subscribe to the transactions stream and watch the transaction metadata to see which offers are modified.

-

Offers and Trust

-

The limit values of trust lines (See TrustSet) do not affect offers. In other words, you can use an offer to acquire more than the maximum amount you trust an issuer to redeem.

-

However, holding non-XRP balances still requires a trust line to the address issuing those balances. When an offer is taken, it automatically creates any necessary trust lines, setting their limits to 0. Because trust lines increase the reserve an account must hold, any offers that would require a new trust line also require the address to have enough XRP to meet the reserve for that trust line.

-

A trust line indicates an issuer you trust enough to accept their issuances as payment, within limits. Offers are explicit instructions to acquire certain issuances, so they are allowed to go beyond those limits.

-

Offer Preference

-

Existing offers are grouped by exchange rate (sometimes called "offer quality"), which is measured as the ratio between TakerGets and TakerPays. Offers with a higher exchange rate are taken preferentially. (That is, the person accepting the offer receives as much as possible for the amount of currency they pay out.) Offers with the same exchange rate are taken on the basis of which offer was placed in the earliest ledger version.

-

When offers of the same exchange rate are placed in the same ledger version, the order in which they are taken is determined by the canonical order in which the transactions were applied to the ledger. This behavior is designed to be deterministic, efficient, and hard to game.

-

TickSize

-

Requires the TickSize amendment.

-

When an Offer is placed into an order book, its exchange rate is truncated based on the TickSize values set by the issuers of the currencies involved in the Offer. When a trader offers to exchange XRP and an issued currency, the TickSize from the issuer of the currency applies. When a trader offers to exchange two issued currencies, the offer uses the smaller TickSize value (that is, the one with fewer significant digits). If neither currency has a TickSize set, the default behavior applies.

-

The TickSize value truncates the number of significant digits in the exchange rate of an offer when it gets placed in an order book. Issuers can set TickSize to an integer from 3 to 15 using an AccountSet transaction. The exchange rate is represented as a number of significant digits plus an exponent; the TickSize does not affect the exponent. This allows the XRP Ledger to represent exchange rates between assets that vary greatly in value (for example, a hyperinflated currency compared to a rare commodity). The lower the TickSize an issuer sets, the larger the increment traders must offer to be considered a higher exchange rate than the existing Offers.

-

The TickSize does not affect the portion of an Offer that can be executed immediately. (For that reason, OfferCreate transactions with tfImmediateOrCancel are unaffected by TickSize values.) If the Offer cannot be fully executed, the transaction processing engine calculates the exchange rate and truncates it based on TickSize. Then, the engine rounds the remaining amount of the Offer from the "less important" side to match the truncated exchange rate. For a default OfferCreate transaction (a "buy" Offer), the TakerPays amount (the amount being bought) gets rounded. If the tfSell flag is enabled (a "sell" Offer) the TakerGets amount (the amount being sold) gets rounded.

-

When an issuer enables, disables, or changes the TickSize, Offers that were placed under the previous setting are unaffected.

-

Expiration

-

Since transactions can take time to propagate and confirm, the timestamp of a ledger is used to determine offer validity. An offer only expires when its Expiration time is before the most-recently validated ledger. In other words, an offer with an Expiration field is still considered "active" if its expiration time is later than the timestamp of the most-recently validated ledger, regardless of what your local clock says.

-

You can determine the final disposition of an offer with an Expiration as soon as you see a fully-validated ledger with a close time equal to or greater than the expiration time.

-

Note: Since only new transactions can modify the ledger, an expired offer can stay on the ledger after it becomes inactive. The offer is treated as unfunded and has no effect, but it can continue to appear in results (for example, from the ledger_entry command). Later on, the expired offer can get finally deleted as a result of another transaction (such as another OfferCreate) if the server finds it while processing.

-

If an OfferCreate transaction has an Expiration time that has already passed when the transaction first gets included in a ledger, the transaction does not execute the offer but still results in a tesSUCCESS transaction code. (This is because such a transaction could still successfully cancel another offer.)

-

Auto-Bridging

-

Any OfferCreate that would exchange two non-XRP currencies could potentially use XRP as an intermediary currency in a synthetic order book. This is because of auto-bridging, which serves to improve liquidity across all currency pairs by using XRP as a vehicle currency. This works because of XRP's nature as a native cryptocurrency to the XRP Ledger. Offer execution can use a combination of direct and auto-bridged offers to achieve the best total exchange rate.

-

Example: Anita places an offer to sell GBP and buy BRL. She might fund that this uncommon currency market has few offers. There is one offer with a good rate, but it has insufficient quantity to satisfy Anita's trade. However, both GBP and BRL have active, competitive markets to XRP. Auto-bridging software finds a way to complete Anita's offer by purchasing XRP with GBP from one trader, then selling the XRP to another trader to buy BRL. Anita automatically gets the best rate possible by combining the small offer in the direct GBP:BRL market with the better composite rates created by pairing GBP:XRP and XRP:BRL offers.

-

Auto-bridging happens automatically on any OfferCreate transaction. Payment transactions do not autobridge by default, but path-finding can find paths that have the same effect.

-

OfferCreate Flags

-

Transactions of the OfferCreate type support additional values in the Flags field, as follows:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Flag NameHex ValueDecimal ValueDescription
tfPassive0x0001000065536If enabled, the offer does not consume offers that exactly match it, and instead becomes an Offer node in the ledger. It still consumes offers that cross it.
tfImmediateOrCancel0x00020000131072Treat the offer as an Immediate or Cancel order. If enabled, the offer never becomes a ledger node: it only tries to match existing offers in the ledger.
tfFillOrKill0x00040000262144Treat the offer as a Fill or Kill order. Only try to match existing offers in the ledger, and only do so if the entire TakerPays quantity can be obtained.
tfSell0x00080000524288Exchange the entire TakerGets amount, even if it means obtaining more than the TakerPays amount in exchange.
-

The following invalid flag combination prompts a temINVALID_FLAG error:

-
    -
  • tfImmediateOrCancel and tfFillOrKill
    • -
-

Note: When an OfferCreate uses tfImmediateOrCancel or tfFillOrKill and the offer cannot be executed when placed, the transaction may conclude "successfully" without trading any currency or having any effect on the order books. In this case, the transaction has the result code tesSUCCESS, it pays the transaction cost and uses up a Sequence number, but has no other effect.

-

Payment

-

[Source]

-

A Payment transaction represents a transfer of value from one account to another. (Depending on the path taken, this can involve additional exchanges of value, which occur atomically.)

-

Payments are also the only way to create accounts.

-

Example payment:

-
{
-  "TransactionType" : "Payment",
-  "Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-  "Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-  "Amount" : {
-     "currency" : "USD",
-     "value" : "1",
-     "issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
-  },
-  "Fee": "10",
-  "Flags": 2147483648,
-  "Sequence": 2,
-}
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldJSON TypeInternal TypeDescription
AmountCurrency AmountAmountThe amount of currency to deliver. For non-XRP amounts, the nested field names MUST be lower-case. If the tfPartialPayment flag is set, deliver up to this amount instead.
DestinationStringAccountThe unique address of the account receiving the payment.
DestinationTagUnsigned IntegerUInt32(Optional) Arbitrary tag that identifies the reason for the payment to the destination, or a hosted recipient to pay.
InvoiceIDStringHash256(Optional) Arbitrary 256-bit hash representing a specific reason or identifier for this payment.
PathsArray of path arraysPathSet(Optional, auto-fillable) Array of payment paths to be used for this transaction. Must be omitted for XRP-to-XRP transactions.
SendMaxCurrency AmountAmount(Optional) Highest amount of source currency this transaction is allowed to cost, including transfer fees, exchange rates, and slippage. Does not include the XRP destroyed as a cost for submitting the transaction. For non-XRP amounts, the nested field names MUST be lower-case. Must be supplied for cross-currency/cross-issue payments. Must be omitted for XRP-to-XRP payments.
DeliverMinCurrency AmountAmount(Optional) Minimum amount of destination currency this transaction should deliver. Only valid if this is a partial payment. For non-XRP amounts, the nested field names are lower-case.
-

Special issuer Values for SendMax and Amount

-

Most of the time, the issuer field of a non-XRP Currency Amount indicates a financial institution's issuing address. However, when describing payments, there are special rules for the issuer field in the Amount and SendMax fields of a payment.

-
    -
  • There is only ever one balance for the same currency between two addresses. This means that, sometimes, the issuer field of an amount actually refers to a counterparty that is redeeming issuances, instead of the address that created the issuances.
    • -
  • When the issuer field of the destination Amount field matches the Destination address, it is treated as a special case meaning "any issuer that the destination accepts." This includes all addresses to which the destination has extended trust lines, as well as issuances created by the destination which are held on other trust lines.
    • -
  • When the issuer field of the SendMax field matches the source account's address, it is treated as a special case meaning "any issuer that the source can use." This includes creating new issuances on trust lines that other accounts have extended to the source account, and sending issuances the source account holds from other issuers.
    • -
-

Creating Accounts

-

The Payment transaction type is the only way to create new accounts in the XRP Ledger. To do so, send an amount of XRP that is equal or greater than the account reserve to a mathematically-valid account address that does not exist yet. When the Payment is processed, a new AccountRoot node is added to the ledger.

-

If you send an insufficient amount of XRP, or any other currency, the Payment fails.

-

Paths

-

If present, the Paths field must contain a path set - an array of path arrays. Each individual path represents one way value can flow from the sender to receiver through various intermediary accounts and order books. A single transaction can potentially use multiple paths, for example if the transaction exchanges currency using several different order books to achieve the best rate.

-

You must omit the Paths field for direct payments, including:

-
    -
  • An XRP-to-XRP transfer.
    • -
  • A direct transfer on a trust line that connects the sender and receiver.
    • -
-

If the Paths field is provided, the server decides at transaction processing time which paths to use, from the provided set plus a default path (the most direct way possible to connect the specified accounts). This decision is deterministic and attempts to minimize costs, but it is not guaranteed to be perfect.

-

The Paths field must not be an empty array, nor an array whose members are all empty arrays.

-

For more information, see Paths.

-

Payment Flags

-

Transactions of the Payment type support additional values in the Flags field, as follows:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Flag NameHex ValueDecimal ValueDescription
tfNoDirectRipple0x0001000065536Do not use the default path; only use paths included in the Paths field. This is intended to force the transaction to take arbitrage opportunities. Most clients do not need this.
tfPartialPayment0x00020000131072If the specified Amount cannot be sent without spending more than SendMax, reduce the received amount instead of failing outright. See Partial Payments for more details.
tfLimitQuality0x00040000262144Only take paths where all the conversions have an input:output ratio that is equal or better than the ratio of Amount:SendMax. See Limit Quality for details.
-

Partial Payments

-

A partial payment allows a payment to succeed by reducing the amount received. Partial payments are useful for returning payments without incurring additional costs to oneself. However, partial payments can also be used to exploit integrations that naively assume the Amount field of a successful transaction always describes the exact amount delivered.

-

A partial payment is any Payment transaction with the tfPartialPayment flag enabled. A partial payment can be successful if it delivers any positive amount greater than or equal to its DeliverMin field (or any positive amount at all if DeliverMin is not specified) without sending more than the SendMax value.

-

The delivered_amount field of a payment's metadata indicates the amount of currency actually received by the destination account.

-

For more information, see the full article on Partial Payments.

-

Limit Quality

-

The XRP Ledger defines the "quality" of a currency exchange as the ratio of the numeric amount in to the numeric amount out. For example, if you spend $2 USD to receive £1 GBP, then the "quality" of that exchange is 0.5.

-

The tfLimitQuality flag allows you to set a minimum quality of conversions that you are willing to take. This limit quality is defined as the destination Amount divided by the SendMax amount (the numeric amounts only, regardless of currency). When set, the payment processing engine avoids using any paths whose quality (conversion rate) is worse (numerically lower) than the limit quality.

-

By itself, the tfLimitQuality flag reduces the number of situations in which a transaction can succeed. Specifically, it rejects payments where some part of the payment uses an unfavorable conversion, even if the overall average average quality of conversions in the payment is equal or better than the limit quality. If a payment is rejected in this way, the transaction result is tecPATH_DRY.

-

Consider the following example. If I am trying to send you 100 Chinese Yuan (Amount = 100 CNY) for 20 United States dollars (SendMax = 20 USD) or less, then the limit quality is 5. Imagine one trader is offering ¥95 for $15 (a ratio of about 6.3 CNY per USD), but the next best offer in the market is ¥5 for $2 (a ratio of 2.5 CNY per USD). If I were to take both offers to send you 100 CNY, then it would cost me 17 USD, for an average quality of about 5.9.

-

Without the tfLimitQuality flag set, this transaction would succeed, because the $17 it costs me is within my specified SendMax. However, with the tfLimitQuality flag enabled, the transaction would fail instead, because the path to take the second offer has a quality of 2.5, which is worse than the limit quality of 5.

-

The tfLimitQuality flag is most useful when combined with partial payments. When both tfPartialPayment and tfLimitQuality are set on a transaction, then the transaction delivers as much of the destination Amount as it can, without using any conversions that are worse than the limit quality.

-

In the above example with a ¥95/$15 offer and a ¥5/$2 offer, the situation is different if my transaction has both tfPartialPayment and tfLimitQuality enabled. If we keep my SendMax of 20 USD and a destination Amount of 100 CNY, then the limit quality is still 5. However, because I am doing a partial payment, the transaction sends as much as it can instead of failing if the full destination amount cannot be sent. This means that my transaction consumes the ¥95/$15 offer, whose quality is about 6.3, but it rejects the ¥5/$2 offer because that offer's quality of 2.5 is worse than the quality limit of 5. In the end, my transaction only delivers ¥95 instead of the full ¥100, but it avoids wasting money on poor exchange rates.

-

PaymentChannelClaim

-

[Source]

-

Requires the PayChan Amendment.

-

Claim XRP from a payment channel, adjust the payment channel's expiration, or both. This transaction can be used differently depending on the transaction sender's role in the specified channel:

-

The source address of a channel can:

-
    -
  • Send XRP from the channel to the destination with or without a signed Claim.
    • -
  • Set the channel to expire as soon as the channel's SettleDelay has passed.
    • -
  • Clear a pending Expiration time.
    • -
  • Close a channel immediately, with or without processing a claim first. The source address cannot close the channel immediately if the channel has XRP remaining.
    • -
-

The destination address of a channel can:

-
    -
  • Receive XRP from the channel using a signed Claim.
    • -
  • Close the channel immediately after processing a Claim, refunding any unclaimed XRP to the channel's source.
    • -
-

Any address sending this transaction can:

-
    -
  • Cause a channel to be closed if its Expiration or CancelAfter time is older than the previous ledger's close time. Any validly-formed PaymentChannelClaim transaction has this effect regardless of the contents of the transaction.
    • -
-

Example PaymentChannelClaim:

-
{
-  "Channel": "C1AE6DDDEEC05CF2978C0BAD6FE302948E9533691DC749DCDD3B9E5992CA6198",
-  "Balance": "1000000",
-  "Amount": "1000000",
-  "Signature": "30440220718D264EF05CAED7C781FF6DE298DCAC68D002562C9BF3A07C1E721B420C0DAB02203A5A4779EF4D2CCC7BC3EF886676D803A9981B928D3B8ACA483B80ECA3CD7B9B",
-  "PublicKey": "32D2471DB72B27E3310F355BB33E339BF26F8392D5A93D3BC0FC3B566612DA0F0A"
-}
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldJSON TypeInternal TypeDescription
ChannelStringHash256The unique ID of the channel, as a 64-character hexadecimal string.
BalanceStringAmount(Optional) Total amount of XRP, in drops, delivered by this channel after processing this claim. Required to deliver XRP. Must be more than the total amount delivered by the channel so far, but not greater than the Amount of the signed claim. Must be provided except when closing the channel.
AmountStringAmount(Optional) The amount of XRP, in drops, authorized by the Signature. This must match the amount in the signed message. This is the cumulative amount of XRP that can be dispensed by the channel, including XRP previously redeemed.
SignatureStringVariableLength(Optional) The signature of this claim, as hexadecimal. The signed message contains the channel ID and the amount of the claim. Required unless the sender of the transaction is the source address of the channel.
PublicKeyStringPubKey(Optional) The public key used for the signature, as hexadecimal. This must match the PublicKey stored in the ledger for the channel. Required unless the sender of the transaction is the source address of the channel and the Signature field is omitted. (The transaction includes the PubKey so that rippled can check the validity of the signature before trying to apply the transaction to the ledger.)
-

PaymentChannelClaim Flags

-

Transactions of the PaymentChannelClaim type support additional values in the Flags field, as follows:

- - - - - - - - - - - - - - - - - - - - - - - -
Flag NameHex ValueDecimal ValueDescription
tfRenew0x0001000065536Clear the channel's Expiration time. (Expiration is different from the channel's immutable CancelAfter time.) Only the source address of the payment channel can use this flag.
tfClose0x00020000131072Request to close the channel. Only the channel source and destination addresses can use this flag. This flag closes the channel immediately if it has no more XRP allocated to it after processing the current claim, or if the destination address uses it. If the source address uses this flag when the channel still holds XRP, this schedules the channel to close after SettleDelay seconds have passed. (Specifically, this sets the Expiration of the channel to the close time of the previous ledger plus the channel's SettleDelay time, unless the channel already has an earlier Expiration time.) If the destination address uses this flag when the channel still holds XRP, any XRP that remains after processing the claim is returned to the source address.
-

PaymentChannelCreate

-

[Source]

-

Requires the PayChan Amendment.

-

Create a unidirectional channel and fund it with XRP. The address sending this transaction becomes the "source address" of the payment channel.

-

Example PaymentChannelCreate:

-
{
-    "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-    "TransactionType": "PaymentChannelCreate",
-    "Amount": "10000",
-    "Destination": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-    "SettleDelay": 86400,
-    "PublicKey": "32D2471DB72B27E3310F355BB33E339BF26F8392D5A93D3BC0FC3B566612DA0F0A",
-    "CancelAfter": 533171558,
-    "DestinationTag": 23480,
-    "SourceTag": 11747
-}
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldJSON TypeInternal TypeDescription
AmountStringAmountAmount of XRP, in drops, to deduct from the sender's balance and set aside in this channel. While the channel is open, the XRP can only go to the Destination address. When the channel closes, any unclaimed XRP is returned to the source address's balance.
DestinationStringAccountIDAddress to receive XRP claims against this channel. This is also known as the "destination address" for the channel.
SettleDelayNumberUInt32Amount of time the source address must wait before closing the channel if it has unclaimed XRP.
PublicKeyStringPubKeyThe public key of the key pair the source will use to sign claims against this channel, in hexadecimal. This can be any secp256k1 or Ed25519 public key.
CancelAfterNumberUInt32(Optional) The time, in seconds since the Ripple Epoch, when this channel expires. Any transaction that would modify the channel after this time closes the channel without otherwise affecting it. This value is immutable; the channel can be closed earlier than this time but cannot remain open after this time.
DestinationTagNumberUInt32(Optional) Arbitrary tag to further specify the destination for this payment channel, such as a hosted recipient at the destination address.
SourceTagNumberUInt32(Optional) Arbitrary tag to further specify the source for this payment channel, such as a hosted sender at the source address.
-

PaymentChannelFund

-

[Source]

-

Requires the PayChan Amendment.

-

Add additional XRP to an open payment channel, update the expiration time of the channel, or both. Only the source address of the channel can use this transaction. (Transactions from other addresses fail with the error tecNO_PERMISSION.)

-

Example PaymentChannelFund:

-
{
-    "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-    "TransactionType": "PaymentChannelFund",
-    "Channel": "C1AE6DDDEEC05CF2978C0BAD6FE302948E9533691DC749DCDD3B9E5992CA6198",
-    "Amount": "200000",
-    "Expiration": 543171558
-}
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldJSON TypeInternal TypeDescription
ChannelStringHash256The unique ID of the channel to fund, as a 64-character hexadecimal string.
AmountStringAmountAmount of XRP, in drops to add to the channel. To set the expiration for a channel without adding more XRP, set this to "0".
ExpirationNumberUInt32(Optional) New Expiration time to set for the channel, in seconds since the Ripple Epoch. This must be later than either the current time plus the SettleDelay of the channel, or the existing Expiration of the channel. After the Expiration time, any transaction that would access the channel closes the channel without taking its normal action. Any unspent XRP is returned to the source address when the channel closes. (Expiration is separate from the channel's immutable CancelAfter time.)
- -

SetRegularKey

-

[Source]

-

A SetRegularKey transaction changes the regular key associated with an address.

-
{
-    "Flags": 0,
-    "TransactionType": "SetRegularKey",
-    "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-    "Fee": "12",
-    "RegularKey": "rAR8rR8sUkBoCZFawhkWzY4Y5YoyuznwD"
-}
-
- - - - - - - - - - - - - - - - - -
FieldJSON TypeInternal TypeDescription
RegularKeyStringAccountID(Optional) A base-58-encoded Ripple address to use as the regular key. If omitted, removes the existing regular key.
-

In addition to the master key, which is mathematically-related to an address, you can associate at most 1 additional key pair with an address using this type of transaction. The additional key pair is called a regular key. If your address has a regular key pair defined, you can use the secret key of the regular key pair to authorize transactions.

-

A regular key pair is generated in the same way as any other Ripple keys (for example, with wallet_propose), but it can be changed. A master key pair is an intrinsic part of an address's identity (the address is derived from the master public key). You can disable a master key but you cannot change it.

-

You can protect your master secret by using a regular key instead of the master key to sign transactions whenever possible. If your regular key is compromised, but the master key is not, you can use a SetRegularKey transaction to regain control of your address. In some cases, you can even send a key reset transaction without paying the transaction cost.

-

For even greater security, you can use multi-signing, but multi-signing requires additional XRP for the transaction cost and reserve.

-

SignerListSet

-

[Source]

-

The SignerListSet transaction creates, replaces, or removes a list of signers that can be used to multi-sign a transaction. This transaction type was introduced by the MultiSign amendment. New in: rippled 0.31.0

-

Example SignerListSet:

-
{
-    "Flags": 0,
-    "TransactionType": "SignerListSet",
-    "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-    "Fee": "10000",
-    "SignerQuorum": 3,
-    "SignerEntries": [
-        {
-            "SignerEntry": {
-                "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-                "SignerWeight": 2
-            }
-        },
-        {
-            "SignerEntry": {
-                "Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
-                "SignerWeight": 1
-            }
-        },
-        {
-            "SignerEntry": {
-                "Account": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
-                "SignerWeight": 1
-            }
-        }
-    ]
-}
-
- - - - - - - - - - - - - - - - - - - - - - - -
FieldJSON TypeInternal TypeDescription
SignerQuorumNumberUInt32A target number for the signer weights. A multi-signature from this list is valid only if the sum weights of the signatures provided is greater than or equal to this value. To delete a SignerList, use the value 0.
SignerEntriesArrayArray(Omitted when deleting) Array of SignerEntry objects, indicating the addresses and weights of signers in this list. A SignerList must have at least 1 member and no more than 8 members. No address may appear more than once in the list, nor may the Account submitting the transaction appear in the list.
-

An account may not have more than one SignerList. A successful SignerListSet transaction replaces the existing SignerList, if one exists. To delete a SignerList, you must set SignerQuorum to 0 and omit the SignerEntries field. Otherwise, the transaction fails with the error temMALFORMED. A transaction to delete a SignerList is considered successful even if there was no SignerList to delete.

-

You cannot create a SignerList such that the SignerQuorum could never be met. The SignerQuorum must be greater than 0 but less than or equal to the sum of the SignerWeight values in the list. Otherwise, the transaction fails with the error temMALFORMED.

-

You can create, update, or remove a SignerList using the master key, regular key, or the current SignerList, if those methods of signing transactions are available.

-

You cannot remove the last method of signing transactions from an account. If an account's master key is disabled (it has the lsfDisableMaster flag enabled) and the account does not have a Regular Key configured, then you cannot delete the SignerList from the account. Instead, the transaction fails with the error tecNO_ALTERNATIVE_KEY.

-

TrustSet

-

[Source]

-

Create or modify a trust line linking two accounts.

-
{
-    "TransactionType": "TrustSet",
-    "Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
-    "Fee": "12",
-    "Flags": 262144,
-    "LastLedgerSequence": 8007750,
-    "LimitAmount": {
-      "currency": "USD",
-      "issuer": "rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc",
-      "value": "100"
-    },
-    "Sequence": 12
-}
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldJSON TypeInternal TypeDescription
LimitAmountObjectAmountObject defining the trust line to create or modify, in the format of a Currency Amount.
LimitAmount.currencyString(Amount.currency)The currency to this trust line applies to, as a three-letter ISO 4217 Currency Code or a 160-bit hex value according to currency format. "XRP" is invalid.
LimitAmount.valueString(Amount.value)Quoted decimal representation of the limit to set on this trust line.
LimitAmount.issuerString(Amount.issuer)The address of the account to extend trust to.
QualityInUnsigned IntegerUInt32(Optional) Value incoming balances on this trust line at the ratio of this number per 1,000,000,000 units. A value of 0 is shorthand for treating balances at face value.
QualityOutUnsigned IntegerUInt32(Optional) Value outgoing balances on this trust line at the ratio of this number per 1,000,000,000 units. A value of 0 is shorthand for treating balances at face value.
-

Trust Limits

-

All balances on the XRP Ledger, except for XRP, represent value owed in the world outside the XRP Ledger. The address that issues those funds in the XRP Ledger (identified by the issuer field of the LimitAmount object) is expected to pay the balance back, outside of the XRP Ledger, when users redeem their XRP Ledger balances by returning them to the issuer.

-

Since a computer program cannot force a someone to keep a promise and not default in real life, trust lines represent a way of configuring how much you trust an issuer to hold on your behalf. Since a large, reputable financial institution is more likely to be able to pay you back than, say, your broke roommate, you can set different limits on each trust line, to indicate the maximum amount you are willing to let the issuer "owe" you in the XRP Ledger. If the issuer defaults or goes out of business, you can lose up to that much money because the balances you hold in the XRP Ledger can no longer be exchanged for equivalent balances elsewhere. (You can still keep or trade the issuances in the XRP Ledger, but they no longer have any reason to be worth anything.)

-

There are two cases where you can hold a balance on a trust line that is greater than your limit: when you acquire more of that currency through trading, or when you decrease the limit on your trust line.

-

Since a trust line occupies space in the ledger, a trust line increases the XRP your account must hold in reserve. This applies to the account extending trust, not to the account receiving it.

-

A trust line with settings in the default state is equivalent to no trust line.

-

The default state of all flags is off, except for the NoRipple flag, whose default state depends on the DefaultRipple flag.

-

The Auth flag of a trust line does not determine whether the trust line counts towards its owner's XRP reserve requirement. However, an enabled Auth flag prevents the trust line from being in its default state. An authorized trust line can never be deleted. An issuer can pre-authorize a trust line with the tfSetfAuth flag only, even if the limit and balance of the trust line are 0.

-

TrustSet Flags

-

Transactions of the TrustSet type support additional values in the Flags field, as follows:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Flag NameHex ValueDecimal ValueDescription
tfSetfAuth0x0001000065536Authorize the other party to hold issuances from this account. (No effect unless using the asfRequireAuth AccountSet flag.) Cannot be unset.
tfSetNoRipple0x00020000131072Blocks rippling between two trustlines of the same currency, if this flag is set on both. (See No Ripple for details.)
tfClearNoRipple0x00040000262144Clears the No-Rippling flag. (See NoRipple for details.)
tfSetFreeze0x001000001048576Freeze the trustline.
tfClearFreeze0x002000002097152Unfreeze the trustline.
-

Pseudo-Transactions

-

Pseudo-Transactions are never submitted by users, nor propagated through the network. Instead, a server may choose to inject them in a proposed ledger directly. If enough servers inject an equivalent pseudo-transaction for it to pass consensus, then it becomes included in the ledger, and appears in ledger data thereafter.

-

Some of the fields that are mandatory for normal transactions do not make sense for pseudo-transactions. In those cases, the pseudo-transaction has the following default values:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDefault Value
AccountACCOUNT_ZERO
Sequence0
Fee0
SigningPubKey""
Signature""
-

EnableAmendment

-

Tracks the progress of the amendment process for changes in transaction processing. This can indicate that a proposed amendment gained or lost majority approval, or that an amendment has been enabled.

-

Note: You cannot send a pseudo-transaction, but you may find one when processing ledgers.

- - - - - - - - - - - - - - - - - - - - - - - -
FieldJSON TypeInternal TypeDescription
AmendmentStringHash256A unique identifier for the amendment. This is not intended to be a human-readable name. See Amendments for a list of known amendments.
LedgerSequenceNumberUInt32The index of the ledger version where this amendment appears. This distinguishes the pseudo-transaction from other occurrences of the same change.
-

EnableAmendment Flags

-

The Flags value of the EnableAmendment pseudo-transaction indicates the status of the amendment at the time of the ledger including the pseudo-transaction.

-

A Flags value of 0 (no flags) indicates that the amendment has been enabled, and applies to all ledgers afterward. Other Flags values are as follows:

- - - - - - - - - - - - - - - - - - - - - - - -
Flag NameHex ValueDecimal ValueDescription
tfGotMajority0x0001000065536Support for this amendment increased to at least 80% of trusted validators starting with this ledger version.
tfLostMajority0x00020000131072Support for this amendment decreased to less than 80% of trusted validators starting with this ledger version.
-

SetFee

-

A change in transaction cost or account reserve requirements as a result of Fee Voting.

-

Note: You cannot send a pseudo-transaction, but you may find one when processing ledgers.

-
{
-    "Account": "rrrrrrrrrrrrrrrrrrrrrhoLvTp",
-    "BaseFee": "000000000000000A",
-    "Fee": "0",
-    "ReferenceFeeUnits": 10,
-    "ReserveBase": 20000000,
-    "ReserveIncrement": 5000000,
-    "Sequence": 0,
-    "SigningPubKey": "",
-    "TransactionType": "SetFee",
-    "date": 439578860,
-    "hash": "1C15FEA3E1D50F96B6598607FC773FF1F6E0125F30160144BE0C5CBC52F5151B",
-    "ledger_index": 3721729,
-  }
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldJSON TypeInternal TypeDescription
BaseFeeStringUInt64The charge, in drops of XRP, for the reference transaction, as hex. (This is the transaction cost before scaling for load.)
ReferenceFeeUnitsUnsigned IntegerUInt32The cost, in fee units, of the reference transaction
ReserveBaseUnsigned IntegerUInt32The base reserve, in drops
ReserveIncrementUnsigned IntegerUInt32The incremental reserve, in drops
LedgerSequenceNumberUInt32The index of the ledger version where this pseudo-transaction appears. This distinguishes the pseudo-transaction from other occurrences of the same change.
-

Transaction Results

-

Immediate Response

-

The response from the submit command contains a provisional result from the rippled server indicating what happened during local processing of the transaction.

-

The response from submit contains the following fields:

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
engine_resultStringA code that categorizes the result, such as tecPATH_DRY
engine_result_codeSigned IntegerA number that corresponds to the engine_result, although exact values are subject to change.
engine_result_messageStringA human-readable message explaining what happened. This message is intended for developers to diagnose problems, and is subject to change without notice.
-

If nothing went wrong when submitting and applying the transaction locally, the response looks like this:

-
    "engine_result": "tesSUCCESS",
-    "engine_result_code": 0,
-    "engine_result_message": "The transaction was applied. Only final in a validated ledger."
-
-

Note: A successful result at this stage does not indicate that the transaction has completely succeeded; only that it was successfully applied to the provisional version of the ledger kept by the local server. See Finality of Results for details.

-

Looking up Transaction Results

-

To see the final result of a transaction, use the tx command, account_tx command, or other response from rippled. Look for "validated": true to indicate that this response uses a ledger version that has been validated by consensus.

- - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
meta.TransactionResultStringA code that categorizes the result, such as tecPATH_DRY
validatedBooleanWhether or not this result comes from a validated ledger. If false, then the result is provisional. If true, then the result is final.
-
    "hash": "E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7",
-    "meta": {
-      ...
-      "TransactionResult": "tesSUCCESS"
-    },
-    "validated": true
-
-

Result Categories

-

Both the engine_result and the meta.TransactionResult use standard codes to identify the results of transactions, as follows:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CategoryPrefixDescription
Local errortelThe rippled server had an error due to local conditions, such as high load. You may get a different response if you resubmit to a different server or at a different time.
Malformed transactiontemThe transaction was not valid, due to improper syntax, conflicting options, a bad signature, or something else.
FailuretefThe transaction cannot be applied to the server's current (in-progress) ledger or any later one. It may have already been applied, or the condition of the ledger makes it impossible to apply in the future.
RetryterThe transaction could not be applied, but it might be possible to apply later.
Successtes(Not an error) The transaction succeeded. This result only final in a validated ledger.
Claimed cost onlytecThe transaction did not achieve its intended purpose, but the transaction cost was destroyed. This result is only final in a validated ledger.
-

The distinction between a local error (tel) and a malformed transaction (tem) is a matter of protocol-level rules. For example, the protocol sets no limit on the maximum number of paths that can be included in a transaction. However, a server may define a finite limit of paths it can process. If two different servers are configured differently, then one of them may return a tel error for a transaction with many paths, while the other server could successfully process the transaction. If enough servers are able to process the transaction that it survives consensus, then it can still be included in a validated ledger.

-

By contrast, a tem error implies that no server anywhere can apply the transaction, regardless of settings. Either the transaction breaks the rules of the protocol, it is unacceptably ambiguous, or it is completely nonsensical. The only way a malformed transaction could become valid is through changes in the protocol; for example, if a new feature is adopted, then transactions using that feature could be considered malformed by servers that are running older software which predates that feature.

-

Claimed Cost Justification

-

Although it may seem unfair to charge a transaction cost for a failed transaction, the tec class of errors exists for good reasons:

-
    -
  • Transactions submitted after the failed one do not have to have their Sequence values renumbered. Incorporating the failed transaction into a ledger uses up the transaction's sequence number, preserving the expected sequence.
    • -
  • Distributing the transaction throughout the network increases network load. Enforcing a cost makes it harder for attackers to abuse the network with failed transactions.
    • -
  • The transaction cost is generally very small in real-world value, so it should not harm users unless they are sending large quantities of transactions.
    • -
-

Finality of Results

-

The order in which transactions apply to the consensus ledger is not final until a ledger is closed and the exact transaction set is approved by the consensus process. A transaction that succeeded initially could still fail, and a transaction that failed initially could still succeed. Additionally, a transaction that was rejected by the consensus process in one round could achieve consensus in a later round.

-

A validated ledger can include successful transactions (tes result codes) as well as failed transactions (tec result codes). No transaction with any other result is included in a ledger.

-

For any other result code, it can be difficult to determine if the result is final. The following table summarizes when a transaction's outcome is final, based on the result code from submitting the transaction:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Error CodeFinality
tesSUCCESSFinal when included in a validated ledger
Any tec codeFinal when included in a validated ledger
Any tem codeFinal unless the protocol changes to make the transaction valid
tefPAST_SEQFinal when another transaction with the same sequence number is included in a validated ledger
tefMAX_LEDGERFinal when a validated ledger has a sequence number higher than the transaction's LastLedgerSequence field, and no validated ledger includes the transaction
-

Any other transaction result is potentially not final. In that case, the transaction could still succeed or fail later, especially if conditions change such that the transaction is no longer prevented from applying. For example, trying to send a non-XRP currency to an account that does not exist yet would fail, but it could succeed if another transaction sends enough XRP to create the destination account. A server might even store a temporarily-failed, signed transaction and then successfully apply it later without asking first.

-

Understanding Transaction Metadata

-

The metadata section of a transaction includes detailed information about all the changes to the shared XRP Ledger that the transaction caused. This is true of any transaction that gets included in a ledger, whether or not it is successful. Naturally, the changes are only final if the transaction is validated.

-

Some fields that may appear in transaction metadata include:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldValueDescription
AffectedNodesArrayList of nodes that were created, deleted, or modified by this transaction, and specific changes to each.
DeliveredAmountCurrency AmountDEPRECATED. Replaced by delivered_amount. Omitted if not a partial payment.
TransactionIndexUnsigned IntegerThe transaction's position within the ledger that included it. (For example, the value 2 means it was the 2nd transaction in that ledger.)
TransactionResultStringA result code indicating whether the transaction succeeded or how it failed.
delivered_amountCurrency AmountThe Currency Amount actually received by the Destination account. Use this field to determine how much was delivered, regardless of whether the transaction is a partial payment. New in: rippled 0.27.0
-

delivered_amount

-

The Amount of a Payment transaction indicates the amount to deliver to the Destination, so if the transaction was successful, then the destination received that much -- except if the transaction was a partial payment. (In that case, any positive amount up to Amount might have arrived.) Rather than choosing whether or not to trust the Amount field, you should use the delivered_amount field of the metadata to see how much actually reached its destination.

-

The delivered_amount field of transaction metadata is included in all successful Payment transactions, and is formatted like a normal currency amount. However, the delivered amount is not available for transactions that meet both of the following criteria:

-
    -
  • Is a partial payment, and
    • -
  • Included in a validated ledger before 2014-01-20
    • -
-

If both conditions are true, then delivered_amount contains the string value unavailable instead of an actual amount. If this happens, you can only figure out the actual delivered amount by reading the AffectedNodes in the transaction's metadata.

-

See also: Partial Payments

-

Full Transaction Response List

-

[Source]

-

tel Codes

-

These codes indicate an error in the local server processing the transaction; it is possible that another server with a different configuration or load level could process the transaction successfully. They have numerical values in the range -399 to -300. The exact code for any given error is subject to change, so don't rely on it.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CodeExplanation
telBAD_DOMAINThe transaction specified a domain value (for example, the Domain field of an AccountSet transaction) that cannot be used, probably because it is too long to store in the ledger.
telBAD_PATH_COUNTThe transaction contains too many paths for the local server to process.
telBAD_PUBLIC_KEYThe transaction specified a public key value (for example, as the MessageKey field of an AccountSet transaction) that cannot be used, probably because it is too long.
telCAN_NOT_QUEUEThe transaction did not meet the open ledger cost, but this server did not queue this transaction because it did not meet the queuing restrictions. You can try again later or sign and submit a replacement transaction with a higher transaction cost in the Fee field.
telFAILED_PROCESSINGAn unspecified error occurred when processing the transaction.
telINSUF_FEE_PThe Fee from the transaction is not high enough to meet the server's current transaction cost requirement, which is derived from its load level.
telLOCAL_ERRORUnspecified local error.
telNO_DST_PARTIALThe transaction is an XRP payment that would fund a new account, but the tfPartialPayment flag was enabled. This is disallowed.
-

tem Codes

-

These codes indicate that the transaction was malformed, and cannot succeed according to the XRP Ledger protocol. They have numerical values in the range -299 to -200. The exact code for any given error is subject to change, so don't rely on it.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CodeExplanation
temBAD_AMOUNTAn amount specified by the transaction (for example the destination Amount or SendMax values of a Payment) was invalid, possibly because it was a negative number.
temBAD_AUTH_MASTERThe key used to sign this transaction does not match the master key for the account sending it, and the account does not have a Regular Key set.
temBAD_CURRENCYThe transaction improperly specified a currency field. See Specifying Currency Amounts for the correct format.
temBAD_EXPIRATIONThe transaction improperly specified an expiration value, for example as part of an OfferCreate transaction. Alternatively, the transaction did not specify a required expiration value, for example as part of an EscrowCreate transaction.
temBAD_FEEThe transaction improperly specified its Fee value, for example by listing a non-XRP currency or some negative amount of XRP.
temBAD_ISSUERThe transaction improperly specified the issuer field of some currency included in the request.
temBAD_LIMITThe TrustSet transaction improperly specified the LimitAmount value of a trustline.
temBAD_OFFERThe OfferCreate transaction specifies an invalid offer, such as offering to trade XRP for itself, or offering a negative amount.
temBAD_PATHThe Payment transaction specifies one or more Paths improperly, for example including an issuer for XRP, or specifying an account differently.
temBAD_PATH_LOOPOne of the Paths in the Payment transaction was flagged as a loop, so it cannot be processed in a bounded amount of time.
temBAD_SEND_XRP_LIMITThe Payment transaction used the tfLimitQuality flag in a direct XRP-to-XRP payment, even though XRP-to-XRP payments do not involve any conversions.
temBAD_SEND_XRP_MAXThe Payment transaction included a SendMax field in a direct XRP-to-XRP payment, even though sending XRP should never require SendMax. (XRP is only valid in SendMax if the destination Amount is not XRP.)
temBAD_SEND_XRP_NO_DIRECTThe Payment transaction used the tfNoDirectRipple flag for a direct XRP-to-XRP payment, even though XRP-to-XRP payments are always direct.
temBAD_SEND_XRP_PARTIALThe Payment transaction used the tfPartialPayment flag for a direct XRP-to-XRP payment, even though XRP-to-XRP payments should always deliver the full amount.
temBAD_SEND_XRP_PATHSThe Payment transaction included Paths while sending XRP, even though XRP-to-XRP payments should always be direct.
temBAD_SEQUENCEThe transaction is references a sequence number that is higher than its own Sequence number, for example trying to cancel an offer that would have to be placed after the transaction that cancels it.
temBAD_SIGNATUREThe signature to authorize this transaction is either missing, or formed in a way that is not a properly-formed signature. (See tecNO_PERMISSION for the case where the signature is properly formed, but not authorized for this account.)
temBAD_SRC_ACCOUNTThe Account on whose behalf this transaction is being sent (the "source account") is not a properly-formed account address.
temBAD_TRANSFER_RATEThe TransferRate field of an AccountSet transaction is not properly formatted.
temDST_IS_SRCThe TrustSet transaction improperly specified the destination of the trust line (the issuer field of LimitAmount) as the Account sending the transaction. You cannot extend a trust line to yourself. (In the future, this code could also apply to other cases where the destination of a transaction is not allowed to be the account sending it.)
temDST_NEEDEDThe transaction improperly omitted a destination. This could be the Destination field of a Payment transaction, or the issuer sub-field of the LimitAmount field fo a TrustSet transaction.
temINVALIDThe transaction is otherwise invalid. For example, the transaction ID may not be the right format, the signature may not be formed properly, or something else went wrong in understanding the transaction.
temINVALID_FLAGThe transaction includes a Flag that does not exist, or includes a contradictory combination of flags.
temMALFORMEDUnspecified problem with the format of the transaction.
temREDUNDANTThe transaction would do nothing; for example, it is sending a payment directly to the sending account, or creating an offer to buy and sell the same currency from the same issuer.
temREDUNDANT_SEND_MAXRemoved in: rippled 0.28.0
temRIPPLE_EMPTYThe Payment transaction includes an empty Paths field, but paths are necessary to complete this payment.
temBAD_WEIGHTThe SignerListSet transaction includes a SignerWeight that is invalid, for example a zero or negative value.
temBAD_SIGNERThe SignerListSet transaction includes a signer who is invalid. For example, there may be duplicate entries, or the owner of the SignerList may also be a member.
temBAD_QUORUMThe SignerListSet transaction has an invalid SignerQuorum value. Either the value is not greater than zero, or it is more than the sum of all signers in the list.
temUNCERTAINUsed internally only. This code should never be returned.
temUNKNOWNUsed internally only. This code should never be returned.
temDISABLEDThe transaction requires logic that is disabled. Typically this means you are trying to use an amendment that is not enabled for the current ledger.
-

tef Codes

-

These codes indicate that the transaction failed and was not included in a ledger, but the transaction could have succeeded in some theoretical ledger. Typically this means that the transaction can no longer succeed in any future ledger. They have numerical values in the range -199 to -100. The exact code for any given error is subject to change, so don't rely on it.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CodeExplanation
tefALREADYThe same exact transaction has already been applied.
tefBAD_ADD_AUTHDEPRECATED.
tefBAD_AUTHThe key used to sign this account is not authorized to modify this account. (It could be authorized if the account had the same key set as the Regular Key.)
tefBAD_AUTH_MASTERThe single signature provided to authorize this transaction does not match the master key, but no regular key is associated with this address.
tefBAD_LEDGERWhile processing the transaction, the ledger was discovered in an unexpected state. If you can reproduce this error, please report an issue to get it fixed.
tefBAD_QUORUMThe transaction was multi-signed, but the total weights of all included signatures did not meet the quorum.
tefBAD_SIGNATUREThe transaction was multi-signed, but contained a signature for an address not part of a SignerList associated with the sending account.
tefCREATEDDEPRECATED.
tefEXCEPTIONWhile processing the transaction, the server entered an unexpected state. This may be caused by unexpected inputs, for example if the binary data for the transaction is grossly malformed. If you can reproduce this error, please report an issue to get it fixed.
tefFAILUREUnspecified failure in applying the transaction.
tefINTERNALWhen trying to apply the transaction, the server entered an unexpected state. If you can reproduce this error, please report an issue to get it fixed.
tefINVARIANT_FAILEDAn invariant check failed when trying to claim the transaction cost. Requires the EnforceInvariants amendment. If you can reproduce this error, please report an issue.
tefMASTER_DISABLEDThe transaction was signed with the account's master key, but the account has the lsfDisableMaster field set.
tefMAX_LEDGERThe transaction included a LastLedgerSequence parameter, but the current ledger's sequence number is already higher than the specified value.
tefNO_AUTH_REQUIREDThe TrustSet transaction tried to mark a trustline as authorized, but the lsfRequireAuth flag is not enabled for the corresponding account, so authorization is not necessary.
tefNOT_MULTI_SIGNINGThe transaction was multi-signed, but the sending account has no SignerList defined.
tefPAST_SEQThe sequence number of the transaction is lower than the current sequence number of the account sending the transaction.
tefWRONG_PRIORThe transaction contained an AccountTxnID field (or the deprecated PreviousTxnID field), but the transaction specified there does not match the account's previous transaction.
-

ter Codes

-

These codes indicate that the transaction failed, but it could apply successfully in the future, usually if some other hypothetical transaction applies first. They have numerical values in the range -99 to -1. The exact code for any given error is subject to change, so don't rely on it.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CodeExplanation
terFUNDS_SPENTDEPRECATED.
terINSUF_FEE_BThe account sending the transaction does not have enough XRP to pay the Fee specified in the transaction.
terLASTUsed internally only. This code should never be returned.
terNO_ACCOUNTThe address sending the transaction is not funded in the ledger (yet).
terNO_AUTHThe transaction would involve adding currency issued by an account with lsfRequireAuth enabled to a trust line that is not authorized. For example, you placed an offer to buy a currency you aren't authorized to hold.
terNO_LINEUsed internally only. This code should never be returned.
terNO_RIPPLEUsed internally only. This code should never be returned.
terOWNERSThe transaction requires that account sending it has a nonzero "owners count", so the transaction cannot succeed. For example, an account cannot enable the lsfRequireAuth flag if it has any trust lines or available offers.
terPRE_SEQThe Sequence number of the current transaction is higher than the current sequence number of the account sending the transaction.
terRETRYUnspecified retriable error.
terQUEUEDThe transaction met the load-scaled transaction cost but did not meet the open ledger requirement, so the transaction has been queued for a future ledger.
-

tes Success

-

The code tesSUCCESS is the only code that indicates a transaction succeeded. This does not always mean it did what it was supposed to do. (For example, an OfferCancel can "succeed" even if there is no offer for it to cancel.) Success uses the numerical value 0.

- - - - - - - - - - - - - -
CodeExplanation
tesSUCCESSThe transaction was applied and forwarded to other servers. If this appears in a validated ledger, then the transaction's success is final.
-

tec Codes

-

These codes indicate that the transaction failed, but it was applied to a ledger to apply the transaction cost. They have numerical values in the range 100 to 199. The exact codes sometimes appear in ledger data, so they do not change, but we recommend not relying on the numeric value regardless.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CodeValueExplanation
tecCLAIM100Unspecified failure, with transaction cost destroyed.
tecCRYPTOCONDITION_ERROR146This EscrowCreate or EscrowFinish transaction contained a malformed or mismatched crypto-condition.
tecDIR_FULL121The address sending the transaction cannot own any more objects in the ledger.
tecDST_TAG_NEEDED143The Payment transaction omitted a destination tag, but the destination account has the lsfRequireDestTag flag enabled. New in: rippled 0.28.0
tecFAILED_PROCESSING105An unspecified error occurred when processing the transaction.
tecFROZEN137The OfferCreate transaction failed because one or both of the assets involved are subject to a global freeze.
tecINSUF_RESERVE_LINE122The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: Reserves) This error occurs when the counterparty already has a trust line in a non-default state to the sending account for the same currency. (See tecNO_LINE_INSUF_RESERVE for the other case.)
tecINSUF_RESERVE_OFFER123The transaction failed because the sending account does not have enough XRP to create a new Offer. (See: Reserves)
tecINSUFFICIENT_RESERVE141The transaction would increase the reserve requirement higher than the sending account's balance. SignerListSet, PaymentChannelCreate, PaymentChannelFund, and EscrowCreate can return this error code. See SignerLists and Reserves for more information.
tecINTERNAL144Unspecified internal error, with transaction cost applied. This error code should not normally be returned. If you can reproduce this error, please report an issue.
tecINVARIANT_FAILED147An invariant check failed when trying to execute this transaction. Requires the EnforceInvariants amendment. If you can reproduce this error, please report an issue.
tecNEED_MASTER_KEY142This transaction tried to cause changes that require the master key, such as disabling the master key or giving up the ability to freeze balances. New in: rippled 0.28.0
tecNO_ALTERNATIVE_KEY130The transaction tried to remove the only available method of authorizing transactions. This could be a SetRegularKey transaction to remove the regular key, a SignerListSet transaction to delete a SignerList, or an AccountSet transaction to disable the master key. (Prior to rippled 0.30.0, this was called tecMASTER_DISABLED.)
tecNO_AUTH134The transaction failed because it needs to add a balance on a trust line to an account with the lsfRequireAuth flag enabled, and that trust line has not been authorized. If the trust line does not exist at all, tecNO_LINE occurs instead.
tecNO_DST124The account on the receiving end of the transaction does not exist. This includes Payment and TrustSet transaction types. (It could be created if it received enough XRP.)
tecNO_DST_INSUF_XRP125The account on the receiving end of the transaction does not exist, and the transaction is not sending enough XRP to create it.
tecNO_ENTRY140Reserved for future use.
tecNO_ISSUER133The account specified in the issuer field of a currency amount does not exist.
tecNO_LINE135The TakerPays field of the OfferCreate transaction specifies an asset whose issuer has lsfRequireAuth enabled, and the account making the offer does not have a trust line for that asset. (Normally, making an offer implicitly creates a trust line if necessary, but in this case it does not bother because you cannot hold the asset without authorization.) If the trust line exists, but is not authorized, tecNO_AUTH occurs instead.
tecNO_LINE_INSUF_RESERVE126The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: Reserves) This error occurs when the counterparty does not have a trust line to this account for the same currency. (See tecINSUF_RESERVE_LINE for the other case.)
tecNO_LINE_REDUNDANT127The transaction failed because it tried to set a trust line to its default state, but the trust line did not exist.
tecNO_PERMISSION139The sender does not have permission to perform this operation. For example, the EscrowFinish transaction tried to release a held payment before its FinishAfter time, or someone tried to use PaymentChannelFund on a channel the sender does not own.
tecNO_REGULAR_KEY131The AccountSet transaction tried to disable the master key, but the account does not have another way to authorize transactions. If multi-signing is enabled, this code is deprecated and tecNO_ALTERNATIVE_KEY is used instead.
tecNO_TARGET138The transaction referenced an Escrow or PayChannel ledger node that doesn't exist, either because it never existed or it has already been deleted. (For example, another EscrowFinish transaction has already executed the held payment.) Alternatively, the destination account has asfDisallowXRP set so it cannot be the destination of this PaymentChannelCreate or EscrowCreate transaction.
tecOVERSIZE145This transaction could not be processed, because the server created an excessively large amount of metadata when it tried to apply the transaction. New in: rippled 0.29.0-hf1
tecOWNERS132The transaction requires that account sending it has a nonzero "owners count", so the transaction cannot succeed. For example, an account cannot enable the lsfRequireAuth flag if it has any trust lines or available offers.
tecPATH_DRY128The transaction failed because the provided paths did not have enough liquidity to send anything at all. This could mean that the source and destination accounts are not linked by trust lines.
tecPATH_PARTIAL101The transaction failed because the provided paths did not have enough liquidity to send the full amount.
tecUNFUNDED129The transaction failed because the account does not hold enough XRP to pay the amount in the transaction and satisfy the additional reserve necessary to execute this transaction. (See: Reserves)
tecUNFUNDED_ADD102DEPRECATED.
tecUNFUNDED_PAYMENT104The transaction failed because the sending account is trying to send more XRP than it holds, not counting the reserve. (See: Reserves)
tecUNFUNDED_OFFER103The OfferCreate transaction failed because the account creating the offer does not have any of the TakerGets currency.
- -
-
-
- - - - \ No newline at end of file diff --git a/ripple-api-tool.html b/ripple-api-tool.html deleted file mode 100644 index 0c4395831a..0000000000 --- a/ripple-api-tool.html +++ /dev/null @@ -1,211 +0,0 @@ - - - - - - - - WebSocket API Tool - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-
Offline
-
-
-
-
-
-

WebSocket Request

- -
-

server_info

-

-
Invalid JSON
-

JSON

-
-
-
Send request
-
-
-
-

Response

-
- -
-

-
-
-
-

Stream output

-
    -
  • show
    • -
  • pause
    • -
-

-
-
-
-
-
-
-
-
- - - - - - - - - - - \ No newline at end of file diff --git a/tool-jsonrpc.html b/tool-jsonrpc.html deleted file mode 100644 index 0277b8d61f..0000000000 --- a/tool-jsonrpc.html +++ /dev/null @@ -1,184 +0,0 @@ - - - - - - - - rippled JSON-RPC Tool - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-
-
-
-
-
-

REST Request

- -
-

-

-
Invalid JSON
-
-

http://localhost/rippled

-
-
- -
-
-

Response

-
- - -
-
-
-
-
-
-
-
- -
-
- - - - - - - - - - - - - - \ No newline at end of file diff --git a/tutorial-escrow.html b/tutorial-escrow.html deleted file mode 100644 index b73ab14877..0000000000 --- a/tutorial-escrow.html +++ /dev/null @@ -1,972 +0,0 @@ - - - - - - - - Escrow Tutorials - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

Escrow Tutorials

-

The XRP Ledger supports held payments, or escrows, that can be executed only after a certain time has passed or a cryptographic condition has been fulfilled. Escrows can only send XRP, not issued currencies. You can use these features to build publicly-provable smart contracts. This article explains basic tasks relating to held payments.

- -

Availability of Escrow

-

Held payments been enabled by the "Escrow" Amendment to the XRP Ledger Consensus Protocol since 2017-03-31. A previous version of the same functionality was available on the Ripple Test Net by the name "Suspended Payments" (SusPay) in 2016.

-

When testing in stand-alone mode, you can force the Escrow feature to be enabled locally regardless of the amendment status. Add the following stanza to your rippled.cfg:

-
[features]
-Escrow
-
-

You can check the status of the Escrow amendment using the feature command.

-

Send a Time-Held Escrow

-

The EscrowCreate transaction type can create an escrow whose only condition for release is that a specific time has passed. To do this, use the FinishAfter field and omit the Condition field.

-

1. Calculate release time

-

You must specify the time as whole seconds since the Ripple Epoch, which is 946684800 seconds after the UNIX epoch. For example, to release funds at midnight UTC on November 13, 2017:

-
- -
// JavaScript Date() is natively expressed in milliseconds; convert to seconds
-const release_date_unix = Math.floor( new Date("2017-11-13T00:00:00Z") / 1000 );
-const release_date_ripple = release_date_unix - 946684800;
-console.log(release_date_ripple);
-// 563846400
-
- -
-

Warning: If you use a UNIX time in the FinishAfter field without converting to the equivalent Ripple time first, that sets the unlock time to an extra 30 years in the future!

-

2. Submit EscrowCreate transaction

-

Sign and submit an EscrowCreate transaction. Set the FinishAfter field of the transaction to the time when the held payment should be released. Omit the Condition field to make time the only condition for releasing the held payment. Set the Destination to the recipient, which may be the same address as the sender.

-

Caution: Never submit a secret key to a server you do not control. Do not send a secret key unencrypted over the network.

-

Request:

-
- -
{
-  "id": 2,
-  "command": "submit",
-  "secret": "s████████████████████████████",
-  "tx_json": {
-      "Account": "rajgkBmMxmz161r8bWYH7CQAFZP5bA9oSG",
-      "TransactionType": "EscrowCreate",
-      "Amount": "10000",
-      "Destination": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-      "FinishAfter": 557020800
-  }
-}
-
-
-

Response:

-
- -
{
-  "id": 2,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "engine_result": "tesSUCCESS",
-    "engine_result_code": 0,
-    "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
-    "tx_blob": "1200012280000000240000000120252133768061400000000000271068400000000000000A732103C3555B7339FFDDB43495A8371A3A87B4C66B67D49D06CB9BA1FDBFEEB57B6E437446304402203C9AA4C21E1A1A7427D41583283E7A513DDBDD967B246CADD3B2705D858A7A8E02201BEA7B923B18910EEB9F306F6DE3B3F53549BBFAD46335B62B4C34A6DCB4A47681143EEB46C355B04EE8D08E8EED00F422895C79EA6A83144B4E9C06F24296074F7BC48F92A97916C6DC5EA9",
-    "tx_json": {
-      "Account": "rajgkBmMxmz161r8bWYH7CQAFZP5bA9oSG",
-      "Amount": "10000",
-      "Destination": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-      "Fee": "10",
-      "FinishAfter": 557020800,
-      "Flags": 2147483648,
-      "Sequence": 1,
-      "SigningPubKey": "03C3555B7339FFDDB43495A8371A3A87B4C66B67D49D06CB9BA1FDBFEEB57B6E43",
-      "TransactionType": "EscrowCreate",
-      "TxnSignature": "304402203C9AA4C21E1A1A7427D41583283E7A513DDBDD967B246CADD3B2705D858A7A8E02201BEA7B923B18910EEB9F306F6DE3B3F53549BBFAD46335B62B4C34A6DCB4A476",
-      "hash": "55B2057332F8999208C43BA1E7091B423A16E5ED2736C06300B4076085205263"
-    }
-  }
-}
-
-
-

Take note of the transaction's identifying hash value so you can check its final status when it is included in a validated ledger version.

-

3. Wait for validation

-

On the live network or the Ripple Test Net, you can wait 4-7 seconds for the ledger to close automatically.

-

If you're running rippled in stand-alone mode, use the ledger_accept command to manually close the ledger.

-

4. Confirm that the escrow was created

-

Use the tx command with the transaction's identifying hash to check its final status. Look for a CreatedNode in the transaction metadata to indicate that it created an Escrow ledger object.

-

Request:

-
- -
{
-  "id": 3,
-  "command": "tx",
-  "transaction": "55B2057332F8999208C43BA1E7091B423A16E5ED2736C06300B4076085205263"
-}
-
-
-

Response:

-
- -
{
-  "id": 3,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "Account": "rajgkBmMxmz161r8bWYH7CQAFZP5bA9oSG",
-    "Amount": "10000",
-    "Destination": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-    "Fee": "10",
-    "FinishAfter": 557020800,
-    "Flags": 2147483648,
-    "Sequence": 1,
-    "SigningPubKey": "03C3555B7339FFDDB43495A8371A3A87B4C66B67D49D06CB9BA1FDBFEEB57B6E43",
-    "TransactionType": "EscrowCreate",
-    "TxnSignature": "304402203C9AA4C21E1A1A7427D41583283E7A513DDBDD967B246CADD3B2705D858A7A8E02201BEA7B923B18910EEB9F306F6DE3B3F53549BBFAD46335B62B4C34A6DCB4A476",
-    "date": 557014081,
-    "hash": "55B2057332F8999208C43BA1E7091B423A16E5ED2736C06300B4076085205263",
-    "inLedger": 1828796,
-    "ledger_index": 1828796,
-    "meta": {
-      "AffectedNodes": [
-        {
-          "ModifiedNode": {
-            "LedgerEntryType": "AccountRoot",
-            "LedgerIndex": "13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8",
-            "PreviousTxnID": "613B28E0890FC975F2CBA3D700F75116F623B1E3FE48CB7CB2EB216EAD6F097D",
-            "PreviousTxnLgrSeq": 1799920
-          }
-        },
-        {
-          "CreatedNode": {
-            "LedgerEntryType": "Escrow",
-            "LedgerIndex": "2B9845CB9DF686B9615BF04F3EC66095A334D985E03E71B893B90FCF6D4DC9E6",
-            "NewFields": {
-              "Account": "rajgkBmMxmz161r8bWYH7CQAFZP5bA9oSG",
-              "Amount": "10000",
-              "Destination": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-              "FinishAfter": 557020800
-            }
-          }
-        },
-        {
-          "ModifiedNode": {
-            "FinalFields": {
-              "Account": "rajgkBmMxmz161r8bWYH7CQAFZP5bA9oSG",
-              "Balance": "9999989990",
-              "Flags": 0,
-              "OwnerCount": 1,
-              "Sequence": 2
-            },
-            "LedgerEntryType": "AccountRoot",
-            "LedgerIndex": "AE5AB6584A76C37C7382B6880609FC7792D90CDA36FF362AF412EB914C1715D3",
-            "PreviousFields": {
-              "Balance": "10000000000",
-              "OwnerCount": 0,
-              "Sequence": 1
-            },
-            "PreviousTxnID": "F181D45FD094A7417926F791D9DF958B84CE4B7B3D92CC9DDCACB1D5EC59AAAA",
-            "PreviousTxnLgrSeq": 1828732
-          }
-        },
-        {
-          "CreatedNode": {
-            "LedgerEntryType": "DirectoryNode",
-            "LedgerIndex": "D623EBEEEE701D4323D0ADA5320AF35EA8CC6520EBBEF69343354CD593DABC88",
-            "NewFields": {
-              "Owner": "rajgkBmMxmz161r8bWYH7CQAFZP5bA9oSG",
-              "RootIndex": "D623EBEEEE701D4323D0ADA5320AF35EA8CC6520EBBEF69343354CD593DABC88"
-            }
-          }
-        }
-      ],
-      "TransactionIndex": 3,
-      "TransactionResult": "tesSUCCESS"
-    },
-    "validated": true
-  }
-}
-
-
-

5. Wait for the release time

-

Held payments with a FinishAfter time cannot be finished until a ledger has already closed with a close_time header field that is later than the Escrow node's FinishAfter time.

-

You can check the close time of the most recently-validated ledger with the ledger command:

-

Request:

-
- -
{
-  "id": 4,
-  "command": "ledger",
-  "ledger_index": "validated"
-}
-
-
-

Response:

-
- -
{
-  "id": 4,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "ledger": {
-      "accepted": true,
-      "account_hash": "3B5A8FF5334F94F4D3D09F236F9D1B4C028FCAE30948ACC986D461DDEE1D886B",
-      "close_flags": 0,
-      "close_time": 557256670,
-      "close_time_human": "2017-Aug-28 17:31:10",
-      "close_time_resolution": 10,
-      "closed": true,
-      "hash": "A999223A80174A7CB39D766B625C9E476F24AD2F15860A712CD029EE5ED1C320",
-      "ledger_hash": "A999223A80174A7CB39D766B625C9E476F24AD2F15860A712CD029EE5ED1C320",
-      "ledger_index": "1908253",
-      "parent_close_time": 557256663,
-      "parent_hash": "6A70C5336ACFDA05760D827776079F7A544D2361CFD5B21BD55A92AA20477A61",
-      "seqNum": "1908253",
-      "totalCoins": "99997280690562728",
-      "total_coins": "99997280690562728",
-      "transaction_hash": "49A51DFB1CAB2F134D93D5D1C5FF55A15B12DA36DAF9F5862B17C47EE966647D"
-    },
-    "ledger_hash": "A999223A80174A7CB39D766B625C9E476F24AD2F15860A712CD029EE5ED1C320",
-    "ledger_index": 1908253,
-    "validated": true
-  }
-}
-
-
-

6. Submit EscrowFinish transaction

-

Sign and submit an EscrowFinish transaction to execute the release of the funds after the FinishAfter time has passed. Set the Owner field of the transaction to the Account address from the EscrowCreate transaction, and the OfferSequence to the Sequence number from the EscrowCreate transaction. For an escrow held only by time, omit the Condition and Fulfillment fields.

-

Tip: The EscrowFinish transaction is necessary because the XRP Ledger's state can only be modified by transactions. The sender of this transaction may be the recipient of the escrow, the original sender of the escrow, or any other XRP Ledger address.

-

Caution: Never submit a secret key to a server you do not control. Do not send a secret key unencrypted over the network.

-

Request:

-
- -
{
-  "id": 5,
-  "command": "submit",
-  "secret": "s████████████████████████████",
-  "tx_json": {
-    "Account": "rajgkBmMxmz161r8bWYH7CQAFZP5bA9oSG",
-    "TransactionType": "EscrowFinish",
-    "Owner": "rajgkBmMxmz161r8bWYH7CQAFZP5bA9oSG",
-    "OfferSequence": 1
-  }
-}
-
-
-

Response:

-
- -
{
-  "id": 5,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "engine_result": "tesSUCCESS",
-    "engine_result_code": 0,
-    "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
-    "tx_blob": "1200022280000000240000000220190000000168400000000000000A732103C3555B7339FFDDB43495A8371A3A87B4C66B67D49D06CB9BA1FDBFEEB57B6E4374473045022100923B91BA4FD6450813F5335D71C64BA9EB81304A86859A631F2AD8571424A46502200CCE660D36781B84634C5F23619EB6CFCCF942709F54DCCF27CF6F499AE78C9B81143EEB46C355B04EE8D08E8EED00F422895C79EA6A82143EEB46C355B04EE8D08E8EED00F422895C79EA6A",
-    "tx_json": {
-      "Account": "rajgkBmMxmz161r8bWYH7CQAFZP5bA9oSG",
-      "Fee": "10",
-      "Flags": 2147483648,
-      "OfferSequence": 1,
-      "Owner": "rajgkBmMxmz161r8bWYH7CQAFZP5bA9oSG",
-      "Sequence": 2,
-      "SigningPubKey": "03C3555B7339FFDDB43495A8371A3A87B4C66B67D49D06CB9BA1FDBFEEB57B6E43",
-      "TransactionType": "EscrowFinish",
-      "TxnSignature": "3045022100923B91BA4FD6450813F5335D71C64BA9EB81304A86859A631F2AD8571424A46502200CCE660D36781B84634C5F23619EB6CFCCF942709F54DCCF27CF6F499AE78C9B",
-      "hash": "41856A742B3CAF307E7B4D0B850F302101F0F415B785454F7501E9960A2A1F6B"
-    }
-  }
-}
-
-
-

Take note of the transaction's identifying hash value so you can check its final status when it is included in a validated ledger version.

-

7. Wait for validation

-

On the live network or the Ripple Test Net, you can wait 4-7 seconds for the ledger to close automatically.

-

If you're running rippled in stand-alone mode, use the ledger_accept command to manually close the ledger.

-

8. Confirm final result

-

Use the tx command with the EscrowFinish transaction's identifying hash to check its final status. In particular, look in the transaction metadata for a ModifiedNode of type AccountRoot for the destination of the escrowed payment. The FinalFields of the object should reflect the increase in XRP in the Balance field.

-

Request:

-
- -
{
-  "id": 21,
-  "command": "tx",
-  "transaction": "41856A742B3CAF307E7B4D0B850F302101F0F415B785454F7501E9960A2A1F6B"
-}
-
-
-

Response:

-
- -
{
-  "id": 21,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "Account": "rajgkBmMxmz161r8bWYH7CQAFZP5bA9oSG",
-    "Fee": "10",
-    "Flags": 2147483648,
-    "OfferSequence": 1,
-    "Owner": "rajgkBmMxmz161r8bWYH7CQAFZP5bA9oSG",
-    "Sequence": 2,
-    "SigningPubKey": "03C3555B7339FFDDB43495A8371A3A87B4C66B67D49D06CB9BA1FDBFEEB57B6E43",
-    "TransactionType": "EscrowFinish",
-    "TxnSignature": "3045022100923B91BA4FD6450813F5335D71C64BA9EB81304A86859A631F2AD8571424A46502200CCE660D36781B84634C5F23619EB6CFCCF942709F54DCCF27CF6F499AE78C9B",
-    "date": 557256681,
-    "hash": "41856A742B3CAF307E7B4D0B850F302101F0F415B785454F7501E9960A2A1F6B",
-    "inLedger": 1908257,
-    "ledger_index": 1908257,
-    "meta": {
-      "AffectedNodes": [
-        {
-          "ModifiedNode": {
-            "FinalFields": {
-              "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-              "Balance": "400210000",
-              "Flags": 0,
-              "OwnerCount": 0,
-              "Sequence": 1
-            },
-            "LedgerEntryType": "AccountRoot",
-            "LedgerIndex": "13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8",
-            "PreviousFields": {
-              "Balance": "400200000"
-            },
-            "PreviousTxnID": "55B2057332F8999208C43BA1E7091B423A16E5ED2736C06300B4076085205263",
-            "PreviousTxnLgrSeq": 1828796
-          }
-        },
-        {
-          "DeletedNode": {
-            "FinalFields": {
-              "Account": "rajgkBmMxmz161r8bWYH7CQAFZP5bA9oSG",
-              "Amount": "10000",
-              "Destination": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-              "FinishAfter": 557020800,
-              "Flags": 0,
-              "OwnerNode": "0000000000000000",
-              "PreviousTxnID": "55B2057332F8999208C43BA1E7091B423A16E5ED2736C06300B4076085205263",
-              "PreviousTxnLgrSeq": 1828796
-            },
-            "LedgerEntryType": "Escrow",
-            "LedgerIndex": "2B9845CB9DF686B9615BF04F3EC66095A334D985E03E71B893B90FCF6D4DC9E6"
-          }
-        },
-        {
-          "ModifiedNode": {
-            "FinalFields": {
-              "Account": "rajgkBmMxmz161r8bWYH7CQAFZP5bA9oSG",
-              "Balance": "9999989980",
-              "Flags": 0,
-              "OwnerCount": 0,
-              "Sequence": 3
-            },
-            "LedgerEntryType": "AccountRoot",
-            "LedgerIndex": "AE5AB6584A76C37C7382B6880609FC7792D90CDA36FF362AF412EB914C1715D3",
-            "PreviousFields": {
-              "Balance": "9999989990",
-              "OwnerCount": 1,
-              "Sequence": 2
-            },
-            "PreviousTxnID": "55B2057332F8999208C43BA1E7091B423A16E5ED2736C06300B4076085205263",
-            "PreviousTxnLgrSeq": 1828796
-          }
-        },
-        {
-          "ModifiedNode": {
-            "FinalFields": {
-              "Flags": 0,
-              "Owner": "rajgkBmMxmz161r8bWYH7CQAFZP5bA9oSG",
-              "RootIndex": "D623EBEEEE701D4323D0ADA5320AF35EA8CC6520EBBEF69343354CD593DABC88"
-            },
-            "LedgerEntryType": "DirectoryNode",
-            "LedgerIndex": "D623EBEEEE701D4323D0ADA5320AF35EA8CC6520EBBEF69343354CD593DABC88"
-          }
-        }
-      ],
-      "TransactionIndex": 2,
-      "TransactionResult": "tesSUCCESS"
-    },
-    "validated": true
-  }
-}
-
-
-

Send a conditionally-held escrow

-

1. Generate condition and fulfillment

-

XRP Ledger escrows require PREIMAGE-SHA-256 Crypto-Conditions. To calculate a condition and fulfillment in the proper format, you should use a Crypto-Conditions library such as five-bells-condition. For fulfillments, Ripple recommends using one of the following methods to generate the fulfillment:

-
    -
  • Use a cryptographically secure source of randomness to generate at least 32 random bytes.
    • -
  • Follow Interledger Protocol's PSK specification and use an HMAC-SHA-256 of the ILP packet as the fulfillment.
    • -
-

Example JavaScript code for a random fulfillment and condition:

-
cc = require('five-bells-condition');
-
-const fulfillment_bytes = crypto.randomBytes(32);
-const myFulfillment = new cc.PreimageSha256();
-myFulfillment.setPreimage(fulfillment_bytes);
-console.log(myFulfillment.serializeBinary().toString('hex'));
-// (Random hexadecimal, 72 chars in length)
-console.log(myFulfillment.getConditionBinary().toString('hex'));
-// (Random hexadecimal, 78 chars in length)
-
-

Save the condition and the fulfillment for later. Be sure to keep the fulfillment secret until you want to finish executing the held payment. Anyone who knows the fulfillment can finish the escrow, releasing the held funds to their intended destination.

-

2. Calculate release or cancel time

-

A Conditional Escrow transaction must contain either a CancelAfter or FinishAfter field, or both. The CancelAfter field lets the XRP revert to the sender if the condition is not fulfilled before the specified time. The FinishAfter field specifies a time before which the escrow cannot execute, even if someone sends the correct fulfillment. Whichever field you provide, the time it specifies must be in the future.

-

Example for setting a CancelAfter time of 24 hours in the future:

-
- -
const rippleOffset = 946684800;
-const CancelAfter = Math.floor(Date.now() / 1000) + (24*60*60) - rippleOffset;
-console.log(CancelAfter);
-// Example: 556927412
-
- -
-

Warning: In the XRP Ledger, you must specify time as seconds since the Ripple Epoch (2000-01-01T00:00:00Z). If you use a UNIX time in the CancelAfter or FinishAfter field without converting to the equivalent Ripple time first, that sets the unlock time to an extra 30 years in the future!

-

3. Submit EscrowCreate transaction

-

Sign and submit an EscrowCreate transaction. Set the Condition field of the transaction to the time when the held payment should be released. Set the Destination to the recipient, which can be the same address as the sender. Include the CancelAfter or FinishAfter time you calculated in the previous step.

-

Caution: Never submit a secret key to a server you do not control. Do not send a secret key unencrypted over the network.

-

Request:

-
- -
{
-  "id": 1,
-  "command": "submit",
-  "secret": "s████████████████████████████",
-  "tx_json": {
-    "Account": "rEhw9vD98ZrkY4tZPvkZst5H18RysqFdaB",
-    "TransactionType": "EscrowCreate",
-    "Amount": "100000",
-    "Destination": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-    "Condition": "A0258020E24D9E1473D4DF774F6D8E089067282034E4FA7ECACA2AD2E547953B2C113CBD810120",
-    "CancelAfter": 556927412
-  }
-}
-
-
-

Response:

-
- -
{
-  "id": 1,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "engine_result": "tesSUCCESS",
-    "engine_result_code": 0,
-    "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
-    "tx_blob": "120001228000000024000000052024213209B46140000000000186A068400000000000000A732103E498E35BC1E109C5995BD3AB0A6D4FFAB61B853C8F6010FABC5DABAF34478B61744730450221008AC8BDC2151D5EF956197F0E6E89A4F49DEADC1AC38367870E444B1EA8D88D97022075E31427B455DFF87F0F22B849C71FC3987A91C19D63B6D0242E808347EC8A8F701127A0258020E24D9E1473D4DF774F6D8E089067282034E4FA7ECACA2AD2E547953B2C113CBD81012081149A2AA667E1517EFA8A6B552AB2EDB859A99F26B283144B4E9C06F24296074F7BC48F92A97916C6DC5EA9",
-    "tx_json": {
-      "Account": "rEhw9vD98ZrkY4tZPvkZst5H18RysqFdaB",
-      "Amount": "100000",
-      "CancelAfter": 556927412,
-      "Condition": "A0258020E24D9E1473D4DF774F6D8E089067282034E4FA7ECACA2AD2E547953B2C113CBD810120",
-      "Destination": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-      "Fee": "10",
-      "Flags": 2147483648,
-      "Sequence": 5,
-      "SigningPubKey": "03E498E35BC1E109C5995BD3AB0A6D4FFAB61B853C8F6010FABC5DABAF34478B61",
-      "TransactionType": "EscrowCreate",
-      "TxnSignature": "30450221008AC8BDC2151D5EF956197F0E6E89A4F49DEADC1AC38367870E444B1EA8D88D97022075E31427B455DFF87F0F22B849C71FC3987A91C19D63B6D0242E808347EC8A8F",
-      "hash": "E22D1F6EB006CAD35E0DBD3B4F3748427055E4C143EBE95AA6603823AEEAD324"
-    }
-  }
-}
-
-
-

4. Wait for validation

-

On the live network or the Ripple Test Net, you can wait 4-7 seconds for the ledger to close automatically.

-

If you're running rippled in stand-alone mode, use the ledger_accept command to manually close the ledger.

-

5. Confirm that the escrow was created

-

Use the tx command with the transaction's identifying hash to check its final status. In particular, look for a CreatedNode in the transaction metadata to indicate that it created an Escrow ledger object.

-

Request:

-
- -
{
-  "id": 3,
-  "command": "tx",
-  "transaction": "E22D1F6EB006CAD35E0DBD3B4F3748427055E4C143EBE95AA6603823AEEAD324"
-}
-
-
-

Response:

-
- -
{
-  "id": 3,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "Account": "rEhw9vD98ZrkY4tZPvkZst5H18RysqFdaB",
-    "Amount": "100000",
-    "CancelAfter": 556927412,
-    "Condition": "A0258020E24D9E1473D4DF774F6D8E089067282034E4FA7ECACA2AD2E547953B2C113CBD810120",
-    "Destination": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-    "Fee": "10",
-    "Flags": 2147483648,
-    "Sequence": 5,
-    "SigningPubKey": "03E498E35BC1E109C5995BD3AB0A6D4FFAB61B853C8F6010FABC5DABAF34478B61",
-    "TransactionType": "EscrowCreate",
-    "TxnSignature": "30450221008AC8BDC2151D5EF956197F0E6E89A4F49DEADC1AC38367870E444B1EA8D88D97022075E31427B455DFF87F0F22B849C71FC3987A91C19D63B6D0242E808347EC8A8F",
-    "date": 556841101,
-    "hash": "E22D1F6EB006CAD35E0DBD3B4F3748427055E4C143EBE95AA6603823AEEAD324",
-    "inLedger": 1772019,
-    "ledger_index": 1772019,
-    "meta": {
-      "AffectedNodes": [
-        {
-          "ModifiedNode": {
-            "LedgerEntryType": "AccountRoot",
-            "LedgerIndex": "13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8",
-            "PreviousTxnID": "52C4F626FE6F33699B6BE8ADF362836DDCE9B0B1294BFAA15D65D61501350BE6",
-            "PreviousTxnLgrSeq": 1771204
-          }
-        },
-        {
-          "ModifiedNode": {
-            "FinalFields": {
-              "Flags": 0,
-              "Owner": "rEhw9vD98ZrkY4tZPvkZst5H18RysqFdaB",
-              "RootIndex": "4B4EBB6D8563075813D47491CC325865DFD3DC2E94889F0F39D59D9C059DD81F"
-            },
-            "LedgerEntryType": "DirectoryNode",
-            "LedgerIndex": "4B4EBB6D8563075813D47491CC325865DFD3DC2E94889F0F39D59D9C059DD81F"
-          }
-        },
-        {
-          "ModifiedNode": {
-            "FinalFields": {
-              "Account": "rEhw9vD98ZrkY4tZPvkZst5H18RysqFdaB",
-              "Balance": "9999798970",
-              "Flags": 0,
-              "OwnerCount": 1,
-              "Sequence": 6
-            },
-            "LedgerEntryType": "AccountRoot",
-            "LedgerIndex": "5F3B7107F4B524367A173A2B0EAB66E8CC4D2178C1B0C0528CB2F73A8B6BF254",
-            "PreviousFields": {
-              "Balance": "9999898980",
-              "OwnerCount": 0,
-              "Sequence": 5
-            },
-            "PreviousTxnID": "52C4F626FE6F33699B6BE8ADF362836DDCE9B0B1294BFAA15D65D61501350BE6",
-            "PreviousTxnLgrSeq": 1771204
-          }
-        },
-        {
-          "CreatedNode": {
-            "LedgerEntryType": "Escrow",
-            "LedgerIndex": "E2CF730A31FD419382350C9DBD8DB7CD775BA5AA9B97A9BE9AB07304AA217A75",
-            "NewFields": {
-              "Account": "rEhw9vD98ZrkY4tZPvkZst5H18RysqFdaB",
-              "Amount": "100000",
-              "CancelAfter": 556927412,
-              "Condition": "A0258020E24D9E1473D4DF774F6D8E089067282034E4FA7ECACA2AD2E547953B2C113CBD810120",
-              "Destination": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
-            }
-          }
-        }
-      ],
-      "TransactionIndex": 0,
-      "TransactionResult": "tesSUCCESS"
-    },
-    "validated": true
-  }
-}
-
-
-

6. Submit EscrowFinish transaction

-

Sign and submit an EscrowFinish transaction to execute the release of the funds after the FinishAfter time has passed. Set the Owner field of the transaction to the Account address from the EscrowCreate transaction, and the OfferSequence to the Sequence number from the EscrowCreate transaction. Set the Condition and Fulfillment fields to the condition and fulfillment values, in hexadecimal, that you generated in step 1. Set the Fee (transaction cost) value based on the size of the fulfillment in bytes: a conditional EscrowFinish requires at least 330 drops of XRP plus 10 drops per 16 bytes in the size of the fulfillment.

-

Note: If you included a FinishAfter field in the EscrowCreate transaction, you cannot execute it before that time has passed, even if you provide the correct fulfillment for the Escrow's condition. The EscrowFinish transaction fails with the result code tecNO_PERMISSION if the previously-closed ledger's close time is before the FinishAfter time.

-

Caution: Never submit a secret key to a server you do not control. Do not send a secret key unencrypted over the network.

-
- -
{
-  "id": 4,
-  "command": "submit",
-  "secret": "s████████████████████████████",
-  "tx_json": {
-    "Account": "rEhw9vD98ZrkY4tZPvkZst5H18RysqFdaB",
-    "TransactionType": "EscrowFinish",
-    "Owner": "rEhw9vD98ZrkY4tZPvkZst5H18RysqFdaB",
-    "OfferSequence": 5,
-    "Condition": "A0258020E24D9E1473D4DF774F6D8E089067282034E4FA7ECACA2AD2E547953B2C113CBD810120",
-    "Fulfillment": "A0228020D280D1A02BAD0D2EBC0528B92E9BF37AC3E2530832C2C52620307135156F1048",
-    "Fee": "500"
-  }
-}
-
-
-

Response:

-
- -
{
-  "id": 4,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "engine_result": "tesSUCCESS",
-    "engine_result_code": 0,
-    "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
-    "tx_blob": "120002228000000024000000062019000000056840000000000001F4732103E498E35BC1E109C5995BD3AB0A6D4FFAB61B853C8F6010FABC5DABAF34478B617446304402207DE4EA9C8655E75BA01F96345B3F62074313EB42C15D9C4871E30F02202D2BA50220070E52AD308A31AC71E33BA342F31B68D1D1B2A7A3A3ED6E8552CA3DCF14FBB2701024A0228020D280D1A02BAD0D2EBC0528B92E9BF37AC3E2530832C2C52620307135156F1048701127A0258020E24D9E1473D4DF774F6D8E089067282034E4FA7ECACA2AD2E547953B2C113CBD81012081149A2AA667E1517EFA8A6B552AB2EDB859A99F26B282149A2AA667E1517EFA8A6B552AB2EDB859A99F26B2",
-    "tx_json": {
-      "Account": "rEhw9vD98ZrkY4tZPvkZst5H18RysqFdaB",
-      "Condition": "A0258020E24D9E1473D4DF774F6D8E089067282034E4FA7ECACA2AD2E547953B2C113CBD810120",
-      "Fee": "500",
-      "Flags": 2147483648,
-      "Fulfillment": "A0228020D280D1A02BAD0D2EBC0528B92E9BF37AC3E2530832C2C52620307135156F1048",
-      "OfferSequence": 5,
-      "Owner": "rEhw9vD98ZrkY4tZPvkZst5H18RysqFdaB",
-      "Sequence": 6,
-      "SigningPubKey": "03E498E35BC1E109C5995BD3AB0A6D4FFAB61B853C8F6010FABC5DABAF34478B61",
-      "TransactionType": "EscrowFinish",
-      "TxnSignature": "304402207DE4EA9C8655E75BA01F96345B3F62074313EB42C15D9C4871E30F02202D2BA50220070E52AD308A31AC71E33BA342F31B68D1D1B2A7A3A3ED6E8552CA3DCF14FBB2",
-      "hash": "0E88368CAFC69A722ED829FAE6E2DD3575AE9C192691E60B5ACDF706E219B2BF"
-    }
-  }
-}
-
-
-

Take note of the transaction's identifying hash value so you can check its final status when it is included in a validated ledger version.

-

7. Wait for validation

-

On the live network or the Ripple Test Net, you can wait 4-7 seconds for the ledger to close automatically.

-

If you're running rippled in stand-alone mode, use the ledger_accept command to manually close the ledger.

-

8. Confirm final result

-

Use the tx command with the EscrowFinish transaction's identifying hash to check its final status. In particular, look in the transaction metadata for a ModifiedNode of type AccountRoot for the destination of the escrowed payment. The FinalFields of the object should reflect the increase in XRP in the Balance field.

-

Request:

-
{
-  "id": 20,
-  "command": "tx",
-  "transaction": "52C4F626FE6F33699B6BE8ADF362836DDCE9B0B1294BFAA15D65D61501350BE6"
-}
-
-

Response:

-
{
-  "id": 20,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "Account": "rEhw9vD98ZrkY4tZPvkZst5H18RysqFdaB",
-    "Condition": "A0258020E24D9E1473D4DF774F6D8E089067282034E4FA7ECACA2AD2E547953B2C113CBD810120",
-    "Fee": "500",
-    "Flags": 2147483648,
-    "Fulfillment": "A0228020D280D1A02BAD0D2EBC0528B92E9BF37AC3E2530832C2C52620307135156F1048",
-    "OfferSequence": 2,
-    "Owner": "rEhw9vD98ZrkY4tZPvkZst5H18RysqFdaB",
-    "Sequence": 4,
-    "SigningPubKey": "03E498E35BC1E109C5995BD3AB0A6D4FFAB61B853C8F6010FABC5DABAF34478B61",
-    "TransactionType": "EscrowFinish",
-    "TxnSignature": "3045022100925FEBE21C2E57F81C472A4E5869CAB1D0164C472A46532F39F6F9F7ED6846D002202CF9D9063ADC4CC0ADF4C4692B7EE165C5D124CAA855649389E245D993F41D4D",
-    "date": 556838610,
-    "hash": "52C4F626FE6F33699B6BE8ADF362836DDCE9B0B1294BFAA15D65D61501350BE6",
-    "inLedger": 1771204,
-    "ledger_index": 1771204,
-    "meta": {
-      "AffectedNodes": [
-        {
-          "ModifiedNode": {
-            "FinalFields": {
-              "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-              "Balance": "400100000",
-              "Flags": 0,
-              "OwnerCount": 0,
-              "Sequence": 1
-            },
-            "LedgerEntryType": "AccountRoot",
-            "LedgerIndex": "13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8",
-            "PreviousFields": {
-              "Balance": "400000000"
-            },
-            "PreviousTxnID": "795CBC8AFAAB9DC7BD9944C7FAEABF9BB0802A84520BC649213AD6A2C3256C95",
-            "PreviousTxnLgrSeq": 1770775
-          }
-        },
-        {
-          "ModifiedNode": {
-            "FinalFields": {
-              "Flags": 0,
-              "Owner": "rEhw9vD98ZrkY4tZPvkZst5H18RysqFdaB",
-              "RootIndex": "4B4EBB6D8563075813D47491CC325865DFD3DC2E94889F0F39D59D9C059DD81F"
-            },
-            "LedgerEntryType": "DirectoryNode",
-            "LedgerIndex": "4B4EBB6D8563075813D47491CC325865DFD3DC2E94889F0F39D59D9C059DD81F"
-          }
-        },
-        {
-          "ModifiedNode": {
-            "FinalFields": {
-              "Account": "rEhw9vD98ZrkY4tZPvkZst5H18RysqFdaB",
-              "Balance": "9999898980",
-              "Flags": 0,
-              "OwnerCount": 0,
-              "Sequence": 5
-            },
-            "LedgerEntryType": "AccountRoot",
-            "LedgerIndex": "5F3B7107F4B524367A173A2B0EAB66E8CC4D2178C1B0C0528CB2F73A8B6BF254",
-            "PreviousFields": {
-              "Balance": "9999899480",
-              "OwnerCount": 1,
-              "Sequence": 4
-            },
-            "PreviousTxnID": "5C2A1E7B209A7404D3722A010D331A8C1C853109A47DDF620DE5E3D59F026581",
-            "PreviousTxnLgrSeq": 1771042
-          }
-        },
-        {
-          "DeletedNode": {
-            "FinalFields": {
-              "Account": "rEhw9vD98ZrkY4tZPvkZst5H18RysqFdaB",
-              "Amount": "100000",
-              "Condition": "A0258020E24D9E1473D4DF774F6D8E089067282034E4FA7ECACA2AD2E547953B2C113CBD810120",
-              "Destination": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-              "FinishAfter": 556838185,
-              "Flags": 0,
-              "OwnerNode": "0000000000000000",
-              "PreviousTxnID": "795CBC8AFAAB9DC7BD9944C7FAEABF9BB0802A84520BC649213AD6A2C3256C95",
-              "PreviousTxnLgrSeq": 1770775
-            },
-            "LedgerEntryType": "Escrow",
-            "LedgerIndex": "DC524D17B3F650E7A215B332F418E54AE59B0DFC5392E74958B0037AFDFE8C8D"
-          }
-        }
-      ],
-      "TransactionIndex": 1,
-      "TransactionResult": "tesSUCCESS"
-    },
-    "validated": true
-  }
-}
-
-

Look up escrows by sender

-

All pending escrows are stored in the ledger as Escrow objects. You can look up escrow nodes owned by your address using the account_objects method.

-

Request:

-
- -
{
-  "id": 5,
-  "command": "account_objects",
-  "account": "rEhw9vD98ZrkY4tZPvkZst5H18RysqFdaB",
-  "ledger_index": "validated",
-  "type": "escrow"
-}
-
-
-

Response:

-
- -
{
-  "id": 5,
-  "status": "success",
-  "type": "response",
-  "result": {
-    "account": "rEhw9vD98ZrkY4tZPvkZst5H18RysqFdaB",
-    "account_objects": [
-      {
-        "Account": "rEhw9vD98ZrkY4tZPvkZst5H18RysqFdaB",
-        "Amount": "100000",
-        "CancelAfter": 556927412,
-        "Condition": "A0258020E24D9E1473D4DF774F6D8E089067282034E4FA7ECACA2AD2E547953B2C113CBD810120",
-        "Destination": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-        "Flags": 0,
-        "LedgerEntryType": "Escrow",
-        "OwnerNode": "0000000000000000",
-        "PreviousTxnID": "E22D1F6EB006CAD35E0DBD3B4F3748427055E4C143EBE95AA6603823AEEAD324",
-        "PreviousTxnLgrSeq": 1772019,
-        "index": "E2CF730A31FD419382350C9DBD8DB7CD775BA5AA9B97A9BE9AB07304AA217A75"
-      }
-    ],
-    "ledger_hash": "F2ABEA175F4AB871845B01CB51E4324DBA2C2553EC34448D4AB1EB0A3F2D8EFB",
-    "ledger_index": 1772020,
-    "validated": true
-  }
-}
-
-
-

Tip: If you don't know what OfferSequence to use in the EscrowFinish transaction to execute an escrow, use the tx method to look up the transaction that created the escrow, using the identifying hash of the transaction in the Escrow's PreviousTxnID field. Use the Sequence value of that transaction as the OfferSequence value when finishing the escrow.

-
-
-
- - - - \ No newline at end of file diff --git a/tutorial-gateway-guide.html b/tutorial-gateway-guide.html deleted file mode 100644 index 9c9502b7f7..0000000000 --- a/tutorial-gateway-guide.html +++ /dev/null @@ -1,927 +0,0 @@ - - - - - - - - Gateway Guide - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

Becoming an XRP Ledger Gateway

-

Gateways are the businesses that link the XRP Ledger to the rest of the world. An existing online financial institution can expand to act as a gateway in the the XRP Ledger. By becoming an XRP Ledger gateway, a financial services business can gain several advantages:

-
    -
  • By enabling its customers to send and receive value in the XRP Ledger, the business increases its value proposition to customers.
    • -
  • By accepting payments from the XRP Ledger, the business increases the number of ways that customers can fund accounts at its business, even internationally.
    • -
  • The business can use XRP Ledger-related services as a new source of revenue.
    • -
-

This document explains the concepts and steps necessary to become an XRP Ledger gateway. In this document, we use a fictional online currency exchange named "ACME" and its customers as examples, to show how ACME can expand its business to include being an XRP Ledger gateway.

-

Contact Information

-

You are not on your own. Ripple wants gateways to succeed, so we are here to help. Please contact us if you need help building and growing your gateway.

-
    -
  • Contact partners@ripple.com for enterprise-class integrations, infrastructure advice, and other business development needs.
    • -
  • Contact support@ripple.com for technical questions, clarifications, bug reports, and feature requests.
    • -
-

Gateways Explained

-

Gateways are businesses that provide a way for money and other forms of value to move in and out of the XRP Ledger. There are three major models that gateways can follow, with different purposes and modes of operation.

-
    -
  • An Issuing Gateway receives money (or other assets of value) outside of the XRP Ledger, and creates issuances in the XRP Ledger. This provides a direct way for customers to get money in and out of the XRP Ledger. All currencies in the XRP Ledger, except for XRP, take the form of issuances tied to a specific issuing gateway.
    • -
  • A Private Exchange holds XRP and lets its customers buy and sell that XRP in its own system. Most cryptocurrencies rely on private exchanges to provide a market for the cryptocurrency, but the XRP Ledger has a currency exchange built into the protocol itself.
    • -
  • Merchants accept payment within the XRP Ledger in exchange for goods and services in the outside world. Currently, Ripple (the company) does provide support for merchant operations using the XRP Ledger.
    • -
-

This guide focuses on running an issuing gateway.

-

Trust Lines and Issuances

-

All assets in the XRP Ledger, except for the native cryptocurrency XRP, are represented as issuances, which are digital balances that represent currency or assets of value held by an issuer. Within the XRP Ledger, counterparties can send and trade issuances without requiring intervention from the issuer. Typically, a gateway sends issuances to customers when it receives money in systems and ledgers outside the XRP Ledger, and promises to send money to customers in outside systems in exchange for being repaid in issuances in the XRP Ledger. Issuances get their value from a gateway's agreement to honor the obligation that the issuances represent. No computer system can force an XRP Ledger gateway to honor that obligation.

-

The XRP Ledger has a system of directional accounting relationships, called trust lines, to make sure that users only hold issuances from counterparties they trust.

-

A "trust line" is link between two addresses in the XRP Ledger. A trust line represents an explicit statement of willingness to hold gateway debt obligations. When a customer sends money into the XRP Ledger, a gateway takes custody of those assets outside of Ripple, and sends issuances in the XRP Ledger to the customer's address. When a customer sends money out of the XRP Ledger, she makes an XRP Ledger payment to the gateway, and the gateway credits the customer in its own system of record, or in some other account.

-

XRP

-

XRP is the native cryptocurrency of the XRP Ledger. Like issuances, XRP can be freely sent and exchanged among XRP Ledger addresses. Unlike issuances, XRP is not tied to an accounting relationship. XRP can be sent directly from any XRP Ledger address to any other, without going through a gateway or liquidity provider. This helps make XRP a convenient bridge currency. For more information on XRP, see the XRP Portal.

-

XRP also serves other purposes in the XRP Ledger, in particular as a protective measure against spamming the network. All XRP Ledger addresses need a small amount of XRP to pay the costs of maintaining the XRP Ledger. The transaction cost and reserve are neutral fees denoted in XRP and not paid to any party.

-

Issuing gateways do not need to accumulate or exchange XRP. They must only hold a small balance of XRP to send transactions through the network. The XRP equivalent of $10 USD should be enough for at least one year of transaction costs for a busy gateway.

-

Private exchanges and liquidity providers may choose to hold additional XRP for trading. Ripple (the company) does not promote XRP as a speculative investment.

-

Liquidity and Currency Exchange

-

The XRP Ledger contains a currency exchange, where any user can place and fulfill bids to exchange XRP and issuances in any combination. Cross-currency payments automatically use the currency exchange to convert currency atomically when the transaction is executed. In this way, users who choose make offers in the distributed exchange provide the liquidity that makes the XRP Ledger useful.

-

Currency traders who hold a gateway's issuances can provide liquidity to other popular currencies, without the gateway needing to float a large reserve in various destination currencies. The gateway also does not need to take on the risk of financial exchange. However, a gateway may still want to provide liquidity to XRP or other popular currencies at a baseline rate, especially when the gateway is new to the exchange. If you do provide liquidity, use a different address for trading than your issuing address.

-

Third-party liquidity providers can use the rippled APIs, RippleAPI JavaScript Library, or a third-party client application to access the distributed exchange. Some client applications look up the addresses associated with a gateway using ripple.txt, so it can be helpful to publish a good ripple.txt.

-

Contact partners@ripple.com for help establishing liquidity between your gateway and others.

-

Suggested Business Practices

-

The value of a gateway's issuances in the XRP Ledger comes directly from the trust that customers can redeem them with the gateway when needed. We recommend the following precautions to reduce the risk of business interruptions:

- -

Hot and Cold Wallets

-

In the XRP Ledger, financial institutions typically use multiple XRP Ledger addresses to minimize the risk associated with a compromised secret key. Ripple strongly recommends the following separation of roles:

-
    -
  • One issuing address, also known as a "cold wallet." This address is the hub of the financial institution's accounting relationships in the ledger, but sends as few transactions as possible.
    • -
  • One or more operational addresses, also known as "hot wallets." Automated, internet-connected systems use the secret keys to these addresses to conduct day-to-day business like transfers to customers and partners.
    • -
  • Optional standby addresses, also known as "warm wallets." Trusted human operators use these addresses to transfer money to the operational addresses.
    • -
-

For more information, see Issuing and Operational Addresses

-

Fees and Revenue Sources

-

There are several ways in which a gateway can seek to profit from XRP Ledger integration. These can include:

-
    -
  • Withdrawal and Deposit fees. Gateways typically charge a small fee (such as 1%) for the service of adding or removing money from the XRP Ledger. You have the power to determine the rate you credit people when they move money onto and off of the XRP Ledger through your gateway.
    • -
  • Transfer fees. You can set a percentage fee to charge automatically when customers send each other issuances created by your issuing address. This amount is debited from the XRP Ledger, decreasing your obligation each time your issuances change hands. See TransferRate for details.
    • -
  • Indirect revenue from value added. XRP Ledger integration can provide valuable functionality for your customers that distinguishes your business from your competitors.
    • -
  • Interest on XRP Ledger-backed funds. You can keep the collateral for the funds you issue in XRP Ledger in a bank account that earns interest. Make sure you can always access enough funds to service customer withdrawals.
    • -
  • Financial Exchange. A gateway can also make offers to buy and sell its issuances for other issuances in the XRP Ledger, providing liquidity to cross-currency payments and possibly making a profit. (As with all financial exchange, profits are not guaranteed.)
    • -
-

Choosing Fee Rates

-

Fees imposed by gateways are optional. Higher fees earn more revenue when a gateway's services are used. On the other hand, high fees discourage customers from using your services. Consider the fees that are charged by other gateways, especially ones issuing similar currencies, as well as traditional payment systems outside of the XRP Ledger, such as wire fees. Choosing the right fee structure is a matter of balancing your pricing with what the market is willing to pay.

-

Gateway Compliance

-

Gateways are responsible for complying with local regulations and reporting to the appropriate agencies. Regulations vary by country and state, but may include the reporting and compliance requirements described in the following sections.

-

Know Your Customer (KYC)

-

Know Your Customer (KYC) refers to due diligence activities conducted by a financial institution to determine and verify the identity of its customers in order to prevent use of the institution for criminal activity. Criminal activity in financial terms may include money laundering, terrorist financing, financial fraud, and identity theft. Customers may be individuals, intermediaries, or businesses.

-

The KYC process generally aims to:

-
    -
  • -

    Identify the customer (and, in the case of organizations and businesses, any beneficial owners)

    -
    • -
  • -

    Understand the purpose and intended nature of the business relationship

    -
    • -
  • -

    Understand the expected transaction activity.

    -
    • -
-

KYC is critical for financial institutions and related businesses to mitigate risk, especially legal and reputational risk. Having an inadequate or nonexistent KYC program may result in civil and criminal penalties for the institution or individual employees.

-

See also:

- -

Anti-Money Laundering (AML) and Combating the Financing of Terrorism (CFT)

-

Money laundering is the process of moving illegal funds by disguising the source, nature or ownership so that funds can be legally accessed or distributed via legitimate financial channels and credible institutions. In short, it is converting “dirty money” into “clean money.” Anti-Money Laundering (AML) refers to the laws and procedures designed to stop money laundering from occurring.

-

Terrorist financing is the solicitation, collection, and/or provision of funds to organizations engaged in terrorist activity or organizations that support terrorism and its proliferation. Combating the Financing of Terrorism (CFT) refers to the process of identifying, reporting, and blocking flows of funds used to finance terrorism.

-

See also:

- -

Source of Funds

-

To prevent illicit funds from passing through their systems, financial institutions must be able to determine within reason if the source of a customer’s funds is linked to criminal activity.

-

Determining the exact source of funds for every customer may not be administratively feasible. As a result, some regulatory authorities may not provide specific regulation or guidance for all accounts. In specific cases, however, authorities may require financial institutions to identify and report the source of funds. Guidance by the FATF recommends that where the risks of money laundering or terrorist financing are higher (commonly referred to as a “risk-based approach”), financial institutions conduct enhanced due diligence, including but not limited to determining the customer’s source of funds.

-

Suspicious Activity Reporting

-

If a financial institution suspects that funds may be related to criminal activity, the institution must file a Suspicious Activity Report (SAR) with the appropriate regulatory authority. Failure to report suspicious activity may result in in penalties for the institution.

-

See also:

- -

Travel Rule

-

The Travel Rule is a Bank Secrecy Act (BSA) rule requiring funds-transmitting financial institutions to forward certain information to the next financial institution if the funds transmittal equals or exceeds the USD equivalent of $3,000. The following information must be included in the transmittal order:

-
    -
  • The name of the transmittor,
    • -
  • The account number of the transmittor, if used,
    • -
  • The address of the transmittor,
    • -
  • The identity of the transmittor's financial institution,
    • -
  • The amount of the transmittal order,
    • -
  • The execution date of the transmittal order, and
    • -
  • The identity of the recipient's financial institution.
    • -
-

See also:

- -

Fee Disclosure and Tracing Funds

- -

Office of Foreign Assets Control (OFAC)

-

The Office of Foreign Assets Control (OFAC) is an agency of the US Department of Treasury that administers and enforces economic and trade sanctions in support of U.S. foreign policy and national security objectives. All U.S. persons and U.S. incorporated entities and their foreign branches must comply with OFAC regulations. Under OFAC regulations, U.S. financial institutions are prohibited—unless authorized by OFAC or expressly exempted by statute—from conducting transactions and other dealings with individuals, entities, or countries under sanctions or embargo programs administered and enforced by OFAC.

-

See also:

- -

Guidance on Virtual Currency and Money Service Business

- -

XRP Ledger Integration

-

Before Integration

-

Our example exchange, ACME, already accepts withdrawals and deposits from customers using some existing system, and uses its own system of record to track how much balance each user has with the exchange. Such a system can be modeled with a balance sheet and tracking how much currency each user has with ACME.

-

In the following diagram, ACME Exchange starts with €5 on hand, including €1 that belongs to Bob, €2 that belongs to Charlie, and an additional €2 of equity that belongs to ACME itself. Alice deposits €5, so ACME adds her to its balance sheet and ends up with €10.

-

Diagram: Alice sends €5 to ACME. ACME adds her balance to its balance sheet.

-

Assumptions: To integrate with the XRP Ledger, we assume that an exchange such as ACME meets the following assumptions:

-
    -
  • ACME already has a system to accept deposits and withdrawals from some outside payment source.
    • -
  • ACME waits for deposits to clear before crediting them in ACME's system of record.
    • -
  • ACME always keeps enough funds on-hand to pay withdrawals on demand, subject to their terms and conditions.
      -
    • ACME can set fees, minimum withdrawals, and delay times for deposits and withdrawals as their business model demands.
      • -
    -
    • -
-

Sending from Gateway to the XRP Ledger

-

XRP Ledger payments can automatically bridge between currencies, but an issuing gateway normally only sends single-currency payments that go directly to customers. This means debiting a customer's current balance in your system, and then sending the equivalent amount of issuances in the XRP Ledger to the customer's XRP Ledger address.

-

An example flow for a payment into the XRP Ledger:

-
    -
  1. Alice asks to send €3 of her ACME balance into the XRP Ledger.
    2. -
  2. In its system of record, ACME debits Alice's balance €3.
    3. -
  3. ACME submits an XRP Ledger transaction, sending €3 to Alice's XRP Ledger address. The €3 is marked in the XRP Ledger as being "issued" by ACME (3 EUR.ACME).
    4. -
-

Assumptions:

-
    -
  • Alice already has an address in the XRP Ledger separate from her ACME account. Alice manages her XRP Ledger address using a third-party client application.
    • -
-

Diagram: ACME issues 3 EUR.ACME to Alice on the XRP Ledger

-

Requirements for Sending to XRP Ledger

-

There are several prerequisites that ACME must meet for this to happen:

-
    -
  • ACME sets aside money that is issued in the XRP Ledger. ACME can query the XRP Ledger to see who holds its issuances at any time. There are several ways ACME may do this:
      -
    • ACME may create a XRP Ledger collateral account in ACME's system of record.
      • -
    • ACME can store the funds allocated to the XRP Ledger in a separate bank account.
      • -
    • If ACME is a cryptocurrency exchange, ACME can create a separate wallet to hold the funds allocated to the XRP Ledger, as publicly-verifiable proof to customers that the gateway is solvent.
      • -
    -
    • -
  • ACME must control an address in the XRP Ledger. Ripple's best practices recommend using a separate issuing address and operational address. See Issuing and Operational Addresses for details.
      -
    • ACME must enable the DefaultRipple Flag on its issuing address for customers to send and receive its issuances.
      • -
    -
    • -
  • Alice must create an accounting relationship (trust line) from her XRP Ledger address to ACME's issuing address. She can do this from any XRP Ledger client application as long as she knows ACME's issuing address.
      -
    • ACME should publicize its issuing address on its website where customers can find it. It can also use ripple.txt to publish the issuing address to automated systems.
      • -
    -
    • -
  • ACME must create a user interface for Alice to send funds from ACME into the XRP Ledger.
      -
    • ACME needs to know Alice's XRP Ledger address. ACME can have Alice input her XRP Ledger addresss as part of the interface, or ACME can require Alice to input and verify her XRP Ledger address in advance.
      • -
    -
    • -
-

See Sending Payments to Customers for an example of how to send payments into the XRP Ledger.

-

Sending from XRP Ledger to Gateway

-

A payment out of the XRP Ledger means the Gateway receives a payment in the XRP Ledger, and credits a user in the gateway's system of record.

-

An example flow of a payment out of the XRP Ledger:

-
    -
  1. Bob sends an XRP Ledger transaction of €1 to ACME's issuing address.
    2. -
  2. In ACME's system of record, ACME credits Bob's balance €1.
    3. -
-

Payments going from the XRP Ledger to a gateway can be single-currency or cross-currency payments. The gateway's issuing address can only receive issuances it created (or XRP).

-

Requirements for Receiving from XRP Ledger

-

In addition to the requirements for sending into the XRP Ledger, there are several prerequisites that ACME must meet to process payments coming from the XRP Ledger:

-
    -
  • ACME must monitor its XRP Ledger addresses for incoming payments.
    • -
  • ACME must know which user to credit in its system of record for the incoming payments. -
    • -
-

Precautions

-

Processing payments to and from the XRP Ledger naturally comes with some risks, so a gateway should be sure to take care in implementing these processes. We recommend the following precautions:

-
    -
  • Protect yourself against reversible deposits. XRP Ledger payments are irreversible, but many electronic money systems like credit cards or PayPal are not. Scammers can abuse this to take their fiat money back by canceling a deposit after receiving Ripple issuances.
    • -
  • When sending into the XRP Ledger, specify the issuing address as the issuer of the currency. Otherwise, you might accidentally use paths that deliver the same currency issued by other addresses.
    • -
  • Before sending a payment into the XRP Ledger, double check the cost of the payment. A payment from your operational address to a customer should not cost more than the destination amount plus any transfer fee you have set.
    • -
  • Before processing a payment out of Ripple, make sure you know the customer's identity. This makes it harder for anonymous attackers to scam you. Most anti-money-laundering regulations require this anyway. This is especially important because the users sending money from the XRP Ledger could be different than the ones that initially received the money in the XRP Ledger.
    • -
  • Follow the guidelines for reliable transaction submission when sending XRP Ledger transactions.
    • -
  • Robustly monitor for incoming payments, and read the correct amount. Don't mistakenly credit someone the full amount if they only sent a partial payment.
    • -
  • Track your obligations and balances within the XRP Ledger, and compare with the assets in your collateral account. If they do not match up, stop processing withdrawals and deposits until you resolve the discrepancy.
    • -
  • Avoid ambiguous situations. We recommend the following:
      -
    • Enable the DisallowXRP flag for the issuing address and all operational addresses, so customers do not accidentally send you XRP. (Private exchanges should not set this flag, since they trade XRP normally.)
      • -
    • Enable the RequireDest flag for the issuing address and all operational addresses, so customers do not accidentally send a payment without the destination tag to indicate who should be credited.
      • -
    • Enable the RequireAuth flag on all operational addresses so they cannot issue currency by accident.
      • -
    -
    • -
  • Monitor for suspicious or abusive behavior. For example, a user could repeatedly send funds into and out of the XRP Ledger, as a denial of service attack that effectively empties an operational address's balance. Suspend customers whose addresses are involved in suspicious behavior by not processing their XRP Ledger payments.
    • -
-

Trading on Ripple

-

After the issuances have been created in the XRP Ledger, they can be freely transferred and traded by XRP Ledger users. There are several consequences of this situation:

-
    -
  • Anyone can buy/sell EUR.ACME on Ripple. If ACME issues multiple currencies on Ripple, a separate trust line is necessary for each.
      -
    • This includes XRP Ledger users who do not have an account in ACME Exchange's systems. To withdraw the funds successfully from ACME, users still have to register with ACME.
      • -
    • Optionally, ACME uses the Authorized Accounts feature to limit who can hold EUR.ACME in the XRP Ledger.
      • -
    • If ACME determines that a customer has acted in bad faith, ACME can Freeze that user's accounting relationships to ACME in the XRP Ledger, so that the user can no longer trade in the gateway's issuances.
      • -
    -
    • -
  • XRP Ledger users trading and sending EUR.ACME to one another requires no intervention by ACME.
    • -
  • All exchanges and balances in the XRP Ledger are publicly viewable.
    • -
-

The following diagram depicts an XRP Ledger payment sending 2EUR.ACME from Alice to Charlie. ACME can query the XRP Ledger to see updates to its balances any time after the transaction has occurred:

-

Diagram: Alice's sends 2 EUR.ACME from her trust line to Charlie's

-

Freeze

-

A gateway can freeze accounting relationships in the XRP Ledger to meet regulatory requirements:

-
    -
  • Gateways can freeze individual accounting relationships, in case a customer address shows suspicious activity or violates a gateway's terms of use.
    • -
  • Gateways can freeze all accounting relationships to their issuing address, in case of a major security compromise or for migrating to a new issuing address.
    • -
  • Furthermore, gateways can permanently opt out of their ability to freeze accounting relationships. This allows a gateway to assure its customers that it will continue to provide "physical-money-like" services.
    • -
-

For more information, see the Freeze article.

-

Authorized Accounts

-

The XRP Ledger's Authorized Accounts feature enables a gateway to limit who can hold that gateway's issuances, so that unknown XRP Ledger addresses cannot hold the currency the gateway issues. Ripple feels this is not necessary in most cases, since gateways have full control over the process of redeeming Ripple balances for value in the outside world. (You can collect customer information and impose limits on withdrawals at that stage without worrying about what happens within the XRP Ledger.)

-

To use the Authorized Accounts feature, a gateway enables the RequireAuth flag for its issuing address, and then individually approves each accounting relationship. An address can only hold funds issued by a gateway after its accounting relationship with that gateway is approved.

-

The transaction to authorize an accounting relationship must be signed by the issuing address, which unfortunately means an increased risk exposure for that address. The process for sending funds into the XRP Ledger with RequireAuth enabled looks like the following:

-
    -
  1. ACME publishes its issuing address to customers.
    2. -
  2. Alice creates an accounting relationship from her XRP Ledger address to ACME's issuing address, indicating that she is willing to hold ACME's issuances.
    3. -
  3. ACME's issuing address sends a transaction authorizing Alice's accounting relationship.
    4. -
-

See RequireAuth for technical details on how to use Authorized Accounts.

-

Source and Destination Tags

-

Destination Tags are a feature of XRP Ledger payments can be used to indicate the beneficiary or destination for a payment. For example, an XRP Ledger payment to a gateway may include a destination tag to indicate which customer should be credited for the payment. A gateway should keep a mapping of destination tags to accounts in the gateway's system of record.

-

Similarly, Source Tags indicate the originator or source of a payment. Most commonly, a Source Tag is included so that the recipient of the payment knows where to bounce the payment. When you bounce an incoming payment, use the Source Tag from the incoming payment as the Destination Tag of the outgoing (bounce) payment.

-

We recommend providing several kinds of Destination Tags for different purposes:

-
    -
  • Direct mappings to customer accounts
    • -
  • Matching the Source Tags on outgoing payments (in case your payments get bounced)
    • -
  • Tags for quotes, which expire
    • -
  • Other disposable destination tags that customers can generate.
    • -
-

See Generating Source and Destination Tags for recommendations on the technical details of making and using Source Tags and Destination Tags.

-

Gateway Bulletins

-

Historically, Ripple (the company) issued gateway bulletins to introduce new features or discuss topics related to compliance and risk. Gateway Bulletins are listed here in reverse chronological order.

- -

Technical Details

-

Infrastructure

-

For the gateway's own security as well as the stability of the network, Ripple recommends that each gateway run its own rippled servers. Ripple provides detailed and individualized recommendations to businesses interested in running a significant XRP-based business.

-

Contact partners@ripple.com to see how Ripple can help.

-

APIs and Middleware

-

There are several interfaces you can use to connect to the XRP Ledger, depending on your needs and your existing software:

-
    -
  • rippled provides JSON-RPC and WebSocket APIs that can be used as a low-level interface to all core XRP Ledger functionality.
    • -
  • RippleAPI provides a simplified API for JavaScript applications.
    • -
-

Tool Security

-

Any time you submit an XRP Ledger transaction, it must be signed using your secret key. The secret key gives full control over your XRP Ledger address. Never send your secret key to a server operated by someone else. Either use your own rippled server, or sign the transactions locally before sending them to a rippled server.

-

The examples in this document show API methods that include a secret key. This is only safe if you control rippled server yourself, and you connect to it over a connection that is secure from outside listeners. (For example, you could connect over a loopback (localhost) network, a private subnet, or an encrypted VPN.) Alternatively, you could use RippleAPI to sign transactions locally before submitting them to a third-party server.

-

DefaultRipple

-

The DefaultRipple flag controls whether the balances in an accounting relationship allowed to ripple by default. Rippling is what allows customers to trade issuances, so a gateway must allow rippling on all the accounting relationships to its issuing address.

-

Before asking customers to create accounting relationships to its issuing address, a gateway should enable the DefaultRipple flag on that address. Otherwise, the gateway must individually disable the NoRipple flag for each accounting relationship that other addresses have created.

-

The following is an example of using a locally-hosted rippled's submit command to send an AccountSet transaction to enable the DefaultRipple flag:

-

Request:

-
POST http://localhost:8088/
-{
-    "method": "submit",
-    "params": [
-        {
-            "secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
-            "tx_json": {
-                "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-                "Fee": "15000",
-                "Flags": 0,
-                "SetFlag": 8,
-                "TransactionType": "AccountSet"
-            }
-        }
-    ]
-}
-
-

Caution: Never submit a secret key to a server you do not control. Do not send a secret key unencrypted over the network.

-

Response:

-
{
-    "result": {
-        "engine_result": "tesSUCCESS",
-        "engine_result_code": 0,
-        "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
-        "status": "success",
-        "tx_blob": "1200032200000000240000003E202100000008684000000000003A98732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB74473045022100D8F2DEF27DE313E3F0D1E189BF5AC8879F591045950E2A33787C3051169038C80220728A548F188F882EA40A416CCAF2AC52F3ED679563BBE1BAC014BB9E773A333581144B4E9C06F24296074F7BC48F92A97916C6DC5EA9",
-        "tx_json": {
-            "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-            "Fee": "15000",
-            "Flags": 0,
-            "Sequence": 62,
-            "SetFlag": 8,
-            "SigningPubKey": "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB",
-            "TransactionType": "AccountSet",
-            "TxnSignature": "3045022100D8F2DEF27DE313E3F0D1E189BF5AC8879F591045950E2A33787C3051169038C80220728A548F188F882EA40A416CCAF2AC52F3ED679563BBE1BAC014BB9E773A3335",
-            "hash": "665B27B64CE658704FFD326A4FE2F5F5B5E67EACA61DE08258A59D35B883E1D5"
-        }
-    }
-}
-
-

To confirm that an address has DefaultRipple enabled, look up the address using the account_info command, specifying a validated ledger version. Use a bitwise-AND operator to compare the Flags field with 0x00800000 (the ledger flag lsfDefaultRipple). If the result of the bitwise-AND operation is nonzero, then the address has DefaultRipple enabled.

-

Generating Source and Destination Tags

-

You need a scheme to create Source and Destination tags for your customers and payments. (See Source and Destination Tags for an explanation of what Source and Destination Tags are.)

-

For greater privacy and security, we recommend not using monotonically-incrementing numbers as destination tags that correlate 1:1 with customers. Instead, we recommend using convenient internal IDs, but mapping those to destination tags using a quick hash or cipher function such as Hasty Pudding. You should set aside ranges of internal numbers for different uses of destination tags.

-

After passing the internal numbers through your hash function, you can use the result as a destination tag. To be safe, you should check for collisions. Do not reuse destination tags unless they have explicit expiration dates (like quotes and customer-generated tags).

-

We recommend making a user interface to generate a destination tag on-demand when a customer intends to send money to the gateway. Then, consider that destination tag valid only for a payment with the expected amount. Later, bounce any other transactions that reuse the same destination tag.

-

Enable the RequireDest flag on your issuing and operational addresses so that customers must use a destination tag to indicate where funds should go when they send XRP Ledger payments to your gateway.

-

DisallowXRP

-

The DisallowXRP setting (disallowIncomingXRP in RippleAPI) is designed to discourage XRP Ledger users from sending XRP to an address by accident. This reduces the costs and effort of bouncing undesired payments, if your gateway does not trade XRP. The DisallowXRP flag is not strictly enforced, because doing so could allow addresses to become permanently unusable if they run out of XRP. Client applications should honor the DisallowXRP flag by default.

-

An issuing gateway that does not trade XRP should enable the DisallowXRP flag on the gateway's issuing and operational addresses. A private exchange that trades in XRP should only enable the DisallowXRP flag on addresses that are not expected to receive XRP.

-

The following is an example of using a locally-hosted rippled's submit command to send an AccountSet transaction to enable the DisallowXRP flag:

-

Request:

-
POST http://localhost:8088/
-{
-    "method": "submit",
-    "params": [
-        {
-            "secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
-            "tx_json": {
-                "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-                "Fee": "10000",
-                "Flags": 0,
-                "SetFlag": 3,
-                "TransactionType": "AccountSet"
-            }
-        }
-    ]
-}
-
-

Caution: Never submit a secret key to a server you do not control. Do not send a secret key unencrypted over the network.

-

Response:

-
{
-    "result": {
-        "engine_result": "tesSUCCESS",
-        "engine_result_code": 0,
-        "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
-        "status": "success",
-        "tx_blob": "12000322000000002400000164202100000003684000000000002710732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB74473045022100C2E38177E92C3998EB2C22978595784BC4CABCF7D57DE71FCF6CF162FB683A1D02205942D42C440D860B4CF7BB0DF77E4F2C529695854835B2F76DC2D09644FCBB2D81144B4E9C06F24296074F7BC48F92A97916C6DC5EA9",
-        "tx_json": {
-            "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-            "Fee": "10000",
-            "Flags": 0,
-            "Sequence": 356,
-            "SetFlag": 3,
-            "SigningPubKey": "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB",
-            "TransactionType": "AccountSet",
-            "TxnSignature": "3045022100C2E38177E92C3998EB2C22978595784BC4CABCF7D57DE71FCF6CF162FB683A1D02205942D42C440D860B4CF7BB0DF77E4F2C529695854835B2F76DC2D09644FCBB2D",
-            "hash": "096A89DA55A6A1C8C9EE1BCD15A8CADCC52E6D2591393F680243ECEB93161B33"
-        }
-    }
-}
-
-

RequireDest

-

The RequireDest setting (requireDestinationTag in RippleAPI) is designed to prevent customers from sending payments to your address while accidentally forgetting the destination tag that identifies who should be credited for the payment. When enabled, the XRP Ledger rejects any payment to your address that does not specify a destination tag.

-

We recommend enabling the RequireDest flag on all gateway issuing and operational addresses.

-

The following is an example of using a locally-hosted rippled's submit command to send an AccountSet transaction to enable the RequireDest flag:

-

Request:

-
POST http://localhost:5005/
-Content-Type: application/json
-{
-    "method": "submit",
-    "params": [
-        {
-            "secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
-            "tx_json": {
-                "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-                "Fee": "15000",
-                "Flags": 0,
-                "SetFlag": 1,
-                "TransactionType": "AccountSet"
-            }
-        }
-    ]
-}
-
-

Caution: Never submit a secret key to a server you do not control. Do not send a secret key unencrypted over the network.

-

Response:

-
200 OK
-{
-    "result": {
-        "engine_result": "tesSUCCESS",
-        "engine_result_code": 0,
-        "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
-        "status": "success",
-        "tx_blob": "12000322000000002400000161202100000003684000000000003A98732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB74473045022100CD9A87890ADFAC49B8F69EDEC4A0DB99C86667883D7579289B06DAA4B81BF87E02207AC3FEEA518060AB2B538D330614D2594F432901F7C011D7EB92F74383E5340F81144B4E9C06F24296074F7BC48F92A97916C6DC5EA9",
-        "tx_json": {
-            "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-            "Fee": "15000",
-            "Flags": 0,
-            "Sequence": 353,
-            "SetFlag": 3,
-            "SigningPubKey": "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB",
-            "TransactionType": "AccountSet",
-            "TxnSignature": "3045022100CD9A87890ADFAC49B8F69EDEC4A0DB99C86667883D7579289B06DAA4B81BF87E02207AC3FEEA518060AB2B538D330614D2594F432901F7C011D7EB92F74383E5340F",
-            "hash": "59025DD6C9848679BA433448A1DD95833F2F4B64B03E214D074C7A5B6E3E3E70"
-        }
-    }
-}
-
-

RequireAuth

-

The RequireAuth setting (requireAuthorization in RippleAPI) prevents all counterparties from holding balances issued by an address unless the address has specifically approved an accounting relationship with that counterparty.

-

We recommend always enabling RequireAuth for operational addresses and standby addresses, and then never approving any accounting relationships. This prevents operational addresses from creating issuances even by accident. This is a purely precautionary measure, and does not stop those addresses from transferring issuances created by the issuing address, as they are intended to do.

-

If you want to use the Authorized Accounts feature, you must also enable RequireAuth on your issuing address. When using Authorized Accounts, your issuing address must submit a TrustSet transaction to approve each accounting relationship that customers create with your issuing address.

-

You can only enable RequireAuth if the address owns no accounting relationships (trust lines) and no offers in the XRP Ledger, so you must decide whether or not to use it before you start doing business in the XRP Ledger.

-

Enabling RequireAuth

-

The following is an example of using a locally-hosted rippled's submit command to send an AccountSet transaction to enable the RequireAuth flag: (This method works the same way regardless of whether the address is an issuing address, operational address, or standby address.)

-

Request:

-
POST http://localhost:5005/
-{
-    "method": "submit",
-    "params": [
-        {
-            "secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
-            "tx_json": {
-                "Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
-                "Fee": "15000",
-                "Flags": 0,
-                "SetFlag": 2,
-                "TransactionType": "AccountSet"
-            }
-        }
-    ]
-}
-
-

Caution: Never submit a secret key to a server you do not control. Do not send a secret key unencrypted over the network.

-

Authorizing Trust Lines

-

If you are using the Authorized Accounts feature, customers cannot hold balances you issue unless you first authorize their accounting relationships to you in the XRP Ledger.

-

To authorize an accounting relationship, submit a TrustSet transaction from your issuing address, with the user to trust as the issuer of the LimitAmount. Leave the value (the amount to trust them for) as 0, and enable the tfSetfAuth flag for the transaction.

-

The following is an example of using a locally-hosted rippled's submit command to send a TrustSet transaction authorizing the customer address rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn to hold issuances of USD from the issuing address rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW:

-

Request:

-
POST http://localhost:8088/
-{
-    "method": "submit",
-    "params": [
-        {
-            "secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
-            "tx_json": {
-                "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-                "Fee": "15000",
-                "TransactionType": "TrustSet",
-                "LimitAmount": {
-                    "currency": "USD",
-                    "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-                    "value": 0
-                },
-                "Flags": 65536
-            }
-        }
-    ]
-}
-
-

Caution: Never submit a secret key to a server you do not control. Do not send a secret key unencrypted over the network.

-

Robustly Monitoring for Payments

-

To robustly check for incoming payments, gateways should do the following:

-
    -
  • Keep a record of the most-recently-processed transaction and ledger. That way, if you temporarily lose connectivity, you know how far to go back.
    • -
  • Check the result code of every incoming payment. Some payments go into the ledger to charge an anti-spam fee, even though they failed. Only transactions with the result code tesSUCCESS can change non-XRP balances. Only transactions from a validated ledger are final.
    • -
  • Look out for Partial Payments. Payments with the partial-payment flag enabled can be considered "successful" if any non-zero amount is delivered, even miniscule amounts.
      -
    • In rippled, check the transaction for a meta.delivered_amount field. If present, that field indicates how much money actually got delivered to the Destination address.
      • -
    • In RippleAPI, you can search the outcome.BalanceChanges field to see how much the destination address received. In some cases, this can be divided into multiple parts on different trust lines.
      • -
    -
    • -
  • Some transactions change your balances without being payments directly to or from one of your addresses. For example, if ACME sets a nonzero TransferRate, then ACME's issuing address's outstanding obligations decrease each time Bob and Charlie exchange ACME issuances. See TransferRate for more information.
    • -
-

To make things simpler for your customers, we recommend accepting payments to either operational addresses and issuing addresses.

-

As an added precaution, we recommend comparing the balances of your issuing address with the collateral funds in your internal accounting system as of each new XRP Ledger ledger version. The issuing address's negative balances should match the assets you have allocated to XRP Ledger outside the network. If the two do not match up, then you should suspend processing payments into and out of the XRP Ledger until you have resolved the discrepancy.

- -

TransferRate

-

The TransferRate setting (transferRate in RippleAPI) defines a fee to charge for transferring issuances from one XRP Ledger address to another. See Transfer Fees for more information.

-

The following is an example of using a locally-hosted rippled's submit command to send an AccountSet transaction for the issuing address rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW, setting the TransferRate to charge a fee of 0.5%.

-

Request:

-

-{
-    "method": "submit",
-    "params": [
-        {
-            "secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
-            "tx_json": {
-                "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-                "Fee": "10000",
-                "Flags": 0,
-                "TransferRate": 1005000000,
-                "TransactionType": "AccountSet"
-            }
-        }
-    ]
-}
-
-

Response:

-
{
-    "result": {
-        "engine_result": "tesSUCCESS",
-        "engine_result_code": 0,
-        "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
-        "status": "success",
-        "tx_blob": "1200032200000000240000000F2B3BE71540684000000000002710732102B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF74473045022100AAFC3360BE151299523A93F445D5F6EB58AF5A4F8586C8B7818D6C6069660B40022022F46BCDA8FEE256AEB0BA2E92947EF4571F92354AB703E3E6D77FEF7ECBF64E8114204288D2E47F8EF6C99BCC457966320D12409711",
-        "tx_json": {
-            "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-            "Fee": "10000",
-            "Flags": 0,
-            "Sequence": 15,
-            "SigningPubKey": "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
-            "TransactionType": "AccountSet",
-            "TransferRate": 1005000000,
-            "TxnSignature": "3045022100AAFC3360BE151299523A93F445D5F6EB58AF5A4F8586C8B7818D6C6069660B40022022F46BCDA8FEE256AEB0BA2E92947EF4571F92354AB703E3E6D77FEF7ECBF64E",
-            "hash": "24360352FBF5597F313E5985C1766BB4A0D277CE63219AC0C0D81014C1E663BB"
-        }
-    }
-}
-
-

TransferRate with Operational and Standby Addresses

-

All XRP Ledger addresses, including operational and standby addresses, are subject to the transfer fee. If you set a nonzero transfer fee, then you must send extra (to pay the TransferRate) when making payments from your operational address or standby address. In other words, your addresses must pay back a little of the balance your issuing address created, each time you make a payment.

-
    -
  • In rippled's APIs, you should set the SendMax transaction parameter higher than the destination Amount parameter.
    • -
  • In RippleAPI, you should set the source.maxAmount parameter higher than the destination.amount parameter; or, set the source.amount parameter higher than the destination.minAmount parameter.
    • -
-

Note: The TransferRate does not apply when sending issuances directly to the issuing address. The issuing address must always accept its issuances at face value in the XRP Ledger. This means that customers don't have to pay the TransferRate if they send payments to the issuing address directly, but they do when sending to an operational address. If you accept payments at both addresses, you may want to adjust the amount you credit customers in your system of record when customers send payments to the operational address, to compensate for the TransferRate the customer pays.

-

For example: If ACME sets a transfer fee of 1%, an XRP Ledger payment to deliver 5 EUR.ACME from a customer address to ACME's issuing address would cost exactly 5 EUR.ACME. However, the customer would need to send 5.05 EUR.ACME to deliver 5 EUR.ACME to ACME's operational address. (The issuing address's total obligations in the XRP Ledger decrease by 0.05 EUR.ACME.) When ACME credits customers for payments to ACME's operational address, ACME credits the customer for the amount delivered to the operational address and the transfer fee, giving the customer €5,05 in ACME's systems.

-

Sending Payments to Customers

-

When you build an automated system to send payments into the XRP Ledger for your customers, you must make sure that it constructs payments carefully. Malicious actors are constantly trying to find ways to trick a system into paying them more money than it should.

-

One common pitfall is performing pathfinding before sending sending a payment to customers in the XRP Ledger. If you specify the issuers correctly, the default paths can deliver the currency as intended.

-

The following is an example of using a locally-hosted rippled's submit command to send a payment from the operational address rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn to the customer address raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n, sending and delivering funds issued by the issuing address rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW.

-

Request:

-
{
-    "method": "submit",
-    "params": [{
-        "secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
-        "tx_json": {
-            "TransactionType": "Payment",
-            "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-            "Destination": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
-            "Amount": {
-                "currency": "USD",
-                "value": "0.13",
-                "issuer": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW"
-            },
-            "SendMax": {
-                "currency": "USD",
-                "value": "0.13065",
-                "issuer": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW"
-            },
-            "Fee": "10000"
-        }
-    }]
-}
-
-

Reminder: Don't send your secret to a server you do not control.

-

Response:

-
{
-    "result": {
-        "engine_result": "tesSUCCESS",
-        "engine_result_code": 0,
-        "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
-        "status": "success",
-        "tx_blob": "1200002280000000240000016561D4449E57D63540000000000000000000000000005553440000000000204288D2E47F8EF6C99BCC457966320D1240971168400000000000271069D444A4413C6628000000000000000000000000005553440000000000204288D2E47F8EF6C99BCC457966320D12409711732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB7446304402207B75D91DC0EEE613A94E05FD5D031568D8A763E99697FF6328745BD226DA7D4E022005C75D7215FD62CB8E46C55B29FCA8E3FC62FDC55DF300597089DD29863BD3CD81144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143A4C02EA95AD6AC3BED92FA036E0BBFB712C030C",
-        "tx_json": {
-            "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-            "Amount": {
-                "currency": "USD",
-                "issuer": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-                "value": "0.13"
-            },
-            "Destination": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
-            "Fee": "10000",
-            "Flags": 2147483648,
-            "SendMax": {
-                "currency": "USD",
-                "issuer": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-                "value": "0.13065"
-            },
-            "Sequence": 357,
-            "SigningPubKey": "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB",
-            "TransactionType": "Payment",
-            "TxnSignature": "304402207B75D91DC0EEE613A94E05FD5D031568D8A763E99697FF6328745BD226DA7D4E022005C75D7215FD62CB8E46C55B29FCA8E3FC62FDC55DF300597089DD29863BD3CD",
-            "hash": "37B4AA5C77A8EB889164CA012E6F064A46B6B7B51677003FC3617F614608C60B"
-        }
-    }
-}
-
-

In particular, note the following features of the Payment Transaction:

-
    -
  • No Paths field. The payment only succeeds if it can use a default path, which is preferable. Using less direct paths can become much more expensive.
    • -
  • The issuer of both the SendMax and the Amount is the issuing address. This ensures that the transaction sends and delivers issuances from the issuing address, and not from some other gateway.
    • -
  • The value of the SendMax amount is slightly higher than the destination Amount, to compensate for the transfer fee. In this case, the transfer fee is 0.5%, so the SendMax amount is exactly 1.005 times the destination Amount.
    • -
-

Bouncing Payments

-

When one of your addresses receives a payment whose purpose is unclear, we recommend that you try to return the money to its sender. While this is more work than pocketing the money, it demonstrates good faith towards customers. You can have an operator bounce payments manually, or create a system to do so automatically.

-

The first requirement to bouncing payments is robustly monitoring for incoming payments. You do not want to accidentally refund a customer for more than they sent you! (This is particularly important if your bounce process is automated.) The Partial Payment Flag Gateway Bulletin (PDF) explains how to avoid a common problem.

-

Second, you should send bounced payments as Partial Payments. Since third parties can manipulate the cost of pathways between addresses, Partial Payments allow you to divest yourself of the full amount without being concerned about exchange rates within the XRP Ledger. You should publicize your bounced payments policy as part of your terms of use. Send the bounced payment from either an operational address or a standby address.

-
    -
  • To send a Partial Payment using rippled, enable the tfPartialPayment flag on the transaction. Set the Amount field to the amount you received and omit the SendMax field.
    • -
  • To send a Partial Payment using RippleAPI, set the allowPartialPayment field of the Payment object to true. Set the source.maxAmount and destination.amount both equal to the amount you received.
    • -
-

You should use the SourceTag value (source.tag in RippleAPI) from the incoming payment as the DestinationTag value (destination.tag in RippleAPI) for the return payment.

-

To prevent two systems from bouncing payments back and forth indefinitely, you can set a new Source Tag for the outgoing return payment. If you receive an unexpected payment whose Destination Tag matches the Source Tag of a return you sent, then do not bounce it back again.

-

Reliable Transaction Submission

-

The goal of reliably submitting transactions is to achieve the following two properties in a finite amount of time:

-
    -
  • Idempotency - Transactions should be processed once and only once, or not at all.
    • -
  • Verifiability - Applications can determine the final result of a transaction.
    • -
-

To submit transactions reliably, follow these guidelines:

-
    -
  • Persist details of the transaction before submitting it.
    • -
  • Use the LastLedgerSequence parameter. (RippleAPI does this by default.)
    • -
  • Resubmit a transaction if it has not appeared in a validated ledger whose sequence number is less than or equal to the transaction's LastLedgerSequence parameter.
    • -
-

For more information, see Reliable Transaction Submission.

-

ripple.txt

-

The ripple.txt standard provides a way to publish information about your gateway so that automated tools and applications can read and understand it.

-

For example, if you run a validating rippled server, you can use ripple.txt to publish the public key of your validating server. You can also publish information about what currencies your gateway issues, and which XRP Ledger addresses you control, to protect against impostors or confusion.

- -
-
-
- - - - \ No newline at end of file diff --git a/tutorial-listing-xrp.html b/tutorial-listing-xrp.html deleted file mode 100644 index f7889c37fd..0000000000 --- a/tutorial-listing-xrp.html +++ /dev/null @@ -1,776 +0,0 @@ - - - - - - - - Listing XRP as an Exchange - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

Listing XRP as an Exchange

-

This document describes the steps that an exchange needs to take to list XRP. For details about other aspects of rippled and the XRP Ledger, see the Ripple Developer Center.

-

Alpha Exchange

-

For illustrative purposes, this document uses a fictitious business called Alpha Exchange to explain the high-level steps required to list XRP. For the purposes of this document, Alpha Exchange:

-
    -
  • -

    Currently specializes in listing BTC/USD

    -
    • -
  • -

    Wants to add BTC/XRP and XRP/USD trading pairs

    -
    • -
  • -

    Maintains balances for all of its customers

    -
    • -
  • -

    Maintains balances for each of its supported currencies

    -
    • -
-

User Benefits

-

Alpha Exchange wants to list BTC/XRP and XRP/USD trading pairs partially because listing these pairs will benefit its users. Specifically, this support will allow its users to:

-
    -
  • -

    Deposit XRP to Alpha Exchange from the XRP Ledger

    -
    • -
  • -

    Withdraw XRP from Alpha Exchange to the XRP Ledger

    -
    • -
  • -

    Trade XRP with other currencies, such as BTC, USD, among others

    -
    • -
-

Prerequisites for Supporting XRP

-

To support XRP, Alpha Exchange must:

- -

See also:

- -

Partial Payments

-

Before integrating, exchanges should be aware of the partial payments feature. This feature allows XRP Ledger users to send successful payments that reduce the amount received instead of increasing the SendMax. This feature can be useful for returning payments without incurring additional cost as the sender.

-

Partial Payments Warning

-

When the tfPartialPayment flag is enabled, the Amount field is not guaranteed to be the amount received. The delivered_amount field of a payment's metadata indicates the amount of currency actually received by the destination account. When receiving a payment, use delivered_amount instead of the Amount field to determine how much your account received instead.

-

Warning: Be aware that malicious actors could exploit this. For more information, see Partial Payments.

-

Accounts

-

XRP is held in accounts (also referred to as wallets or addresses ) on the XRP Ledger. Accounts on the XRP Ledger are different than accounts on other blockchain ledgers, such as Bitcoin, where accounts incur little to no overhead. In the XRP Ledger, accounts can never be deleted, and each account must hold a separate reserve of XRP that cannot be sent to others. For these reasons, Ripple recommends that institutions not create excessive or needless accounts.

-

To comply with Ripple's recommended best practices, Alpha Exchange should create at least two new accounts on the XRP Ledger. To minimize the risks associated with a compromised secret key, Ripple recommends creating cold, hot, and warm accounts (these are sometimes referred to, respectively, as cold, hot, and warm wallets). The hot/warm/cold model is intended to balance security and convenience. Exchanges listing XRP should create the following accounts:

-
    -
  • -

    A cold wallet to securely hold the majority of XRP and customers' funds. For exchanges, this is also the address to which its users send deposits. To provide optimal security, this account's secret key should be offline.

    -

    If a malicious actor compromises an exchange's cold wallet, the possible consequences are:

    -
      -
    • -

      The malicious actor gets full access to all XRP in the cold wallet.

      -
      • -
    • -

      If the master key is compromised, the malicious actor can irrevocably take control of the cold wallet forever (by disabling the master key and setting a new regular key or signer list). This would also give the malicious actor control over all future XRP received by the cold wallet.

      -
        -
      • If this happens, the exchange has to make a new cold wallet address and tell its customers the new address.
        • -
      -
      • -
    • -

      If the regular key or signer list are comromised, the exchange can regain control of the cold wallet. However, some of a malicious actor's actions cannot easily be undone:

      -
        -
      • -

        The malicious actor could issue currency in the XRP Ledger by using the cold wallet, but that currency should not be valued by anyone (unless the exchange explicitly stated it was also a gateway).

        -
        • -
      • -

        If a malicious actor sets the asfRequireAuth flag for the account, that cannot be unset, although this only relates issuing currency and therefore should not affect an exchange that's not also a gateway. Any other settings a malicious actor sets or unsets with a master key can be reverted.

        -
        • -
      -
      • -
    -
    • -
  • -

    One or more hot wallets to conduct the day-to-day business of managing customers' XRP withdrawals and deposits. For example, with a hot wallet, exchanges can securely support these types of automated XRP transfers. Hot wallets need to be online to service instant withdrawal requests.

    -

    For more information about the possible consequences of a compromised hot wallet, see Operational Account Compromise.

    -
    • -
  • -

    Optionally, one or more warm wallets to provide an additional layer of security between the cold and hot wallets. Unlike a hot wallet, the secret key of a warm wallet does not need to be online. Additionally, you can distribute the secret keys for the warm wallet to several different people and implement multisigning to increase security.

    -

    For more information about the possible consequences of a compromised warm wallet, see Standby Account Compromise.

    -
    • -
-

See also:

- -

Balance Sheets

-

To custody its ccustomers' XRP, Alpha Exchange must track each customer's XRP balance and its own holdings. To do this, Alpha Exchange must create and maintain an additional balance sheet or accounting system. The following table illustrates what this balance sheet might look like.

-

The new XRP Ledger accounts (Alpha Hot, Alpha Warm, Alpha Cold) are in the User column of the XRP Balances on XRP Ledger table.

-

The Alpha Exchange XRP Balances table represents new, additional balance sheet. Alpha Exchange’s software manages their users’ balances of XRP on this accounting system.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
XRP Balances -on XRP LedgerAlpha Exchange -XRP Balances
UserBalanceAcct #UserBalance
Dave25,000123Alice0
Edward45,000456Bob0
Charlie50,000789Charlie0
Alpha Hot0...
Alpha Warm0
Alpha Cold0
...
-

XRP Amounts

-

Amounts of XRP are represented on the XRP Ledger as an unsigned integer count of drops, where one XRP is 1,000,000 drops. Ripple recommends that software store XRP balances as integer amounts of drops, and perform integer arithmetic on these values. However, user interfaces should present balances in units of XRP.

-

One drop (.000001 XRP) cannot be further subdivided. Keep this in mind when calculating and displaying FX rates between XRP and other assets.

-

For more information, see Specifying Currency Amounts.

-

On-Ledger and Off-Ledger

-

With exchanges like Alpha Exchange, XRP can be "on-ledger" or "off-ledger":

-
    -
  • -

    On-Ledger XRP: XRP that can be queried through the public XRP Ledger by specifying the public address of the XRP holder. The counterparty to these balances is the XRP Ledger. For more information, see Currencies.

    -
    • -
  • -

    Off-Ledger XRP: XRP that is held by the accounting system of an exchange and can be queried through the exchange interface. Off-ledger XRP balances are credit-based. The counterparty is the exchange holding the XRP.

    -

    Off-ledger XRP balances are traded between the participants of an exchange. To support these trades, the exchange must hold a balance of on-ledger XRP equal to the aggregate amount of off-ledger XRP that it makes available for trade.

    -
    • -
-

Flow of Funds

-

The remaining sections describe how funds flow through the accounts managed by Alpha Exchange as its users begin to deposit, trade, and redeem XRP balances. To illustrate the flow of funds, this document uses the tables introduced in the "Balance Sheets" section.

-

There are four main steps involved in an exchange's typical flow of funds:

-
    -
  1. -

    Deposit XRP into Exchange

    -
    2. -
  2. -

    Rebalance XRP Holdings

    -
    3. -
  3. -

    Withdraw XRP from Exchange

    -
    4. -
  4. -

    Trade XRP on the Exchange

    -
    5. -
-

This list does not include the prerequisites required of an exchange.

-

At this point, Alpha Exchange has created hot, warm, and cold wallets on the XRP Ledger and added them to its balance sheet, but has not accepted any deposits from its users.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
XRP Balances -on XRP LedgerAlpha Exchange -XRP Balances
UserBalanceAcct #UserBalance
Dave25,000123Alice0
Edward45,000456Bob0
Charlie50,000789Charlie0
Alpha Hot0...
Alpha Warm0
Alpha Cold0
...
-

Deposit XRP into Exchange

-

To track off-ledger XRP balances, exchanges need to create new balance sheets (or similar accounting systems). The following table illustrates the balance changes that take place on Alpha Exchange's new balance sheet as users begin to deposit XRP.

-

A user named Charlie wants to deposit 50,000 XRP to Alpha Exchange. Doing this involves the following steps:

-
    -
  1. -

    Charlie submits a payment of 50,000 XRP (by using RippleAPI or similar software) to Alpha Exchange's cold wallet.

    -

    a. Charlie adds an identifier (in this case, 789) to the payment to associate it with his account at Alpha Exchange. This is called a destination tag. (To use this, Alpha Exchange should have set the asfRequireDest flag on all of its accounts to require all incoming payments to have a destination tag like Charlie's. For more information, see AccountSet Flags).

    -
    2. -
  2. -

    The software at Alpha Exchange detects the incoming payment, and recognizes 789 as the destination tag for Charlie’s account.

    -
    3. -
  3. -

    When it detects the incoming payment, Alpha Exchange's software updates its balance sheet to indicate that the 50,000 XRP it received is controlled by Charlie.

    -

    Charlie can now use up to 50,000 XRP on the exchange. For example, he can create offers to trade XRP with BTC or any of the other currencies Alpha Exchange supports.

    -
    4. -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
XRP Balances -on XRP LedgerAlpha Exchange -XRP Balances
UserBalanceAcct #UserBalance
Dave25,000123Alice0
Edward45,000456Bob0
Charlie100,000 -
50,000		789Charlie0 -
50,000
Alpha Hot0...
Alpha Warm0
Alpha Cold0 -
50,000
...
-

Trade XRP on the Exchange

-

Alpha Exchange users (like Charlie) can trade credit-based balances on Alpha Exchange. Alpha Exchange should keep track of user balances on its new balance sheet as these trades are made. These trades are off-ledger and independent from the XRP Ledger, so the balance changes are not recorded on the XRP Ledger.

-

Customers who hold XRP in their own XRP Ledger accounts can also use the distributed exchange built into the XRP Ledger to trade currencies issued by gateways. For more information about trading on the XRP Ledger, see Lifecycle of an Offer.

-

Rebalance XRP Holdings

-

Exchanges can adjust the balances between their hot and cold wallets at any time. Each balance adjustment consumes a transaction cost, but does not otherwise affect the aggregate balance of all the accounts. The aggregate, on-ledger balance should always exceed the total balance available for trade on the exchange. (The excess should be sufficient to cover the XRP Ledger's transaction cost.)

-

The following table demonstrates a balance adjustment of 80,000 XRP (via a payment on the XRP Ledger) between Alpha Exchange's cold wallet and its hot wallet, where the cold wallet was debited and the hot wallet was credited. If the payment were reversed (debiting the hot wallet and crediting the cold wallet), the hot wallet balance would decrease. Balance adjustments like these allow an exchange to limit the risks associated with holding XRP in online hot wallets.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Alpha Exchange XRP -Off-Ledger BalancesAlpha Exchange XRP On-Ledger Balances
Acct #UserBalanceXRP Ledger AccountBalance
123Alice80,000Hot0 -
80,000
456Bob50,000Warm0
….….
789Charlie50,000Cold180,000 -
100,000
......
-

Withdraw XRP from Exchange

-

Withdrawals allow an exchange's users to move XRP from the exchange's off-ledger balance sheet to an account on the XRP Ledger.

-

In this example, Charlie withdraws 25,000 XRP from Alpha Exchange. This involves the following steps:

-
    -
  1. -

    Charlie initiates the process on Alpha Exchange’s website. He provides instructions to transfer 25,000 XRP to a specific account on the XRP Ledger (named "Charlie XRP Ledger" in the following table).

    -
    2. -
  2. -

    In response to Charlie’s instructions, Alpha Exchange does the following:

    -

    a. Debits the amount (25,000 XRP) from Charlie’s account on its off-ledger balance sheet

    -

    b. Submits a payment on the XRP Ledger for the same amount (25,000 XRP), from Alpha Exchange's hot wallet to Charlie’s XRP Ledger account

    -
    3. -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
XRP Ledger On-Ledger XRP BalancesAlpha Exchange XRP -Off-Ledger BalancesAlpha Exchange XRP On-Ledger Balances
UserBalanceAcct #UserBalanceXRP Ledger AccountBalance
Dave25,000123Alice80,000Hot80,000 -
55,000
Edward45,000456Bob50,000Warm0
….….….
Charlie XRP Ledger50,000 -
75,000		789Charlie50,000 -
25,000		Cold100,000
.........
-
-
-
- - - - \ No newline at end of file diff --git a/tutorial-multisign.html b/tutorial-multisign.html deleted file mode 100644 index 1b9b234d30..0000000000 --- a/tutorial-multisign.html +++ /dev/null @@ -1,727 +0,0 @@ - - - - - - - - How to Multi-Sign - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

How to Multi-Sign

-

Multi-signing is one of three ways to authorize transactions for the XRP Ledger, alongside signing with regular keys and master keys. You can configure your address to allow any combination of the three methods to authorize transactions.

-

Benefits of multi-signing include:

-
    -
  • You can require keys from different devices, so that a malicious actor must compromise multiple machines to send transactions on your behalf.
    • -
  • You can share custody of an address between multiple people, each of whom only has one of several keys necessary to send transactions from that address.
    • -
  • You can delegate the power to send transactions from your address to a group of people, who can control your address if you are unavailable or unable to sign normally.
    • -
  • ... and more.
    • -
-

To use multi-signing:

-
    -
  1. The XRP Ledger peer-to-peer network must have multi-signing enabled.
    2. -
  2. Set up a list of signers on your account.
    3. -
  3. Send transactions using multiple signatures.
    4. -
-

Availability of Multi-Signing

-

Multi-signing has been enabled by an Amendment to the XRP Ledger Consensus Protocol since 2016-06-27.

-

If you want to use multi-signing with rippled with a fresh ledger in stand-alone mode, you must force the MultiSign feature to be enabled. You can check the status of the MultiSign amendment using the feature command.

-

To force the multi-signing feature to be enabled, add the following stanza to your rippled.cfg:

-
[features]
-MultiSign
-
-

Setting up Multi-Signing

-

To multi-sign transactions from a particular address, you must create a list of addresses that can contribute to a multi-signature for your address. This list is stored in the XRP Ledger as a SignerList node. The following procedure demonstrates how to set up a SignerList for your address:

-

1. Prepare a funded address

-

You need an XRP Ledger address that can send transactions, and has enough XRP available. Multi-signing requires more than the usual amount of XRP for the account reserve and transaction cost, increasing with the number of signers and signatures you use.

-

If you started rippled in stand-alone mode with a new genesis ledger, you must:

-
    -
  1. Generate keys for a new address, or reuse keys you already have.
    2. -
  2. Submit a Payment transaction to fund the new address from the genesis account. (Send at least 100,000,000 drops of XRP.)
    3. -
  3. Manually close the ledger.
    4. -
-

2. Prepare member keys

-

You need several sets of XRP Ledger keys (address and secret) to include as members of your SignerList. These can be funded addresses that exist in the ledger, or you can generate new addresses using the wallet_propose command. For example:

-
$ rippled wallet_propose
-Loading: "/home/mduo13/.config/ripple/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-    "result" : {
-        "account_id" : "rnRJ4dpSBKDR2M1itf4Ah6tZZm5xuNZFPH",
-        "key_type" : "secp256k1",
-        "master_key" : "FLOG SEND GOES CUFF GAGE FAT ANTI DEL GUM TIRE ISLE BEAR",
-        "master_seed" : "snheH5UUjU4CWqiNVLny2k21TyKPC",
-        "master_seed_hex" : "A9F859765EB8614D26809836382AFB82",
-        "public_key" : "aBR4hxFXcDNHnGYvTiqb2KU8TTTV1cYV9wXTAuz2DjBm7S8TYEBU",
-        "public_key_hex" : "03C09A5D112B393D531E4F092E3A5769A5752129F0A9C55C61B3A226BB9B567B9B",
-        "status" : "success"
-    }
-}
-
-

Take note of the account_id (XRP Ledger Address) and master_seed (secret key) for each one you generate.

-

3. Send SignerListSet transaction

-

Sign and submit a SignerListSet transaction in the normal (single-signature) way. This associates a SignerList with your XRP Ledger address, so that a combination of signatures from the members of that SignerList can multi-sign later transactions on your behalf.

-

In this example, the SignerList has 3 members, with the weights and quorum set up such that multi-signed transactions need a signature from rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW plus at least one signature from the other two members of the list.

-

Caution: Never submit a secret key to a server you do not control. Do not send a secret key unencrypted over the network.

-
$ rippled submit shqZZy2Rzs9ZqWTCQAdqc3bKgxnYq '{
->     "Flags": 0,
->     "TransactionType": "SignerListSet",
->     "Account": "rnBFvgZphmN39GWzUJeUitaP22Fr9be75H",
->     "Fee": "10000",
->     "SignerQuorum": 3,
->     "SignerEntries": [
->         {
->             "SignerEntry": {
->                 "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
->                 "SignerWeight": 2
->             }
->         },
->         {
->             "SignerEntry": {
->                 "Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
->                 "SignerWeight": 1
->             }
->         },
->         {
->             "SignerEntry": {
->                 "Account": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
->                 "SignerWeight": 1
->             }
->         }
->     ]
-> }'
-Loading: "/home/mduo13/.config/ripple/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "engine_result" : "tesSUCCESS",
-      "engine_result_code" : 0,
-      "engine_result_message" : "The transaction was applied. Only final in a validated ledger.",
-      "status" : "success",
-      "tx_blob" : "12000C2200000000240000000120230000000368400000000000271073210303E20EC6B4A39A629815AE02C0A1393B9225E3B890CAE45B59F42FA29BE9668D74473045022100BEDFA12502C66DDCB64521972E5356F4DB965F553853D53D4C69B4897F11B4780220595202D1E080345B65BAF8EBD6CA161C227F1B62C7E72EA5CA282B9434A6F04281142DECAB42CA805119A9BA2FF305C9AFA12F0B86A1F4EB1300028114204288D2E47F8EF6C99BCC457966320D12409711E1EB13000181147908A7F0EDD48EA896C3580A399F0EE78611C8E3E1EB13000181143A4C02EA95AD6AC3BED92FA036E0BBFB712C030CE1F1",
-      "tx_json" : {
-         "Account" : "rnBFvgZphmN39GWzUJeUitaP22Fr9be75H",
-         "Fee" : "10000",
-         "Flags" : 0,
-         "Sequence" : 1,
-         "SignerEntries" : [
-            {
-               "SignerEntry" : {
-                  "Account" : "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-                  "SignerWeight" : 2
-               }
-            },
-            {
-               "SignerEntry" : {
-                  "Account" : "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
-                  "SignerWeight" : 1
-               }
-            },
-            {
-               "SignerEntry" : {
-                  "Account" : "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
-                  "SignerWeight" : 1
-               }
-            }
-         ],
-         "SignerQuorum" : 3,
-         "SigningPubKey" : "0303E20EC6B4A39A629815AE02C0A1393B9225E3B890CAE45B59F42FA29BE9668D",
-         "TransactionType" : "SignerListSet",
-         "TxnSignature" : "3045022100BEDFA12502C66DDCB64521972E5356F4DB965F553853D53D4C69B4897F11B4780220595202D1E080345B65BAF8EBD6CA161C227F1B62C7E72EA5CA282B9434A6F042",
-         "hash" : "3950D98AD20DA52EBB1F3937EF32F382D74092A4C8DF9A0B1A06ED25200B5756"
-      }
-   }
-}
-
-

Make sure that the Transaction Result is tesSUCCESS. Otherwise, the transaction failed. If you encounter a problem in stand-alone mode or a non-production network, check that multi-sign is enabled.

-

Note: The more members in the SignerList, the more XRP your address must have for purposes of the owner reserve. If your address does not have enough XRP, the transaction fails with tecINSUFFICIENT_RESERVE. See also: SignerLists and Reserves.

-

4. Close the ledger

-

On the live network, you can wait 4-7 seconds for the ledger to close automatically.

-

If you're running rippled in stand-alone mode, use the ledger_accept command to manually close the ledger:

-
$ rippled ledger_accept
-Loading: "/home/mduo13/.config/ripple/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "ledger_current_index" : 6,
-      "status" : "success"
-   }
-}
-
-

5. Confirm the new signer list

-

Use the account_objects command to confirm that the SignerList is associated with the address in the latest validated ledger.

-

Normally, an account can own many objects of different types (such as trust lines and offers). If you funded a new address for this tutorial, the SignerList is the only object in the response.

-
$ rippled account_objects rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC validated
-Loading: "/home/mduo13/.config/ripple/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "account" : "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
-      "account_objects" : [
-         {
-            "Flags" : 0,
-            "LedgerEntryType" : "SignerList",
-            "OwnerNode" : "0000000000000000",
-            "PreviousTxnID" : "8FDC18960455C196A8C4DE0D24799209A21F4A17E32102B5162BD79466B90222",
-            "PreviousTxnLgrSeq" : 5,
-            "SignerEntries" : [
-               {
-                  "SignerEntry" : {
-                     "Account" : "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-                     "SignerWeight" : 2
-                  }
-               },
-               {
-                  "SignerEntry" : {
-                     "Account" : "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
-                     "SignerWeight" : 1
-                  }
-               },
-               {
-                  "SignerEntry" : {
-                     "Account" : "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
-                     "SignerWeight" : 1
-                  }
-               }
-            ],
-            "SignerListID" : 0,
-            "SignerQuorum" : 3,
-            "index" : "79FD203E4DDDF2EA78B798C963487120C048C78652A28682425E47C96D016F92"
-         }
-      ],
-      "ledger_hash" : "56E81069F06492FB410A70218C08169BE3AB3CFD5AEA20E999662D81DC361D9F",
-      "ledger_index" : 5,
-      "status" : "success",
-      "validated" : true
-   }
-}
-
-

If the SignerList is present with the expected contents, then your address is ready to multi-sign.

-

6. Further steps

-

At this point, your address is ready to send a multi-signed transaction. You may also want to:

- -

Sending a Multi-Signed Transaction

-

Before you can multi-sign a transaction, first set up multi-signing for your address. The following procedure demonstrates how to create, sign, and submit a multi-signed transaction.

-

1. Create the transaction

-

Create a JSON object that represents the transaction you want to submit. You have to specify everything about this transaction, including Fee and Sequence. Also include the field SigningPubKey as an empty string, to indicate that the transaction is multi-signed.

-

Keep in mind that the Fee for multi-signed transactions is significantly higher than for regularly-signed transactions. It should be at least (N+1) times the normal transaction cost, where N is the number of signatures you plan to provide. Since it sometimes takes a while to collect signatures from multiple sources, you may want to specify more than the current minimum, in case the transaction cost increases in that time.

-

Here's an example transaction ready to be multi-signed:

-
{
-    "TransactionType": "TrustSet",
-    "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
-    "Flags": 262144,
-    "LimitAmount": {
-        "currency": "USD",
-        "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
-        "value": "100"
-    },
-    "Sequence": 2,
-    "SigningPubKey": "",
-    "Fee": "30000"
-}
-
-

(This transaction creates an accounting relationship from rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC to rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh with a maximum balance of 100 USD.)

-

2. Get one signature

-

Use the sign_for command with the secret key and address of one of the members of your SignerList to get a signature for that member.

-

Caution: Never submit a secret key to a server you do not control. Do not send a secret key unencrypted over the network.

-
$ rippled sign_for rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW <rsA2L..'s secret> '{
->     "TransactionType": "TrustSet",
->     "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
->     "Flags": 262144,
->     "LimitAmount": {
->         "currency": "USD",
->         "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
->         "value": "100"
->     },
->     "Sequence": 2,
->     "SigningPubKey": "",
->     "Fee": "30000"
-> }'
-Loading: "/home/mduo13/.config/ripple/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "status" : "success",
-      "tx_blob" : "1200142200040000240000000263D5038D7EA4C680000000000000000000000000005553440000000000B5F762798A53D543A014CAF8B297CFF8F2F937E868400000000000753073008114A3780F5CB5A44D366520FC44055E8ED44D9A2270F3E010732102B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF744730450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E58114204288D2E47F8EF6C99BCC457966320D12409711E1F1",
-      "tx_json" : {
-         "Account" : "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
-         "Fee" : "30000",
-         "Flags" : 262144,
-         "LimitAmount" : {
-            "currency" : "USD",
-            "issuer" : "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
-            "value" : "100"
-         },
-         "Sequence" : 2,
-         "Signers" : [
-            {
-               "Signer" : {
-                  "Account" : "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-                  "SigningPubKey" : "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
-                  "TxnSignature" : "30450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E5"
-               }
-            }
-         ],
-         "SigningPubKey" : "",
-         "TransactionType" : "TrustSet",
-         "hash" : "A94A6417D1A7AAB059822B894E13D322ED3712F7212CE9257801F96DE6C3F6AE"
-      }
-   }
-}
-
-

Save the tx_json field of the response: it has the new signature in the Signers field. You can discard the value of the tx_blob field.

-

If you encounter a problem in stand-alone mode or a non-production network, check that multi-sign is enabled.

-

3. Get additional signatures

-

You can collect additional signatures in parallel or in serial:

-
    -
  • In parallel: Use the sign_for command with the original JSON for the transaction. Each response has a single signature in the Signers array.
    • -
  • In serial: Use the sign_for command with the tx_json value from the previous sign_for response. Each response adds a new signature to the existing Signers array.
    • -
-

Caution: Never submit a secret key to a server you do not control. Do not send a secret key unencrypted over the network.

-
$ rippled sign_for rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v <rUpy..'s secret> '{
->    "Account" : "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
->    "Fee" : "30000",
->    "Flags" : 262144,
->    "LimitAmount" : {
->       "currency" : "USD",
->       "issuer" : "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
->       "value" : "100"
->    },
->    "Sequence" : 2,
->    "Signers" : [
->       {
->          "Signer" : {
->             "Account" : "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
->             "SigningPubKey" : "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
->             "TxnSignature" : "30450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E5"
->          }
->       }
->    ],
->    "SigningPubKey" : "",
->    "TransactionType" : "TrustSet",
->    "hash" : "A94A6417D1A7AAB059822B894E13D322ED3712F7212CE9257801F96DE6C3F6AE"
-> }'
-Loading: "/home/mduo13/.config/ripple/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "status" : "success",
-      "tx_blob" : "1200142200040000240000000263D5038D7EA4C680000000000000000000000000005553440000000000B5F762798A53D543A014CAF8B297CFF8F2F937E868400000000000753073008114A3780F5CB5A44D366520FC44055E8ED44D9A2270F3E010732102B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF744730450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E58114204288D2E47F8EF6C99BCC457966320D12409711E1E0107321028FFB276505F9AC3F57E8D5242B386A597EF6C40A7999F37F1948636FD484E25B744630440220680BBD745004E9CFB6B13A137F505FB92298AD309071D16C7B982825188FD1AE022004200B1F7E4A6A84BB0E4FC09E1E3BA2B66EBD32F0E6D121A34BA3B04AD99BC181147908A7F0EDD48EA896C3580A399F0EE78611C8E3E1F1",
-      "tx_json" : {
-         "Account" : "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
-         "Fee" : "30000",
-         "Flags" : 262144,
-         "LimitAmount" : {
-            "currency" : "USD",
-            "issuer" : "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
-            "value" : "100"
-         },
-         "Sequence" : 2,
-         "Signers" : [
-            {
-               "Signer" : {
-                  "Account" : "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-                  "SigningPubKey" : "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
-                  "TxnSignature" : "30450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E5"
-               }
-            },
-            {
-               "Signer" : {
-                  "Account" : "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
-                  "SigningPubKey" : "028FFB276505F9AC3F57E8D5242B386A597EF6C40A7999F37F1948636FD484E25B",
-                  "TxnSignature" : "30440220680BBD745004E9CFB6B13A137F505FB92298AD309071D16C7B982825188FD1AE022004200B1F7E4A6A84BB0E4FC09E1E3BA2B66EBD32F0E6D121A34BA3B04AD99BC1"
-               }
-            }
-         ],
-         "SigningPubKey" : "",
-         "TransactionType" : "TrustSet",
-         "hash" : "BD636194C48FD7A100DE4C972336534C8E710FD008C0F3CF7BC5BF34DAF3C3E6"
-      }
-   }
-}
-
-

Depending on the SignerList you configured, you may need to repeat this step several times to get signatures from all the necessary parties.

-

4. Combine signatures and submit

-

If you collected the signatures in serial, the tx_json from the last sign_for response has all the signatures assembled, so you can use that as the argument to the submit_multisigned command.

-

If you collected the signatures in parallel, you must manually construct a tx_json object with all the signatures included. Take the Signers arrays from all the sign_for responses, and combine their contents into a single Signers array that has each signature. Add the combined Signers array to the original transaction JSON value, and use that as the argument to the submit_multisigned command.

-
$ rippled submit_multisigned '{
->              "Account" : "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
->              "Fee" : "30000",
->              "Flags" : 262144,
->              "LimitAmount" : {
->                 "currency" : "USD",
->                 "issuer" : "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
->                 "value" : "100"
->              },
->              "Sequence" : 2,
->              "Signers" : [
->                 {
->                    "Signer" : {
->                       "Account" : "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
->                       "SigningPubKey" : "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
->                       "TxnSignature" : "30450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E5"
->                    }
->                 },
->                 {
->                    "Signer" : {
->                       "Account" : "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
->                       "SigningPubKey" : "028FFB276505F9AC3F57E8D5242B386A597EF6C40A7999F37F1948636FD484E25B",
->                       "TxnSignature" : "30440220680BBD745004E9CFB6B13A137F505FB92298AD309071D16C7B982825188FD1AE022004200B1F7E4A6A84BB0E4FC09E1E3BA2B66EBD32F0E6D121A34BA3B04AD99BC1"
->                    }
->                 }
->              ],
->              "SigningPubKey" : "",
->              "TransactionType" : "TrustSet",
->              "hash" : "BD636194C48FD7A100DE4C972336534C8E710FD008C0F3CF7BC5BF34DAF3C3E6"
->           }'
-Loading: "/home/mduo13/.config/ripple/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-    "result": {
-        "engine_result": "tesSUCCESS",
-        "engine_result_code": 0,
-        "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
-        "status": "success",
-        "tx_blob": "1200142200040000240000000263D5038D7EA4C680000000000000000000000000005553440000000000B5F762798A53D543A014CAF8B297CFF8F2F937E868400000000000753073008114A3780F5CB5A44D366520FC44055E8ED44D9A2270F3E010732102B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF744730450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E58114204288D2E47F8EF6C99BCC457966320D12409711E1E0107321028FFB276505F9AC3F57E8D5242B386A597EF6C40A7999F37F1948636FD484E25B744630440220680BBD745004E9CFB6B13A137F505FB92298AD309071D16C7B982825188FD1AE022004200B1F7E4A6A84BB0E4FC09E1E3BA2B66EBD32F0E6D121A34BA3B04AD99BC181147908A7F0EDD48EA896C3580A399F0EE78611C8E3E1F1",
-        "tx_json": {
-            "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
-            "Fee": "30000",
-            "Flags": 262144,
-            "LimitAmount": {
-                "currency": "USD",
-                "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
-                "value": "100"
-            },
-            "Sequence": 2,
-            "Signers": [{
-                "Signer": {
-                    "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-                    "SigningPubKey": "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
-                    "TxnSignature": "30450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E5"
-                }
-            }, {
-                "Signer": {
-                    "Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
-                    "SigningPubKey": "028FFB276505F9AC3F57E8D5242B386A597EF6C40A7999F37F1948636FD484E25B",
-                    "TxnSignature": "30440220680BBD745004E9CFB6B13A137F505FB92298AD309071D16C7B982825188FD1AE022004200B1F7E4A6A84BB0E4FC09E1E3BA2B66EBD32F0E6D121A34BA3B04AD99BC1"
-                }
-            }],
-            "SigningPubKey": "",
-            "TransactionType": "TrustSet",
-            "hash": "BD636194C48FD7A100DE4C972336534C8E710FD008C0F3CF7BC5BF34DAF3C3E6"
-        }
-    }
-}
-
-

Take note of the hash value from the response so you can check the results of the transaction later. (In this case, the hash is BD636194C48FD7A100DE4C972336534C8E710FD008C0F3CF7BC5BF34DAF3C3E6.)

-

5. Close the ledger

-

If you are using the live network, you can wait 4-7 seconds for the ledger to close automatically.

-

If you're running rippled in stand-alone mode, use the ledger_accept command to manually close the ledger:

-
$ rippled ledger_accept
-Loading: "/home/mduo13/.config/ripple/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-   "result" : {
-      "ledger_current_index" : 7,
-      "status" : "success"
-   }
-}
-
-

6. Confirm transaction results

-

Use the hash value from the response to the submit_multisigned command to look up the transaction using the tx command. In particular, check that the TransactionResult is the string tesSUCCESS.

-

On the live network, you must also confirm that the validated field is set to the boolean true. If the field is not true, you might need to wait longer for the consensus process to finish; or your transaction may be unable to be included in a ledger for some reason.

-

In stand-alone mode, the server automatically considers a ledger to be validated if it has been manually closed.

-
$ rippled tx BD636194C48FD7A100DE4C972336534C8E710FD008C0F3CF7BC5BF34DAF3C3E6
-Loading: "/home/mduo13/.config/ripple/rippled.cfg"
-Connecting to 127.0.0.1:5005
-{
-    "result": {
-        "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
-        "Fee": "30000",
-        "Flags": 262144,
-        "LimitAmount": {
-            "currency": "USD",
-            "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
-            "value": "100"
-        },
-        "Sequence": 2,
-        "Signers": [{
-            "Signer": {
-                "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
-                "SigningPubKey": "02B3EC4E5DD96029A647CFA20DA07FE1F85296505552CCAC114087E66B46BD77DF",
-                "TxnSignature": "30450221009C195DBBF7967E223D8626CA19CF02073667F2B22E206727BFE848FF42BEAC8A022048C323B0BED19A988BDBEFA974B6DE8AA9DCAE250AA82BBD1221787032A864E5"
-            }
-        }, {
-            "Signer": {
-                "Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
-                "SigningPubKey": "028FFB276505F9AC3F57E8D5242B386A597EF6C40A7999F37F1948636FD484E25B",
-                "TxnSignature": "30440220680BBD745004E9CFB6B13A137F505FB92298AD309071D16C7B982825188FD1AE022004200B1F7E4A6A84BB0E4FC09E1E3BA2B66EBD32F0E6D121A34BA3B04AD99BC1"
-            }
-        }],
-        "SigningPubKey": "",
-        "TransactionType": "TrustSet",
-        "date": 512172510,
-        "hash": "BD636194C48FD7A100DE4C972336534C8E710FD008C0F3CF7BC5BF34DAF3C3E6",
-        "inLedger": 6,
-        "ledger_index": 6,
-        "meta": {
-            "AffectedNodes": [{
-                "ModifiedNode": {
-                    "LedgerEntryType": "AccountRoot",
-                    "LedgerIndex": "2B6AC232AA4C4BE41BF49D2459FA4A0347E1B543A4C92FCEE0821C0201E2E9A8",
-                    "PreviousTxnID": "B7E1D33DB7DEA3BB65BFAB2C80E02125F47FCCF6C957A7FDECD915B3EBE0C1DD",
-                    "PreviousTxnLgrSeq": 4
-                }
-            }, {
-                "CreatedNode": {
-                    "LedgerEntryType": "RippleState",
-                    "LedgerIndex": "93E317B32022977C77810A2C558FBB28E30E744C68E73720622B797F957EC5FA",
-                    "NewFields": {
-                        "Balance": {
-                            "currency": "USD",
-                            "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
-                            "value": "0"
-                        },
-                        "Flags": 2162688,
-                        "HighLimit": {
-                            "currency": "USD",
-                            "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
-                            "value": "0"
-                        },
-                        "LowLimit": {
-                            "currency": "USD",
-                            "issuer": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
-                            "value": "100"
-                        }
-                    }
-                }
-            }, {
-                "ModifiedNode": {
-                    "FinalFields": {
-                        "Account": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
-                        "Balance": "999960000",
-                        "Flags": 0,
-                        "OwnerCount": 6,
-                        "Sequence": 3
-                    },
-                    "LedgerEntryType": "AccountRoot",
-                    "LedgerIndex": "A6B1BA6F2D70813100908EA84ABB7783695050312735E2C3665259F388804EA0",
-                    "PreviousFields": {
-                        "Balance": "999990000",
-                        "OwnerCount": 5,
-                        "Sequence": 2
-                    },
-                    "PreviousTxnID": "8FDC18960455C196A8C4DE0D24799209A21F4A17E32102B5162BD79466B90222",
-                    "PreviousTxnLgrSeq": 5
-                }
-            }, {
-                "ModifiedNode": {
-                    "FinalFields": {
-                        "Flags": 0,
-                        "Owner": "rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC",
-                        "RootIndex": "C2728175908D82FB1DE6676F203D8D3C056995A9FA9B369EF326523F1C65A1DE"
-                    },
-                    "LedgerEntryType": "DirectoryNode",
-                    "LedgerIndex": "C2728175908D82FB1DE6676F203D8D3C056995A9FA9B369EF326523F1C65A1DE"
-                }
-            }, {
-                "CreatedNode": {
-                    "LedgerEntryType": "DirectoryNode",
-                    "LedgerIndex": "D8120FC732737A2CF2E9968FDF3797A43B457F2A81AA06D2653171A1EA635204",
-                    "NewFields": {
-                        "Owner": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
-                        "RootIndex": "D8120FC732737A2CF2E9968FDF3797A43B457F2A81AA06D2653171A1EA635204"
-                    }
-                }
-            }],
-            "TransactionIndex": 0,
-            "TransactionResult": "tesSUCCESS"
-        },
-        "status": "success",
-        "validated": true
-    }
-}
-
-
-
-
- - - - \ No newline at end of file diff --git a/tutorial-paychan.html b/tutorial-paychan.html deleted file mode 100644 index 11ca08781f..0000000000 --- a/tutorial-paychan.html +++ /dev/null @@ -1,750 +0,0 @@ - - - - - - - - Payment Channels Tutorial - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

Payment Channels Tutorial

-

Payment Channels are an advanced feature for sending "asynchronous" XRP payments that can be divided into very small increments and settled later. This tutorial walks through the entire process of using a payment channel, with examples using the JSON-RPC API of a local rippled server.

-

Background

-

The process of using a payment channel always involves two parties, a payer and a payee. The payer is an individual person or institution using the XRP Ledger who is a customer of the payee. The payee is a person or business who is doing business on the XRP Ledger (XRP Ledger), receiving XRP as payment for goods or services.

-

The types of goods and services are not defined by the software or in this tutorial. However, the types of goods and services that are a good fit for payment channels are:

-
    -
  • Things that can be transmitted near-instantly, like digital items
    • -
  • Inexpensive things, where the cost of processing a transaction is a non-trivial portion of the price
    • -
  • Things normally bought in bulk, where the exact quantity desired is not known in advance
    • -
-

Ideally, to step through this tutorial, you would have two people, each with the keys to a funded XRP Ledger account. However, you can also step through the tutorial as one person managing two XRP Ledger addresses.

-

Example Values

-

The example addresses used in this tutorial are:

- - - - - - - - - - - - - - - - - - - - - - - - - -
Payer's addressrN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH
Public key used for channel (in base58)aB44YfzW24VDEJQ2UuLPV2PvqcPCSoLnL7y5M1EzhdW4LnK5xMS3
Public key used for channel (in hex)023693F15967AE357D0327974AD46FE3C127113B1110D6044FD41E723689F81CC6
Payee's addressrf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn
-

Tip: In this example, the channel's public key is the public key from the payer's master key pair. This is perfectly safe and valid. It is also perfectly safe and valid to use a different key pair, as long as only the payer knows the public and secret keys for that key pair.

-

Additionally, you'll need a rippled server to send transactions to. The examples in this tutorial assume a rippled server is running on the test machine (localhost) with an unencrypted JSON-RPC API endpoint on port 5005.

-

To test without transferring real XRP, you can use Ripple Test Net addresses with Test Net XRP. If you do use the Ripple Test Net, you can use the Test Net servers' JSON-RPC API by connecting to https://api.altnet.rippletest.net:51234 instead of http://localhost:5005/.

-

You can use any amount of XRP for the payment channels. The example values in this tutorial set aside 100 XRP (100000000 drops) in a payment channel for at least 1 day.

-

Flow Diagram

-

The following diagram summarizes the lifecycle of a payment channel:

-

Payment Channel Flow Diagram

-

You can match up the numbered steps in this diagram with the steps of this tutorial.

-
    -
  1. Payer: Create channel
    2. -
  2. Payee: Check channel
    3. -
  3. Payer: Sign claims
    4. -
  4. Payer: Send claim(s) to payee
    5. -
  5. Payee: Verify claims
    6. -
  6. Payee: Provide goods or services
    7. -
  7. Repeat steps 3-6 as desired
    8. -
  8. Payee: Redeem claim
    9. -
  9. Payer: Request to close channel
    10. -
  10. Payer (or anyone else): Close expired channel
    11. -
-

1. The payer creates a payment channel to a particular recipient.

-

This is a PaymentChannelCreate transaction. As part of this process, the payer sets certain specifics of the channel like an expiration time and a settlement delay, which affect the guarantees around the claims in the channel. The payer also sets the public key that will be used to verify claims against the channel.

-

Tip: The "settlement delay" does not delay the settlement, which can happen as fast as a ledger version closes (3-5 seconds). The "settlement delay" is a forced delay on closing the channel so that the payee has a chance to finish with settlement.

-

The following example shows creation of a payment channel by submitting to a local rippled server with the JSON-RPC API. The payment channel allocates 100 XRP from the example payer (rN7n7...) to the example payee (rf1Bi...) with a settlement delay of 1 day. The public key is the example payer's master public key, in hexadecimal.

-

Request:

-
POST http://localhost:5005/
-Content-Type: application/json
-
-{
-    "method": "submit",
-    "params": [{
-        "secret": "s████████████████████████████",
-        "tx_json": {
-            "Account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-            "TransactionType": "PaymentChannelCreate",
-            "Amount": "100000000",
-            "Destination": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-            "SettleDelay": 86400,
-            "PublicKey": "023693F15967AE357D0327974AD46FE3C127113B1110D6044FD41E723689F81CC6",
-            "DestinationTag": 20170428
-        },
-        "fee_mult_max": 1000
-    }]
-}
-
-

Response:

-
200 OK
-
-{
-    "result": {
-        "engine_result": "tesSUCCESS",
-        "engine_result_code": 0,
-        "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
-        ...
-        "tx_json": {
-            ...
-            "TransactionType": "PaymentChannelCreate",
-            "hash": "3F93C482C0BC2A1387D9E67DF60BECBB76CC2160AE98522C77AF0074D548F67D"
-        }
-    }
-}
-
-

The immediate response to the submit request contains a provisional result with the transaction's identifying hash value. The payer should check the transaction's final result in a validated ledger and get the Channel ID from the metadata. This can be done with the tx command:

-

Request:

-
POST http://localhost:5005/
-Content-Type: application/json
-
-{
-    "method": "tx",
-    "params": [{
-        "transaction": "3F93C482C0BC2A1387D9E67DF60BECBB76CC2160AE98522C77AF0074D548F67D"
-    }]
-}
-
-

Response:

-
200 OK
-
-{
-    "result": {
-        "Account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-        "Amount": "100000000",
-        "Destination": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-        ...
-        "TransactionType": "PaymentChannelCreate",
-        ...
-        "hash": "3F93C482C0BC2A1387D9E67DF60BECBB76CC2160AE98522C77AF0074D548F67D",
-        "inLedger": 29380080,
-        "ledger_index": 29380080,
-        "meta": {
-            "AffectedNodes": [
-                ...
-                {
-                    "CreatedNode": {
-                        "LedgerEntryType": "PayChannel",
-                        "LedgerIndex": "5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3",
-                        "NewFields": {
-                            "Account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-                            "Amount": "100000000",
-                            "Destination": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-                            "DestinationTag": 20170428,
-                            "PublicKey": "023693F15967AE357D0327974AD46FE3C127113B1110D6044FD41E723689F81CC6",
-                            "SettleDelay": 86400
-                        }
-                    }
-                },
-                ...
-            ],
-            "TransactionIndex": 16,
-            "TransactionResult": "tesSUCCESS"
-        },
-        "status": "success",
-        "validated": true
-    }
-}
-
-

In the response from the JSON-RPC, the payer should look for the following:

-
    -
  • In the transaction's meta field, confirm that the TransactionResult is tesSUCCESS.
    • -
  • Confirm that the response has "validated":true to indicate the data comes from a validated ledger. (The result tesSUCCESS is only final if it appears in a validated ledger version.)
    • -
  • In the AffectedNodes array of the transaction's meta field, look for a CreatedNode object with the LedgerEntryType of PayChannel. The LedgerIndex field of the CreatedNode object indicates the Channel ID. (In the above example, this is a hex string starting with "5DB0...") The Channel ID is necessary later to sign claims. - For more information on the PayChannel ledger object type, see PayChannel ledger node type.
    • -
-

2. The payee checks specifics of the payment channel.

-

You can look up payment channels with the account_channels API method, using the payer of the channel, as in the following example (using the JSON-RPC API):

-

Request:

-
POST http://localhost:5005/
-Content-Type: application/json
-
-{
-    "method": "account_channels",
-    "params": [{
-        "account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-        "destination_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-        "ledger_index": "validated"
-    }]
-}
-
-

Response:

-
200 OK
-
-{
-    "result": {
-        "account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-        "channels": [{
-            "account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-            "amount": "100000000",
-            "balance": "0",
-            "channel_id": "5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3",
-            "destination_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-            "destination_tag": 20170428,
-            "public_key": "aB44YfzW24VDEJQ2UuLPV2PvqcPCSoLnL7y5M1EzhdW4LnK5xMS3",
-            "public_key_hex": "023693F15967AE357D0327974AD46FE3C127113B1110D6044FD41E723689F81CC6",
-            "settle_delay": 86400
-        }],
-        "status": "success"
-    }
-}
-
-

The payee should check that the parameters of the payment channel are suitable for their specific use case, including all of the following:

-
    -
  • Confirm the destination_account field has the payee's correct address.
    • -
  • Confirm the settle_delay field has a settlement delay in seconds that provides enough time for the payee to redeem outstanding claims.
    • -
  • Confirm the fields cancel_after (immutable expiration) and expiration (mutable expiration), if they are present, are not too soon. The payee should take note of these times so they can be sure to redeem claims before then.
    • -
  • Take note of the public_key and channel_id fields. These are necessary later to verify and redeem claims.
    • -
  • (Optional) Confirm the destination_tag field is present and has a desired destination tag.
    • -
-

Since there can be multiple channels between the same two parties, it is important for the payee to check the qualities of the correct channel. If there is any chance of confusion, the payer should clarify the Channel ID (channel_id) of the channel to use.

-

3. The payer creates one or more signed claims for the XRP in the channel.

-

The amounts of these claims depends on the specific goods or services the payer wants to pay for.

-

Each claim must be for a cumulative amount. In other words, to purchase two items at 10 XRP each, the first claim should have an amount of 10 XRP and the second claim should have an amount of 20 XRP. The claim can never be more than the total amount of XRP allocated to the channel. (A PaymentChannelFund transaction can increase the total amount of XRP allocated to the channel.)

-

You can create claims with the channel_authorize API method. The following example authorizes 1 XRP from the channel:

-

Request:

-
POST http://localhost:5005/
-Content-Type: application/json
-
-{
-    "method": "channel_authorize",
-    "params": [{
-        "channel_id": "5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3",
-        "secret": "s████████████████████████████",
-        "amount": "1000000"
-    }]
-}
-
-

Response:

-
{
-    "result": {
-        "signature": "304402204EF0AFB78AC23ED1C472E74F4299C0C21F1B21D07EFC0A3838A420F76D783A400220154FB11B6F54320666E4C36CA7F686C16A3A0456800BBC43746F34AF50290064",
-        "status": "success"
-    }
-}
-
-

4. The payer sends a claim to the payee as payment for goods or services.

-

This communication happens "off-ledger" in any communication system the payer and payee can agree to. You should use secure communications for this, but it's not strictly necessary. Only the payer or payee of a channel can redeem claims against that channel.

-

The exact format of the claim is not important as long as it communicates the following information:

- - - - - - - - - - - - - - - - - - - - - -
FieldExample
Channel ID5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3
Amount of XRP, in drops1000000
Signature304402204EF0AFB78AC23ED1C472E74F4299C0C21F1B21D07EFC0A3838A420F76D783A
400220154FB11B6F54320666E4C36CA7F686C16A3A0456800BBC43746F34AF50290064 (Note: this long string has been broken to fit on one line.)
-

The payee also needs to know the Public Key associated with the channel, which is the same throughout the channel's life.

-

5. The payee verifies the claims.

-

You can verify claims using the channel_verify API method. The payee should confirm that the amount of the claim is equal to or greater than the total price of goods and services provided. (Since the amount is cumulative, this is the total price of all goods and services purchased so far.)

-

Example of using channel_verify with the JSON-RPC API:

-

Request:

-
POST http://localhost:5005/
-Content-Type: application/json
-
-{
-    "method": "channel_verify",
-    "params": [{
-        "channel_id": "5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3",
-        "signature": "304402204EF0AFB78AC23ED1C472E74F4299C0C21F1B21D07EFC0A3838A420F76D783A400220154FB11B6F54320666E4C36CA7F686C16A3A0456800BBC43746F34AF50290064",
-        "public_key": "aB44YfzW24VDEJQ2UuLPV2PvqcPCSoLnL7y5M1EzhdW4LnK5xMS3",
-        "amount": "1000000"
-    }]
-}
-
-

Response:

-
200 OK
-
-{
-    "result": {
-        "signature_verified":true,
-        "status":"success"
-    }
-}
-
-

If the response shows "signature_verified": true then the claim's signature is genuine. The payee must also confirm that the channel has enough XRP available to honor the claim. To do this, the payee makes an account_channels request to confirm the most recent validated state of the payment channel.

-

Request:

-
POST http://localhost:5005/
-Content-Type: application/json
-
-{
-    "method": "account_channels",
-    "params": [{
-        "account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-        "destination_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-        "ledger_index": "validated"
-    }]
-}
-
-

Response:

-
200 OK
-
-{
-    "result": {
-        "account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-        "channels": [{
-            "account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-            "amount": "100000000",
-            "balance": "0",
-            "channel_id": "5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3",
-            "destination_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-            "destination_tag": 20170428,
-            "public_key": "aB44YfzW24VDEJQ2UuLPV2PvqcPCSoLnL7y5M1EzhdW4LnK5xMS3",
-            "public_key_hex": "023693F15967AE357D0327974AD46FE3C127113B1110D6044FD41E723689F81CC6",
-            "settle_delay": 86400
-        }],
-        "status": "success"
-    }
-}
-
-

The payee should check the following:

-
    -
  • Find the object in the channels array whose channel_id matches the Channel ID of the claim. It is possible to have multiple payment channels, even between the same parties, but a claim can only be redeemed against the channel with the matching ID.
    • -
  • Confirm that the expiration (mutable expiration) of the channel, if present, is not too soon. The payee must redeem claims before this time.
    • -
  • Confirm that the amount of the claim is equal or less than the amount of the channel. If the amount of the claim is higher, the claim cannot be redeemed unless the payer uses a PaymentChannelFund transaction to increase the total amount of XRP available to the channel.
    • -
  • Confirm that the balance of the channel matches the amount the payee expects to have already received from the channel. If these do not match up, the payee should double-check the channel's transaction history. Some possible explanations for a mismatch include:
      -
    • The payer used a PaymentChannelClaim transaction to deliver XRP from the channel to the payee, but the payee did not notice and record the incoming transaction.
      • -
    • The payee's records include transactions that are "in flight" or have not yet been included in the latest validated ledger version. The payee can use the tx command to look up the state of individual transactions to check this.
      • -
    • The account_channels request did not specify the correct ledger version. (Use "ledger_index": "validated" to get the latest validated ledger version)
      • -
    • The payee previously redeemed XRP but forgot to record it.
      • -
    • The payee attempted to redeem XRP and recorded the tentative result, but the transaction's final validated result was not the same and the payee neglected to record the final validated result.
      • -
    • The rippled server the payee queried has lost sync with the rest of the network or is experiencing an unknown bug. Use the server_info command to check the state of the server. (If you can reproduce this situation, please report an issue.)
      • -
    -
    • -
-

After confirming both the signature and the current state of the payment channel, the payee has not yet received the XRP, but is certain that he or she can redeem the XRP as long as the transaction to do so is processed before the channel expires.

-

6. Payee provides goods or services.

-

At this point, the payee can provide goods and services to the payer, knowing that payment is already assured.

-

For purposes of this tutorial, the payee can give the payer a high-five or equivalent online message as the "goods and services".

-

7. Repeat steps 3-6 as desired.

-

The payer and payee can repeat steps 3 through 6 (creating, transmitting, and verifying claims in exchange for goods and services) as many times and as often as they like without waiting for the XRP Ledger itself. The two main limits of this process are:

-
    -
  • -

    The amount of XRP in the payment channel. (If necessary, the payer can send a PaymentChannelFund transaction to increase the total amount of XRP available to the channel.)

    -
    • -
  • -

    The immutable expiration of the payment channel, if one is set. (The cancel_after field in the account_channels response shows this.)

    -
    • -
-

8. When ready, the payee redeems a claim for the authorized amount.

-

This is the point where the payee finally receives some XRP from the channel.

-

This is a PaymentChannelClaim transaction with the Balance, Amount, Signature, and PublicKey fields provided. Because claim values are cumulative, the payee only needs to redeem the largest (most recent) claim to get the full amount. The payee is not required to redeem the claim for the full amount authorized.

-

The payee can do this multiple times, to settle partially while still doing business, if desired.

-

Example of claiming XRP from a channel:

-

Request:

-
POST http://localhost:5005/
-Content-Type: application/json
-
-{
-    "method": "submit",
-    "params": [{
-            "secret": "s████████████████████████████",
-            "tx_json": {
-                "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-                "TransactionType": "PaymentChannelClaim",
-                "Amount": "1000000",
-                "Balance": "1000000",
-                "Channel": "5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3",
-                "PublicKey": "023693F15967AE357D0327974AD46FE3C127113B1110D6044FD41E723689F81CC6",
-                "Signature": "304402204EF0AFB78AC23ED1C472E74F4299C0C21F1B21D07EFC0A3838A420F76D783A400220154FB11B6F54320666E4C36CA7F686C16A3A0456800BBC43746F34AF50290064"
-            },
-            "fee_mult_max": 1000
-        }]
-}
-
-

Response:

-
200 OK
-
-{
-    "result": {
-        "engine_result": "tesSUCCESS",
-        "engine_result_code": 0,
-        "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
-        "status": "success",
-        "tx_blob": "12000F2280000000240000017450165DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB36140000000000F42406240000000000F424068400000000000000A7121023693F15967AE357D0327974AD46FE3C127113B1110D6044FD41E723689F81CC6732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB7447304502210096B933BC24DA77D8C4057B4780B282BA66C668DFE1ACF4EEC063AD6661725797022037C8823669CE91AACA8CC754C9F041359F85B0B32384AEA141EBC3603798A24C7646304402204EF0AFB78AC23ED1C472E74F4299C0C21F1B21D07EFC0A3838A420F76D783A400220154FB11B6F54320666E4C36CA7F686C16A3A0456800BBC43746F34AF5029006481144B4E9C06F24296074F7BC48F92A97916C6DC5EA9",
-        "tx_json": {
-            "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-            "Amount": "1000000",
-            "Balance": "1000000",
-            "Channel": "5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3",
-            "Fee": "10",
-            "Flags": 2147483648,
-            "PublicKey": "023693F15967AE357D0327974AD46FE3C127113B1110D6044FD41E723689F81CC6",
-            "Sequence": 372,
-            "Signature": "304402204EF0AFB78AC23ED1C472E74F4299C0C21F1B21D07EFC0A3838A420F76D783A400220154FB11B6F54320666E4C36CA7F686C16A3A0456800BBC43746F34AF50290064",
-            "SigningPubKey": "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB",
-            "TransactionType": "PaymentChannelClaim",
-            "TxnSignature": "304502210096B933BC24DA77D8C4057B4780B282BA66C668DFE1ACF4EEC063AD6661725797022037C8823669CE91AACA8CC754C9F041359F85B0B32384AEA141EBC3603798A24C",
-            "hash": "C9FE08FC88CF76C3B06622ADAA47AE99CABB3380E4D195E7751274CFD87910EB"
-        }
-    }
-}
-
-

The payee should confirm that this transaction is successful in a validated ledger. For the full details, see Reliable Transaction Submission.

-

9. When the payer and payee are done doing business, the payer requests for the channel to be closed.

-

This is a PaymentChannelClaim transaction with the tfClose flag set, or a PaymentChannelFund transaction with the Expiration field set. (9a in the flow diagram).

-

If the channel has no XRP remaining in it when the payer requests to close the channel, it closes immediately.

-

If the channel does have XRP remaining, the request to close a channel acts as a final warning to the payee to redeem any outstanding claims right away. The payee has an amount of time no less than the settlement delay before the channel is closed. The exact number of seconds varies slightly based on the close times of ledgers.

-

The payee can also close a payment channel immediately after processing a claim (9b in the flow diagram).

-

Example of submitting a transaction requesting a channel to close:

-
{
-    "method": "submit",
-    "params": [{
-        "secret": "s████████████████████████████",
-        "tx_json": {
-            "Account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-            "TransactionType": "PaymentChannelClaim",
-            "Channel": "5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3",
-            "Flags": 2147614720
-        },
-        "fee_mult_max": 1000
-    }]
-}
-
-

After the transaction is included in a validated ledger, either party can look up the currently-scheduled expiration of the channel using the account_channels method. Be sure to specify "ledger_index": "validated" to get data from the latest validated ledger version.

-

Example account_channels response:

-
{
-    "result": {
-        "account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-        "channels": [
-            {
-                "account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-                "amount": "100000000",
-                "balance": "1000000",
-                "channel_id": "5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3",
-                "destination_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-                "destination_tag": 20170428,
-                "expiration": 547073182,
-                "public_key": "aB44YfzW24VDEJQ2UuLPV2PvqcPCSoLnL7y5M1EzhdW4LnK5xMS3",
-                "public_key_hex": "023693F15967AE357D0327974AD46FE3C127113B1110D6044FD41E723689F81CC6",
-                "settle_delay": 86400
-            }
-        ],
-        "status": "success"
-    }
-}
-
-

In this example, the expiration value 547073182 in seconds since the Ripple Epoch maps to 2017-05-02T20:46:22Z, so any claims not redeemed by that time are no longer valid.

-

10. Anyone can close the expired channel.

-

After the settlement delay has passed or the channel has reached its planned expiration time, the channel is expired. Any further transaction that would affect the channel can only close it, returning unclaimed XRP to the payer.

-

The channel can remain on the ledger in an expired state indefinitely. This is because the ledger cannot change except as the results of a transaction, so someone must send a transaction to cause the expired channel to close. As long as the channel remains on the ledger, it counts as an object owned by the payer for purposes of the owner reserve.

-

Ripple recommends that the payer sends a second PaymentChannelClaim transaction with the tfClose flag for this purpose. However, other accounts, even those not involved in the payment channel, can cause an expired channel to close.

-

The command to submit the transaction is identical to the previous example requesting channel expiration. (However, its resulting auto-filled Sequence number, signature, and identifying hash are unique.)

-

Example of submitting a transaction to close an expired channel:

-
{
-    "method": "submit",
-    "params": [{
-        "secret": "s████████████████████████████",
-        "tx_json": {
-            "Account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-            "TransactionType": "PaymentChannelClaim",
-            "Channel": "5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3",
-            "Flags": 2147614720
-        },
-        "fee_mult_max": 1000
-    }]
-}
-
-

When the transaction has been included in a validated ledger, you can look at the metadata of the transaction to confirm that it deleted the channel and returned the XRP to the sender.

-

Example response from using the tx command to look up the transaction from this step:

-
{
-    "result": {
-        "Account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-        "Channel": "5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3",
-        "Fee": "5606",
-        "Flags": 2147614720,
-        "Sequence": 41,
-        "SigningPubKey": "023693F15967AE357D0327974AD46FE3C127113B1110D6044FD41E723689F81CC6",
-        "TransactionType": "PaymentChannelClaim",
-        "TxnSignature": "3044022008922FEB6F7D35D42006685BCBB007103D2A40AFAA69A7CFC10DF529F94BB6A402205D67816F50BBAEE0A2709AA3A93707304EC21133550FD2FF7436AD0C3CA6CE27",
-        "date": 547091262,
-        "hash": "9C0CAAC3DD1A74461132DA4451F9E53BDF4C93DFDBEFCE1B10021EC569013B33",
-        "inLedger": 29480670,
-        "ledger_index": 29480670,
-        "meta": {
-            "AffectedNodes": [
-                {
-                    "ModifiedNode": {
-                        "LedgerEntryType": "AccountRoot",
-                        "LedgerIndex": "13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8",
-                        "PreviousTxnID": "C9FE08FC88CF76C3B06622ADAA47AE99CABB3380E4D195E7751274CFD87910EB",
-                        "PreviousTxnLgrSeq": 29385089
-                    }
-                },
-                {
-                    "DeletedNode": {
-                        "FinalFields": {
-                            "Account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-                            "Amount": "100000000",
-                            "Balance": "1000000",
-                            "Destination": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
-                            "DestinationTag": 20170428,
-                            "Expiration": 547073182,
-                            "Flags": 0,
-                            "OwnerNode": "0000000000000000",
-                            "PreviousTxnID": "C5C70B2BCC515165B7F62ACC8126F8F8B655EB6E1D949A49B2358262BDA986B4",
-                            "PreviousTxnLgrSeq": 29451256,
-                            "PublicKey": "023693F15967AE357D0327974AD46FE3C127113B1110D6044FD41E723689F81CC6",
-                            "SettleDelay": 86400
-                        },
-                        "LedgerEntryType": "PayChannel",
-                        "LedgerIndex": "5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3"
-                    }
-                },
-                {
-                    "ModifiedNode": {
-                        "FinalFields": {
-                            "Account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-                            "Balance": "1041862844",
-                            "Flags": 0,
-                            "OwnerCount": 2,
-                            "Sequence": 42
-                        },
-                        "LedgerEntryType": "AccountRoot",
-                        "LedgerIndex": "B1CB040A17F9469BC00376EC8719535655824AD16CB5F539DD5765FEA88FDBE3",
-                        "PreviousFields": {
-                            "Balance": "942868450",
-                            "OwnerCount": 3,
-                            "Sequence": 41
-                        },
-                        "PreviousTxnID": "C5C70B2BCC515165B7F62ACC8126F8F8B655EB6E1D949A49B2358262BDA986B4",
-                        "PreviousTxnLgrSeq": 29451256
-                    }
-                },
-                {
-                    "ModifiedNode": {
-                        "FinalFields": {
-                            "Flags": 0,
-                            "Owner": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
-                            "RootIndex": "E590FC40B4F24D18341569BD3702A2D4E07E7BC04D11CE63608B67979E67030C"
-                        },
-                        "LedgerEntryType": "DirectoryNode",
-                        "LedgerIndex": "E590FC40B4F24D18341569BD3702A2D4E07E7BC04D11CE63608B67979E67030C"
-                    }
-                }
-            ],
-            "TransactionIndex": 7,
-            "TransactionResult": "tesSUCCESS"
-        },
-        "status": "success",
-        "validated": true
-    }
-}
-
-

In the transaction's metadata, look for the following:

-
    -
  • A DeletedNode entry with "LedgerEntryType": "PayChannel". The LedgerIndex field should match the Channel ID. This indicates that the channel was deleted.
    • -
  • A ModifiedNode entry with "LedgerEntryType": "AccountRoot". The change in the Balance field in PreviousFields and FinalFields reflects the unspent XRP being returned to the payer.
    • -
-

Those fields indicate that the payment channel is closed.

-

Conclusion

-

This concludes the tutorial of Payment Channel usage. Ripple encourages users to find unique and interesting use cases to take full advantage of the speed and convenience of payment channels.

-
-
-
- - - - \ No newline at end of file diff --git a/tutorial-reliable-transaction-submission.html b/tutorial-reliable-transaction-submission.html deleted file mode 100644 index 3b12a69ea7..0000000000 --- a/tutorial-reliable-transaction-submission.html +++ /dev/null @@ -1,582 +0,0 @@ - - - - - - - - Reliable Transaction Submission - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

Reliable Transaction Submission

-

Financial institutions and other services using the XRP Ledger should use the best practices described here to make sure that transactions are validated or rejected in a verifiable and prompt way. You should submit transactions to trusted (locally operated) rippled servers.

-

The best practices detailed in this document allow applications to submit transactions to the XRP Ledger while achieving:

-
    -
  1. Idempotency - Transactions should be processed once and only once, or not at all.
    2. -
  2. Verifiability - Applications can determine the final result of a transaction.
    3. -
-

Applications which fail to implement best practices are at risk of the following errors:

-
    -
  1. Submitting transactions which are inadvertently never executed.
    2. -
  2. Mistaking provisional transaction results for their final, immutable results.
    3. -
  3. Failing to find authoritative results of transactions previously applied to the ledger.
    4. -
-

These types of errors can potentially lead to serious problems. For example, an application that fails to find a prior successful payment transaction might erroneously submit another transaction, duplicating the original payment. This underscores the importance that applications base their actions on authoritive transaction results, using the techniques described in this document.

-

Background

-

The XRP Ledger protocol provides a ledger shared across all servers in the network. Through a process of consensus and validation, the network agrees on order in which transactions are applied to (or omitted from) the ledger.

-

Well-formed transactions submitted to trusted XRP Ledger servers are usually validated or rejected in a matter of seconds. There are cases, however, in which a well-formed transaction is neither validated nor rejected this quickly. One specific case can occur if the global transaction cost increases after an application sends a transaction. If the transaction cost increases above what has been specified in the transaction, the transaction is not included in the next validated ledger. If at some later date the global transaction cost decreases, the transaction could be included in a later ledger. If the transaction does not specify an expiration, there is no limit to how much later this can occur.

-

If a power or network outage occurs, applications face more challenges finding the status of submitted transactions. Applications must take care both to properly submit a transaction and later to properly get authoritative results.

-

Transaction Timeline

-

The XRP Ledger provides several APIs for submitting transactions, including rippled, and RippleAPI. Regardless of the API used, the transaction is applied to the ledger as follows.

-
    -
  1. An account owner creates and signs a transaction.
    2. -
  2. The owner submits the transaction to the network as a candidate transaction.
      -
    • Malformed or nonsensical transactions are rejected immediately.
      • -
    • Well-formed transactions may provisionally succeed, then later fail.
      • -
    • Well-formed transactions may provisionally fail, then later succeed.
      • -
    • Well-formed transactions may provisionally succeed, and then later succeed in a slightly different way. (For example, by consuming a different offer and achieving a better or worse exchange rate than the provisional execution.)
      • -
    -
    3. -
  3. Through consensus and validation, the transaction is applied to the ledger. Even some failed transactions are applied, to enforce a cost for being propagated through the network.
    4. -
  4. The validated ledger includes the transaction, and its effects are reflected in the ledger state.
      -
    • Transaction results are no longer provisional, success or failure is now final and immutable.
      • -
    -
    5. -
-

Note: When submitting a transaction via rippled, a successful status code returned from a submit command indicates the rippled server has received the candidate transaction. The transaction may or may not be applied to a validated ledger.

-

APIs may return provisional results based on the result of applying candidate transactions to the current, in-progress ledger. Applications must not confuse these with the final, immutable, results of a transaction. Immutable results are found only in validated ledgers. Applications may need to query the status of a transaction repeatedly, until the ledger containing the transaction results is validated.

-

While applying transactions, rippled servers use the last validated ledger, a snapshot of the ledger state based on transactions the entire network has validated. The process of consensus and validation apply a set of new transactions to the last validated ledger in canonical order, resulting in a new validated ledger. This new validated ledger instance and the ones that preceded it form the ledger history.

-

Each validated ledger instance has a sequence number, which is one greater than the sequence number of the preceding instance. Each ledger also has an identifying hash value, which is uniquely determined from its contents. There may be many different versions of in-progress ledgers, which have the same sequence number but different hash values. Only one version can ever be validated.

-

Each validated ledger has a canonical order in which transactions apply. This order is deterministic based on the final transaction set of the ledger. In contrast, each rippled server's in-progress ledger is calculated incrementally, as transactions are received. The order in which transactions execute provisionally is usually not the same as the order in which transactions execute to build a new validated ledger. This is one reason why the provisional outcome of a transaction may be different than the final result. For example, a payment may achieve a different final exchange rate depending on whether it executes before or after another payment that would consume the same offer.

-

LastLedgerSequence

-

LastLedgerSequence is an optional parameter of all transactions. This instructs the XRP Ledger that a transaction must be validated on or before a specific ledger instance. The XRP Ledger never includes a transaction in a ledger instance whose sequence number is higher than the transaction's LastLedgerSequence parameter.

-

Use the LastLedgerSequence parameter to prevent undesirable cases where a transaction is not confirmed promptly but could be included in a future ledger. You should specify the LastLedgerSequence parameter on every transaction. Automated processes should use a value of 4 greater than the last validated ledger index to make sure that a transaction is validated or rejected in a predictable and prompt way.

-

Applications using rippled APIs should explicitly specify a LastLedgerSequence when submitting transactions. RippleAPI uses the maxLedgerVersion field of Transaction Instructions to specify the LastLedgerSequence. RippleAPI automatically provides an appropriate value by default. You can specify maxLedgerVersion as null to intentionally omit LastLedgerSequence, in case you want a transaction that can be executed after an unlimited amount of time.

-

Best Practices

-

Reliable Transactions Submission

-

Applications submitting transactions should use the following practices to submit reliably even in the event that a process dies or other failure occurs. Application transaction results must be verified so that applications can act on the final, validated results.

-

Submission and verification are two separate procedures which may be implemented using the logic described in this document.

-
    -
  1. Submission - The transaction is submitted to the network and a provisional result is returned.
    2. -
  2. Verification - The authoritative result is determined by examining validated ledgers.
    3. -
-

Submission

-

Persist details of the transaction before submission, in case of power failure or network failure before submission completes. On restart, the persisted values make it possible to verify the status of the transaction.

-

The submission process:

-
    -
  1. Construct and sign the transaction
      -
    • Include LastLedgerSequence parameter
      • -
    -
    2. -
  2. Persist the transaction details, saving:
      -
    • Transaction hash
      • -
    • LastLedgerSequence
      • -
    • Sender address and sequence number
      • -
    • Application-specific data, as needed
      • -
    -
    3. -
  3. Submit the transaction
    4. -
-

Verification

-

During normal operation, applications may check the status of submitted transactions by their hashes; or, depending on the API used, receive notifications when transactions have been validated (or failed). This normal operation may be interrupted, for example by network failures or power failures. In case of such interruption applications need to reliably verify the status of transactions which may or may not have been submitted to the network before the interruption.

-

On restart, or the determination of a new last validated ledger (pseudocode):

-
For each persisted transaction without validated result:
-    Query transaction by hash
-    If (result appears in validated ledger)
-        Persist the final result
-        If (result code is tesSUCCESS)
-            Application may act based on successful transaction
-        Else
-            Application may act based on failure
-            Maybe resubmit with new LastLedgerSequence and Fee
-    Else if (LastLedgerSequence > newest validated ledger)
-        Wait for more ledgers to be validated
-    Else
-        If (server has contiguous ledger history up to and
-            including the ledger identified by LastLedgerSequence)
-            The transaction failed
-            Submit a new transaction, if appropriate for application
-        Else
-            Repeat submission of original transaction
-
-

Technical Application

-

To implement the transaction submission and verification best practices, applications need to do the following:

-
    -
  1. Determine the signing account's next sequence number
      -
    • Each transaction has an account-specific sequence number. This guarantees the order in which transactions signed by an account are executed and makes it safe to resubmit a transaction without danger of the transaction being applied to the ledger more than once.
      • -
    -
    2. -
  2. Decide on a LastLedgerSequence
      -
    • A transaction's LastLedgerSequence is calculated from the last validated ledger sequence number.
      • -
    -
    3. -
  3. Construct and sign the transaction
      -
    • Persist the details of a signed transaction before submission.
      • -
    -
    4. -
  4. Submit the transaction
      -
    • Initial results are provisional and subject to change.
      • -
    -
    5. -
  5. Determine the final result of a transaction
      -
    • Final results are an immutable part of the ledger history.
      • -
    -
    6. -
-

How the application does these actions depends on the API the application uses. An application may use any of the following interfaces:

-
    -
  1. rippled's internal APIs
    2. -
  2. RippleAPI
    3. -
  3. Any number of other software APIs layered on top of rippled
    4. -
-

rippled - Submitting and Verifying Transactions

-

Determine the Account Sequence

-

rippled provides the account_info method to learn an account's sequence number in the last validated ledger.

-

JSON-RPC Request:

-
{
-  "method": "account_info",
-  "params": [
-    {
-      "account": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W",
-      "ledger": "validated"
-    }
-  ]
-}
-
-

Response body:

-
{
-    "result": {
-        "validated": true,
-        "status": "success",
-        "ledger_index": 10266396,
-        "account_data": {
-            "index": "96AB97A1BBC37F4F8A22CE28109E0D39D709689BDF412FE8EDAFB57A55E37F38",
-            "Sequence": 4,
-            "PreviousTxnLgrSeq": 9905632,
-            "PreviousTxnID": "CAEE0E34B3DB50A7A0CA486E3A236513531DE9E52EAC47CE4C26332CC847DE26",
-            "OwnerCount": 2,
-            "LedgerEntryType": "AccountRoot",
-            "Flags": 0,
-            "Balance": "49975988",
-            "Account": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W"
-        }
-    }
-}
-
-

In this example, the account's sequence is 4 (note "Sequence": 4, in "account_data") as of the last validated ledger (note "ledger": "validated" in the request, and "validated": "true" in the response).

-

If an application were to submit three transactions signed by this account, they would use sequence numbers 4, 5, and 6. To submit multiple transactions without waiting for validation of each, an application should keep a running account sequence number.

-

Determine the Last Validated Ledger

-

rippled provides the server_state command which returns the ledger sequence number of the last validated ledger.

-

Request:

-
{
-  "id": "client id 1",
-  "method": "server_state"
-}
-
-

Response:

-
{
-    "result": {
-        "status": "success",
-        "state": {
-            "validation_quorum": 3,
-            "validated_ledger": {
-                "seq": 10268596,
-                "reserve_inc": 5000000,
-                "reserve_base": 20000000,
-                "hash": "0E0901DA980251B8A4CCA17AB4CA6C3168FE83FA1D3F781AFC5B9B097FD209EF",
-                "close_time": 470798600,
-                "base_fee": 10
-            },
-            "server_state": "full",
-            "published_ledger": 10268596,
-            "pubkey_node": "n9LGg37Ya2SS9TdJ4XEuictrJmHaicdgTKiPJYi8QRSdvQd3xMnK",
-            "peers": 58,
-            "load_factor": 256000,
-            "load_base": 256,
-            "last_close": {
-                "proposers": 5,
-                "converge_time": 3004
-            },
-            "io_latency_ms": 2,
-            "fetch_pack": 10121,
-            "complete_ledgers": "10256331-10256382,10256412-10268596",
-            "build_version": "0.26.4-sp3-private"
-        }
-    }
-}
-
-

In this example the last validated ledger sequence number is 10268596 (found under result.state.validated_ledger in the response). Note also this example indicates a gap in ledger history. The server used here would not be able to provide information about the transactions applied during that gap (ledgers 10256383 through 10256411). If configured to do so, the server eventually retrieves that part of the ledger history.

-

Construct the Transaction

-

rippled provides the sign method to prepare a transaction for submission. This method requires an account secret, which should only be passed to trusted rippled instances. This example issues 10 FOO (a made-up currency) to another XRP Ledger address.

-

Request:

-
{
-    "method": "sign",
-    "params": [
-        {
-            "offline": true,
-            "secret": "sssssssssssssssssssssssssssss",
-            "tx_json": {
-               "Account": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W",
-                "Sequence": 4,
-                "LastLedgerSequence": 10268600,
-                "Fee": 10000,
-                "Amount": {
-                    "currency": "FOO",
-                    "issuer": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W",
-                    "value": "10"
-                },
-                "Destination": "rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM",
-                "TransactionType": "Payment"
-            }
-        }
-    ]
-}
-
-

Notice the application specifies the account sequence "Sequence": 4, learned from an earlier call to account_info, to avoid tefPAST_SEQ errors.

-

Notice also the LastLedgerSequence based on the last validated ledger our application learned from server_state. The recommendation for backend applications is to use (last validated ledger sequence + 4). Alternately, use a value of (current ledger + 3). If LastLedgerSequence is miscalculated and less than the last validated ledger, the transaction fails with tefMAX_LEDGER error.

-

Response:

-
{
-    "result": {
-        "tx_json": {
-            "hash": "395C313F6F11F70FEBAF3785529A6D6DE3F44C7AF679515A7EAE22B30146DE57",
-            "TxnSignature": "304402202646962A21EC0516FCE62DC9280F79E7265778C571E9410D795E67BB72A2D8E402202FF4AF7B2E2160F5BCA93011CB548014626CAC7FCBEBDB81FE8193CEFF69C753",
-            "TransactionType": "Payment",
-            "SigningPubKey": "0267268EE0DDDEE6A862C9FF9DDAF898CF17060A673AF771B565AA2F4AE24E3FC5",
-            "Sequence": 4,
-            "LastLedgerSequence": 10268600,
-            "Flags": 2147483648,
-            "Fee": "10000",
-            "Destination": "rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM",
-            "Amount": {
-                "value": "10",
-                "issuer": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W",
-                "currency": "FOO"
-            },
-            "Account": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W"
-        },
-        "tx_blob": "12000022800000002400000004201B009CAFB861D4C38D7EA4C68000000000000000000000000000464F4F0000000000AC5FA3BB28A09BD2EC1AE0EED2315060E83D796A68400000000000271073210267268EE0DDDEE6A862C9FF9DDAF898CF17060A673AF771B565AA2F4AE24E3FC57446304402202646962A21EC0516FCE62DC9280F79E7265778C571E9410D795E67BB72A2D8E402202FF4AF7B2E2160F5BCA93011CB548014626CAC7FCBEBDB81FE8193CEFF69C7538114AC5FA3BB28A09BD2EC1AE0EED2315060E83D796A831438BC6F9F5A6F6C4E474DB0D59892E90C2C7CED5C",
-        "status": "success"
-    }
-}
-
-

Applications should persist the transaction's hash before submitting. The result of the sign method includes the hash under tx_json.

-

Submit the transaction

-

rippled provides the submit method, allowing us to submit the signed transaction. This uses the tx_blob parameter that was returned by the sign method.

-

Request:

-
{
-    "method": "submit",
-    "params": [
-        {
-        "tx_blob": "12000022800000002400000004201B009CAFB861D4C38D7EA4C68000000000000000000000000000464F4F0000000000AC5FA3BB28A09BD2EC1AE0EED2315060E83D796A68400000000000271073210267268EE0DDDEE6A862C9FF9DDAF898CF17060A673AF771B565AA2F4AE24E3FC57446304402202646962A21EC0516FCE62DC9280F79E7265778C571E9410D795E67BB72A2D8E402202FF4AF7B2E2160F5BCA93011CB548014626CAC7FCBEBDB81FE8193CEFF69C7538114AC5FA3BB28A09BD2EC1AE0EED2315060E83D796A831438BC6F9F5A6F6C4E474DB0D59892E90C2C7CED5C"
-        }
-    ]
-}
-
-

Response:

-
{
-    "result": {
-        "tx_json": {
-            "hash": "395C313F6F11F70FEBAF3785529A6D6DE3F44C7AF679515A7EAE22B30146DE57",
-            "TxnSignature": "304402202646962A21EC0516FCE62DC9280F79E7265778C571E9410D795E67BB72A2D8E402202FF4AF7B2E2160F5BCA93011CB548014626CAC7FCBEBDB81FE8193CEFF69C753",
-            "TransactionType": "Payment",
-            "SigningPubKey": "0267268EE0DDDEE6A862C9FF9DDAF898CF17060A673AF771B565AA2F4AE24E3FC5",
-            "Sequence": 4,
-            "LastLedgerSequence": 10268600,
-            "Flags": 2147483648,
-            "Fee": "10000",
-            "Destination": "rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM",
-            "Amount": {
-                "value": "10",
-                "issuer": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W",
-                "currency": "FOO"
-            },
-            "Account": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W"
-        },
-        "tx_blob": "12000022800000002400000004201B009CAFB861D4C38D7EA4C68000000000000000000000000000464F4F0000000000AC5FA3BB28A09BD2EC1AE0EED2315060E83D796A68400000000000271073210267268EE0DDDEE6A862C9FF9DDAF898CF17060A673AF771B565AA2F4AE24E3FC57446304402202646962A21EC0516FCE62DC9280F79E7265778C571E9410D795E67BB72A2D8E402202FF4AF7B2E2160F5BCA93011CB548014626CAC7FCBEBDB81FE8193CEFF69C7538114AC5FA3BB28A09BD2EC1AE0EED2315060E83D796A831438BC6F9F5A6F6C4E474DB0D59892E90C2C7CED5C",
-        "status": "success",
-        "engine_result_message": "The transaction was applied.",
-        "engine_result_code": 0,
-        "engine_result": "tesSUCCESS"
-    }
-}
-
-

This a preliminary result. Final results are only available from validated ledgers. The lack of a "validated": true field indicates that this is not an immutable result.

-

Verify the Transaction

-

The transaction hash, generated when the transaction was signed, is passed to the tx method to retrieve the result of a transaction.

-

Request:

-
{
-    "method": "tx",
-    "params": [
-        {
-            "transaction": "395C313F6F11F70FEBAF3785529A6D6DE3F44C7AF679515A7EAE22B30146DE57",
-            "binary": false
-        }
-    ]
-}
-
-

Response:

-
{
-    "result": {
-        "validated": true,
-        "status": "success",
-        "meta": {
-            "TransactionResult": "tesSUCCESS",
-            "TransactionIndex": 2,
-            "AffectedNodes": [...]
-        },
-        "ledger_index": 10268599[d],
-        "inLedger": 10268599,
-        "hash": "395C313F6F11F70FEBAF3785529A6D6DE3F44C7AF679515A7EAE22B30146DE57",
-        "date": 470798270,
-        "TxnSignature": "304402202646962A21EC0516FCE62DC9280F79E7265778C571E9410D795E67BB72A2D8E402202FF4AF7B2E2160F5BCA93011CB548014626CAC7FCBEBDB81FE8193CEFF69C753",
-        "TransactionType": "Payment",
-        "SigningPubKey": "0267268EE0DDDEE6A862C9FF9DDAF898CF17060A673AF771B565AA2F4AE24E3FC5",
-        "Sequence": 4,
-        "LastLedgerSequence": 10268600,
-        "Flags": 2147483648,
-        "Fee": "10000",
-        "Destination": "rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM",
-        "Amount": {
-            "value": "10",
-            "issuer": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W",
-            "currency": "FOO"
-        },
-        "Account": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W"
-    }
-}
-
-

This example response shows "validated": true, indicating the transaction has been included in a validated ledger, so the result of the transaction is immutable. Further, the metadata includes "TransactionResult": "tesSUCCESS", indicating the transaction was applied to the ledger.

-

If the response does not include "validated": true, the result is provisional and subject to change. To retrieve a final result, applications must invoke the tx method again, allowing enough time for the network to validate more ledger instances. It may be necessary to wait for the ledger specified in LastLedgerSequence to be validated, although if the transaction is included in an earlier validated ledger the result become immutable at that time.

-

Verify Missing Transaction

-

Applications must handle cases where a call to the tx method returns a txnNotFound error.

-
{
-    "result": {
-        "status": "error",
-        "request": {
-            "transaction": "395C313F6F11F70FEBAF3785529A6D6DE3F44C7AF679515A7EAE22B30146DE56",
-            "command": "tx",
-            "binary": false
-        },
-        "error_message": "Transaction not found.",
-        "error_code": 24,
-        "error": "txnNotFound"
-    }
-}
-
-

The txnNotFound result code occurs in cases where the transaction is not included in any ledger. However, it could also occur when a rippled instance does not have a complete ledger history, or if the transaction has not yet propagated to the rippled instance. Applications should make further queries to determine how to react.

-

The server_state method (used earlier to determine the last validated ledger) indicates how complete the ledger history is, under result.state.complete_ledgers.

-
{
-    "result": {
-        "status": "success",
-        "state": {
-            "validation_quorum": 3,
-            "validated_ledger": {
-                "seq": 10269447,
-                "reserve_inc": 5000000,
-                "reserve_base": 20000000,
-                "hash": "D05C7ECC66DD6F4FEA3A6394F209EB5D6824A76C16438F562A1749CCCE7EAFC2",
-                "close_time": 470802340,
-                "base_fee": 10
-            },
-            "server_state": "full",
-            "pubkey_node": "n9LJ5eCNjeUXQpNXHCcLv9PQ8LMFYy4W8R1BdVNcpjc1oDwe6XZF",
-            "peers": 84,
-            "load_factor": 256000,
-            "load_base": 256,
-            "last_close": {
-                "proposers": 5,
-                "converge_time": 2002
-            },
-            "io_latency_ms": 1,
-            "complete_ledgers": "10256331-10256382,10256412-10269447",
-            "build_version": "0.26.4-sp3-private"
-        }
-    }
-}
-
-

Our example transaction specified LastLedgerSequence 10268600, based on the last validated ledger at the time, plus four. To determine whether our missing transaction has permanently failed, our rippled server must have ledgers 10268597 through 10268600. If the server has those validated ledgers in its history, and tx returns txnNotFound, then the transaction has failed and cannot be included in any future ledger. In this case, application logic may dictate building and submitting a replacement transaction with the same account sequence and updated LastLedgerSequence.

-

The server may report a last validated ledger sequence number less than the specified LastLedgerSequence. If so, the txnNotFound indicates either (a) the submitted transaction has not been distributed to the network, or (b) the transaction has been distributed to the network but has not yet been processed. To handle the former case, applications may submit again the same signed transaction. Because the transaction has a unique account sequence number, it can be processed at most once.

-

Finally the server may show one or more gaps in the transaction history. The completed_ledgers field shown in the response above indicates that ledgers 10256383 through 10256411 are missing from this rippled instance. Our example transaction can only appear in ledgers 10268597 - 10268600 (based on when it was submitted and LastLedgerSequence), so the gap shown here is not relevant. However, if the gap indicated a ledger in that range was missing, then an application would need to query another rippled server (or wait for this one to retrieve the missing ledgers) to determine that a txnNotFound result is immutable.

-

Additional Resources

- -
-
-
- - - - \ No newline at end of file diff --git a/tutorial-rippleapi-beginners-guide.html b/tutorial-rippleapi-beginners-guide.html deleted file mode 100644 index a76680249e..0000000000 --- a/tutorial-rippleapi-beginners-guide.html +++ /dev/null @@ -1,526 +0,0 @@ - - - - - - - - RippleAPI Beginners Guide - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

RippleAPI Beginners Guide

-

This tutorial guides you through the basics of building an XRP Ledger-connected application using Node.js and RippleAPI, a JavaScript API for accessing the XRP Ledger.

-

The scripts and configuration files used in this guide are available in the Ripple Dev Portal GitHub Repository.

-

Environment Setup

-

The first step to using RippleAPI is setting up your development environment.

-

Install Node.js and npm

-

RippleAPI is built as an application for the Node.js runtime environment, so the first step is getting Node.js installed. RippleAPI requires Node.js version 0.12, version 4.x, or higher.

-

This step depends on your operating system. We recommend the official instructions for installing Node.js using a package manager for your operating system. If the packages for Node.js and npm (Node Package Manager) are separate, install both. (This applies to Arch Linux, CentOS, Fedora, and RHEL.)

-

After you have installed Node.js, you can check the version of the node binary from a command line:

-
node --version
-
-

On some platforms, the binary is named nodejs instead:

-
nodejs --version
-
-

Use NPM to install RippleAPI and dependencies

-

RippleAPI uses the newest version of JavaScript, ECMAScript 6 (also known as ES2015). To use the new features of ECMAScript 6, RippleAPI depends on Babel-Node and its ES2015 presets. You can use npm to install RippleAPI and these dependencies together.

-

1. Create a new directory for your project

-

Create a folder called (for example) my_ripple_experiment:

-
mkdir my_ripple_experiment && cd my_ripple_experiment
-
-

Optionally, start a Git repository in that directory so you can track changes to your code.

-
git init
-
-

Alternatively, you can create a repo on GitHub to version and share your work. After setting it up, clone the repo to your local machine and cd into that directory.

-

2. Create a new package.json file for your project.

-

Use the following template, which includes:

-
    -
  • RippleAPI itself (ripple-lib)
    • -
  • Babel (babel-cli)
    • -
  • The ECMAScript 6 presets for Babel (babel-preset-es2015)
    • -
  • (Optional) ESLint (eslint) for checking code quality.
    • -
-
{
-  "name": "my_ripple_experiment",
-  "version": "0.0.1",
-  "license": "MIT",
-  "private": true,
-  "//": "Change the license to something appropriate. You may want to use 'UNLICENSED' if you are just starting out.",
-  "dependencies": {
-    "ripple-lib": "*",
-    "babel-cli": "^6.0.0",
-    "babel-preset-es2015": "*"
-  },
-  "babel": {
-    "presets": ["es2015"]
-  },
-  "devDependencies": {
-    "eslint": "*"
-  }
-}
-
-

3. Use NPM to install the dependencies.

-
npm install
-
-

This automatically installs all the dependencies defined in the package.json into the local folder node_modules/. (We recommend not using npm -g to install the dependencies globally.)

-

The install process may take a while and end with a few warnings. You may safely ignore the following warnings:

-
npm WARN optional Skipping failed optional dependency /chokidar/fsevents:
-npm WARN notsup Not compatible with your operating system or architecture: fsevents@1.0.6
-npm WARN ajv@1.4.10 requires a peer of ajv-i18n@0.1.x but none was installed.
-
-

First RippleAPI Script

-

This script, get-account-info.js, fetches information about a hard-coded account. Use it to test that RippleAPI works:

-
'use strict';
-const RippleAPI = require('ripple-lib').RippleAPI;
-
-const api = new RippleAPI({
-  server: 'wss://s1.ripple.com' // Public rippled server
-});
-api.connect().then(() => {
-  /* begin custom code ------------------------------------ */
-  const myAddress = 'rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn';
-
-  console.log('getting account info for', myAddress);
-  return api.getAccountInfo(myAddress);
-
-}).then(info => {
-  console.log(info);
-  console.log('getAccountInfo done');
-
-  /* end custom code -------------------------------------- */
-}).then(() => {
-  return api.disconnect();
-}).then(() => {
-  console.log('done and disconnected.');
-}).catch(console.error);
-
-

Running the script

-

RippleAPI and the script both use the ECMAScript 6 version of JavaScript. That's why we installed Babel earlier. The easiest way to run ECMAScript 6 is to use the babel-node binary, which NPM installs in the node_modules/.bin/ directory of your project. Thus, running the script looks like this:

-
./node_modules/.bin/babel-node get-account-info.js
-
-

Output:

-
getting account info for rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn
-{ sequence: 359,
-  xrpBalance: '75.181663',
-  ownerCount: 4,
-  previousInitiatedTransactionID: 'E5C6DD25B2DCF534056D98A2EFE3B7CFAE4EBC624854DE3FA436F733A56D8BD9',
-  previousAffectingTransactionID: 'E5C6DD25B2DCF534056D98A2EFE3B7CFAE4EBC624854DE3FA436F733A56D8BD9',
-  previousAffectingTransactionLedgerVersion: 18489336 }
-getAccountInfo done
-done and disconnected.
-
-

Understanding the script

-

In addition to RippleAPI-specific code, this script uses syntax and conventions that are recent developments in JavaScript. Let's divide the sample code into smaller chunks to explain each one.

-

Script opening

-
'use strict';
-const RippleAPI = require('ripple-lib').RippleAPI;
-
-

The opening line enables strict mode. This is purely optional, but it helps you avoid some common pitfalls of JavaScript. See also: Restrictions on Code in Strict Mode.

-

The second line imports RippleAPI into the current scope using Node.js's require function. RippleAPI is one of the modules ripple-lib exports.

-

Instantiating the API

-
const api = new RippleAPI({
-  server: 'wss://s1.ripple.com' // Public rippled server
-});
-
-

This section creates a new instance of the RippleAPI class, assigning it to the variable api. (The const keyword means you can't reassign the value api to some other value. The internal state of the object can still change, though.)

-

The one argument to the constructor is an options object, which has a variety of options. The server parameter tells it where it should connect to a rippled server.

-
    -
  • The example server setting uses a secure WebSocket connection to connect to one of the public servers that Ripple (the company) operates.
    • -
  • If you don't include the server option, RippleAPI runs in offline mode instead, which only provides methods that don't need network connectivity.
    • -
  • You can specify a Ripple Test Net server instead to connect to the parallel-world Test Network instead of the production XRP Ledger.
    • -
  • If you run your own rippled, you can instruct it to connect to your local server. For example, you might say server: 'ws://localhost:5005' instead.
    • -
-

Connecting and Promises

-
api.connect().then(() => {
-
-

The connect() method is one of many RippleAPI methods that returns a Promise, which is a special kind of JavaScript object. A Promise is designed to do an asynchronous operation that returns a value later, such as querying the XRP Ledger.

-

When you get a Promise back from some expression (like api.connect()), you call the Promise's then method and pass in a callback function. Passing a function as an argument is conventional in JavaScript, taking advantage of how JavaScript functions are first-class objects.

-

When a Promise finishes with its asynchronous operations, the Promise runs the callback function you passed it. The return value from the then method is another Promise object, so you can "chain" that into another then method, or the Promise's catch method, which also takes a callback. The callback you pass to catch gets called if something goes wrong.

-

Finally, we have more new ECMAScript 6 syntax - an arrow function. Arrow functions are a shorter way of defining anonymous functions. This is convenient for defining lots of one-off functions as callbacks. The syntax ()=> {...} is mostly equivalent to function() {...}. If you want an anonymous function with one parameter, you can use a syntax like info => {...} instead, which is almost the same as function(info) {...} syntax.

-

Custom code

-
  /* begin custom code ------------------------------------ */
-  const myAddress = 'rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn';
-
-  console.log('getting account info for', myAddress);
-  return api.getAccountInfo(myAddress);
-
-}).then(info => {
-  console.log(info);
-  console.log('getAccountInfo done');
-
-  /* end custom code -------------------------------------- */
-
-

This is the part that you change to do whatever you want the script to do.

-

The example code looks up an XRP Ledger account by its address. Try running the code with different addresses to see different results.

-

The console.log() function is built into both Node.js and web browsers, and writes out to the console. This example includes lots of console output to make it easier to understand what the code is doing.

-

Keep in mind that the example code starts in the middle of a callback function (called when RippleAPI finishes connecting). That function calls RippleAPI's getAccountInfo method, and returns the results.

-

The getAccountInfo API method returns another Promise, so the line }).then( info => { defines another anonymous callback function to run when this Promise's asynchronous work is done. Unlike the previous case, this callback function takes one argument, called info, which holds the asynchronous return value from the getAccountInfo API method. The rest of this callback function outputs that return value to the console.

-

Cleanup

-
}).then(() => {
-  return api.disconnect();
-}).then(() => {
-  console.log('done and disconnected.');
-}).catch(console.error);
-
-

The rest of the sample code is mostly more boilerplate code. The first line ends the previous callback function, then chains to another callback to run when it ends. That method disconnects cleanly from the XRP Ledger, and has yet another callback which writes to the console when it finishes. If your script waits on RippleAPI events, do not disconnect until you are done waiting for events.

-

The catch method ends this Promise chain. The callback provided here runs if any of the Promises or their callback functions encounters an error. In this case, we pass the standard console.error function, which writes to the console, instead of defining a custom callback. You could define a smarter callback function here to intelligently catch certain error types.

-

Waiting for Validation

-

One of the biggest challenges in using the XRP Ledger (or any decentralized system) is knowing the final, immutable transaction results. Even if you follow the best practices you still have to wait for the consensus process to finally accept or reject your transaction. The following example code demonstrates how to wait for the final outcome of a transaction:

-
'use strict';
-/* import RippleAPI and support libraries */
-const RippleAPI = require('ripple-lib').RippleAPI;
-const assert = require('assert');
-
-/* Credentials of the account placing the order */
-const myAddr = 'rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn';
-const mySecret = 's████████████████████████████';
-
-/* Define the order to place here */
-const myOrder = {
-  'direction': 'buy',
-  'quantity': {
-    'currency': 'FOO',
-    'counterparty': 'rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v',
-    'value': '100'
-  },
-  'totalPrice': {
-    'currency': 'XRP',
-    'value': '1000'
-  }
-};
-
-/* Milliseconds to wait between checks for a new ledger. */
-const INTERVAL = 1000;
-/* Instantiate RippleAPI. Uses s2 (full history server) */
-const api = new RippleAPI({server: 'wss://s2.ripple.com'});
-/* Number of ledgers to check for valid transaction before failing */
-const ledgerOffset = 5;
-const myInstructions = {maxLedgerVersionOffset: ledgerOffset};
-
-
-/* Verify a transaction is in a validated XRP Ledger version */
-function verifyTransaction(hash, options) {
-  console.log('Verifing Transaction');
-  return api.getTransaction(hash, options).then(data => {
-    console.log('Final Result: ', data.outcome.result);
-    console.log('Validated in Ledger: ', data.outcome.ledgerVersion);
-    console.log('Sequence: ', data.sequence);
-    return data.outcome.result === 'tesSUCCESS';
-  }).catch(error => {
-    /* If transaction not in latest validated ledger,
-       try again until max ledger hit */
-    if (error instanceof api.errors.PendingLedgerVersionError) {
-      return new Promise((resolve, reject) => {
-        setTimeout(() => verifyTransaction(hash, options)
-        .then(resolve, reject), INTERVAL);
-      });
-    }
-    return error;
-  });
-}
-
-
-/* Function to prepare, sign, and submit a transaction to the XRP Ledger. */
-function submitTransaction(lastClosedLedgerVersion, prepared, secret) {
-  const signedData = api.sign(prepared.txJSON, secret);
-  return api.submit(signedData.signedTransaction).then(data => {
-    console.log('Tentative Result: ', data.resultCode);
-    console.log('Tentative Message: ', data.resultMessage);
-    /* If transaction was not successfully submitted throw error */
-    assert.strictEqual(data.resultCode, 'tesSUCCESS');
-    /* 'tesSUCCESS' means the transaction is being considered for the next ledger, and requires validation. */
-
-    /* If successfully submitted, begin validation workflow */
-    const options = {
-      minLedgerVersion: lastClosedLedgerVersion,
-      maxLedgerVersion: prepared.instructions.maxLedgerVersion
-    };
-    return new Promise((resolve, reject) => {
-      setTimeout(() => verifyTransaction(signedData.id, options)
-    .then(resolve, reject), INTERVAL);
-    });
-  });
-}
-
-
-api.connect().then(() => {
-  console.log('Connected');
-  return api.prepareOrder(myAddr, myOrder, myInstructions);
-}).then(prepared => {
-  console.log('Order Prepared');
-  return api.getLedger().then(ledger => {
-    console.log('Current Ledger', ledger.ledgerVersion);
-    return submitTransaction(ledger.ledgerVersion, prepared, mySecret);
-  });
-}).then(() => {
-  api.disconnect().then(() => {
-    console.log('api disconnected');
-    process.exit();
-  });
-}).catch(console.error);
-
-

This code creates and submits an order transaction, although the same principles apply to other types of transactions as well. After submitting the transaction, the code uses a new Promise, which queries the ledger again after using setTimeout to wait a fixed amount of time, to see if the transaction has been verified. If it hasn't been verified, the process repeats until either the transaction is found in a validated ledger or the returned ledger is higher than the LastLedgerSequence parameter.

-

In rare cases (particularly with a large delay or a loss of power), the rippled server may be missing a ledger version between when you submitted the transaction and when you determined that the network has passed the maxLedgerVersion. In this case, you cannot be definitively sure whether the transaction has failed, or has been included in one of the missing ledger versions. RippleAPI returns MissingLedgerHistoryError in this case.

-

If you are the administrator of the rippled server, you can manually request the missing ledger(s). Otherwise, you can try checking the ledger history using a different server. (Ripple runs a public full-history server at s2.ripple.com for this purpose.)

-

See Reliable Transaction Submission for a more thorough explanation.

-

RippleAPI in Web Browsers

-

RippleAPI can also be used in a web browser if you compile a browser-compatible version and include lodash as a dependency before the RippleAPI script.

-

Build Instructions

-

To use RippleAPI in a browser, you need to build a browser-compatible version. The following process compiles RippleAPI into a single JavaScript file you can include in a webpage.

-

1. Download a copy of the RippleAPI git repository.

-

If you have Git installed, you can clone the repository and check out the release branch, which always has the latest official release:

-
git clone https://github.com/ripple/ripple-lib.git
-cd ripple-lib
-git checkout release
-
-

Alternatively, you can download an archive (.zip or .tar.gz) of a specific release from the RippleAPI releases page and extract it.

-

2. Install dependencies using NPM

-

You need to have NPM (Node.js Package Manager) installed first.

-

Then, from within the ripple-lib directory, you can use NPM to install all the necessary dependencies:

-
npm install
-
-

(We recommend not using npm -g to install dependencies globally.)

-

This can take a while, and may include some warnings. The following warnings are benign and do not indicate a problem:

-
npm WARN optional Skipping failed optional dependency /chokidar/fsevents:
-npm WARN notsup Not compatible with your operating system or architecture: fsevents@1.0.6
-
-

3. Use Gulp to build a single JavaScript output

-

RippleAPI comes with code to use the gulp package to compile all its source code into browser-compatible JavaScript files. Gulp is automatically installed as one of the dependencies, so all you have to do is run it. RippleAPI's configuration makes this easy:

-
npm run build
-
-

Output:

-
> ripple-lib@0.16.5 build /home/username/ripple-lib
-> gulp
-
-[15:22:30] Using gulpfile /home/username/ripple-lib/Gulpfile.js
-[15:22:30] Starting 'build'...
-[15:22:30] Starting 'build-debug'...
-[15:22:42] Finished 'build' after 12 s
-[15:22:42] Starting 'build-min'...
-[15:22:42] Finished 'build-debug' after 12 s
-[15:22:51] Finished 'build-min' after 9.83 s
-[15:22:51] Starting 'default'...
-[15:22:51] Finished 'default' after 4.58 μs
-
-

This may take a while. At the end, the build process creates a new build/ folder, which contains the files you want.

-

The file build/ripple-<VERSION NUMBER>.js is a straight export of RippleAPI (whatever version you built) ready to be used in browsers. The file ending in -min.js is the same thing, but with the content minified for faster loading.

-

Example Browser Usage

-

The following HTML file demonstrates basic usage of the browser version of RippleAPI to connect to a public rippled server and report information about that server. Instead of using Node.js's "require" syntax, the browser version creates a global variable named ripple, which contains the RippleAPI class.

-

To use this example, you must first build RippleAPI and then copy one of the resulting output files to the same folder as this HTML file. (You can use either the minified or full-size version.) Change the first <script> tag in this example to use the correct file name for the version of RippleAPI you built.

-

browser-demo.html:

-
<!DOCTYPE html>
-<html>
-<head>
-  <script src="https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.15.0/lodash.js"></script>
-  <script src="ripple-0.17.7-min.js"></script>
-  <script>
-    console.log(ripple);
-    var api = new ripple.RippleAPI({server:'wss://s1.ripple.com/'});
-    api.connect().then(function() {
-        return api.getServerInfo();
-    }).then(function(server_info) {
-    document.body.innerHTML += "<p>Connected to rippled server!</p>" +
-"      <table>" +
-"        <tr><th>Version</th>" +
-"          <td>" + server_info.buildVersion + "</td></tr>" +
-"        <tr><th>Ledgers available</th>" +
-"          <td>" + server_info.completeLedgers + "</td></tr>" +
-"        <tr><th>hostID</th>" +
-"          <td>" + server_info.hostID + "</td></tr>" +
-"        <tr><th>Most Recent Validated Ledger Seq.</th>" +
-"          <td>" + server_info.validatedLedger.ledgerVersion + "</td></tr>" +
-"        <tr><th>Most Recent Validated Ledger Hash</th>" +
-"          <td>" + server_info.validatedLedger.hash + "</td></tr>" +
-"        <tr><th>Seconds since last ledger validated</th>" +
-"          <td>" + server_info.validatedLedger.age + "</td></tr>" +
-"      </table>";
-    });
-  </script>
-  <style type="text/css">
-    td, th { border: 1px solid black; padding: 5px; }
-    table { border-collapse: collapse; }
-  </style>
-</head>
-<body></body>
-</html>
-
-
-
-
- - - - \ No newline at end of file diff --git a/tutorial-rippled-setup.html b/tutorial-rippled-setup.html deleted file mode 100644 index 8df8463f02..0000000000 --- a/tutorial-rippled-setup.html +++ /dev/null @@ -1,498 +0,0 @@ - - - - - - - - rippled Setup - Ripple Developer Portal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
-
-

Operating rippled Servers

-

The core server of the XRP Ledger peer-to-peer network is rippled. Anyone can run their own rippled server that follows the network and keeps a complete copy of the XRP Ledger. You can even have your server take part in the consensus process.

-

This page contains instructions for:

- -

Types of rippled Servers

-

The rippled server software can run in several modes depending on its configuration, including:

-
    -
  • Stock server - follows the network with a local copy of the ledger.
    • -
  • Validating server, or validator for short - participates in consensus.
    • -
  • rippled server in stand-alone mode - for testing. Does not communicate to other rippled servers.
    • -
-

You can also run the rippled executable as a client application for accessing rippled APIs locally. (Two instances of the same binary can run side-by-side in this case; one as a server, and the other running briefly as a client and then terminating.)

-

Reasons to Run a Stock Server

-

There are lots of reasons you might want to run your own rippled server, but most of them can be summarized as: you can trust your own server, you have control over its workload, and you're not at the mercy of others to decide when and how you can access it. Of course, you must practice good network security to protect your server from malicious hackers.

-

You need to trust the rippled you use. If you connect to a malicious server, there are many ways that it can take advantage of you or cause you to lose money. For example:

-
    -
  • A malicious server could report that you were paid when no such payment was made.
    • -
  • It could selectively show or hide payment paths and currency exchange offers to guarantee its own profit while not providing you the best deal.
    • -
  • If you sent it your address's secret key, it could make arbitrary transactions on your behalf, and even transfer or destroy all the money your address holds.
    • -
-

Additionally, running your own server gives you admin control over it, which allows you to run important admin-only and load-intensive commands. If you use a shared server, you have to worry about other users of the same server competing with you for the server's computing power. Many of the commands in the WebSocket API can put a lot of strain on the server, so rippled has the option to scale back its responses when it needs to. If you share a server with others, you may not always get the best results possible.

-

Finally, if you run a validating server, you can use a stock server as a proxy to the public network while keeping your validating server on a private subnet only accessible to the outside world through the stock server. This makes it more difficult to compromise the integrity of your validating server.

-

Reasons to Run a Validator

-

The robustness of the XRP Ledger depends on an interconnected web of validators who each trust a few other validators not to collude. The more operators with different interests there are who run validators, the more certain each member of the network can be that it continues to run impartially. If you or your organization relies on the XRP Ledger, it is in your interest to contribute to the consensus process.

-

Not all rippled servers need to be validators: trusting more servers from the same operator does not offer better protection against collusion. An organization might run validators in multiple regions for redundancy in case of natural disasters and other emergencies.

-

If your organization runs a validating server, you may also run one or more stock servers, to balance the computing load of API access, or as a proxy between your validation server and the outside network.

-

Properties of a Good Validator

-

There are several properties that define a good validator. The more of these properties your server embodies, the more reason others have to include your server in their list of trusted validators:

-
    -
  • Availability. An ideal validator should always be running, submitting validation votes for every proposed ledger.
      -
    • Strive for 100% uptime.
      • -
    -
    • -
  • Agreement. A validator's votes should match the outcome of the consensus process as often as possible. To do otherwise could indicate that the validator's software is outdated, buggy, or intentionally biased.
      -
    • Always run the latest rippled release without modifications.
      • -
    -
    • -
  • Timeliness. A validator's votes should arrive quickly, and not after a consensus round has already finished.
      -
    • A fast internet connection helps with this.
      • -
    -
    • -
  • Identified. It should be clear who runs the validator. Ideally, a list of trusted validators should include validators operated by different owners in multiple legal jurisdictions and geographic areas, to reduce the chance that any localized events could interfere with the validator's impartial operation. -
    • -
-

At present, Ripple (the company) cannot recommend any validators aside from the 5 core validators run by Ripple: these validators are included in the default rippled configuration. However, we are collecting data on other validators and building tools to report on their performance. For metrics on validators, see validators.ripple.com.

-

Installing rippled

-

For development, you can compile rippled from source.

-

Production rippled instances can use Ripple's binary executable, available from the Ripple yum repository.

-

System Requirements

-

A rippled server should run comfortably on commodity hardware, to make it inexpensive to participate in the network. At present, we recommend the following:

-
    -
  • Operating System:
      -
    • Production: CentOS or RedHat Enterprise Linux (latest release) or Ubuntu (15.04+) supported
      • -
    • Development: Mac OS X, Windows (64-bit), or most Linux distributions
      • -
    -
    • -
  • CPU: 64-bit x86_64, 2+ cores
    • -
  • Disk: Minimum 50GB SSD recommended (500+ IOPS, more is better) for the database partition
    • -
  • RAM: 4+GB
    • -
-

Amazon EC2's m3.large VM size may be appropriate depending on your workload. (Validating servers need more resources.)

-

Naturally, a fast network connection is preferable.

-

Installation on CentOS/Red Hat with yum

-

This section assumes that you are using CentOS 7 or Red Hat Enterprise Linux 7.

-
    -
  1. -

    Install the Ripple RPM repository:

    -
    $ sudo rpm -Uvh https://mirrors.ripple.com/ripple-repo-el7.rpm
-
    -
    2. -
  2. -

    Install the rippled software package:

    -
    $ sudo yum install --enablerepo=ripple-stable rippled
-
    -
    3. -
  3. -

    Configure the rippled service to start on system boot:

    -
    $ sudo systemctl enable rippled.service
-
    -
    4. -
  4. -

    Start the rippled service

    -
    $ sudo systemctl start rippled.service
-
    -
    5. -
-

Installation on Ubuntu with alien

-

This section assumes that you are using Ubuntu 15.04 or later.

-
    -
  1. -

    Install yum-utils and alien:

    -
    $ sudo apt-get update
-$ sudo apt-get install yum-utils alien
-
    -
    2. -
  2. -

    Install the Ripple RPM repository:

    -
    $ sudo rpm -Uvh https://mirrors.ripple.com/ripple-repo-el7.rpm
-
    -
    3. -
  3. -

    Download the rippled software package:

    -
    $ yumdownloader --enablerepo=ripple-stable --releasever=el7 rippled
-
    -
    4. -
  4. -

    Verify the signature on the rippled software package:

    -
    $ sudo rpm --import https://mirrors.ripple.com/rpm/RPM-GPG-KEY-ripple-release && rpm -K rippled*.rpm
-
    -
    5. -
  5. -

    Install the rippled software package:

    -
    $ sudo alien -i --scripts rippled*.rpm && rm rippled*.rpm
-
    -
    6. -
  6. -

    Configure the rippled service to start on system boot:

    -
    $ sudo systemctl enable rippled.service
-
    -
    7. -
  7. -

    Start the rippled service

    -
    $ sudo systemctl start rippled.service
-
    -
    8. -
-

Postinstall

-

It can take several minutes for rippled to sync with the rest of the network, during which time it outputs warnings about missing ledgers. After that, you have a fully functional stock rippled server that you can use for local signing and API access to the XRP Ledger.

-

rippled commands can be run with:

-
    $ /opt/ripple/bin/rippled <command>
-
-

Updating rippled

-

You can subscribe to the rippled Google Group to receive notifications of new rippled releases.

-

Automatic Update on CentOS/Red Hat

-

Automatic rippled updates can be enabled with a one-time Cron configuration:

-
    -
  1. -

    Check that /opt/ripple/bin/update-rippled.sh exists. If it does not, update manually.

    -
    2. -
  2. -

    Install crond:

    -
    $ sudo yum install cronie
-
    -
    3. -
  3. -

    Open the crontab file for editing

    -
    $ sudo crontab -e
-
    -
    4. -
  4. -

    Add the following to the crontab file. Be sure to add a blank line at the end of the file.

    -
    RANDOM_DELAY=59
-0 * * * * /opt/ripple/bin/update-rippled.sh
-
    -
    5. -
-

The script updates the installed rippled package within an hour of each new release.

-

Manual Update on CentOS/Red Hat

-

Run the following commands to update to the latest release of rippled:

-
    $ sudo rpm -Uvh --replacepkgs https://mirrors.ripple.com/ripple-repo-el7.rpm
-    $ sudo yum update --enablerepo=ripple-stable rippled
-    $ sudo systemctl daemon-reload
-    $ sudo service rippled restart
-
-

Manual Update on Ubuntu

-

Run the following commands to update to the latest release of rippled:

-
    $ sudo rpm -Uvh --replacepkgs https://mirrors.ripple.com/ripple-repo-el7.rpm
-    $ yumdownloader --enablerepo=ripple-stable --releasever=el7 rippled
-    $ rpm -K rippled*.rpm
-    $ sudo alien -i --scripts rippled*.rpm
-    $ sudo systemctl daemon-reload
-    $ sudo service rippled restart
-
-

Running a Validator

-

Running a rippled validator that participates in the Consensus process is simple:

-
    -
  1. Enable validation on your rippled server.
      -
    • At first, your server is an untrusted validator. Others can see the validations your server issues, but they disregard them in the consensus process.
      • -
    -
    2. -
  2. Share the public key with the public, especially other rippled operators.
    3. -
  3. When other rippled operators add your public key to their list of trusted servers, you have become a trusted validator. -
    4. -
-

Validator Setup

-

The validator-keys tool (included in the rippled RPM) is the recommended means to securely generate and manage your validator keys.

-
    -
  1. -

    Install a rippled server.

    -
    2. -
  2. -

    Generate a validator key pair:

    -
    $ /opt/ripple/bin/validator-keys create_keys
-
    -

    Warning: Store the generated validator-keys.json key file in a secure but recoverable location, such as an encrypted USB flash drive. Do not modify its contents.

    -
    3. -
  3. -

    Generate a validator token and edit your rippled.cfg file to add the [validator_token] value.

    -
    $ /opt/ripple/bin/validator-keys create_token --keyfile /path/to/your/validator-keys.json
-
    -

    If you had previously configured your validator without using the validator-keys tool, you will need to also delete the [validation_seed] from your rippled.cfg file. This changes your validator public key.

    -
    4. -
  4. -

    Start rippled:

    -
    $ sudo service rippled restart
-
    -
    5. -
-

See the validator-keys-tool GitHub repository for more information about managing validator keys.

-

Public-Facing Server

-

To protect a production validator from DDoS attacks, you can use a stock rippled server as a proxy between the validator and the outside network.

-
    -
  1. -

    Set up the rippled validator.

    -
    2. -
  2. -

    Set up one or more stock rippled servers.

    -
    3. -
  3. -

    Configure the validator and stock rippled servers to be clustered with each other.

    -
    4. -
  4. -

    Make the following configuration changes to your validator:

    -
      -
    • Copy the [ips_fixed] list and paste it under [ips]. These fields should contain only the IP addresses and ports of the public-facing rippled(s). The validator connects to only these peers.
      • -
    • Change [peer_private] to 1 to prevent its IP address from being forwarded.
      • -
    -
    5. -
  5. -

    Configure the validator host machine's firewall to only accept inbound connections from its public-facing rippled(s).

    -
    6. -
-

Remember to restart rippled for config changes to take effect.

-

Take care not to publish the IP address of your validator.

-

Domain Verification

-

Network participants are unlikely to trust validators without knowing who is operating them. To address this concern, validator operators can associate their validator with a web domain that they control.

-
    -
  1. -

    Find your validator public key by running the following on the validator server:

    -
    $ /opt/ripple/bin/rippled server_info -q | grep pubkey_validator
-
    -
    2. -
  2. -

    Sign the validator public key (from step 1) using the SSL private key used for your domain. The SSL private key file does not need to be stored on the validator server.

    -
    $ openssl dgst -sha256 -hex -sign /path/to/your/ssl.key <(echo <your-validator-public-key>)
-
    -
    3. -
  3. -

    Using validator-keys tool (included in the rippled RPM), sign the domain name:

    -
    $ /opt/ripple/bin/validator-keys --keyfile /path/to/your/validator-keys.json sign <your-domain-name>
-
    -
    4. -
  4. -

    In order to have the verified validator domain published, email validators@ripple.com with both signatures as well as the validator public key and domain name.

    -
    5. -
-

Additional Configuration

-

rippled should connect to the XRP Ledger with the default configuration. However, you can change your settings by editing the rippled.cfg file (located at /opt/ripple/etc/rippled.cfg when installing rippled with yum).

-

See the rippled GitHub repository for a description of all configuration options.

-

Changes to the [debug_logfile] or [database_path] sections may require you to give the rippled user and group ownership to your new configured path:

-
    $ chown -R rippled:rippled <configured path>
-
-

Restart rippled for any configuration changes to take effect:

-
    $ sudo service rippled restart
-
-

Parallel Networks

-

Most of the time, we describe the XRP Ledger as one collective, singular entity -- and that's mostly true. There is one production XRP Ledger peer-to-peer network, and all business that takes place on the XRP Ledger occurs within the production network.

-

However, sometimes you may want to do tests and experiments without interacting with the core network. That's why Ripple started the Ripple Test Net, an "alternate universe" network, which can act as a testing ground for applications and the rippled server itself, without impacting the business operations of everyday XRP Ledger users. The Ripple Test Net (also known as the AltNet) has a separate supply of TestNet-only XRP, which Ripple gives away for free to parties interested in developing applications on the Test Net.

-

Caution: Ripple makes no guarantees about the stability of the test network. It has been and continues to be used to test various properties of server configuration, network topology, and network performance.

-

Over time, there may also be smaller, temporary test networks for specific purposes.

-

Parallel Networks and Consensus

-

There is no rippled setting that defines which network it uses. Instead, it uses the consensus of validators it trusts to know which ledger to accept as the truth. When different consensus groups of rippled instances only trust other members of the same group, each group continues as a parallel network. Even if malicious or misbehaving computers connect to both networks, the consensus process overrides the confusion as long as the members of each network are not configured to trust members of another network in excess of their quorum settings.

-

Clustering

-

If you are running multiple rippled servers in a single datacenter, you can configure those servers into a cluster to maximize efficiency. Running your rippled servers in a cluster provides the following benefits:

-
    -
  • Clustered rippled servers share the work of cryptography. If one server has verified the authenticity of a message, the other servers in the cluster trust it and do not re-verify.
    • -
  • Clustered servers share information about peers and API clients that are misbehaving or abusing the network. This makes it harder to attack all servers of the cluster at once.
    • -
  • Clustered servers always propagate transactions throughout the cluster, even if the transaction does not meet the current load-based transaction fee on some of them.
    • -
-

To enable clustering, change the following sections of your config file for each server:

-
    -
  • -

    List the IP address and port of each other server under the [ips_fixed] section. The port should be the one from the other servers' protocol = peer setting in their rippled.cfg. Example:

    -
    [ips_fixed]
-192.168.0.1 51235
-192.168.0.2 51235
-
    -
    • -
  • -

    Generate a unique seed (using the validation_create command) for each of your servers, and configure it under the [node_seed] section. The rippled server uses this key to sign its messages to other servers in the peer-to-peer network.

    -
    • -
  • -

    Add the public keys (for peer communication) of each of your other servers under the [cluster_nodes] section.

    -
    • -
-
-
-
- - - - \ No newline at end of file