The WebSocket API v1 order book feed provides all of the market data needed to maintain a local copy of a Kraken order book.
For example, the order book feed for XBT/USD could be used to retrieve and maintain the order book for our Bitcoin/US Dollar currency pair, exactly as the order book is shown on our trading platform.
The order book feed provides an initial snapshot of the current order book, and then streams updates to the order book in real time, so an order book maintained via the order book feed will be up to date at all times.
Full details of the JSON format for the order book feed are available in our WebSocket API v1 documentation.
After subscribing to the order book feed, the first market data message will be a snapshot of the current order book.
The order book snapshot includes the entire order book up to the requested (subscribed) depth, such as the following example of the XBT/USD order book to a depth of 10:
[0,{"as":[["5290.80000","1.00000000","1556724667.748660"],["5290.90000","4.49956524","1556724664.331028"],["5291.70000","1.00000000","1556724653.480504"],["5292.00000","0.95388940","1556724619.682690"],["5292.20000","1.51300000","1556724494.497326"],["5293.10000","0.69800000","1556724667.635414"],["5293.20000","2.00000000","1556724656.022756"],["5293.90000","2.83200000","1556724668.057687"],["5294.10000","0.99600000","1556724666.340462"],["5294.50000","5.00000000","1556724661.980996"]],"bs":[["5290.10000","1.43195600","1556724666.594179"],["5289.80000","2.00000000","1556724663.082526"],["5289.40000","0.49400000","1556724665.274827"],["5289.20000","0.89533312","1556724640.520134"],["5287.40000","3.23600000","1556724660.997516"],["5287.30000","3.33000000","1556724659.999108"],["5287.00000","10.20000000","1556724635.850932"],["5286.00000","3.86378703","1556724662.757360"],["5285.70000","6.40000000","1556724488.785281"],["5283.90000","0.50000000","1556723616.006805"]]},"book-10","XBT/USD"]
The snapshot includes the current best bid/ask prices, with their available volumes, and the date/time that the price level was most recently updated (as a UNIX timestamp in seconds to 6 decimal places).
Price Level Changes
After the initial snapshot, the price levels of the order book are modified in real time via update, insert, and delete messages.
Update Messages
An update message updates a price level that already exists within the order book by providing a new volume and timestamp, such as the following update for price level 5293.1 on the ask side of the order book:
[0,{"a":[["5293.10000","0.39800000","1556724673.104421"]], "c":"408163318"},"book-10","XBT/USD"]
While the price remains the same (5293.1), the available volume at that price is changed from 0.69800000 (as provided by the initial snapshot) to 0.39800000, and the new timestamp for the price level reflects the date/time that the change occurred.
Update messages only change price levels that already exist within the order book; they do not add or remove price levels to/from the order book.
Insert Messages
An insert message adds a new price level to the order book, such as the following insert for price level 5294.4 on the ask side of the order book:
[0,{"a":[["5294.40000","0.99600000","1556724672.663220"]], "c":"393966308"},"book-10","XBT/USD"]
Each insert message includes the new price level (5294.4), the available volume at that price (0.99600000), and the timestamp that the price level was most recently updated.
Insert messages change the price levels within the order book by creating a new price level, moving all of the subsequent price levels (lower bid prices or higher ask prices) outwards, and pushing the outermost price level out of the scope of the order book.
For example, from the initial snapshot above, the insert message:
[0,{"a":[["5294.40000","0.99600000","1556724672.663220"]], "c":"393966308"},"book-10","XBT/USD"]
Would add price level 5294.4 into the order book at level 10 (the highest ask price), and move price level 5294.5 out of the scope of the order book (by effectively moving 5294.5 to level 11).
Delete Messages
A delete message removes a price level from the order book, such as the following partial delete message for price level 5294.1 on the ask side of the order book:
[0,{"a":[["5294.10000","0.00000000","1556724670.010241"]] ... },"book-10","XBT/USD"]
Delete messages include the price level which no longer exists, always specify an available volume of 0.0, and include a timestamp indicating the date/time that the price level was removed from the order book.
Delete messages change the price levels within the order book by removing the affected price level (from the order book entirely, not just from the subscribed depth), moving all of the subsequent price levels (lower bid prices or higher ask prices) inwards, and pulling a new price level into the scope of the order book.
Note that a delete is always immediately followed an insert that brings a new price level into scope at the outermost level (such as level 10 for a subscribed depth of 10).
For example, from the initial snapshot above, the delete/insert message:
[0,{"a":[["5294.10000","0.00000000","1556724670.010241"],["5294.70000","3.34000000","1556724653.951982","r"]], "c":"3679121060"},"book-10","XBT/USD"]
This would delete price level 5294.1 from level 9 of the order book, move price level 5294.5 from level 10 to level 9, and immediately add the new price level 5294.7 to level 10 of the order book (the outermost level and highest ask price for a depth of 10).
Additional Resources
Further details of the order book logic are available via a sample order book transcript and example code implementing asynchronous (multi-threaded) and synchronous (single-threaded) command line clients.
The decimal and thousands separators shown in this article may differ from the formats displayed on our trading platforms. Review our article on how we use points and commas for more information.