Execution: venue.trade() in chat code, strategy.execute() in strategy agents. Available in live (HYPERLIQUID) and paper (HYPERLIQUID_PAPER) modes. Data reference: Hyperliquid Data.

Overview

Hyperliquid is an on-chain exchange for perpetual futures and spot pairs. Scalar Field connects to it as a tradable venue: market data is read from Hyperliquid’s public API, and orders are placed against an exchange account funded with USDC bridged from your Arbitrum wallet. A paper account (HYPERLIQUID_PAPER) is also available with virtual USDC and fills simulated against the live order book — see Paper Trading.

Specification	Value
Instruments	Perpetual futures (`H:BTC`, `H:ETH`, …) and spot markets (canonical ids like `H:@142`; readable pair shown as `display_symbol`)
Modes	`HYPERLIQUID` (live), `HYPERLIQUID_PAPER` (paper)
Direction	Long and short (perps)
Margin	Cross or isolated, per-market maximum leverage
Hours	24/7
Fill model	Synchronous market orders
Slippage tolerance	`slippage_bps`, default 50 (0.5%)
Minimum order	$10 notional (live; no minimum on paper)
Currency	USDC (held on the exchange)

Order Semantics

Symbols use the H: prefix: H:BTC for perps, canonical internal pair ids like H:@142 for spot. The symbol on every surface — trade input, trade responses, positions, history — is this same canonical id, so always match on it; the readable pair is display-only, carried separately as display_symbol (with base_asset/quote_asset). Never construct a pair name yourself — major-asset spot tokens are Unit-wrapped (BTC spot is UBTC, shown as H:UBTC/USDC; H:BTC/USDC does not exist). Discover markets with screenHyperliquidMarkets(): its coin column is the canonical id and name is the readable pair.
Quantity is in the base asset (e.g. 0.01 for H:BTC), not USD. To size from a dollar budget, use round(budget / price, sz_decimals). sz_decimals is returned by screenHyperliquidMarkets(); quantities that round to zero are rejected.
Selling more than the current position opens a short. Perp positions carry signed quantities — negative means short.
Orders below $10 notional are rejected on the live account (no minimum on paper).
Fills are synchronous: venue.trade() blocks until the order fills or is rejected. Fill records include Hyperliquid-specific fields direction (e.g. "Open Short") and closed_pnl.

Account Structure

Unlike wallet-funded venues, Hyperliquid holds its own USDC:

cash on the account equals main-dex perps free collateral (withdrawable) — this is the buying power for new perp positions.
Spot and perp balances are separate. venue.balances(account="HYPERLIQUID") returns one row per balance class, tagged "perp" or "spot".
account_value, margin_used, and portfolio_value include equity held on HIP-3 builder-deployed perp dexs (markets with symbols like H:xyz:AAPL). Each HIP-3 dex holds its own USDC collateral; its perp balance rows carry an extra dex key with the dex name.
Perp positions carry additional fields: leverage, leverage_type (cross/isolated), liq_price, and margin_used.

Paper Trading

HYPERLIQUID_PAPER is a simulated Hyperliquid account with virtual USDC. Order calls have the same shape as live — pass account="HYPERLIQUID_PAPER" — so strategy code validated on paper runs unchanged against the live account.

No setup. The paper account is provisioned automatically on first use (or with one click from the portfolio page). No wallet, bridging, deposits, or transfers are ever needed.
Pre-funded balances. Every USDC bucket — perp, spot, and each HIP-3 dex — is pre-funded with $10M virtual USDC. HIP-3 buckets are seeded on first trade, so HIP-3 symbols (H:xyz:AAPL) trade immediately without moving collateral.
Realistic fills. Market orders are simulated against the live Hyperliquid L2 order book: the fill price is the volume-weighted average of consumed book levels within the slippage limit (slippage_bps, default 50). Real taker fees (4.5 bps) are charged on every fill. Orders that cannot fill within the slippage limit are rejected with NO_LIQUIDITY.
Full perp mechanics. Shorts, cross leverage (venue.set_leverage()), real hourly funding rates, and cross-margin liquidations are all simulated. Spot is long-only.

Differences vs live:

	Live	Paper
Funding source	USDC bridged from `WALLET_ARB`	Virtual USDC, pre-funded
Transfers (spot ↔ perp ↔ HIP-3)	Required, done from the UI	Never needed — every bucket is pre-funded
Order types	Market orders	Market orders
Minimum order	$10 notional	None
Size rounding	Rounded to `sz_decimals`	Not applied
Margin	Cross or isolated	Cross only

