Spot Websockets

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

Bases: SpotWSClientBase

This client only supports the Kraken Websocket API v2.

Class to access public and private/authenticated websocket connections.

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

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.SpotWSClient.subscribe() and kraken.spot.SpotWSClientV.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

import asyncio
from kraken.spot import SpotWSClient


class Client(SpotWSClient):

    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"
    )
    # open the websocket connections
    await client.start()
    await auth_client.start()

    # 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 as instance

import asyncio
from kraken.spot import SpotWSClient


async def on_message(message):
    print(message)

async def main():

    client = SpotWSClient(callback=on_message)
    await client.start()
    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 as context manager

import asyncio
from kraken.spot import SpotWSClient

async def on_message(message):
    print(message)

async def main():
    async with SpotWSClient(
        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]

Returns the active private subscriptions

Returns:

List of active private subscriptions

Return type:

list[dict]

Raises:

ConnectionError – If there is no active private connection

property active_public_subscriptions: list[dict]

Returns the active public subscriptions

Returns:

List of active public subscriptions

Return type:

list[dict]

Raises:

ConnectionError – If there is no active public connection.

async async_close() → None

Closes the aiohttp session

property exception_occur: bool

Returns True if any connection was stopped due to an exception.

get_nonce() → str

Return a new nonce

async 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.SpotWSClient 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.

Override this property if the exchange supports additional private channels.

• executions

• balances

• level3

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.

Override this property if the exchange supports additional public channels.

The available public channels are listed below:

• book

• instrument

• ohlc

• ticker

• trade

Returns:

List of available public channel names

Return type:

list[str]

async request(method: str, uri: str, params: dict | None = None, timeout: int = 10, *, auth: bool = True, do_json: bool = False, return_raw: bool = False, query_str: str | None = None, extra_params: str | dict | None = None) → Coroutine

Handles the requested requests, by sending the request, handling the response, and returning the message or in case of an error the respective Exception.

Parameters:

• method (str) – The request method, e.g., GET, POST, PUT, …

• uri (str) – The endpoint to send the message

• auth (bool) – If the requests needs authentication (default: True)

• params (dict, optional) – The query or post parameter of the request (default: None)

• timeout (int) – Timeout for the request (default: 10)

• do_json (bool) – If the params must be “jsonified” - in case of nested dict style

• return_raw (bool, optional) – If the response should be returned without parsing. This is used for example when requesting an export of the trade history as .zip archive.

• query_str (str, optional) – Add custom values to the query /0/public/Nfts?filter%5Bcollection_id%5D=NCQNABO-XYCA7-JMMSDF&page_size=10

Raises:

kraken.exceptions.KrakenException.* – If the response contains errors

Returns:

The response

Return type:

dict | list | aiohttp.ClientResponse

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.SpotWSClient.send_message() function. The client must be instantiated as described in kraken.spot.SpotWSClient 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: 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: 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: 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: 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 fuck-ups 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: 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: 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: 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.SpotWSClient.subscribe() instead.

Spot Websocket: Subscribe to a websocket feed

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

async start() → None

Method to start the websocket connection.

async stop() → None

Method to stop the websocket connection.

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.SpotWSClient to run the following example:

Spot Websocket: 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 un-subscription message (only the params part)

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

Spot Websocket: Unsubscribe from a websocket feed

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

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

Bases: SpotWSClient

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 SpotOrderBookClient
import asyncio

class OrderBook(SpotOrderBookClient):
    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.start()

    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 SpotOrderBookClient
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.start()

    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

property active_private_subscriptions: list[dict]

Returns the active private subscriptions

Returns:

List of active private subscriptions

Return type:

list[dict]

Raises:

ConnectionError – If there is no active private connection

property active_public_subscriptions: list[dict]

Returns the active public subscriptions

Returns:

List of active public subscriptions

Return type:

list[dict]

Raises:

ConnectionError – If there is no active public connection.

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

async async_close() → None

Closes the aiohttp session

property depth: int

Return the fixed depth of this orderbook client.

property exception_occur: bool

Returns True if any connection was stopped due to an exception.

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

get_nonce() → str

Return a new nonce

async 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_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.

property private_channel_names: list[str]

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

Override this property if the exchange supports additional private channels.

• executions

• balances

• level3

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.

Override this property if the exchange supports additional public channels.

The available public channels are listed below:

• book

• instrument

• ohlc

• ticker

• trade

Returns:

List of available public channel names

Return type:

list[str]

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

async request(method: str, uri: str, params: dict | None = None, timeout: int = 10, *, auth: bool = True, do_json: bool = False, return_raw: bool = False, query_str: str | None = None, extra_params: str | dict | None = None) → Coroutine

Handles the requested requests, by sending the request, handling the response, and returning the message or in case of an error the respective Exception.

Parameters:

• method (str) – The request method, e.g., GET, POST, PUT, …

• uri (str) – The endpoint to send the message

• auth (bool) – If the requests needs authentication (default: True)

• params (dict, optional) – The query or post parameter of the request (default: None)

• timeout (int) – Timeout for the request (default: 10)

• do_json (bool) – If the params must be “jsonified” - in case of nested dict style

• return_raw (bool, optional) – If the response should be returned without parsing. This is used for example when requesting an export of the trade history as .zip archive.

• query_str (str, optional) – Add custom values to the query /0/public/Nfts?filter%5Bcollection_id%5D=NCQNABO-XYCA7-JMMSDF&page_size=10

Raises:

kraken.exceptions.KrakenException.* – If the response contains errors

Returns:

The response

Return type:

dict | list | aiohttp.ClientResponse

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.SpotWSClient.send_message() function. The client must be instantiated as described in kraken.spot.SpotWSClient 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: 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: 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: 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: 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 fuck-ups 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: 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: 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: 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.SpotWSClient.subscribe() instead.

Spot Websocket: Subscribe to a websocket feed

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

async start() → None

Method to start the websocket connection.

async stop() → None

Method to stop the websocket connection.

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.SpotWSClient to run the following example:

Spot Websocket: 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 un-subscription message (only the params part)

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

Spot Websocket: Unsubscribe from a websocket feed

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