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.

Client order ids

Every order must be placed under a client id in ClientOrderId::uuid() form: a UUID, lowercase and hyphenated. Any other id is refused at placement with OrderError::Rejected, before anything is sent.

Hyperliquid tracks an order by its venue oid and by an optional 16-byte cloid, and reports the cloid back on every order record, REST and WebSocket alike. This client sends the client id as the cloid and turns the one reported back into the same id, so every account snapshot, open-order listing and order update names an order by the id it was placed with. Only that form of UUID comes back unchanged, which is why nothing else is accepted.

An order placed some other way, such as the web app, has no cloid and is reported under its oid. It cannot be one of this client’s orders, which is what lets an account snapshot declare its order list complete (see InstrumentAccountSnapshot::orders_complete).

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)

SDK limitations (hyperliquid_rust_sdk 0.6.x): neither the open orders this client reads nor OrderUpdate carry an order’s trigger fields or time in force, so orders from both are reported as OrderKind::Limit, GoodUntilCancelled. Track OrderKind from the placement request.

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.