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.

Builder attribution

Orders submitted through the adapter include a NautilusTrader builder address with a zero fee rate. This is for attribution only and does not charge any additional fees. No builder code approval is required.

When trading via a vault (vault_address configured), the builder address is omitted from orders. Hyperliquid does not allow vaults to approve builder fees, so including the builder address would cause the exchange to reject the order.

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, HIP-3 builder-deployed perpetuals, 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")

HIP-3 perpetuals

Format: {dex}:{Asset}-USD-PERP

HIP-3 markets use a dex prefix separated by a colon. The dex name identifies which builder-deployed perp dex the market belongs to.

Examples:

• xyz:TSLA-USD-PERP - Tesla perp on trade.xyz
• xyz:GOLD-USD-PERP - Gold perp on trade.xyz
• flx:NVDA-USD-PERP - Nvidia perp on Felix
• vntl:SPACEX-USD-PERP - SpaceX perp on Ventuals

To subscribe in your strategy:

InstrumentId.from_str("xyz:TSLA-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")

HIP-3 builder-deployed perpetuals

HIP-3 allows qualified deployers to launch permissionless perp dexes on Hyperliquid. These markets include equities (TSLA, NVDA, AAPL), commodities (gold, crude oil), indices (S&P 500), and pre-IPO tokens (SpaceX, OpenAI).

HIP-3 instruments are excluded by default. To load them, include HyperliquidProductType.PERP_HIP3 in the requested product types.

For direct instrument provider usage:

from nautilus_trader.adapters.hyperliquid.enums import HyperliquidProductType
from nautilus_trader.adapters.hyperliquid.providers import HyperliquidInstrumentProvider

provider = HyperliquidInstrumentProvider(
    client=client,
    product_types=[
        HyperliquidProductType.PERP,
        HyperliquidProductType.SPOT,
        HyperliquidProductType.PERP_HIP3,
    ],
)

For live TradingNode usage, pass the same product_types through the Hyperliquid client config:

from nautilus_trader.adapters.hyperliquid import HyperliquidDataClientConfig
from nautilus_trader.adapters.hyperliquid import HyperliquidExecClientConfig
from nautilus_trader.adapters.hyperliquid import HyperliquidProductType

HyperliquidDataClientConfig(
    product_types=(
        HyperliquidProductType.PERP,
        HyperliquidProductType.PERP_HIP3,
    ),
)

HyperliquidExecClientConfig(
    product_types=(
        HyperliquidProductType.PERP,
        HyperliquidProductType.PERP_HIP3,
    ),
)

Once HIP-3 instruments are loaded, you can filter them with InstrumentProviderConfig:

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

Differences from standard perpetuals

HIP-3 markets trade on the same HyperCore matching engine and use the same order API. The key differences are:

• Higher fees: 2x standard perp fees by default. The deployer receives half.
• Isolated margin: HIP-3 markets default to isolated-only margin.
• Deployer-managed oracles: The deployer operates the oracle feed, not validators.
• Growth mode: Some dexes enable growth mode, which reduces protocol fees by 90%.

For full protocol details, see the Hyperliquid docs:

• HIP-3 proposal
• HIP-3 deployer actions
• Asset IDs
• Fees

Wildcard character sanitization

Some HIP-3 dexes deploy assets whose venue names contain * or ? bytes (for example dex:STREAMABCD****-USD-PERP). Those bytes collide with the Nautilus message bus pattern syntax (* = zero-or-more, ? = one-char) and would corrupt subscription routing if embedded in topic strings unchanged.

The Hyperliquid adapter substitutes both bytes with x when constructing the InstrumentId.symbol, so a HIP-3 asset named dex:STREAMABCD**** is exposed to strategies as:

InstrumentId.from_str("dex:STREAMABCDxxxx-USD-PERP.HYPERLIQUID")

The substitution applies only to the Nautilus-internal symbol used in topics, caches, logs, and config. The venue-official name is preserved on the instrument's raw_symbol field for HTTP and WebSocket wire calls, and order submissions reference the numeric asset index, so the round-trip with Hyperliquid is unaffected.

When subscribing to a HIP-3 instrument with wildcard bytes in its venue name, use the sanitized form. Symbols without * or ? are passed through unchanged.

The substitution is lossy: two distinct venue names such as dex:FOO* and dex:FOO? would normalize onto the same Nautilus symbol. The instrument loader detects collisions, keeps the first definition, and logs a warning with the dropped venue name; the dropped instrument will not be tradeable through Nautilus until the venue rename resolves the collision.

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. All perpetual data types (mark prices, index prices, funding rates) apply to both standard and HIP-3 perps.

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

Modify as cancel-replace

Hyperliquid implements order modification as a cancel-replace. The modify action on the exchange endpoint cancels the original order (old oid) and opens a replacement with a new oid. Both legs share the same client order ID (cloid).

The modify HTTP response only confirms success. The orderUpdates WebSocket subscription then delivers an ACCEPTED(new_oid) status report, followed by a CANCELED(old_oid) for the original leg.

The Rust-native HyperliquidExecutionClient (used through HyperliquidExecutionClientFactory) runs detection, deduplication, and event promotion on the Rust side via the WsDispatchState owned by the execution client. On submission the client registers an OrderIdentity (strategy, instrument, side, type, quantity, last-known price) keyed by client_order_id. Each inbound status report or fill is routed through the dispatch: tracked orders emit typed OrderEventAny::* events via ExecutionEventEmitter::send_order_event; external orders fall back to the raw OrderStatusReport / FillReport so the engine can reconcile. The dispatch compares the report's venue_order_id against the last cached value for the cloid; when they differ it promotes the ACCEPTED to OrderUpdated and suppresses the paired stale cancel:

If Hyperliquid delivers CANCELED(old_oid) before ACCEPTED(new_oid) for an in-flight modify, the pending-modify marker lets the dispatch drop the old leg's cancel and still route the subsequent ACCEPTED through the OrderUpdated path. The marker is only set after a confirmed HTTP success, so a failed modify never leaves stale race state. Because detection otherwise relies on the cached venue_order_id, the adapter also recovers a modify that times out on the HTTP call but still reaches the venue: the eventual WS ACCEPTED(new_oid) sees the old cached oid and translates to OrderUpdated. See GH-3827.

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 reports account state with USDC balances and margin usage. Standard perps default to cross margin. HIP-3 perps typically require isolated margin. On connect, the execution client performs a full reconciliation of orders, fills, and positions against Hyperliquid's clearinghouse state. This keeps the local cache 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)
• HYPERLIQUID_ACCOUNT_ADDRESS (optional, for agent wallet 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).

Funding rates

Hyperliquid perpetual futures use a fixed 1-hour funding interval. The adapter sets interval to 60 (minutes) on all FundingRateUpdate objects.

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.adapters.hyperliquid import HyperliquidProductType
from nautilus_trader.config import InstrumentProviderConfig
from nautilus_trader.config import TradingNodeConfig

config = TradingNodeConfig(
    data_clients={
        HYPERLIQUID: HyperliquidDataClientConfig(
            instrument_provider=InstrumentProviderConfig(load_all=True),
            product_types=(
                HyperliquidProductType.PERP,
                HyperliquidProductType.PERP_HIP3,
            ),
            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),
            product_types=(
                HyperliquidProductType.PERP,
                HyperliquidProductType.PERP_HIP3,
            ),
            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