Horizon + Hyperliquid

Trade perpetual futures and spot on Hyperliquid’s L1 chain with wallet-based auth.

Partially verified. As of v0.8.7+, the critical signing issues from the earlier audit (msgpack key ordering, cloid format, spot asset offset, error handling, cancel-by-cloid action type) are fixed. Order submission and cancel should now work end-to-end. Has not been tested against a live Hyperliquid account with real funds, so verify the behavior matches expectations before deploying significant size.

Hyperliquid is a decentralized perpetual futures and spot exchange running on its own L1 chain. It offers deep liquidity, sub-second finality, and transparent on-chain order books. Horizon connects to Hyperliquid for perp/spot trading with wallet-based EIP-712 authentication.

Quick Setup

hz.run(
    name="hl_perps",
    exchange=hz.Hyperliquid(private_key="0x..."),
    mode="live",
    ...
)

Credentials

Explicit

hz.Hyperliquid(private_key="0xac0974bec39a...")

Environment variables

export HYPERLIQUID_PRIVATE_KEY="0xac0974bec39a..."

hz.Hyperliquid()  # reads from env

Hyperliquid Configuration

@dataclass
class Hyperliquid:
    private_key: str | None = None
    testnet: bool = False
    api_url: str | None = None
    vault_address: str | None = None

Field	Default	Description
private_key	None	EVM private key, 0x-prefixed hex (env: HYPERLIQUID_PRIVATE_KEY)
testnet	False	Use testnet endpoint
api_url	auto	Override API URL (auto-selects mainnet/testnet)
vault_address	None	Vault address for sub-account trading (env: HYPERLIQUID_VAULT_ADDRESS)

Authentication

Hyperliquid uses EIP-712 wallet signing — no API key/secret needed, just a private key. Every write operation is signed with the wallet’s secp256k1 key using a Hyperliquid-specific EIP-712 domain:

• Domain: {name: "Exchange", version: "1", chainId: 1337, verifyingContract: 0x0}
• Type: Agent(address source, bytes32 connectionId)
• Source: keccak256("a") (mainnet) or keccak256("b") (testnet)

Only two REST endpoints are used:

• POST /info — all read operations (metadata, fills, positions, prices)
• POST /exchange — all write operations (orders, cancels) with EIP-712 signature

Symbol Mapping

Hyperliquid identifies assets by integer indices, not ticker symbols. The SDK resolves symbols automatically via metadata on first use:

Asset Type	Index Range	Examples
Perpetuals	0–9999	BTC=0, ETH=1, SOL=2
Spot	≥10000	Spot tokens

# Use standard ticker symbols — SDK resolves to indices
market = hz.Market(id="BTC", name="Bitcoin Perpetual")
market = hz.Market(id="ETH", name="Ethereum Perpetual")

Horizon Field	Hyperliquid Field	Notes
OrderRequest.market_id	coin	Resolved to asset index internally
OrderRequest.order_side	is_buy	true for buy, false for sell
OrderRequest.price	limit_px	Sent as string with 5 sig figs
OrderRequest.size	sz	Sent as string with 5 sig figs

Market Orders

Hyperliquid has no native market order type. The SDK implements market orders as aggressive limit IOC with 5% slippage:

1. Fetch current mid price via allMids
2. Place limit IOC at mid × 1.05 (buy) or mid × 0.95 (sell)
3. Unfilled portion is immediately canceled (IOC behavior)

Hyperliquid uses Side.Long for all positions — perps and spot. Prediction market concepts like Side.Yes / Side.No do not apply.

Vault Trading

For sub-account (vault) trading, specify a vault address:

hz.Hyperliquid(
    private_key="0x...",
    vault_address="0xabcdef...",
)

The vault address is included in the EIP-712 signing payload and sent with every request.

Testnet

hz.Hyperliquid(testnet=True)

Uses https://api.hyperliquid-testnet.xyz automatically. Get testnet funds from the Hyperliquid testnet faucet.

Multi-Exchange

Use Hyperliquid alongside other exchanges:

hz.run(
    name="cross_venue",
    exchanges=[
        hz.Hyperliquid(),       # perps
        hz.Coinbase(),          # spot hedge
        hz.Polymarket(),        # prediction markets
    ],
    mode="live",
    ...
)

Getting Started

1. Generate or use an existing EVM private key
2. Fund your Hyperliquid account by depositing USDC via the Hyperliquid bridge
3. Set the environment variable or pass directly:
   export HYPERLIQUID_PRIVATE_KEY="0x..."
   
4. Start trading:
   hz.run(
       name="my_strategy",
       exchange=hz.Hyperliquid(),
       markets=["BTC", "ETH"],
       mode="live",
       pipeline=[my_pipeline],
   )