Skip to main content
Execution: venue.trade() in chat code, strategy.execute() in strategy agents. 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.
SpecificationValue
InstrumentsPerpetual futures (H:BTC, H:ETH, …) and spot pairs (H:PURR/USDC, H:@142)
DirectionLong and short (perps)
MarginCross or isolated, per-market maximum leverage
Hours24/7
Fill modelSynchronous market orders
Slippage toleranceslippage_bps, default 50 (0.5%)
Minimum order$10 notional
CurrencyUSDC (held on the exchange)

​
Order Semantics

  • Symbols use the H: prefix: H:BTC for perps, H:PURR/USDC for spot. Discover markets with screenHyperliquidMarkets().
  • 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.
  • 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 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".
  • Perp positions carry additional fields: leverage, leverage_type (cross/isolated), liq_price, and margin_used.

​
Connecting and Funding

  1. Connect Hyperliquid from the portfolio page.
  2. Fund your Arbitrum wallet (WALLET_ARB) with USDC.
  3. 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 pairs use the same call
resp = venue.trade("buy", "H:PURR/USDC", 100, account="HYPERLIQUID")
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.
FunctionPurposeReturns
screenHyperliquidMarkets()Filter perp/spot markets by volume, open interest, 24h change, or funding rateDataFrame: 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 bookDict per coin: mid_price, bids/asks DataFrames
getHyperliquidFunding(coins, start, end)Historical hourly funding rates per perpDataFrame: ts_recv, coin, funding_rate, premium
getHyperliquidPositions(wallet)Open perp positions and spot balances for any walletDataFrame: 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 valueDataFrame: 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.

​
Related