Struct HyperliquidSpotClient 

pub struct HyperliquidSpotClient { /* private fields */ }

Hyperliquid spot trading execution client.

Wraps the official hyperliquid_rust_sdk to implement the ExecutionClient trait for spot trading on Hyperliquid DEX.

Implementations

impl HyperliquidSpotClient

pub async fn connect( config: HyperliquidConfig, ) -> Result<Self, ConnectivityError>

Create a new spot client asynchronously.

Use this when calling from an async context (e.g., tokio tests). For sync contexts, use ExecutionClient::new().

Errors

ConnectivityError::Socket when the SDK clients cannot be created, or Hyperliquid’s spotMeta cannot be read (see Spot coins).

pub fn wallet_address(&self) -> String

Returns the wallet address as a hex string (for logging/debugging).

pub async fn order_precision( &self, instrument: &InstrumentNameExchange, ) -> Option<OrderPrecision>

The precision rules for orders on the spot pair instrument (BASE-QUOTE-SPOT), from its base token’s szDecimals.

open_order refuses an order that breaks them with OrderError::InvalidPrecision and sends nothing. Round with these rules first. See OrderPrecision.

None when instrument is not of that form, or Hyperliquid lists no such pair. A pair missing from the pairs this client holds is looked for in spotMeta again first, at most once every 10 seconds, so a pair listed since the client connected is found.

None too when instrument spells the pair’s tokens differently from Hyperliquid, even only in ASCII case (KPEPE-USDC-SPOT for kPEPE/USDC). Every order report names the pair as Hyperliquid spells it, so open_order refuses an order under any other spelling, naming the one to use.

Trait Implementations

impl Clone for HyperliquidSpotClient

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for HyperliquidSpotClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl ExecutionClient for HyperliquidSpotClient

fn new(config: Self::Config) -> Self

Creates a new Hyperliquid spot client synchronously.

Panics

• If no Tokio runtime is available on the current thread
• If called from within an async context (e.g., inside async fn, spawn, or block_on)
• If SDK initialization fails (network error, invalid credentials), or Hyperliquid’s spotMeta cannot be read

Recommended Usage

Use HyperliquidSpotClient::connect instead — it’s async-safe and returns Result. This method exists only for trait compliance; prefer connect() in all new code.

async fn account_stream( &self, _assets: &[AssetNameExchange], _instruments: &[InstrumentNameExchange], ) -> Result<Self::AccountStream, UnindexedClientError>

Returns a live stream of account events (fills, order updates) for spot orders.

Instrument filtering

The instruments parameter is ignored — Hyperliquid’s WebSocket API does not support per-instrument subscriptions for user events. All fills and order updates are delivered, but we filter client-side to only emit spot events (see Spot coins).

Task lifecycle

Spawns three background tasks (fills, orders, and the reconnect’s order check) that are automatically cancelled when the returned stream is dropped.

Orders that ended while disconnected

After each reconnect the stream reports how each order the client holds as live ended, where it did, exactly as HyperliquidClient’s does; see its account_stream. The listing leaves out an order on a spot coin missing from spotMeta, which cannot be on an instrument the client holds an order on, but a lookup that finds an order on one, even after spotMeta is read again (see Spot coins), fails, and is retried.

async fn fetch_trades( &self, start: DateTime<Utc>, end: DateTime<Utc>, instruments: &[InstrumentNameExchange], ) -> Result<TradesRead<AssetNameExchange, InstrumentNameExchange>, UnindexedClientError>

Reads the span with userFillsByTime, to its end within the call, so the read is always complete (resume: None). Hyperliquid keeps only each wallet’s 10,000 most recent fills, so a span reaching further back is read only as far as those go, and held_since says where that is.

const EXCHANGE: ExchangeId = ExchangeId::HyperliquidSpot

const SUPPORTED_KINDS: &'static [InstrumentKindDiscriminant]

The InstrumentKindDiscriminants this client can trade.

type Config = HyperliquidConfig

type AccountStream = Pin<Box<dyn Stream<Item = AccountEvent<ExchangeId, AssetNameExchange, InstrumentNameExchange>> + Send>>

async fn account_snapshot( &self, _assets: &[AssetNameExchange], instruments: &[InstrumentNameExchange], ) -> Result<UnindexedAccountSnapshot, UnindexedClientError>

Reads the account’s balances, and its open orders and positions for instruments, from the venue.

async fn cancel_order( &self, request: OrderRequestCancel<ExchangeId, &InstrumentNameExchange>, ) -> UnindexedOrderResponseCancel

Cancel an order at the venue.

async fn open_order( &self, request: OrderRequestOpen<ExchangeId, &InstrumentNameExchange>, ) -> Order<ExchangeId, InstrumentNameExchange, UnindexedOrderState>

Place an order on the exchange.

async fn fetch_balances( &self, _assets: &[AssetNameExchange], ) -> Result<Vec<AssetBalance<AssetNameExchange>>, UnindexedClientError>

Fetch current balances for the specified assets.

async fn fetch_open_orders( &self, instruments: &[InstrumentNameExchange], ) -> Result<Vec<Order<ExchangeId, InstrumentNameExchange, Open>>, UnindexedClientError>

Fetch currently open orders, optionally filtered by instrument.

fn validate_config( config: &Self::Config, instruments: &[ClientInstrument<'_>], ) -> Result<(), String>

Checks config against the instruments this client is about to be built to trade, before Self::new is called. Err names what is wrong.

fn cancel_orders<'a>( &self, requests: impl IntoIterator<Item = OrderRequestCancel<ExchangeId, &'a InstrumentNameExchange>>, ) -> impl Stream<Item = UnindexedOrderResponseCancel> + Send

fn open_orders<'a>( &self, requests: impl IntoIterator<Item = OrderRequestOpen<ExchangeId, &'a InstrumentNameExchange>>, ) -> impl Stream<Item = Order<ExchangeId, InstrumentNameExchange, UnindexedOrderState>> + Send

impl OrderStatusClient for HyperliquidSpotClient

Looks each order up with orderStatus (weight 2), as HyperliquidClient does; see its implementation for how each status is reported. An order on a spot coin missing from spotMeta even after it is read again (see Spot coins) fails the call, since it cannot be told apart from an order on the key’s instrument.

The account stream runs the same lookup itself after a reconnect; see account_stream.

async fn fetch_order_status( &self, key: &UnindexedOrderKey, ) -> Result<VenueOrderStatus, UnindexedClientError>

One orderStatus (weight 2), which reports a live order as well as an ended one, read as fetch_ended_orders reads it.

Errors

When the lookup fails, the order is on a spot coin missing from spotMeta, or Hyperliquid’s record of the order does not convert.

async fn fetch_ended_orders( &self, orders: &[UnindexedOrderKey], ) -> Result<Vec<UnindexedInactiveOrder>, UnindexedClientError>

How each of orders ended, for those that have.