Transport

hl.BaseTransport

Bases: ABC

Abstract base class for transport implementations.

BaseTransport defines the interface for all transport mechanisms used to communicate with the Hyperliquid API. Transport classes handle the low-level details of sending requests and receiving responses, abstracting away the underlying communication protocol (HTTP, WebSocket, etc.).

Note: This is an internal class. Users typically don't interact with transport classes directly - they are used internally by Info and Exchange classes.

Examples:

Create an API instance and use the HttpTransport to make a request:

>>> api = await Api.create(address="0x...", secret_key="0x...")
... # HttpTransport is used internally by api.info and api.exchange
... response = await api.info.all_mids()  # Uses HttpTransport.invoke()

Methods:

Name	Description
invoke	Send a request payload and return the response.

invoke abstractmethod async

invoke(
    payload: Any, validators: list[Rule] | None = None
) -> Result[Any, ApiError]

Send a request payload and return the response.

This is the core method that all transport implementations must provide. It handles sending the payload to the appropriate endpoint and returning the parsed response, optionally applying validation.

Parameters:

Name	Type	Description	Default
payload	Any	The request payload to send.	required
validators	list[Rule] | None	Optional validation functions that will be called on successful responses. The validators should return the validated/transformed response or raise an exception if validation fails. Raised exceptions will be caught and converted to Result.err().	None

Returns:

Type	Description
Result[Any, ApiError]	Result[Any, ApiError]: A Result containing either the validated response or an error (transport error, HTTP error, or validation error).

hl.HttpTransport

HttpTransport(
    network: Network, endpoint: Literal["info", "exchange"]
)

Bases: BaseTransport

HTTP transport implementation for request-response communication.

HttpTransport handles communication over HTTP connections using POST requests to the Hyperliquid API endpoints. This is the primary transport mechanism for most API operations including trading, account management, and data retrieval.

Note: This is an internal class. Users typically don't create HttpTransport instances directly - they are created automatically by the Api class.

Attributes:

Name	Type	Description
network		The network to use.
url		The complete URL for the target endpoint.
endpoint	Literal['info', 'exchange']	The API endpoint to target ("info" or "exchange").

Creates an HTTP client configured for optimal communication with the Hyperliquid API, including HTTP/2 support and proper headers.

Parameters:

Name	Type	Description	Default
network	Network	The network to use.	required
endpoint	Literal['info', 'exchange']	The API endpoint to target.	required

Note

The HTTP client is automatically cleaned up when this transport instance is garbage collected, ensuring proper resource management.

Methods:

Name	Description
invoke	Send an HTTP POST request with the given payload.

invoke async

invoke(
    payload: Any, validators: list[Rule] | None = None
) -> Result[Any, ApiError]

Send an HTTP POST request with the given payload.

Performs a POST request to the configured endpoint with the payload serialized as JSON. Handles response parsing and error checking.

Parameters:

Name	Type	Description	Default
payload	Any	The payload to send as JSON. If None, an empty dictionary will be sent. Defaults to None.	required
validators	list[Rule] | None	Optional validation functions that will be called on successful responses. The validators should return an error if validation fails otherwise return None. Returned errors will be converted to Result.err().	None

Returns:

Type	Description
Result[Any, ApiError]	Result[Any, ApiError]: A Result containing either the validated response or an error (transport error, HTTP error, or validation error).

Note

If JSON parsing fails, returns an UnexpectedSchemaError.

hl.WsTransport

WsTransport(network: Network)

Bases: BaseTransport

Client for the Hyperliquid websocket API.

Parameters:

Name	Type	Description	Default
network	Network	The network to use.	required

Methods:

Name	Description
invoke	Send a request to the websocket API.
post	Send an info or exchange request to the websocket API.
run	Run the websocket client as a task until context exits.
run_forever	Run the websocket manager main loop forever or until it is cancelled.
subscribe	Subscribe to a data stream using the websocket.
unsubscribe	Unsubscribe from a data stream using the websocket.

invoke async

invoke(
    payload: Any, validators: list[Rule] | None = None
) -> Result[Any, ApiError]

Send a request to the websocket API.

Parameters:

Name	Type	Description	Default
payload	dict	The payload to send to the websocket API.	required
validators	list[Rule] | None	The validators to apply to the response.	None

post async

post(
    endpoint: Literal["info", "exchange"], request: Any
) -> Any

Send an info or exchange request to the websocket API.

These requests are normally sent as an HTTP POST request to the /info or /exchange endpoints, but can also be sent via the websocket.

Parameters:

Name	Type	Description	Default
endpoint	Literal['info', 'exchange']	The endpoint to send the request to.	required
request	Any	The request to send.	required

Returns:

Name	Type	Description
Any	Any	The response from the websocket API.

run async

run() -> AsyncGenerator[None, None]

Run the websocket client as a task until context exits.

run_forever async

run_forever() -> None

Run the websocket manager main loop forever or until it is cancelled.

subscribe async

subscribe(
    subscription: Subscription,
    message_queue: Queue[T_Msg] | None = None,
) -> tuple[int, Queue[T_Msg]]

Subscribe to a data stream using the websocket.

Parameters:

Name	Type	Description	Default
subscription	Subscription	The details of what data to subscribe to.	required
message_queue	Queue | None	The queue to send received messages to. If None, a new queue will be created. The queue will be returned to the caller.	None

Returns:

Type	Description
tuple[int, Queue[T_Msg]]	tuple[int, asyncio.Queue]: A tuple containing the subscription ID and the message queue that will receive messages from the subscription. The subscription ID can be used to unsubscribe.

unsubscribe async

unsubscribe(subscription_id: int) -> None

Unsubscribe from a data stream using the websocket.

Parameters:

Name	Type	Description	Default
subscription_id	int	The subscription ID returned by :method:subscribe.	required