Last updated

ledger

[Source]

The ledger command retrieves information about the public ledger. New in: Clio v1.0.0

Note that the Clio server returns validated ledger data by default.

Request Format

An example of the request format:

  1. WebSocket
  2. JSON-RPC
{
    "id": 14,
    "command": "ledger",
    "ledger_index": "validated",
    "transactions": false,
    "expand": false,
    "owner_funds": false,
    "diff": false
}

The request can contain the following parameters:

FieldTypeDescription
ledger_hashHash(Optional) A 20-byte hex string for the ledger version to use. (See Specifying Ledgers).
ledger_indexLedger Index(Optional) The ledger index of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying Ledgers)
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.
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.
diffBoolean(Optional) If true, returns all objects that were added, modified, or deleted as part of applying transactions in the specified ledger.

The ledger field is deprecated and may be removed without further notice.

Note

The ledger command in Clio does not support the following fields that are supported by ledger command in rippled:

  • accounts
  • full
  • queue

Clio will always forward the request to rippled when any of the above fields is set to true.

Response Format

An example of a successful response:

  1. WebSocket
  2. JSON-RPC
{
  "result": {
    "ledger_hash": "3787026448652A36491493C1202A443B2A6CC6022599BB0B25DDB0802DD7F1E7",
    "ledger_index": 82681623,
    "validated": true,
    "ledger": {
      "account_hash": "39D34D858A0FD652143ED84B67A09193772DE0CCEBD2D63619E679293B7A3388",
      "close_flags": 0,
      "close_time": 748569571,
      "close_time_human": "2023-Sep-20 23:59:31.000000000 UTC",
      "close_time_resolution": 10,
      "closed": true,
      "ledger_hash": "3787026448652A36491493C1202A443B2A6CC6022599BB0B25DDB0802DD7F1E7",
      "ledger_index": "82681623",
      "parent_close_time": 748569570,
      "parent_hash": "674FF6C68956E06CB9628833677C3DD71824C87C0AEFB487984CF98C3964DAEE",
      "total_coins": "99988406188847858",
      "transaction_hash": "11EE9C448D6B07B88A80B4FC7935B485E513816B3B47D0976CE9F51E7CF10A85"
    }
  },
  "status": "success",
  "type": "response",
  "warnings": [
    {
      "id": 2001,
      "message": "This is a clio server. clio only serves validated data. If you want to talk to rippled, include 'ledger_index':'current' in your request"
    }
  ]
}

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.accountStateArray(Omitted unless requested) All the account-state information in this ledger.
ledger.close_flagsIntegerA bit-map of flags relating to the closing of 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. Always uses the UTC time zone.
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_close_timeIntegerThe time at which the previous ledger was closed.
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.
validatedBoolean(May be omitted) If true, this is a validated ledger version. If omitted or set to false, this ledger's data is not final.
diffObject(Omitted unless requested with the diff parameter) Object containing an array of hashes that were added, modified, or deleted as part of applying transactions for the ledger.

If the request specified "owner_funds": true and expanded transactions, the response has a field owner_funds in the metaData object of each OfferCreate 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.

If the request specified "diff": true, the response has an object diff. The fields of this object are as follows:

FieldValueDescription
object_idStringThe object identifier.
HashesObject or Hex StringDepending on whether the request set binary to true or false, this field returns the contents of the object that was created, the new value of an object that was modified, or an empty string if the object was deleted.

Response When diff is true

{% code-snippet file="/_api-examples/ledger-clio/jsonrpc-diff-response.json" language="json" /%}

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.