Spot Websockets

class kraken.spot.KrakenSpotWSClientV2(key: str = '', secret: str = '', callback: Callable | None = None, *, no_public: bool = False, beta: bool = False)

Bases: KrakenSpotWSClientBase

This client only supports the Kraken Websocket API v2.

Class to access public and private/authenticated websocket connections.

• https://docs.kraken.com/websockets-v2

… please use kraken.spot.KrakenSpotWSClientV1 for accessing the Kraken’s Websocket API v1.

This class holds up to two websocket connections, one private and one public. The core functionalities are un-/subscribing to websocket feeds and sending messages. See kraken.spot.KrakenSpotWSClientV2.subscribe() and kraken.spot.KrakenSpotWSClientV2.send_message() for more information.

When accessing private endpoints that need authentication make sure, that the Access WebSockets API API key permission is set in the user’s account. To place or cancel orders, querying ledger information or accessing live portfolio changes (fills, new orders, …) there are separate permissions that must be enabled if required.

Parameters:

• key (str, optional) – API Key for the Kraken Spot API (default: "")

• secret (str, optional) – Secret API Key for the Kraken Spot API (default: "")

• url (str, optional) – Set a specific URL to access the Kraken REST API

• no_public – Disables public connection (default: False). If not set or set to False, the client will create a public and a private connection per default. If only a private connection is required, this parameter should be set to True.

• beta (bool) – Use the beta websocket channels (maybe not supported anymore, default: False)

HowTo: Use the Kraken Spot websocket client (v2)

import asyncio
from kraken.spot import KrakenSpotWSClientV2


class Client(KrakenSpotWSClientV2):

    async def on_message(self, message):
        print(message)


async def main():

    client = Client()         # unauthenticated
    client_auth = Client(     # authenticated
        key="kraken-api-key",
        secret="kraken-secret-key"
    )

    # subscribe to the desired feeds:
    await client.subscribe(
        params={"channel": "ticker", "symbol": ["BTC/USD"]}
    )
    # from now on the on_message function receives the ticker feed

    while not client.exception_occur:
        await asyncio.sleep(6)

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        pass

HowTo: Use the websocket client (v2) as instance

import asyncio
from kraken.spot import KrakenSpotWSClientV2


async def main():
    async def on_message(message):
        print(message)

    client = KrakenSpotWSClientV2(callback=on_message)
    await client.subscribe(
        params={"channel": "ticker", "symbol": ["BTC/USD"]}
    )

    while not client.exception_occur:
        await asyncio.sleep(10)


if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        pass

HowTo: Use the websocket client (v2) as context manager

import asyncio
from kraken.spot import KrakenSpotWSClientV2

async def on_message(message):
    print(message)

async def main():
    async with KrakenSpotWSClientV2(
        key="api-key",
        secret="secret-key",
        callback=on_message
    ) as session:
        await session.subscribe(
            params={"channel": "ticker", "symbol": ["BTC/USD"]}
        )

    while True
        await asyncio.sleep(6)


if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        pass

property active_private_subscriptions: list[dict] | Any

Returns the active private subscriptions

Returns:

List of active private subscriptions

Return type:

list[dict] | Any

Raises:

ConnectionError – If there is no active private connection

property active_public_subscriptions: list[dict] | Any

Returns the active public subscriptions

Returns:

List of active public subscriptions

Return type:

list[dict] | Any

Raises:

ConnectionError – If there is no active public connection.

get_ws_token() → dict

Get the authentication token to establish the authenticated websocket connection. This is used internally and in most cases not needed outside.

• https://docs.kraken.com/rest/#tag/Websockets-Authentication

Returns:

The authentication token

Return type:

dict

async on_message(message: dict | list) → None

Calls the defined callback function (if defined). In most cases you have to overwrite this function since it will receive all incoming messages that will be sent by Kraken.

See kraken.spot.KrakenSpotWSClientV1 and kraken.spot.KrakenSpotWSClientV2 for examples to use this function.

Parameters:

message (dict | list) – The message received sent by Kraken via the websocket connection

property private_channel_names: list[str]

Returns the list of valid values for channel when un-/subscribing from/to private feeds that need authentication.

