Module hyperliquid 

Hyperliquid ExecutionClient implementations for perpetual futures and spot trading.

Uses the official hyperliquid_rust_sdk crate for REST and WebSocket API access. Gated behind the “hyperliquid” feature flag.

Modules

• HyperliquidClient: Perpetual futures client
• spot::HyperliquidSpotClient: Spot trading client

Authentication

Hyperliquid uses EVM-based authentication (Ethereum private key + EIP-712 signatures) instead of traditional API key/secret. The SDK handles all signing internally.

Architecture

• REST (InfoClient): account_snapshot, fetch_balances, fetch_open_orders, fetch_trades. fetch_trades posts to /info through the SDK’s HTTP client but parses the response into common::UserFill rather than the SDK’s type, which drops tid and feeToken.
• REST (ExchangeClient): open_order, cancel_order
• WebSocket (InfoClient with with_reconnect): account_stream via UserFills + OrderUpdates subscriptions

SDK Delegation Model

This client delegates connection management to the official hyperliquid_rust_sdk:

Responsibility	Implementation
Reconnection	InfoClient::with_reconnect() handles WebSocket reconnection automatically
Heartbeat	SDK manages WebSocket ping/pong internally
Deduplication	This client’s own, on the fills stream. See below.
Fill recovery	Not implemented — use ExecutionClient::fetch_trades after reconnect if needed

Caller responsibilities:

• If fill recovery is critical, monitor for reconnection events and call fetch_trades()
• REST clients (InfoClient::new(), ExchangeClient::new()) do NOT auto-reconnect; only WebSocket streams via with_reconnect() do

Trade identity and duplicate fills

A Trade’s id is the venue’s tid, which identifies the fill. It is deliberately not hash, which identifies the transaction: one aggressive order sweeping several resting orders produces several fills under a single hash, and keying on the hash makes them indistinguishable. Hyperliquid documents tid as unique per fill but qualified by coin rather than globally, so callers reconciling across instruments should qualify it the same way.

The fills subscription opens with a snapshot of recent fills and the SDK resubscribes on every reconnect, so the same fill is redelivered each time the socket comes back. A trade is a delta the consumer accumulates, so this client deduplicates the stream itself — the cache is scoped to one ExecutionClient::account_stream call and survives reconnects within it.

Order updates are deliberately not deduplicated. They assert absolute state rather than a delta, so a replayed one is idempotent while a dropped one could strand a consumer on stale state.

ExecutionClient::fetch_trades does not deduplicate: it answers the window it was asked for, and its results reach the caller rather than the stream. A caller feeding both into one consumer should expect overlap and reconcile on the trade id.

Conditional Orders (Stop, TakeProfit)

Hyperliquid supports conditional (trigger) orders via the ClientOrder::Trigger variant.

Supported order kinds:

• Stop → market order triggered at stop price (tpsl: "sl", is_market: true)
• StopLimit → limit order triggered at stop price (tpsl: "sl", is_market: false)
• TakeProfit → market order triggered at take-profit price (tpsl: "tp", is_market: true)
• TakeProfitLimit → limit order triggered at take-profit price (tpsl: "tp", is_market: false)

Unsupported: TrailingStop, TrailingStopLimit (Hyperliquid does not support trailing stops)

UUID requirement: Trigger orders MUST use ClientOrderId::uuid() for the client order ID. The SDK’s cancel_by_cloid() requires a valid UUID. Non-UUID client IDs will be rejected at order placement with a clear error message.

SDK limitations (hyperliquid_rust_sdk 0.6.x):

• fetch_open_orders: Returns OpenOrdersResponse which lacks trigger fields (is_trigger, trigger_px). All orders appear as OrderKind::Limit.
• account_stream (WebSocket): OrderUpdate uses BasicOrder which also lacks trigger fields. Downstream consumers should correlate orders by cloid and track OrderKind from the placement response.

Limitations

• Price precision: Hyperliquid requires 5 significant figures for prices

Re-exports

pub use config::HyperliquidConfig;

pub use config::HyperliquidConfigError;

Modules

common

Shared utilities for Hyperliquid execution clients (perps and spot).

config

Configuration for the Hyperliquid execution client.

error

Error mapping for Hyperliquid SDK errors to rustrade-execution error types.

spot

Hyperliquid spot trading ExecutionClient implementation.

Structs

HyperliquidClient

Hyperliquid perpetual futures execution client.