# ledger

[[Source]](https://github.com/XRPLF/rippled/blob/master/src/xrpld/rpc/handlers/LedgerHandler.cpp)

Retrieve information about the public [ledger](/docs/concepts/ledgers).

## Request Format

An example of the request format:

WebSocket

```json
{
    "id": "example_ledger_req",
    "command": "ledger",
    "ledger_index": "validated",
    "transactions": false,
    "expand": false,
    "owner_funds": false
}
```

JSON-RPC

```json
{
    "method": "ledger",
    "params": [
        {
            "ledger_index": "validated",
            "transactions": false,
            "expand": false,
            "owner_funds": false
        }
    ]
}
```

Commandline

```sh
#Syntax: ledger ledger_index|ledger_hash [full|tx]
# "full" is equivalent to "full": true
# "tx" is equivalent to "transactions": true
rippled ledger validated
```

The request can contain the following parameters:

| `Field` | Type | Required? | Description |
|  --- | --- | --- | --- |
| `ledger_hash` | [Hash](/docs/references/protocol/data-types/basic-data-types#hashes) | No | A 32-byte hex string for the ledger version to use. (See [Specifying Ledgers](/docs/references/protocol/data-types/basic-data-types#specifying-ledgers)). |
| `ledger_index` | [Ledger Index](/docs/references/protocol/data-types/basic-data-types#ledger-index) | No | The [ledger index](/docs/references/protocol/data-types/basic-data-types#ledger-index) of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers](/docs/references/protocol/data-types/basic-data-types#specifying-ledgers)) |
| `transactions` | Boolean | No | If `true`, return information on transactions in the specified ledger version. The default is `false`. Ignored if you did not specify a ledger version. |
| `expand` | Boolean | No | Provide full JSON-formatted information for transaction/account information instead of only hashes. The default is `false`. Ignored unless you request transactions, accounts, or both. |
| `owner_funds` | Boolean | No | If `true`, include `owner_funds` field in the metadata of OfferCreate transactions in the response. The default is `false`. Ignored unless transactions are included and `expand` is true. |
| `binary` | Boolean | No | If `true`, and `transactions` and `expand` are both also `true`, return transaction information in binary format (hexadecimal string) instead of JSON format. |
| `queue` | Boolean | No | If `true`, and the command is requesting the `current` ledger, includes an array of [queued transactions](/docs/concepts/transactions/transaction-cost#queued-transactions) in the results. |


The `ledger` field is deprecated and may be removed without further notice. The `full`, `accounts`, and `type` fields (admin-only) are also deprecated; the Clio server does not implement these parameters.

## Response Format

An example of a successful response:

WebSocket
{
    "id": "example_ledger_req",
    "result": {
      "ledger": {
        "account_hash": "B8B2C0C3F9E75E3AEE31D467B2544AB56244E618890BA58679707D6BFC0AF41D",
        "close_flags": 0,
        "close_time": 752188602,
        "close_time_human": "2023-Nov-01 21:16:42.000000000 UTC",
        "close_time_resolution": 10,
        "closed": true,
        "ledger_hash": "1BEECD5D21592EABDEF98D8E4BC038AD10B5700FF7E98011870DF5D6C2A2F39B",
        "ledger_index": "83626901",
        "parent_close_time": 752188601,
        "parent_hash": "6B32CFC42B32C5FB90019AE17F701D96B499A4C8E148A002E18135A434A19D98",
        "total_coins": "99988256314388830",
        "transaction_hash": "21586C664DC47E12AF34F22EBF1DB55D23F8C98972542BAC0C39B1009CAC84D4"
      },
      "ledger_hash": "1BEECD5D21592EABDEF98D8E4BC038AD10B5700FF7E98011870DF5D6C2A2F39B",
      "ledger_index": 83626901,
      "validated": true
    },
    "status": "success",
    "type": "response"
}

JSON-RPC
200 OK

{
    "result": {
      "ledger": {
        "account_hash": "23C1C8F8ACCEFACBDD9A1804CC25E652A324F9EABD7D0BEF103DA56D6E0306E7",
        "close_flags": 0,
        "close_time": 752188801,
        "close_time_human": "2023-Nov-01 21:20:01.000000000 UTC",
        "close_time_resolution": 10,
        "closed": true,
        "ledger_hash": "140B769E9ED61FCD675A6EEC1F005084614314C1D675C2CFDD11A1024BBD2C96",
        "ledger_index": "83626952",
        "parent_close_time": 752188800,
        "parent_hash": "7D169A530960AFA8A0E38D036D8EF960BC2C2E02C4A0CE848A4200B9376AC99C",
        "total_coins": "99988256304478252",
        "transaction_hash": "77226182F58D9B5C798262F0E9D8C575D174E434F0C3C7119FB658BA70004CE9"
      },
      "ledger_hash": "140B769E9ED61FCD675A6EEC1F005084614314C1D675C2CFDD11A1024BBD2C96",
      "ledger_index": 83626952,
      "status": "success",
      "validated": true
    }
}

Commandline
Loading: "/etc/opt/ripple/rippled.cfg"
2023-Nov-01 21:38:14.638871262 UTC HTTPClient:NFO Connecting to 127.0.0.1:5005

{
    "result": {
      "ledger": {
        "account_hash": "23C1C8F8ACCEFACBDD9A1804CC25E652A324F9EABD7D0BEF103DA56D6E0306E7",
        "close_flags": 0,
        "close_time": 752188801,
        "close_time_human": "2023-Nov-01 21:20:01.000000000 UTC",
        "close_time_resolution": 10,
        "closed": true,
        "ledger_hash": "140B769E9ED61FCD675A6EEC1F005084614314C1D675C2CFDD11A1024BBD2C96",
        "ledger_index": "83626952",
        "parent_close_time": 752188800,
        "parent_hash": "7D169A530960AFA8A0E38D036D8EF960BC2C2E02C4A0CE848A4200B9376AC99C",
        "total_coins": "99988256304478252",
        "transaction_hash": "77226182F58D9B5C798262F0E9D8C575D174E434F0C3C7119FB658BA70004CE9"
      },
      "ledger_hash": "140B769E9ED61FCD675A6EEC1F005084614314C1D675C2CFDD11A1024BBD2C96",
      "ledger_index": 83626952,
      "status": "success",
      "validated": true
    }
}

The response follows the [standard format](/docs/references/http-websocket-apis/api-conventions/response-formatting), with a successful result containing information about the ledger, including the following fields:

| `Field` | Type | Description |
|  --- | --- | --- |
| `ledger` | Object | The complete [ledger header data](/docs/references/protocol/ledger-data/ledger-header) of this ledger, with some additional fields added for convenience. |
| `ledger.account_hash` | String | [Hash](/docs/references/protocol/data-types/basic-data-types#hashes) of all account state information in this ledger, as hexadecimal. |
| `ledger.close_flags` | Number | A bit-map of [flags relating to the closing of this ledger](/docs/references/protocol/ledger-data/ledger-header#close-flags). |
| `ledger.close_time` | Number | The time this ledger was closed, in [seconds since the Ripple Epoch](/docs/references/protocol/data-types/basic-data-types#specifying-time). |
| `ledger.close_time_human` | String | The time this ledger was closed, in human-readable format. Always uses the UTC time zone. |
| `ledger.close_time_resolution` | Number | Ledger close times are rounded to within this many seconds. |
| `ledger.closed` | Boolean | Whether or not this ledger has been closed. |
| `ledger.ledger_hash` | String | Unique identifying hash of the entire ledger. |
| `ledger.ledger_index` | [API v1](/docs/references/http-websocket-apis#api-versioning): String  [API v2](/docs/references/http-websocket-apis#api-versioning): Number | The [Ledger Index](/docs/references/protocol/data-types/basic-data-types#ledger-index) of this ledger. |
| `ledger.parent_close_time` | Number | The time at which the previous ledger was closed. |
| `ledger.parent_hash` | String | The unique identifying hash of the ledger that came immediately before this one, as hexadecimal. |
| `ledger.total_coins` | String | Total number of XRP drops in the network, as a quoted integer. (This decreases as transaction costs destroy XRP.) |
| `ledger.transaction_hash` | String | [Hash](/docs/references/protocol/data-types/basic-data-types#hashes) of the transaction information included in this ledger. |
| `ledger.transactions` | Array | *(Omitted unless requested)* Transactions applied in this ledger version. By default, members are the transactions' identifying [Hash](/docs/references/protocol/data-types/basic-data-types#hashes) 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_hash` | String | The unique identifying hash of the entire ledger, as hexadecimal. |
| `ledger_index` | Number | The [Ledger Index](/docs/references/protocol/data-types/basic-data-types#ledger-index) of this ledger. |
| `validated` | Boolean | *(May be omitted)* If `true`, this is a validated ledger version. If omitted or set to `false`, this ledger's data is not final. |
| `queue_data` | Array | *(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. |


The `ledger.accountState` field (omitted unless requested with `"full": true` or `"accounts": true`) is deprecated.

The following deprecated fields have been removed: `accepted`, `hash` (use `ledger_hash` instead), `seqNum` (use `ledger_index` instead), `totalCoins` (use `total_coins` instead). Updated in: rippled 1.12.0

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:

| Field | Value | Description |
|  --- | --- | --- |
| `account` | String | The [Address](/docs/references/protocol/data-types/basic-data-types#addresses) of the sender for this queued transaction. |
| `tx` | String or Object | By default, this is a String containing the [identifying hash](/docs/references/protocol/data-types/basic-data-types#hashes) 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](/docs/references/protocol/transactions) including the transaction's identifying hash in the `hash` field. |
| `retries_remaining` | Number | How many times this transaction can be retried before being dropped. |
| `preflight_result` | String | The tentative result from preliminary transaction checking. This is always `tesSUCCESS`. |
| `last_result` | String | *(May be omitted)* If this transaction was left in the queue after getting a [retriable (`ter`) result](/docs/references/protocol/transactions/transaction-results/ter-codes), this is the exact `ter` result code it got. |
| `auth_change` | Boolean | *(May be omitted)* Whether this transaction changes this address's [ways of authorizing transactions](/docs/concepts/transactions#authorizing-transactions). |
| `fee` | String | *(May be omitted)* The [Transaction Cost](/docs/concepts/transactions/transaction-cost) of this transaction, in [drops of XRP](/docs/references/protocol/data-types/basic-data-types#specifying-currency-amounts). |
| `fee_level` | String | *(May be omitted)* The transaction cost of this transaction, relative to the minimum cost for this type of transaction, in [fee levels](/docs/concepts/transactions/transaction-cost#fee-levels). |
| `max_spend_drops` | String | *(May be omitted)* The maximum amount of [XRP, in drops](/docs/references/protocol/data-types/basic-data-types#specifying-currency-amounts), 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 transaction](/docs/references/protocol/transactions/types/offercreate). The purpose of this field is to make it easier to track the [funding status of offers](/docs/concepts/tokens/decentralized-exchange/offers#lifecycle-of-an-offer) with each new validated ledger. This field is defined slightly differently than the version of this field in [Order Book subscription streams](/docs/references/http-websocket-apis/public-api-methods/subscription-methods/subscribe#order-book-streams):

| `Field` | Value | Description |
|  --- | --- | --- |
| `owner_funds` | String | Numeric 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](/docs/concepts/tokens/fungible-tokens/freezes). |


## Possible Errors

* Any of the [universal error types](/docs/references/http-websocket-apis/api-conventions/error-formatting#universal-errors).
* `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 localhost).