See https://docs.kraken.com/websockets-v2/#channels for all channels.

Currently there is only one private channel (June 2023):

• executions

Returns:

List of available private channel names

Return type:

list[str]

property private_methods: list[str]

Returns the list of available methods - parameters are similar to the REST API trade methods.

The available methods and their documentation are listed below (as of June 2023):

• add_order

• batch_order

• batch_cancel

• cancel_all

• cancel_all_orders_after

• cancel_order

• edit_order

Returns:

List of available methods

Return type:

list[str]

property public_channel_names: list[str]

Returns the list of valid values for channel when un-/subscribing from/to public feeds without authentication.

See https://docs.kraken.com/websockets-v2/#channels for all channels.

The available public channels are listed below:

• book

• instrument

• ohlc

• ticker

• trade

Returns:

List of available public channel names

Return type:

list[str]

property return_unique_id: str

Returns a unique uuid string

Returns:

uuid

Return type:

str

async send_message(message: dict, *, raw: bool = False) → None

Sends a message via the websocket connection. For private messages the authentication token will be assigned automatically if raw=False.

The user can specify a req_d within the message to identify corresponding responses via websocket feed.

Parameters:

• message (dict) – The information to send

• raw (bool, optional) – If set to True the message will be sent directly.

The following examples demonstrate how to use the kraken.spot.KrakenSpotWSClientV2.send_message() function. The client must be instantiated as described in kraken.spot.KrakenSpotWSClientV2 where client uses public connections (without authentication) and client_auth must be instantiated using valid credentials since only this way placing or canceling orders can be done.

Please note that the send_message function will automatically pass the authentication token (except for the case if raw=True ).

Placing orders using an authenticated websocket connection can be easily done as shown in the example below. See https://docs.kraken.com/websockets-v2/#add-order to retrieve more information about the available parameters.

Spot Websocket v2: Place a new order

>>> await client_auth.send_message(
...     message={
...         "method": "add_order",
...         "params": {
...             "limit_price": 1234.56,
...             "order_type": "limit",
...             "order_userref": 123456789,
...             "order_qty": 1.0,
...             "side": "buy",
...             "symbol": "BTC/USD",
...         },
...     }
... )

Placing orders as batch can be done by passing batch_add as method. Its parameters and limitations are described in https://docs.kraken.com/websockets-v2/#batch-add.

Spot Websocket v2: Placing orders as batch

>>> await client_auth.send_message(
...     message={
...         "method": "batch_add",
...         "params": {
...             "orders": [
...                 {
...                     "limit_price": 1000.23,
...                     "order_qty": 1,
...                     "order_type": "limit",
...                     "order_userref": 123456789,
...                     "side": "buy",
...                 },
...                 {
...                     "limit_price": 500.21,
...                     "order_qty": 2.12345,
...                     "order_type": "limit",
...                     "order_userref": 212345679,
...                     "side": "sell",
...                     "stp_type": "cancel_both",
...                 },
...             ],
...             "symbol": "BTC/USD",
...             "validate": True,
...         },
...     }
... )

Cancel orders as batch is available using the batch_cancel method as described in https://docs.kraken.com/websockets-v2/#batch-cancel.

Spot Websocket v2: Cancel orders as batch

>>> await client_auth.send_message(
...     message={
...         "method": "batch_cancel",
...         "params": {
...             "orders": [
...                 "123456789",
...                 "212345679",
...                 "ORDER-ID123-4567890"
...             ],
...         },
...     }
... )

