Last updated
Edit

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:

FieldTypeRequired?Description
ledger_hashHashNoA 32-byte hex string for the ledger version to use. (See Specifying Ledgers)
ledger_indexLedger IndexNoThe 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:

FieldTypeDescription
changesArrayList 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_hashHashThe identifying hash of the ledger version that was used when retrieving this data.
ledger_indexLedger IndexThe ledger index of the ledger version that was used when retrieving this data.
ledger_timeNumberThe official close time of the ledger that was used when retrieving this data, in seconds since the Ripple Epoch.
typeStringThe string bookChanges, which indicates that this is an order book update message.
validatedBoolean(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:

FieldTypeDescription
currency_aStringAn 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_bStringAn 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_aString - NumberThe 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_bString - NumberThe volume of the second currency (that is, currency_b) that moved as a result of trades through this order book in this ledger.
highString - NumberThe 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.)
lowString - NumberThe lowest exchange rate among all offers matched in this ledger, as a ratio of the first currency to the second currency.
openString - NumberThe 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.
closeString - NumberThe 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.