book_changes
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 }
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_indexorledger_hashexplicitly instead of using a default or a shortcut string. (Issue #5034) - JSON-RPC API responses may be missing the
validatedfield 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 theledger_hashorledger_indexdoes 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.