Base Clients and Internals

The following classes and data structures are listed for completeness. Please avoid using them since these are internals and may change without any warning.

They are the base classes for Spot and Futures REST and websocket clients.

class kraken.base_api.SpotClient(key: str = '', secret: str = '', url: str = '', proxy: str | None = None, *, use_custom_exceptions: bool = True)

Bases: object

This class is the base for all Spot clients, handles un-/signed requests and returns exception handled results.

If you are facing timeout errors on derived clients, you can make use of the TIMEOUT attribute to deviate from the default 10 seconds.

Kraken sometimes rejects requests that are older than a certain time without further information. To avoid this, the session manager creates a new session every 5 minutes.

Parameters:

  • key (str, optional) – Spot API public key (default: "")

  • secret (str, optional) – Spot API secret key (default: "")

  • url (str, optional) – URL to access the Kraken API (default: https://api.kraken.com)

  • proxy (str, optional) – proxy URL, may contain authentication information

get_nonce() → str

Return a new nonce

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) → dict[str, Any] | list[str] | list[dict[str, Any]] | Response

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)

  • extra_params (str | dict, optional) – Additional 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 | requests.Response

property return_unique_id: str

Returns a unique uuid string

Returns:

uuid

Return type:

str

class kraken.base_api.SpotAsyncClient(key: str = '', secret: str = '', url: str = '', proxy: str | None = None, *, use_custom_exceptions: bool = True)

Bases: SpotClient

This class provides the base client for accessing the Kraken Spot and NFT API using asynchronous requests.

If you are facing timeout errors on derived clients, you can make use of the TIMEOUT attribute to deviate from the default 10 seconds.

Kraken sometimes rejects requests that are older than a certain time without further information. To avoid this, the session manager creates a new session every 5 minutes.

Parameters:

  • key (str, optional) – Spot API public key (default: "")

  • secret (str, optional) – Spot API secret key (default: "")

  • url (str, optional) – URL to access the Kraken API (default: https://api.kraken.com)

  • proxy (str, optional) – proxy URL, may contain authentication information

async_close() → None

Closes the aiohttp session

async close() → None

Closes the aiohttp session

get_nonce() → str

Return a new nonce

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

class kraken.base_api.FuturesClient(key: str = '', secret: str = '', url: str = '', proxy: str | None = None, *, sandbox: bool = False, use_custom_exceptions: bool = True)

Bases: object

The base class for all Futures clients handles un-/signed requests and returns exception handled results.

If you are facing timeout errors on derived clients, you can make use of the TIMEOUT attribute to deviate from the default 10 seconds.

If the sandbox environment is chosen, the keys must be generated from here:

https://demo-futures.kraken.com/settings/api

Kraken sometimes rejects requests that are older than a certain time without further information. To avoid this, the session manager creates a new session every 5 minutes.

Parameters:

  • key (str, optional) – Futures API public key (default: "")

  • secret (str, optional) – Futures API secret key (default: "")

  • url (str, optional) – The URL to access the Futures Kraken API (default: https://futures.kraken.com)

  • sandbox (bool, optional) – If set to True the URL will be https://demo-futures.kraken.com (default: False)

  • proxy (str, optional) – proxy URL, may contain authentication information

get_nonce() → str

Return a new nonce

request(method: str, uri: str, post_params: dict | None = None, query_params: dict | None = None, timeout: int = 10, *, auth: bool = True, return_raw: bool = False, extra_params: str | dict | None = None) → dict | list | Response

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, and PUT

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

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

  • extra_params (str | dict, optional) – Additional query parameter of the request (default: None)

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

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

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

  • 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.

Raises:

kraken.exceptions.* – If the response contains errors

Returns:

The response

Return type:

dict | list | requests.Response

class kraken.base_api.FuturesAsyncClient(key: str = '', secret: str = '', url: str = '', proxy: str | None = None, *, sandbox: bool = False, use_custom_exceptions: bool = True)

Bases: FuturesClient

This class provides the base client for accessing the Kraken Futures API using asynchronous requests.

If you are facing timeout errors on derived clients, you can make use of the TIMEOUT attribute to deviate from the default 10 seconds.

If the sandbox environment is chosen, the keys must be generated from here:

https://demo-futures.kraken.com/settings/api

Parameters:

  • key (str, optional) – Futures API public key (default: "")

  • secret (str, optional) – Futures API secret key (default: "")

  • url (str, optional) – The URL to access the Futures Kraken API (default: https://futures.kraken.com)

  • proxy (str, optional) – proxy URL, may contain authentication information

  • sandbox (bool, optional) – If set to True the URL will be https://demo-futures.kraken.com (default: False)

async_close() → None

Closes the aiohttp session

async close() → None

Closes the aiohttp session

get_nonce() → str

Return a new nonce

async request(method: str, uri: str, post_params: dict | None = None, query_params: dict | None = None, timeout: int = 10, *, auth: bool = True, return_raw: bool = False) → dict | list | aiohttp.ClientResponse | Awaitable

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, and PUT

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

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

  • extra_params (str | dict, optional) – Additional query parameter of the request (default: None)

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

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

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

  • 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.

Raises:

kraken.exceptions.* – If the response contains errors

Returns:

The response

Return type:

dict | list | requests.Response

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

Bases: SpotAsyncClient

This is the base class for kraken.spot.SpotWSClient. It extends the REST API base class and is used to provide the base functionalities that are used for Kraken Websocket API v2.

This is an internal class and should not be used outside.

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)

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.

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]

This function must be overloaded and return a list of names that can be subscribed to (for authenticated connections).

property public_channel_names: list[str]

This function must be overloaded and return a list of names that can be subscribed to (for unauthenticated connections).

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(*args: Any, **kwargs: Any) → None

This functions must be overloaded and should be used to send messages via the websocket connection(s).

async start() → None

Method to start the websocket connection.

stop() → None

Method to stop the websocket connection.

async subscribe(*args: Any, **kwargs: Any) → None

This function must be overloaded and should be used to subscribe to websocket channels/feeds.

async unsubscribe(*args: Any, **kwargs: Any) → None

This function must be overloaded and should be used to unsubscribe from websocket channels/feeds.

class kraken.spot.websocket.connectors.ConnectSpotWebsocket(client: SpotWSClientBase, endpoint: str, callback: Callable | None, *, is_auth: bool = False)

Bases: ConnectSpotWebsocketBase

This class extends the kraken.spot.websocket.connectors.ConnectSpotWebsocketBase and can be instantiated to create and maintain a websocket connection using the Kraken Websocket API v2.

This is an internal class and should not be used outside.

Parameters:

  • client (kraken.spot.SpotWSClientBase) – The websocket client that wants to connect

  • endpoint (str) – The websocket endpoint

  • callback (function) – Callback function that receives the websocket messages

  • is_auth (bool, optional) – If the websocket connects to endpoints that require authentication (default: False)

property client: SpotWSClientBase

Return the websocket client

async close_connection() → None

Closes the websocket connection and thus forces a reconnect

property is_auth: bool

Returns True if the connection can access privat endpoints

async send_ping() → None

Sends ping to Kraken

async start() → None

Starts the websocket connection

async stop() → None

Stops the websocket connection

property subscriptions: list[dict]

Returns a copy of active subscriptions