Spot Websockets¶

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

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.
rest_url (str, optional) – Set a specific REST URL to access the Kraken Spot API (default: None).
ws_url (str, optional) – Set a specific Websocket URL to access the Kraken Spot API (default: None).
auth_ws_url – Set a specific Authenticated Websocket URL to access the Kraken Spot API (default: None).

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

HowTo: How to connect to other Kraken instances¶

client_auth = SpotWSClient(
    key="api-key",
    secret="secret-key",
    rest_url="https://api.vip.uat.lobster.kraken.com",
    ws_url="wss://ws.vip.uat.lobster.kraken.com",
    auth_ws_url="wss://ws-auth.vip.uat.lobster.kraken.com",
)

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_close() → None¶: Closes the aiohttp session

async close() → None¶: Method to close the websocket connection.

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/api/docs/guides/spot-ws-auth

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.

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
amend_order <https://docs.kraken.com/api/docs/websocket-v2/amend_order>`_
cancel_order
cancel_all
cancel_all_orders_after
batch_order
batch_cancel
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:

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/api/docs/websocket-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/api/docs/websocket-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/api/docs/websocket-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/api/docs/websocket-v2/cancel_all).

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/api/docs/websocket-v2/cancel_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/api/docs/websocket-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/api/docs/websocket-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.

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.

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.

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 Crypto Asset 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/api/docs/guides/spot-ws-book-v1

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_close() → None¶: Closes the aiohttp session

async close() → None¶: Method to close the websocket connection.

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/api/docs/guides/spot-ws-auth

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.

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
amend_order <https://docs.kraken.com/api/docs/websocket-v2/amend_order>`_
cancel_order
cancel_all
cancel_all_orders_after
batch_order
batch_cancel
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:

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

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.

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

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/api/docs/websocket-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/api/docs/websocket-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/api/docs/websocket-v2/cancel_all).

Spot Websocket: Cancel all orders¶

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

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/api/docs/websocket-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/api/docs/websocket-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.

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.

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.

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"]}
... )