book_changes

[Source]

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

Request Format

An example of the request format:

{
    "id": "example_book_changes",
    "command": "book_changes",
    "ledger_index": 88530953
}

Try it! >

The request includes the following parameters:

Field	Type	Required?	Description
`ledger_hash`	Hash	No	A 32-byte hex string for the ledger version to use. (See Specifying Ledgers)
`ledger_index`	Ledger Index	No	The ledger index of the ledger to use, or a shortcut string to choose a ledger automatically. (See Specifying Ledgers)

Known Issues

There are several known issue with this method in rippled.

You must specify the ledger_index or ledger_hash explicitly instead of using a default or a shortcut string. (Issue #5034)
JSON-RPC API responses may be missing the validated field even when querying validated ledgers. (#5035)
When querying a recently-closed ledger, a successful response may sometimes return a Ledger Request Object instead of the intended data. (#5033)
When querying data from older ledgers, the server may take a long time (over 30 seconds) to respond. (#5036)

These bugs do not apply to Clio servers.

Response Format

An example of a successful response:

{
    "result": {
      "type": "bookChanges",
      "ledger_hash": "7AB08A2415C10E07201521F3260F77ADFF4902A528EA66378E259A07767A24B9",
      "ledger_index": 88530953,
      "ledger_time": 771100891,
      "validated": true,
      "changes": [
        {
          "currency_a": "XRP_drops",
          "currency_b": "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/CNY",
          "volume_a": "44082741",
          "volume_b": "158.6978676",
          "high": "277777.7777777778",
          "low": "277777.7777777778",
          "open": "277777.7777777778",
          "close": "277777.7777777778"
        },
        {
          "currency_a": "XRP_drops",
          "currency_b": "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/XLM",
          "volume_a": "44191586",
          "volume_b": "217.6925474337355",
          "high": "202999.9948135647",
          "low": "202999.9948135647",
          "open": "202999.9948135647",
          "close": "202999.9948135647"
        },
        {
          "currency_a": "XRP_drops",
          "currency_b": "rf5YPb9y9P3fTjhxNaZqmrwaj5ar8PG1gM/47414C4100000000000000000000000000000000",
          "volume_a": "100000000",
          "volume_b": "1242.61659179386",
          "high": "80475.34586323083",
          "low": "80475.34586323083",
          "open": "80475.34586323083",
          "close": "80475.34586323083"
        },
        {
          "currency_a": "XRP_drops",
          "currency_b": "rsoLo2S1kiGeCcn6hCUXVrCpGMWLrRrLZz/534F4C4F00000000000000000000000000000000",
          "volume_a": "33734",
          "volume_b": "0.1454210006367",
          "high": "231974.7481608686",
          "low": "231974.7481608686",
          "open": "231974.7481608686",
          "close": "231974.7481608686"
        },
        {
          "currency_a": "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/CNY",
          "currency_b": "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/USD",
          "volume_a": "158.6978670792",
          "volume_b": "21.76925474337",
          "high": "7.290000000001503",
          "low": "7.290000000001503",
          "open": "7.290000000001503",
          "close": "7.290000000001503"
        },
        {
          "currency_a": "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/USD",
          "currency_b": "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/XLM",
          "volume_a": "21.76925474337355",
          "volume_b": "217.6925474337355",
          "high": "0.1",
          "low": "0.1",
          "open": "0.1",
          "close": "0.1"
        }
      ]
    },
    "id": "example_book_changes",
    "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 the following fields:

Field	Type	Description
`changes`	Array	List of Book Update Objects, containing one entry for each order book that was updated in this ledger version. The array is empty if no order books were updated.
`ledger_hash`	Hash	The identifying hash of the ledger version that was used when retrieving this data.
`ledger_index`	Ledger Index	The ledger index of the ledger version that was used when retrieving this data.
`ledger_time`	Number	The official close time of the ledger that was used when retrieving this data, in seconds since the Ripple Epoch.
`type`	String	The string `bookChanges`, which indicates that this is an order book update message.
`validated`	Boolean	(May be omitted) If `true`, the information comes from a validated ledger version.

Book Update Objects

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

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

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

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

Possible Errors

Any of the universal error types.
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.
invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.