This module implements the websocket handler.

class web3data.handlers.websocket.WebsocketHandler(api_key: str, blockchain_id: str, url: str = None)[source]

Bases: object

The subhandler for websocket-related queries.


A user-defined handler for websocket close events.


ws – The websocket client instance

on_error(ws, error)[source]

A user-defined handler for websocket errors.

  • ws – The websocket client instance

  • error – The error message


A user-defined handler for websocket open events.


ws – The websocket client instance

register(params: Union[Iterable[str], str], callback=None)[source]

Register a new event to listen for and its callback.

This will subscribe to the given event identifiers and execute the provided callback function once the specified event is coming in. Please note that the listening and callback-handling routine only starts once the websocket client is running.

The callback function should take two parameters: ws and message. The first parameter is the websocket client instance, which allows the user to update the client context. The latter argiment is the message, deserialized from the JSON object received by the websocket server.

  • params – The event to subscribe to

  • callback – The callback function to execute


Run the websocket listening loop.

This is a blocking endless loop that will send the subscription events to the websocket server, handle the responses, and then distribute the incoming messages across the registered callbacks.

Any keyword arguments passed to this method are passed on to the websocket client’s run_forever method. Please consult the project’s documentation for more details: https://pypi.org/project/websocket_client/


kwargs – Additional arguments to pass to the websocket client


Unregister a subscription from the websocket server.

Given an external ID (i.e. the subscription ID), this will remove the subscription data including locally stored payloads and identifiers. It will also trigger an unsubscribe message for the subscription being sent to the websocket server.


external_id – The subscription ID to remove