Cancel all orders can be used as the name suggests - to cancel all open orders (see https://docs.kraken.com/websockets-v2/#cancel-all-orders).

Spot Websocket v2: Cancel all orders

>>> await client_auth.send_message(
...     message={
...         "method": "cancel_all",
...     }
... )

Death Man’s Switch is a useful utility to reduce the risk of losses due to network fuckups since it will cancel all orders if the call was not received by Kraken within a certain amount of time. See https://docs.kraken.com/websockets-v2/#cancel-all-orders-after for more information.

Spot Websocket v2: Death Man’s Switch / cancel_all_orders_after

>>> await client_auth.send_message(
...     message={
...         "method": "cancel_all_orders_after",
...         "params": {"timeout": 60},
...     }
... )

Canceling orders is a common task during trading and can be done as described in https://docs.kraken.com/websockets-v2/#cancel-order.

Spot Websocket v2: Cancel order(s)

>>> await client_auth.send_message(
...     message={
...         "method": "cancel_order",
...         "params": {
...             "order_id": ["ORDER-ID123-456789", "ORDER-ID123-987654"],
...         },
...     }
... )

Editing orders can be done as shown in the example below. See https://docs.kraken.com/websockets-v2/#edit-order for more information.

Spot Websocket v2: Cancel order(s)

>>> await client_auth.send_message(
...     message={
...         "method": "edit_order",
...         "params": {
...             "order_id": "ORDER-ID123-456789",
...             "order_qty": 2.5,
...             "symbol": "BTC/USD",
...         },
...     }
... )

Subscribing to websocket feeds can be done using the send_message function but it is recommended to use kraken.spot.KrakenSpotWSClientV2.subscribe() instead.

Spot Websocket v2: Subscribe to a websocket feed

>>> await client.send_message(
...     message={
...         "method": "subscribe",
...         "params": {"channel": "book", "snapshot": False, "symbol": ["BTC/USD"]},
...     }
... )

async subscribe(params: dict, req_id: int | None = None) → None

Subscribe to a channel/feed

Success or failures are sent over the websocket connection and can be received via the on_message or callback function.

When accessing private endpoints and subscription feeds that need authentication make sure that the Access WebSockets API API key permission is set in the users Kraken account.

• https://docs.kraken.com/websockets-v2/#subscribe

See https://docs.kraken.com/websockets-v2/#channels for all channels.

Please note that this function automatically assigns the method key and sets its value to subscribe. The authentication token is also assigned automatically, so only the params are needed here.

Parameters:

• params (dict) – The subscription message

• req_id (int, optional) – Identification number that will be added to the response message sent by the websocket feed.

Initialize your client as described in kraken.spot.KrakenSpotWSClientV2 to run the following example:

Spot Websocket v2: Subscribe to a websocket feed

>>> await client.subscribe(
...     params={"channel": "ticker", "symbol": ["BTC/USD"]}
... )

async unsubscribe(params: dict, req_id: int | None = None) → None

Unsubscribe from a channel/feed

Success or failures are sent via the websocket connection and can be received via the on_message or callback function.

When accessing private endpoints and subscription feeds that need authentication make sure, that the Access WebSockets API API key permission is set in the users Kraken account.

• https://docs.kraken.com/websockets-v2/#unsubscribe

Parameters:

params (dict) – The unsubscription message (only the params part)

Initialize your client as described in kraken.spot.KrakenSpotWSClientV2 to run the following example:

Spot Websocket v2: Unsubscribe from a websocket feed

>>> await client.unsubscribe(
...     params={"channel": "ticker", "symbol": ["BTC/USD"]}
... )

class kraken.spot.KrakenSpotWSClientV1(key: str = '', secret: str = '', callback: Callable | None = None, *, no_public: bool = False, beta: bool = False)

Bases: KrakenSpotWSClientBase

Deprecated since version v2.2.0.

Class to access public and private/authenticated websocket connections.

This client only supports the Kraken Websocket API v1.

• https://docs.kraken.com/websockets

… please use KrakenSpotWSClientV2 for accessing the Kraken Websockets API v2.

This class holds up to two websocket connections, one private and one public.

When accessing private endpoints that need authentication make sure, that the Access WebSockets API API key permission is set in the user’s account. To place or cancel orders, querying ledger information or accessing live portfolio changes (fills, new orders, …) there are separate permissions that must be enabled if required.

Parameters:

• key (str, optional) – API Key for the Kraken Spot API (default: "")

• secret (str, optional) – Secret API Key for the Kraken Spot API (default: "")

• url (str, optional) – Set a specific URL to access the Kraken REST API

• no_public – Disables public connection (default: False). If not set or set to False, the client will create a public and a private connection per default. If only a private connection is required, this parameter should be set to True.

• beta (bool) – Use the beta websocket channels (maybe not supported anymore, default: False)

HowTo: Use the Kraken Spot websocket client (v1)

import asyncio
from kraken.spot import KrakenSpotWSClientV1


class Client(KrakenSpotWSClientV1):

    async def on_message(self, message):
        print(message)


async def main():

    client = Client()         # unauthenticated
    client_auth = Client(     # authenticated
        key="kraken-api-key",
        secret="kraken-secret-key"
    )

    # subscribe to the desired feeds:
    await client.subscribe(
        subscription={"name": ticker},
        pair=["XBTUSD", "DOT/EUR"]
    )
    # from now on the on_message function receives the ticker feed

    while not client.exception_occur:
        await asyncio.sleep(6)

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        pass

HowTo: Use the websocket client (v1) as instance

import asyncio
from kraken.spot import KrakenSpotWSClientV1


async def main() -> None:
    async def on_message(message) -> None:
        print(message)

    client = KrakenSpotWSClientV1(callback=on_message)
    await client.subscribe(
        subscription={"name": "ticker"},
        pair=["XBT/USD"]
    )

    while not client.exception_occur:
        await asyncio.sleep(10)


if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        pass

HowTo: Use the websocket client (v1) as context manager

import asyncio
from kraken.spot import KrakenSpotWSClientV1

async def on_message(message):
    print(message)

async def main() -> None:
    async with KrakenSpotWSClientV1(
        key="api-key",
        secret="secret-key",
        callback=on_message
    ) as session:
        await session.subscribe(
            subscription={"name": "ticker"},
            pair=["XBT/USD"]
        )

    while True
        await asyncio.sleep(6)


if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        pass

property active_private_subscriptions: list[dict] | Any

Returns the active private subscriptions

Returns:

List of active private subscriptions

Return type:

list[dict] | Any

Raises:

ConnectionError – If there is no active private connection

property active_public_subscriptions: list[dict] | Any

Returns the active public subscriptions

Returns:

List of active public subscriptions

Return type:

list[dict] | Any

Raises:

ConnectionError – If there is no active public connection.

async cancel_all_orders() → None

Cancel all open Spot orders.

Requires the Access WebSockets API and Cancel/close orders API key permissions.

• https://docs.kraken.com/websockets/#message-cancelAll

Raises:

KrakenAuthenticationError – If the websocket is not connected or the connection is not authenticated

Returns:

None

Initialize your client as described in kraken.spot.KrakenSpotWSClientV1 to run the following example:

Spot Websocket: Cancel all Orders

>>> await client_auth.cancel_all_orders()

async cancel_all_orders_after(timeout: int = 0) → None

Set a Death Man’s Switch

Requires the Access WebSockets API and Cancel/close orders API key permissions.

• https://docs.kraken.com/websockets/#message-cancelAllOrdersAfter

Parameters:

timeout (int) – Set the timeout in seconds to cancel the orders after, set to 0 to reset.

Raises:

KrakenAuthenticationError – If the websocket is not connected or the connection is not authenticated

Returns:

None

Initialize your client as described in kraken.spot.KrakenSpotWSClientV1 to run the following example:

Spot Websocket: Death Man’s Switch

>>> await client_auth.cancel_all_orders_after(timeout=60)

async cancel_order(txid: list[str]) → None

Cancel a specific order or a list of orders.

Requires the Access WebSockets API and Cancel/close orders API key permissions.

• https://docs.kraken.com/websockets/#message-cancelOrder

Parameters:

txid (list[str]) – A single or multiple transaction ids as list

Raises:

KrakenAuthenticationError – If the websocket is not connected or the connection is not authenticated

Returns:

None

Initialize your client as described in kraken.spot.KrakenSpotWSClientV1 to run the following example:

Spot Websocket: Cancel an order

>>> await client_auth.cancel_order(txid=["OBGFYP-XVQNL-P4GMWF"])

create_order(ordertype: str, side: str, pair: str, volume: str | float, price: str | float | None = None, price2: str | float | None = None, leverage: str | float | None = None, oflags: str | list[str] | None = None, starttm: str | int | None = None, expiretm: str | int | None = None, deadline: str | None = None, userref: str | int | None = None, close_ordertype: str | None = None, close_price: str | float | None = None, close_price2: str | float | None = None, timeinforce: str | int | None = None, *, truncate: bool = False, validate: bool = False) → None

Create an order and submit it.

Requires the Access WebSockets API and Create and modify orders API key permissions.

• https://docs.kraken.com/websockets/#message-addOrder

Parameters:

• ordertype (str) – The type of order, one of: limit, market, stop-loss, take-profit, stop-loss-limit, settle-position, take-profit-limit (see: https://support.kraken.com/hc/en-us/sections/200577136-Order-types)

• side (str) – The side - one of buy, sell

• pair (str) – The asset pair to trade

• volume (str | float) – The volume of the order that is being created

• price (str | float, optional) – The limit price for limit orders or the trigger price for orders with ordertype one of stop-loss, stop-loss-limit, take-profit, and take-profit-limit

• price2 (str | float, optional) – The second price for stop-loss-limit and take-profit-limit orders (see the referenced Kraken documentation for more information)

• leverage (str | float, optional) – The leverage

• oflags (str | list[str], optional) – Order flags like post, fcib, fciq, nomp, viqc (see the referenced Kraken documentation for more information)

• starttm (str | int, optional) – Unix timestamp or seconds defining the start time (default: "0")

• expiretim (str) – Unix timestamp or time in seconds defining the expiration of the order (default: "0" - i.e., no expiration)

• deadline (str) – RFC3339 timestamp + {0..60} seconds that defines when the matching engine should reject the order.

• userref (int) – User reference id for example to group orders

• close_ordertype (str, optional) – Conditional close order type, one of: limit, stop-loss, take-profit, stop-loss-limit, take-profit-limit

• close_price (str | float, optional) – Conditional close price

• close_price2 (str | float, optional) – Second conditional close price

• timeinforce (str, optional) – How long the order remains in the orderbook, one of: GTC, IOC, GTD (see the referenced Kraken documentation for more information)

• truncate (bool, optional) – If enabled: round the price and volume to Kraken’s maximum allowed decimal places. See https://support.kraken.com/hc/en-us/articles/4521313131540 fore more information about decimals.

• validate (bool, optional) – Validate the order without placing on the market (default: False)

Raises:

• KrakenAuthenticationError – If the websocket is not connected or the connection is not authenticated

• ValueError – If input is not correct

Return type:

None

Initialize your client as described in kraken.spot.KrakenSpotWSClientV1 to run the following example:

Spot Websocket: Create an order

>>> await client_auth.create_order(
...     ordertype="market",
...     pair="XBTUSD",
...     side="buy",
...     volume=0.001
... )
>>> await client_auth.create_order(
...     ordertype="limit",
...     side="buy",
...     pair="XBTUSD",
...     volume=0.02,
...     price=23000,
...     expiretm=120,
...     oflags=["post", "fcib"]
... )

edit_order(orderid: str, reqid: str | int | None = None, pair: str | None = None, price: str | float | None = None, price2: str | float | None = None, volume: str | float | None = None, oflags: str | list[str] | None = None, newuserref: str | int | None = None, *, truncate: bool = False, validate: bool = False) → None

Edit an open order that was placed on the Spot market.

Requires the Access WebSockets API and Create and modify orders API key permissions.

• https://docs.kraken.com/websockets/#message-editOrder

Parameters:

• orderId (str) – The orderId of the order to edit

• reqid (str | int, optional) – Filter by reqid

• pair (str, optional) – Filter by pair

• price (str | int | float, optional) – Set a new price

• price2 (str | int | float, optional) – Set a new second price

• volume (str | int | float, optional) – Set a new volume

• oflags (str | list[str], optional) – Set new oflags (overwrite old ones)

• newuserref (str | int, optional) – Set a new user reference id

• truncate (bool, optional) – If enabled: round the price and volume to Kraken’s maximum allowed decimal places. See https://support.kraken.com/hc/en-us/articles/4521313131540 fore more information about decimals.

• validate (bool, optional) – Validate the input without applying the changes (default: False)

Raises:

• KrakenAuthenticationError – If the websocket is not connected or the connection is not authenticated

• ValueError – If input is not correct

Return type:

None

Initialize your client as described in kraken.spot.KrakenSpotWSClientV1 to run the following example:

Spot Websocket: Edit an order

>>> await client_auth.edit_order(
...     orderId="OBGFYP-XVQNL-P4GMWF",
...     volume=0.75,
...     pair="XBTUSD",
...     price=20000
... )

get_ws_token() → dict

Get the authentication token to establish the authenticated websocket connection. This is used internally and in most cases not needed outside.

• https://docs.kraken.com/rest/#tag/Websockets-Authentication

Returns:

The authentication token

Return type:

dict

async on_message(message: dict | list) → None

Calls the defined callback function (if defined). In most cases you have to overwrite this function since it will receive all incoming messages that will be sent by Kraken.

See kraken.spot.KrakenSpotWSClientV1 and kraken.spot.KrakenSpotWSClientV2 for examples to use this function.

Parameters:

message (dict | list) – The message received sent by Kraken via the websocket connection

property private_channel_names: list[str]

Returns the private subscription names

Returns:

List of private subscription names (ownTrades, openOrders)

Return type:

list[str]

property public_channel_names: list[str]

Returns the public subscription names

Returns:

List of public subscription names (ticker, spread, book, ohlc, trade, *)

Return type:

list[str]

property return_unique_id: str

Returns a unique uuid string

Returns:

uuid

Return type:

str

async send_message(message: dict, *, private: bool = False, raw: bool = False) → None

Sends a message via the websocket connection. For private messages the authentication token will be assigned automatically if raw=False.

The user can specify a reqid within the message to identify corresponding responses via websocket feed.

Parameters:

• message (dict) – The content to send

• private (bool, optional) – Use authentication (default: False)

• raw (bool, optional) – If set to True the message will be sent directly.

async subscribe(subscription: dict, pair: list[str] | None = None) → None

Subscribe to a channel

Success or failures are sent over the websocket connection and can be received via the on_message callback function.

When accessing private endpoints and subscription feeds that need authentication make sure, that the Access WebSockets API API key permission is set in the users Kraken account.

• https://docs.kraken.com/websockets/#message-subscribe

Parameters:

• subscription (dict) – The subscription message

• pair (list[str], optional) – The pair to subscribe to

Initialize your client as described in kraken.spot.KrakenSpotWSClientV1 to run the following example:

Spot Websocket v1: Subscribe to a websocket feed

>>> await client.subscribe(
...     subscription={"name": ticker},
...     pair=["XBTUSD", "DOT/EUR"]
... )

async unsubscribe(subscription: dict, pair: list[str] | None = None) → None

Unsubscribe from a feed

Success or failures are sent via the websocket connection and can be received via the on_message or callback function.

When accessing private endpoints and subscription feeds that need authentication make sure, that the Access WebSockets API API key permission is set in the users Kraken account.

• https://docs.kraken.com/websockets/#message-unsubscribe

Parameters:

• subscription (dict) – The subscription to unsubscribe from

• pair (list[str], optional) – The pair or list of pairs to unsubscribe

Initialize your client as described in kraken.spot.KrakenSpotWSClientV1 to run the following example:

Spot Websocket v1: Unsubscribe from a websocket feed

>>> await client.unsubscribe(
...     subscription={"name": ticker},
...     pair=["XBTUSD", "DOT/EUR"]
... )

class kraken.spot.OrderbookClientV2(depth: int = 10, callback: Callable | None = None)

Bases: object

This client is using the Kraken Websocket API v2

The orderbook client can be used for instantiation and maintaining one or multiple order books for Spot trading on the Kraken cryptocurrency exchange. It uses websockets to subscribe to book feeds and receives book updates, calculates the checksum and will publish the raw message to the on_book_update() function or to the specified callback function.

get() can be used to access a specific book of this client - they will always be up-to date when used from within on_book_update().

The client will resubscribe to the book feed(s) if any errors occur and publish the changes to the mentioned function(s). This is required to compute the correct checksum internally.

This class has a default book depth of 10. Available depths are: 10, 25, 50, 100, 500, 1000. This client can handle multiple books - but only for one depth. When subscribing to books with different depths, please use separate instances of this class.

• https://docs.kraken.com/websockets-v2/#calculate-book-checksum

Example: Create and maintain a Spot orderbook as custom class

from typing import Any
from kraken.spot import OrderbookClientV2
import asyncio

class OrderBook(OrderbookClientV2):
    async def on_book_update(self: "OrderBook", pair: str, message:
    list) -> None:
        '''This function must be overloaded to get the recent updates.'''
        book: dict[str, Any] = self.get(pair=pair) bid:s
        list[tuple[str, str]] = list(book["bid"].items()) ask:
        list[tuple[str, str]] = list(book["ask"].items())

        print("Bid         Volume                Ask         Volume") for level in
        range(self.depth):
            print(
                f"{bid[level][0]} ({bid[level][1]})      {ask[level][0]}
                ({ask[level][1]})"
            )

async def main() -> None:
    orderbook: OrderBook = OrderBook(depth=10) await orderbook.add_book(
        pairs=["XBT/USD"]  # we can also subscribe to more currency
        pairs
    )

    while not orderbook.exception_occur:
        await asyncio.sleep(10)

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        pass

Example: Create and maintain a Spot orderbook using a callback

from typing import Any
from kraken.spot import OrderbookClientV2
import asyncio

async def my_callback(self: "OrderBook", pair: str, message: dict) -> None:
    '''This function do not need to be async.'''
    print(message)

async def main() -> None:
    orderbook: OrderBook = OrderBook(depth=100, callback=my_callback)
    await orderbook.add_book(
        pairs=["XBT/USD"]  # we can also subscribe to more currency
        pairs
    )

    while not orderbook.exception_occur:
        await asyncio.sleep(10)

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        pass

async add_book(pairs: list[str]) → None

Add an orderbook to this client. The feed will be subscribed and updates will be published to the on_book_update() function.

Parameters:

• pairs (list[str]) – The pair(s) to subscribe to

• depth (int) – The book depth

property depth: int

Return the fixed depth of this orderbook client.

property exception_occur: bool

Can be used to determine if any critical error occurred within the websocket connection. If so, the function will return True and the client instance is most likely not usable anymore. So this is the switch lets the user know, when to delete the current one and create a new one.

Returns:

True if any critical error occurred else False

Return type:

bool

get(pair: str) → dict | None

Returns the orderbook for a specific pair.

Parameters:

pair (str) – The pair to get the orderbook from

Returns:

The orderbook of that pair.

Return type:

dict

static get_first(values: tuple) → float

This function is used as callback for the sorted method to sort a tuple/list by its first value and while ensuring that the values are floats and comparable.

Parameters:

values (tuple) – A tuple of string values

Returns:

The first value of values as float.

Return type:

float

async on_book_update(pair: str, message: dict) → None

This function will be called every time the orderbook gets updated. It needs to be overloaded if no callback function was defined during the instantiation of this class.

Parameters:

• pair (str) – The currency pair of the orderbook that has been updated.

• message (dict) – The book message sent by Kraken

async on_message(message: list | dict) → None

This function must not be overloaded - it would break this client!

It receives and processes the book related websocket messages and is only publicly visible for those who understand and are willing to mock it.

async remove_book(pairs: list[str]) → None

Unsubscribe from a subscribed orderbook.

Parameters:

• pairs (list[str]) – The pair(s) to unsubscribe from

• depth (int) – The book depth

class kraken.spot.OrderbookClientV1(depth: int = 10, callback: Callable | None = None)

Bases: object

This client is using the Kraken Websocket API v1

Please use kraken.spot.OrderbookClientV2 to access the Kraken Websocket API v2.

The orderbook client can be used for instantiation and maintaining one or multiple orderbooks for Spot trading on the Kraken cryptocurrency exchange. It connects to the websocket feed(s) and receives the book updates, calculates the checksum and will publish the changes to the on_book_update() function or to the specified callback function.

The get() function can be used to access a specific book of this client.

The client will resubscribe to the book feed(s) if any errors occur and publish the changes to the mentioned function(s).

This class has a fixed book depth. Available depths are: {10, 25, 50, 100}

• https://support.kraken.com/hc/en-us/articles/360027821131-WebSocket-API-v1-How-to-maintain-a-valid-order-book

• https://docs.kraken.com/websockets/#book-checksum

Example: Create and maintain a Spot orderbook as custom class

from typing import Any
from kraken.spot import OrderbookClientV1
import asyncio

class OrderBook(OrderbookClientV1):
    async def on_book_update(self: "OrderBook", pair: str, message: list) -> None:
        '''This function must be overloaded to get the recent
        updates.''' book: Dict[str, Any] = self.get(pair=pair) bid:
        list[tuple[str, str]] = list(book["bid"].items()) ask:
        list[tuple[str, str]] = list(book["ask"].items())

        print("Bid         Volume                Ask         Volume") for level in
        range(self.depth):
            print(
                f"{bid[level][0]} ({bid[level][1]})      {ask[level][0]}
                ({ask[level][1]})"
            )

async def main() -> None:
    orderbook: OrderBook = OrderBook(depth=10) await orderbook.add_book(
        pairs=["XBT/USD"]  # we can also subscribe to more currency
        pairs
    )

    while not orderbook.exception_occur:
        await asyncio.sleep(10)

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        pass

Example: Create and maintain a Spot orderbook using a callback

from typing import Any
from kraken.spot import OrderbookClientV1
import asyncio

# … use the Orderbook class defined in the example before
async def my_callback(self: "OrderBook", pair: str, message: list) -> None:
    '''This function do not need to be async.''' print(message)

async def main() -> None:
    orderbook: OrderBook = OrderBook(depth=100, callback=my_callback)
    await orderbook.add_book(
        pairs=["XBT/USD"]  # we can also subscribe to more currency
        pairs
    )

    while not orderbook.exception_occur:
        await asyncio.sleep(10)

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        pass

async add_book(pairs: list[str]) → None

Add an orderbook to this client. The feed will be subscribed and updates will be published to the on_book_update() function.

Parameters:

• pairs (list[str]) – The pair(s) to subscribe to

• depth (int) – The book depth

property depth: int

Return the fixed depth of this orderbook client.

property exception_occur: bool

Can be used to determine if any critical error occurred within the websocket connection. If so, the function will return True and the client instance is most likely not usable anymore. So this is the switch lets the user know, when to delete the current one and create a new one.

Returns:

True if any critical error occurred else False

Return type:

bool

get(pair: str) → dict | None

Returns the orderbook for a specific pair.

Parameters:

pair (str) – The pair to get the orderbook from

Returns:

The orderbook of that pair.

Return type:

dict

OrderbookClientV1: Get ask and bid

# …
class Orderbook(OrderbookClientV1):

    async def on_book_update(
        self: "Orderbook",
        pair: str,
        message: list
    ) -> None:
        book: dict[str, Any] = self.get(pair="XBT/USD")
        ask: list[tuple[str, str]] = list(book["ask"].items())
        bid: list[tuple[str, str]] = list(book["bid"].items())
        # ask and bid are now in format [price, (volume, timestamp)]
        # … and include the whole orderbook

static get_first(values: tuple) → float

This function is used as callback for the sorted method to sort a tuple/list by its first value and while ensuring that the values are floats and comparable.

Parameters:

values (tuple) – A tuple of string values

Returns:

The first value of values as float.

Return type:

float

async on_book_update(pair: str, message: list) → None

This function will be called every time the orderbook gets updated. It needs to be overloaded if no callback function was defined during the instantiation of this class.

Parameters:

• pair (str) – The currency pair of the orderbook that has been updated.

• message (str) – The message sent by Kraken causing the orderbook to update.

async on_message(message: list | dict) → None

This function should not be overloaded - this would break this client!

It receives and processes the book related websocket messages and is only publicly visible for those who understand and are willing to mock it.

async remove_book(pairs: list[str]) → None

Unsubscribe from a subscribed orderbook.

Parameters:

• pairs (list[str]) – The pair(s) to unsubscribe from

• depth (int) – The book depth