Hyperliquid

Hyperliquid is a decentralized perpetual futures and spot exchange built on the Hyperliquid L1, a purpose-built blockchain optimized for trading. HyperCore provides a fully on-chain order book and matching engine. This integration supports live market data ingest and order execution on Hyperliquid.

Overview

This adapter is implemented in Rust with Python bindings. It provides direct integration with Hyperliquid's REST and WebSocket APIs without requiring external client libraries.

The Hyperliquid adapter includes multiple components:

• HyperliquidHttpClient: Low-level HTTP API connectivity.
• HyperliquidWebSocketClient: Low-level WebSocket API connectivity.
• HyperliquidInstrumentProvider: Instrument parsing and loading functionality.
• HyperliquidDataClient: Market data feed manager.
• HyperliquidExecutionClient: Account management and trade execution gateway.
• HyperliquidLiveDataClientFactory: Factory for Hyperliquid data clients (used by the trading node builder).
• HyperliquidLiveExecClientFactory: Factory for Hyperliquid execution clients (used by the trading node builder).

Examples

You can find live example scripts here.

Revoking builder code approval

Previous versions of NautilusTrader required users to approve a builder code fee before trading. This is no longer required. If you previously approved the builder fee and wish to revoke it, you can run the revoke script.

The script reads your private key from environment variables (HYPERLIQUID_PK or HYPERLIQUID_TESTNET_PK).

python nautilus_trader/adapters/hyperliquid/scripts/builder_fee_revoke.py

Testnet:

HYPERLIQUID_TESTNET=true python nautilus_trader/adapters/hyperliquid/scripts/builder_fee_revoke.py

Alternatively, from Rust:

cargo run --bin hyperliquid-builder-fee-revoke

Testnet setup

Hyperliquid provides a testnet environment for testing strategies with mock funds.

Getting testnet funds

To receive testnet USDC, you must first have deposited on mainnet using the same wallet address:

1. Visit the Hyperliquid mainnet portal and make a deposit with your wallet.
2. Visit the testnet faucet using the same wallet.
3. Claim 1,000 mock USDC from the faucet.

Creating a testnet account

1. Visit the Hyperliquid testnet portal.
2. Connect your wallet (MetaMask, WalletConnect, or email).
3. The testnet automatically creates an account for your wallet address.

Exporting your private key

To use your testnet account with NautilusTrader, you need to export your wallet's private key:

MetaMask:

1. Click the three dots menu next to your account.
2. Select "Account details".
3. Click "Show private key".
4. Enter your password and copy the private key.

Setting environment variables

Set your testnet credentials as environment variables:

export HYPERLIQUID_TESTNET_PK="your_private_key_here"
# Optional: for vault trading
export HYPERLIQUID_TESTNET_VAULT="vault_address_here"

The adapter automatically loads these when testnet=True in the configuration.

Product support

Hyperliquid offers linear perpetual futures and native spot markets.

Symbology

Hyperliquid uses a specific symbol format for instruments:

Perpetual futures

Format: {Base}-USD-PERP

Examples:

• BTC-USD-PERP - Bitcoin perpetual futures
• ETH-USD-PERP - Ethereum perpetual futures
• SOL-USD-PERP - Solana perpetual futures

To subscribe in your strategy:

InstrumentId.from_str("BTC-USD-PERP.HYPERLIQUID")
InstrumentId.from_str("ETH-USD-PERP.HYPERLIQUID")

Spot markets

Format: {Base}-{Quote}-SPOT

Examples:

• PURR-USDC-SPOT - PURR/USDC spot pair
• HYPE-USDC-SPOT - HYPE/USDC spot pair

To subscribe in your strategy:

InstrumentId.from_str("PURR-USDC-SPOT.HYPERLIQUID")

Instrument provider

The instrument provider supports filtering when loading instruments via InstrumentProviderConfig(filters=...):

Example loading only perpetual instruments:

instrument_provider=InstrumentProviderConfig(
    load_all=True,
    filters={"market_types": ["perp"]},
)

Data subscriptions

The adapter supports the following data subscriptions:

Supported bar intervals

Orders capability

Hyperliquid supports a full set of order types and execution options.

