rhyperliquid

What is rhyperliquid?

rhyperliquid is a production-grade Rust client library for the Hyperliquid decentralized perpetuals exchange. It provides both a programmatic SDK and terminal-based interfaces for traders and developers who demand type-safety, performance, and reliability in their trading infrastructure. rhyperliquid is built with async-first architecture and is licensed under the Apache and MIT licenses.

Design Principles

As a comprehensive Hyperliquid client, rhyperliquid enables developers to build automated trading strategies, analytics tools, and terminal interfaces while maintaining the safety guarantees and performance characteristics that Rust provides. Building a production-ready trading client requires balancing financial precision, cryptographic correctness, and developer experience with practical performance.

More concretely, our principles are:

1. Type Safety & Financial Precision: Every API response, order type, and market data structure is modeled in Rust's type system to catch invalid requests at compile time. We use rust_decimal for all financial calculations to eliminate floating-point errors. While network and API errors remain runtime concerns, the library prevents entire classes of invalid requests before they're sent.

2. Correctness Over Speed: rhyperliquid prioritizes getting trading operations right. This means proper EIP-712 signing implementation, correct msgpack serialization for action hashing, and careful handling of Hyperliquid's WebSocket heartbeat protocol.

3. Modularity: The crate is structured as composable components. Whether you need just the REST client for backtesting, WebSocket streams for live data, or the CLI for manual trading. All public APIs are documented with examples showing real-world usage patterns.

4. Developer Experience: We believe trading infrastructure should be approachable. The library provides builder patterns for configuration, comprehensive error messages that explain what went wrong, and examples organized by user workflows rather than individual functions. Both library users and CLI users should find the interface intuitive.

5. Battle-Tested Foundations: By leveraging proven crates (tokio for async, reqwest for HTTP, Alloy for Ethereum cryptography), we build on solid foundations rather than reinventing implementations. Our authentication follows Hyperliquid's specifications for both testnet and mainnet environments.

6. Open & Extensible: rhyperliquid is free open source software licensed under Apache/MIT. This enables anyone to build proprietary strategies, modify the client for their needs, or integrate it into larger systems without licensing concerns. We welcome contributions that improve reliability, add features, or enhance documentation.

Features

• Market data queries (spot & perpetuals)
• Account information retrieval
• Order book snapshots
• Historical candle data
• User fills and funding history
• Order placement and cancellation
• Position management
• Vault operations
• Command-line interface for quick queries

Quick Start

Library Usage

use rhyperliquid::HyperliquidClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = HyperliquidClient::builder()
        .testnet()
        .build()?;

    // Get real-time mid prices for all assets
    let mids = client.info().get_all_mids().await?;
    println!("BTC: ${}", mids.get("BTC").unwrap());

    // Fetch L2 orderbook snapshot
    let book = client.info().get_l2_book("ETH").await?;
    println!("Best bid: ${}", book.levels[0].px);

    Ok(())
}

CLI Usage

The CLI provides quick access to market data and account information from your terminal. Below you can find a list of all supported CLI commands. rhyperliquid intentionally only supports place_order and cancel_order (by order id) from the CLI. Other Exchange API commands will be added by request or open source contribution.

# Run CLI commands
cargo run --bin cli --features=cli -- [OPTIONS] <COMMAND>

# Examples:

# Get all mid prices
cargo run --bin cli --features=cli -- all-mids

# Get all mid prices on testnet
cargo run --bin cli --features=cli -- --network testnet all-mids

# Get L2 orderbook for BTC
cargo run --bin cli --features=cli -- l2-book --coin BTC

# Get user's open orders (requires HL_PRIVATE_KEY env var)
export HL_PRIVATE_KEY=your_private_key_here
cargo run --bin cli --features=cli -- --allow-signer-key-env open-orders --user 0x...

# Get candle data
cargo run --bin cli --features=cli -- candle-snapshot \
  --coin ETH \
  --interval 1h \
  --start-time 1640000000000 \
  --end-time 1640100000000

# Get vault details
cargo run --bin cli --features=cli -- vault-details --vault-address 0x...

WebSocket Subscriptions

Subscribe to real-time data feeds using the WebSocket interface:

# Subscribe to open orders updates (requires HL_PRIVATE_KEY env var)
export HL_PRIVATE_KEY=your_private_key_here
RUST_LOG=info cargo run --bin cli --features=cli -- \
  --subscriptions true \
  subscribe-open-orders \
  --user 0xYourAddress

# Subscribe to order book updates
cargo run --bin cli --features=cli -- \
  --subscriptions true \
  subscribe-l2-book \
  --coin BTC

# Subscribe to all mid prices
cargo run --bin cli --features=cli -- \
  --subscriptions true \
  subscribe-all-mids

# Subscribe to trades
cargo run --bin cli --features=cli -- \
  --subscriptions true \
  subscribe-trades \
  --coin ETH

WebSocket subscriptions stream live updates until interrupted with Ctrl+C.

CLI Reference

Global Options

Commands

Exchange API

Market Data

Account & Portfolio

Vault Operations

WebSocket Subscriptions

Market Data Streams

Account & Trading Streams

Advanced Streams

Use --help on any command for detailed parameter information:

cargo run --bin cli --features=cli -- l2-book --help

Trading Examples

Comprehensive examples demonstrating real trading workflows:

For account transfer examples, see examples/account_transfer.rs.

For position leverage and managing an isolated position see examples/leverage_position.rs.

For advanced order examples see examples/advanced_order.rs.

For TWAP order placement see examples/twap_order.rs.

Installation

As a Library Dependency

Add to your Cargo.toml:

[dependencies]
rhyperliquid = "0.2"
tokio = { version = "1.41", features = ["full"] }

CLI Installation

# Install from crates.io
cargo install rhyperliquid --features=cli

# Or install from source
git clone https://github.com/elijahhampton/rhyperliquid.git
cd rhyperliquid
cargo install --path . --features=cli --bin cli

Building from Source

# Clone the repository
git clone https://github.com/elijahhampton/rhyperliquid.git
cd rhyperliquid

# Build the library
cargo build --release

# Build with CLI
cargo build --release --features=cli

# Run tests
cargo test --all-features

# Build documentation
cargo doc --open

Stability and API Guarantees

This crate is under active development.

• Breaking changes may occur between minor versions (0.1 → 0.2)
• Public API is subject to refinement based on usage feedback
• Testnet testing is strongly recommended before mainnet use

Documentation

• API Documentation
• Hyperliquid Official Docs
• Examples

Getting Help

If you have questions:

1. Check the Hyperliquid API Documentation
2. Search existing GitHub Issues
3. Open a new Discussion for questions
4. Open an Issue for bugs

Requirements

Minimum Supported Rust Version (MSRV)

Rust 1.75.0 or higher is required.

# Verify your Rust version
rustc --version

# Update if needed
rustup update stable

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.