Hyperliquid Rust SDK

Fork Notice: This is an actively maintained fork of ferrofluid by ControlCplusControlV. This fork provides complete coverage of all Hyperliquid API endpoints and is under active development.

A high-performance Rust SDK for the Hyperliquid Protocol, built with a "thin wrapper, maximum control" philosophy.

Features

• 🚀 High Performance: Uses simd-json for 10x faster JSON parsing than serde_json
• 🔒 Type-Safe: Strongly-typed Rust bindings with compile-time guarantees
• 🎯 Direct Control: No hidden retry logic or complex abstractions - you control the flow
• ⚡ Fast WebSockets: Built on fastwebsockets for 3-4x performance over tungstenite
• 🛠️ Builder Support: Native support for MEV builders with configurable fees
• 📊 Complete API Coverage: Info, Exchange, and WebSocket providers for all endpoints

Installation

Add this to your Cargo.toml:

[dependencies]
hyperliquid-sdk-rs = "0.1.2"

Quick Start

Reading Market Data

use hyperliquid_sdk_rs::{InfoProvider, Network};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let info = InfoProvider::new(Network::Mainnet);

    // Get all mid prices
    let mids = info.all_mids().await?;
    println!("BTC mid price: {}", mids["BTC"]);

    // Get L2 order book
    let book = info.l2_book("ETH").await?;
    println!("ETH best bid: {:?}", book.levels[0][0]);

    Ok(())
}

Placing Orders

use hyperliquid_sdk_rs::{ExchangeProvider, signers::AlloySigner};
use alloy::signers::local::PrivateKeySigner;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Setup signer
    let signer = PrivateKeySigner::random();
    let hyperliquid_signer = AlloySigner { inner: signer };

    // Create exchange provider
    let exchange = ExchangeProvider::mainnet(hyperliquid_signer);

    // Place an order using the builder pattern
    let result = exchange.order(0) // BTC perpetual
        .limit_buy("50000", "0.001")
        .reduce_only(false)
        .send()
        .await?;

    println!("Order placed: {:?}", result);
    Ok(())
}

WebSocket Subscriptions

use hyperliquid_sdk_rs::{WsProvider, Network, types::ws::Message};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut ws = WsProvider::connect(Network::Mainnet).await?;

    // Subscribe to BTC order book
    let (_id, mut rx) = ws.subscribe_l2_book("BTC").await?;
    ws.start_reading().await?;

    // Handle updates
    while let Some(msg) = rx.recv().await {
        match msg {
            Message::L2Book(book) => {
                println!("BTC book update: {:?}", book.data.coin);
            }
            _ => {}
        }
    }

    Ok(())
}

Managed WebSocket with Auto-Reconnect

For production use, consider the ManagedWsProvider which adds automatic reconnection and keep-alive:

use hyperliquid_sdk_rs::{ManagedWsProvider, WsConfig, Network};
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Configure with custom settings
    let config = WsConfig {
        ping_interval: Duration::from_secs(30),
        auto_reconnect: true,
        exponential_backoff: true,
        ..Default::default()
    };

    let ws = ManagedWsProvider::connect(Network::Mainnet, config).await?;

    // Subscriptions automatically restore on reconnect
    let (_id, mut rx) = ws.subscribe_l2_book("BTC").await?;
    ws.start_reading().await?;

    // Your subscriptions survive disconnections!
    while let Some(msg) = rx.recv().await {
        // Handle messages...
    }

    Ok(())
}

Examples

The examples/ directory contains comprehensive examples covering all SDK features:

Core Examples

• 00_symbols.rs - Working with pre-defined symbols
• 01_info_types.rs - Using the Info provider for market data
• 02_info_provider.rs - Complete Info API coverage (Phase 1, 2, & 3 endpoints)
• 03_exchange_provider.rs - Complete Exchange API coverage (Phase 1, 2, & 3 endpoints)
• 04_websocket.rs - Real-time WebSocket subscriptions (Phase 1 & 2)
• 05_builder_orders.rs - Using MEV builders for orders

Advanced Examples

• 06_twap_orders.rs - TWAP (Time-Weighted Average Price) order workflows
• 07_multi_sig.rs - Multi-signature account operations
• 08_staking_delegation.rs - Token staking and validator delegation
• 09_spot_deployment.rs - Deploying custom spot tokens
• 10_perp_deployment.rs - Deploying custom perpetual markets
• 11_order_tracking.rs - Order tracking system with CLOIDs

Run examples with:

cargo run --example 02_info_provider

Architecture

The SDK follows a modular architecture:

hyperliquid_sdk_rs/
├── providers/
│   ├── info.rs          // Read-only market data (HTTP)
│   ├── exchange/        // Trading operations (module)
│   │   ├── mod.rs       // RawExchangeProvider
│   │   ├── builder.rs   // OrderBuilder pattern
│   │   └── managed.rs   // ManagedExchangeProvider
│   └── websocket.rs     // Real-time subscriptions
├── types/
│   ├── actions.rs       // EIP-712 signable actions
│   ├── requests.rs      // Order, Cancel, Modify structs
│   ├── responses.rs     // API response types
│   ├── info_types.rs    // Info API response types
│   └── ws.rs            // WebSocket message types
└── signers/
    ├── signer.rs        // HyperliquidSigner trait, AlloySigner
    └── privy.rs         // Privy signer support

Performance

The SDK is designed for maximum performance:

• JSON Parsing: Uses simd-json for vectorized parsing
• HTTP Client: Built on hyper + tower for connection pooling
• WebSocket: Uses fastwebsockets for minimal overhead
• Zero-Copy: Minimizes allocations where possible

Builder Support

Native support for MEV builders with configurable fees:

let exchange = ExchangeProvider::mainnet_builder(signer, builder_address);

// All orders automatically include builder info
let order = exchange.order(0)
    .limit_buy("50000", "0.001")
    .send()
    .await?;
    
// Or specify custom builder fee
let result = exchange.place_order_with_builder_fee(&order_request, 10).await?;

Rate Limiting

Built-in rate limiter respects Hyperliquid's limits:

// Rate limiting is automatic
let result = info.l2_book("BTC").await?; // Uses 1 weight
let fills = info.user_fills(address).await?; // Uses 2 weight

Error Handling

Comprehensive error types with thiserror:

match exchange.place_order(&order).await {
    Ok(status) => println!("Success: {:?}", status),
    Err(HyperliquidError::RateLimited { available, required }) => {
        println!("Rate limited: need {} but only {} available", required, available);
    }
    Err(e) => println!("Error: {}", e),
}

Testing

Run the test suite:

cargo test

Integration tests against testnet:

cargo test --features testnet

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

This project is a fork of ferrofluid by ControlCplusControlV. We are grateful for the original work that made this SDK possible.

Built with high-performance crates from the Rust ecosystem:

• alloy-rs for Ethereum primitives
• hyperliquid-rust-sdk (official SDK reference)
• hyper for HTTP
• fastwebsockets for WebSocket
• simd-json for JSON parsing