# book_changes [[Source]](https://github.com/XRPLF/rippled/blob/master/src/xrpld/rpc/BookChanges.h) The method reports information about changes to the order books in the [decentralized exchange (DEX)](/docs/concepts/tokens/decentralized-exchange) compared with the previous ledger version. This may be useful for building "candlestick" charts. ### Request Format An example of the request format: WebSocket ```json { "id": "example_book_changes", "command": "", "ledger_index": 88530953 } ``` JSON-RPC ```json { "method": "", "params": [{ "ledger_index": 88530953 }] } ``` Commandline ```sh #Syntax: book_changes [] rippled book_changes 88530953 ``` The request includes 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)) | ## Response Format An example of a successful response: WebSocket ```json { "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" } ] } ``` JSON-RPC ```json 200 OK { "result" : { "changes" : [ { "close" : "277777.7777777778", "currency_a" : "XRP_drops", "currency_b" : "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/CNY", "high" : "277777.7777777778", "low" : "277777.7777777778", "open" : "277777.7777777778", "volume_a" : "44082741", "volume_b" : "158.6978676" }, { "close" : "202999.9948135647", "currency_a" : "XRP_drops", "currency_b" : "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/XLM", "high" : "202999.9948135647", "low" : "202999.9948135647", "open" : "202999.9948135647", "volume_a" : "44191586", "volume_b" : "217.6925474337355" }, { "close" : "80475.34586323083", "currency_a" : "XRP_drops", "currency_b" : "rf5YPb9y9P3fTjhxNaZqmrwaj5ar8PG1gM/47414C4100000000000000000000000000000000", "high" : "80475.34586323083", "low" : "80475.34586323083", "open" : "80475.34586323083", "volume_a" : "100000000", "volume_b" : "1242.61659179386" }, { "close" : "231974.7481608686", "currency_a" : "XRP_drops", "currency_b" : "rsoLo2S1kiGeCcn6hCUXVrCpGMWLrRrLZz/534F4C4F00000000000000000000000000000000", "high" : "231974.7481608686", "low" : "231974.7481608686", "open" : "231974.7481608686", "volume_a" : "33734", "volume_b" : "0.1454210006367" }, { "close" : "7.290000000001503", "currency_a" : "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/CNY", "currency_b" : "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/USD", "high" : "7.290000000001503", "low" : "7.290000000001503", "open" : "7.290000000001503", "volume_a" : "158.6978670792", "volume_b" : "21.76925474337" }, { "close" : "0.1", "currency_a" : "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/USD", "currency_b" : "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/XLM", "high" : "0.1", "low" : "0.1", "open" : "0.1", "volume_a" : "21.76925474337355", "volume_b" : "217.6925474337355" } ], "ledger_hash" : "7AB08A2415C10E07201521F3260F77ADFF4902A528EA66378E259A07767A24B9", "ledger_index" : 88530953, "ledger_time" : 771100891, "status" : "success", "type" : "bookChanges" } } ``` Commandline ```json Loading: "/etc/opt/ripple/rippled.cfg" 2024-Jun-07 18:41:45.257772761 UTC HTTPClient:NFO Connecting to 127.0.0.1:5005 { "result" : { "changes" : [ { "close" : "277777.7777777778", "currency_a" : "XRP_drops", "currency_b" : "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/CNY", "high" : "277777.7777777778", "low" : "277777.7777777778", "open" : "277777.7777777778", "volume_a" : "44082741", "volume_b" : "158.6978676" }, { "close" : "202999.9948135647", "currency_a" : "XRP_drops", "currency_b" : "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/XLM", "high" : "202999.9948135647", "low" : "202999.9948135647", "open" : "202999.9948135647", "volume_a" : "44191586", "volume_b" : "217.6925474337355" }, { "close" : "80475.34586323083", "currency_a" : "XRP_drops", "currency_b" : "rf5YPb9y9P3fTjhxNaZqmrwaj5ar8PG1gM/47414C4100000000000000000000000000000000", "high" : "80475.34586323083", "low" : "80475.34586323083", "open" : "80475.34586323083", "volume_a" : "100000000", "volume_b" : "1242.61659179386" }, { "close" : "231974.7481608686", "currency_a" : "XRP_drops", "currency_b" : "rsoLo2S1kiGeCcn6hCUXVrCpGMWLrRrLZz/534F4C4F00000000000000000000000000000000", "high" : "231974.7481608686", "low" : "231974.7481608686", "open" : "231974.7481608686", "volume_a" : "33734", "volume_b" : "0.1454210006367" }, { "close" : "7.290000000001503", "currency_a" : "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/CNY", "currency_b" : "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/USD", "high" : "7.290000000001503", "low" : "7.290000000001503", "open" : "7.290000000001503", "volume_a" : "158.6978670792", "volume_b" : "21.76925474337" }, { "close" : "0.1", "currency_a" : "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/USD", "currency_b" : "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y/XLM", "high" : "0.1", "low" : "0.1", "open" : "0.1", "volume_a" : "21.76925474337355", "volume_b" : "217.6925474337355" } ], "ledger_hash" : "7AB08A2415C10E07201521F3260F77ADFF4902A528EA66378E259A07767A24B9", "ledger_index" : 88530953, "ledger_time" : 771100891, "status" : "success", "type" : "bookChanges" } } ``` The response follows the [standard format](/docs/references/http-websocket-apis/api-conventions/response-formatting), with a successful result containing the following fields: | Field | Type | Description | | --- | --- | --- | | `changes` | Array | List of [Book Update Objects](#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](/docs/references/protocol/data-types/basic-data-types#hashes) | The identifying hash of the ledger version that was used when retrieving this data. | | `ledger_index` | [Ledger Index](/docs/references/protocol/data-types/basic-data-types#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](/docs/references/protocol/data-types/basic-data-types#specifying-time). | | `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](/docs/concepts/tokens), this is formatted as the address of the issuer in [base58](/docs/references/protocol/data-types/base58-encodings), followed by a forward-slash (`/`), followed by the [Currency Code](/docs/references/protocol/data-types/currency-formats#currency-codes) 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](/docs/references/protocol/data-types/basic-data-types#specifying-currency-amounts). 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](/docs/references/http-websocket-apis/api-conventions/error-formatting#universal-errors). * `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.