Skip to content

WebSocket Client

Async WebSocket connection manager for Kraken WS v2.

Classes:

  • TradingError –

    Raised when a trading method request is rejected by the server.

  • KrakenWSClient –

    Async WebSocket client for Kraken WS v2.

TradingError

Bases: Exception

Raised when a trading method request is rejected by the server.

KrakenWSClient

Async WebSocket client for Kraken WS v2.

Manages a single WebSocket connection with heartbeat monitoring, client-initiated pings, automatic reconnection, and system status tracking.

Usage::

async with KrakenWSClient() as client:
    msg = await client.receive()

Parameters:

  • url (str, default: 'wss://ws.kraken.com/v2' ) –

    WebSocket endpoint URL.

  • ping_interval (float, default: 10.0 ) –

    Seconds between client pings.

  • ping_timeout (float, default: 10.0 ) –

    Max seconds to wait for pong response.

  • heartbeat_timeout (float, default: 30.0 ) –

    Max silence before triggering reconnect.

  • backoff_base (float, default: 0.5 ) –

    Base delay for exponential backoff.

  • backoff_max (float, default: 30.0 ) –

    Maximum backoff delay.

  • max_reconnect_attempts (int, default: 10 ) –

    Max reconnect retries (0 = disabled).

Methods:

  • connect –

    Open the WebSocket connection and start background tasks.

  • disconnect –

    Cleanly shut down the connection and background tasks.

  • send –

    Serialize and send a request message.

  • receive –

    Get the next typed message from the queue.

  • subscribe –

    Subscribe to a channel.

  • unsubscribe –

    Unsubscribe from a channel.

  • add_order –

    Place a single order.

  • amend_order –

    Amend an order in-place (preserves queue priority).

  • edit_order –

    Edit an order (cancel-and-replace, new order_id).

  • cancel_order –

    Cancel one or more orders.

  • cancel_all –

    Cancel all open orders.

  • cancel_all_orders_after –

    Set/refresh/disable the dead man's switch.

  • batch_add –

    Place 2-15 orders on a single pair.

  • batch_cancel –

    Cancel 2-50 orders.

  • __aiter__ –

    Allow async for msg in client: iteration.

  • __anext__ –

    Yield the next message, stopping when disconnected and drained.

Attributes:

  • state (ConnectionState) –

    Current connection state (read-only).

  • system_status (str | None) –

    Latest system status from the status channel.

  • connection_id (int | None) –

    Connection ID from the status channel.

  • book_manager (OrderBookManager) –

    Access the order book manager for reading book state.

  • subscriptions (dict[tuple[tuple[str, Any], ...], SubscriptionEntry]) –

    Currently tracked subscriptions (read-only copy).

state property 

state

Current connection state (read-only).

system_status property 

system_status

Latest system status from the status channel.

connection_id property 

connection_id

Connection ID from the status channel.

book_manager property 

book_manager

Access the order book manager for reading book state.

subscriptions property 

subscriptions

Currently tracked subscriptions (read-only copy).

connect async 

connect()

Open the WebSocket connection and start background tasks.

Raises:

  • RuntimeError –

    If already connected or connecting.

disconnect async 

disconnect()

Cleanly shut down the connection and background tasks.

send async 

send(msg)

Serialize and send a request message.

Parameters:

  • msg (WSRequest) –

    The request envelope to send.

Raises:

  • RuntimeError –

    If not connected.

receive async 

receive()

Get the next typed message from the queue.

Blocks until a message is available.

subscribe async 

subscribe(params)

Subscribe to a channel.

Parameters:

  • params (SubscriptionParams) –

    Typed subscription parameters.

Returns:

  • WSResponse –

    The server's success response.

Raises:

  • SubscriptionError –

    If the server rejects the subscription.

  • TimeoutError –

    If no response within request_timeout.

  • RuntimeError –

    If not connected.

unsubscribe async 

unsubscribe(params)

Unsubscribe from a channel.

Parameters:

  • params (SubscriptionParams) –

    Typed subscription parameters (must match a tracked sub).

Returns:

  • WSResponse –

    The server's success response.

Raises:

  • KeyError –

    If no matching subscription is tracked.

  • SubscriptionError –

    If the server rejects the unsubscribe.

  • TimeoutError –

    If no response within request_timeout.

  • RuntimeError –

    If not connected.

add_order async 

add_order(params)

Place a single order.

Raises:

amend_order async 

amend_order(params)

Amend an order in-place (preserves queue priority).

Raises:

edit_order async 

edit_order(params)

Edit an order (cancel-and-replace, new order_id).

Raises:

cancel_order async 

cancel_order(params)

Cancel one or more orders.

Raises:

cancel_all async 

cancel_all(params)

Cancel all open orders.

Raises:

cancel_all_orders_after async 

cancel_all_orders_after(params)

Set/refresh/disable the dead man's switch.

Send timeout > 0 to set or refresh the timer. Send timeout = 0 to disable it.

Raises:

batch_add async 

batch_add(params)

Place 2-15 orders on a single pair.

Raises:

batch_cancel async 

batch_cancel(params)

Cancel 2-50 orders.

Raises:

__aiter__ 

__aiter__()

Allow async for msg in client: iteration.

__anext__ async 

__anext__()

Yield the next message, stopping when disconnected and drained.