Skip to content

hyperliquid.md

Latest commit

 

History

History
234 lines (173 loc) · 9.56 KB

hyperliquid.md

File metadata and controls

234 lines (173 loc) · 9.56 KB
Raw

Hyperliquid

Hyperliquid is a decentralized perpetual futures exchange built on the Arbitrum blockchain, offering a fully on-chain order book and matching engine. This integration supports live market data feeds and order execution on Hyperliquid.

:::warning The Hyperliquid integration is under active development. Some features may be incomplete. :::

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).

:::note Most users will define a configuration for a live trading node (as shown below) and won't need to work directly with these lower-level components. :::

Examples

You can find live example scripts here.

Testnet setup

Hyperliquid provides a testnet environment for testing strategies without risking real funds.

Getting testnet credentials

  1. Visit the Hyperliquid testnet portal
  2. Connect your wallet (MetaMask or WalletConnect)
  3. The testnet will automatically create an account for your wallet address
  4. Request testnet funds from the faucet (if available)

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

:::warning Never share your private keys Store private keys securely using environment variables, never commit them to version control. :::

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 will automatically load these when testnet=True in the configuration.

Product support

Hyperliquid currently supports perpetual futures contracts.

Product Type Data Feed Trading Notes
Perpetual Futures ✓ ✓ Both PERP and SPOT instruments.
Spot ✓ ✓ Native spot markets.

:::note All instruments on Hyperliquid are settled in USDC. :::

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")

:::note Spot instruments may include vault tokens (prefixed with vntls:). These are automatically handled by the instrument provider. :::

Orders capability

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

Order types

Order Type Perpetuals Spot Notes
MARKET ✓ ✓ Executed as IOC limit order.
LIMIT ✓ ✓
STOP_MARKET ✓ ✓ Stop loss orders.
STOP_LIMIT ✓ ✓ Stop loss with limit execution.
MARKET_IF_TOUCHED ✓ ✓ Take profit at market.
LIMIT_IF_TOUCHED ✓ ✓ Take profit with limit execution.

:::info Conditional orders (stop and if-touched) are implemented using Hyperliquid's native trigger order functionality with automatic TP/SL mode detection. :::

Time in force

Time in force Perpetuals Spot Notes
GTC ✓ ✓ Good Till Canceled.
IOC ✓ ✓ Immediate or Cancel.
FOK - - Not supported.
GTD - - Not supported.

Execution instructions

Instruction Perpetuals Spot Notes
post_only ✓ ✓ Equivalent to ALO time in force.
reduce_only ✓ ✓ Close-only orders.

Order operations

Operation Perpetuals Spot Notes
Submit order ✓ ✓ Single order submission.
Submit order list ✓ ✓ Batch order submission.
Modify order ✓ ✓ Price and quantity modification.
Cancel order ✓ ✓ Cancel by client order ID.
Cancel all orders ✓ ✓ Cancel all orders for instrument/side.
Batch cancel ✓ ✓ Cancel multiple orders in one request.

Configuration

Data client configuration options

Option Default Description
base_url_http None Override for the REST base URL.
base_url_ws None Override for the WebSocket base URL.
testnet False Connect to the Hyperliquid testnet when True.
http_timeout_secs 10 Timeout (seconds) applied to REST calls.
http_proxy_url None Optional HTTP proxy URL.
ws_proxy_url None Optional WebSocket proxy URL.

Execution client configuration options

Option Default Description
private_key None EVM private key; loaded from HYPERLIQUID_PK or HYPERLIQUID_TESTNET_PK when omitted.
vault_address None Vault address for delegated trading; loaded from HYPERLIQUID_VAULT or HYPERLIQUID_TESTNET_VAULT when omitted.
base_url_http None Override for the REST base URL.
base_url_ws None Override for the WebSocket base URL.
testnet False Connect to the Hyperliquid testnet when True.
max_retries None Maximum retry attempts for order submission/cancel/modify.
retry_delay_initial_ms None Initial delay (milliseconds) between retries.
retry_delay_max_ms None Maximum delay (milliseconds) between retries.
http_timeout_secs 10 Timeout (seconds) applied to REST calls.
http_proxy_url None Optional HTTP proxy URL.
ws_proxy_url None Optional WebSocket proxy URL.

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
        ),
    },
)

:::note When testnet=True, the adapter automatically uses testnet environment variables (HYPERLIQUID_TESTNET_PK and HYPERLIQUID_TESTNET_VAULT) instead of mainnet variables. :::