Connecting and Funding

Paper: no setup — HYPERLIQUID_PAPER is provisioned automatically on first use. Live:

Connect Hyperliquid from the portfolio page.
Fund your Arbitrum wallet (WALLET_ARB) with USDC.
Bridge USDC from WALLET_ARB to Hyperliquid from the portfolio page. Moving USDC between spot and perp balances is also done from the UI.

Usage

from scalarlib import screenHyperliquidMarkets, venue

# Discover markets and size an order
markets = screenHyperliquidMarkets(market_type='perp', query='BTC')
sz_decimals = int(markets.iloc[0]['sz_decimals'])
price = markets.iloc[0]['mark_price']
qty = round(200 / price, sz_decimals)          # ~$200 notional

# Long 0.01 BTC; a sell larger than the position opens a short
resp = venue.trade("buy", "H:BTC", qty, account="HYPERLIQUID")
print(resp["status"], resp["avg_price"])

# Spot uses the same call — discover the canonical id, trade it, and match
# positions on the response symbol
spot = screenHyperliquidMarkets(market_type='spot', query='BTC')
sym = spot.iloc[0]['coin']       # 'H:@142' (name column: 'UBTC/USDC')
resp = venue.trade("buy", sym, 0.00016, account="HYPERLIQUID")
resp["symbol"]                   # 'H:@142' — same id on positions and history
resp["display_symbol"]           # 'H:UBTC/USDC' — human-readable
acct = venue.account(account="HYPERLIQUID")["accounts"][0]
pos = next(p for p in acct["positions"] if p["symbol"] == resp["symbol"])

# Paper account — same call shape, virtual USDC, fills against the live book
resp = venue.trade("buy", "H:BTC", qty, account="HYPERLIQUID_PAPER")

In strategy agents, use strategy.execute(symbol, target_qty) instead — see Strategies.

Data Functions

All functions read Hyperliquid’s public API; positions and fills are public on-chain data for any address, no authentication needed. Full parameter and schema documentation: Hyperliquid Data.

Function	Purpose	Returns
`screenHyperliquidMarkets()`	Filter perp/spot markets by volume, open interest, 24h change, or funding rate	DataFrame: coin, prices, funding, OI, volume, `max_leverage`, `sz_decimals`
`getHyperliquidOHLCV(coins, start, end, timeframe)`	Candles from 1-minute to monthly (~5000 bars per request)	Dict of DataFrames keyed by coin: OHLCV + `num_trades`
`getHyperliquidPriceAndBook(coins, book_depth)`	Live mid price and L2 order book	Dict per coin: `mid_price`, `bids`/`asks` DataFrames
`getHyperliquidFunding(coins, start, end)`	Historical hourly funding rates per perp	DataFrame: `ts_recv`, coin, `funding_rate`, `premium`
`getHyperliquidPositions(wallet)`	Open perp positions and spot balances for any wallet	DataFrame: size (signed), entry price, PnL, leverage, liquidation price
`getHyperliquidTrades(wallet, ...)`	Fill history for any wallet (~2000 most recent)	DataFrame: fills with price, size, direction, `closed_pnl`, fee
`screenHyperliquidWallets(...)`	Rank ~40k wallets by PnL, ROI, volume, or account value	DataFrame: rank, wallet, `account_value`, pnl, roi, volume

Notes

Order sizes are rounded to the market’s sz_decimals; very small quantities may round to zero and be rejected.
Funding accrues hourly on perp positions; funding_since_open on a position shows cumulative funding paid (negative = received).
Daily OHLCV bars are aligned to UTC midnight, which appears as 19:00/20:00 New York time in ts_recv.

Hyperliquid Agent Architecture — how strategy agents share the account: funding and liquidation attribution
Hyperliquid Data — full function reference
Strategies — automated strategy execution
Supported Venues — venue registry and venue.* functions
Trading Fees

Getting Started

Trading

Trading Venues

Market Data

Usage & Pricing

Trading on Hyperliquid

Overview

Order Semantics

Account Structure

Paper Trading

Connecting and Funding

Usage

Data Functions

Notes

​Overview

​Order Semantics

​Account Structure

​Paper Trading

​Connecting and Funding

​Usage

​Data Functions

​Notes

​Related

Overview

Order Semantics

Account Structure

Paper Trading

Connecting and Funding

Usage

Data Functions

Notes

Related