Order types

from decimal import Decimal, ROUND_DOWN

def round_to_sig_figs(price: Decimal, sig_figs: int = 5) -> Decimal:
    if price == 0:
        return Decimal(0)
    shift = sig_figs - int(price.adjusted()) - 1
    if shift <= 0:
        factor = Decimal(10) ** (-shift)
        return (price / factor).to_integral_value() * factor
    return round(price, shift)

Time in force

Execution instructions

Order operations

Order books

Order books are maintained via L2 WebSocket subscription. Each message delivers a full-depth snapshot (clear + rebuild), not incremental deltas.

Account and position management

The adapter uses cross-margin mode and reports account state with USDC balances and margin usage. On connect, the execution client performs a full reconciliation of orders, fills, and positions against Hyperliquid's clearinghouse state. This ensures the local cache is consistent even after restarts or disconnections.

Connection management

The adapter automatically reconnects on WebSocket disconnection using exponential backoff (starting at 250ms, up to 5s). On reconnect, all active subscriptions are resubscribed automatically, and order book snapshots are rebuilt. No manual intervention is required.

A heartbeat ping is sent every 30 seconds to keep the connection alive (Hyperliquid closes idle connections after 60 seconds).

API credentials

There are two options for supplying your credentials to the Hyperliquid clients. Either pass the corresponding values to the configuration objects, or set the following environment variables:

For Hyperliquid mainnet clients, you can set:

• HYPERLIQUID_PK
• HYPERLIQUID_VAULT (optional, for vault trading)

For Hyperliquid testnet clients, you can set:

• HYPERLIQUID_TESTNET_PK
• HYPERLIQUID_TESTNET_VAULT (optional, for vault trading)

Vault trading

Hyperliquid supports vault trading, where a wallet operates on behalf of a vault (sub-account). Orders are signed with the wallet's private key but include the vault address in the signature payload.

To trade via a vault, set the vault_address in your execution client config (or set the HYPERLIQUID_VAULT / HYPERLIQUID_TESTNET_VAULT environment variable).

Rate limiting

The adapter implements a token bucket rate limiter for Hyperliquid's REST API with a capacity of 1200 weight per minute. HTTP info requests are automatically retried with exponential backoff (full jitter) on rate limit (429) and server error (5xx) responses.

Configuration

Data client configuration options

Execution client configuration options

Configuration example

from nautilus_trader.adapters.hyperliquid import HYPERLIQUID
from nautilus_trader.adapters.hyperliquid import HyperliquidDataClientConfig
from nautilus_trader.adapters.hyperliquid import HyperliquidExecClientConfig
from nautilus_trader.config import InstrumentProviderConfig
from nautilus_trader.config import TradingNodeConfig

config = TradingNodeConfig(
    data_clients={
        HYPERLIQUID: HyperliquidDataClientConfig(
            instrument_provider=InstrumentProviderConfig(load_all=True),
            testnet=True,  # Use testnet
        ),
    },
    exec_clients={
        HYPERLIQUID: HyperliquidExecClientConfig(
            private_key=None,  # Loads from HYPERLIQUID_TESTNET_PK env var
            vault_address=None,  # Optional: loads from HYPERLIQUID_TESTNET_VAULT
            instrument_provider=InstrumentProviderConfig(load_all=True),
            testnet=True,  # Use testnet
            normalize_prices=True,  # Rounds prices to 5 significant figures
        ),
    },
)

Then, create a TradingNode and add the client factories:

from nautilus_trader.adapters.hyperliquid import HYPERLIQUID
from nautilus_trader.adapters.hyperliquid import HyperliquidLiveDataClientFactory
from nautilus_trader.adapters.hyperliquid import HyperliquidLiveExecClientFactory
from nautilus_trader.live.node import TradingNode

# Instantiate the live trading node with a configuration
node = TradingNode(config=config)

# Register the client factories with the node
node.add_data_client_factory(HYPERLIQUID, HyperliquidLiveDataClientFactory)
node.add_exec_client_factory(HYPERLIQUID, HyperliquidLiveExecClientFactory)

# Finally build the node
node.build()

Contributing