Python functions: screenHyperliquidMarkets(), getHyperliquidOHLCV(), getHyperliquidPriceAndBook(), getHyperliquidFunding(), getHyperliquidPositions(), getHyperliquidTrades(), screenHyperliquidWallets()
| Specification | Value |
|---|
| Delivery Frequency | continuous, real-time |
| Data Frequency | event-driven (fills, book), bar-aggregated (OHLCV), hourly (funding) |
| Coverage | All live Hyperliquid perpetual futures and spot markets |
| OHLCV Timeframes | 1min to monthly (14 native intervals) |
| Availability | Free |
Product Overview
Overview
Hyperliquid Data provides full read access to Hyperliquid, the leading on-chain perpetual futures exchange. The dataset spans seven functions covering market discovery, price history, order book depth, funding rates, and — because Hyperliquid is fully on-chain — the open positions and complete fill history of any wallet on the exchange, no authentication required.
That last property is what makes this dataset unusually powerful for strategy research: on a traditional exchange you only see your own account; on Hyperliquid you can watch what the most profitable traders are holding and doing in near real time, and build strategies that follow (or fade) them.
Functions at a Glance
| Function | Purpose | Example strategy use |
|---|
screenHyperliquidMarkets() | Discover perp/spot markets with live price, volume, OI, funding | Universe selection for momentum or funding-carry strategies |
getHyperliquidOHLCV() | OHLCV candles from 1-minute to monthly | Backtesting, trend/breakout signals, volatility sizing |
getHyperliquidPriceAndBook() | Live mid price and L2 order book | Slippage estimation and entry timing before execution |
getHyperliquidFunding() | Historical hourly funding rates per perp | Funding-carry (basis) strategies, crowding/sentiment signals |
getHyperliquidPositions() | Open perp positions + spot balances for any wallet | Copy-trading and whale-positioning signals |
getHyperliquidTrades() | Full fill history for any wallet | Reverse-engineering a top trader’s entries and exits |
screenHyperliquidWallets() | Rank ~40k wallets by PnL, ROI, volume | Finding which wallets are worth copying in the first place |
Data Sources
All functions read from Hyperliquid’s own first-party endpoints — there is no third-party intermediary:
- Public info API (
POST https://api.hyperliquid.xyz/info): market metadata and live asset context (metaAndAssetCtxs, spotMetaAndAssetCtxs), candles (candleSnapshot), L2 books (l2Book, allMids), funding history (fundingHistory), wallet positions (clearinghouseState, spotClearinghouseState), and wallet fills (userFills, userFillsByTime). This is the same API the Hyperliquid front end uses. No API key is needed; positions and fills are public on-chain data for any address.
- Stats leaderboard endpoint (
stats-data.hyperliquid.xyz): the full ~40,000-wallet performance dataset behind the official app’s leaderboard page, refreshed periodically upstream. Used only by screenHyperliquidWallets(); downloaded once and cached in-process for 10 minutes.
Ticker Convention
Hyperliquid tickers use the H: namespace prefix, consistent with other Scalar Field asset classes (X: crypto, I: indices, J: Jupiter, C: forex):
| Ticker | Market |
|---|
H:BTC | BTC perpetual |
H:ETH | ETH perpetual |
H:PURR/USDC | PURR/USDC spot pair |
H:@142 | Spot pair by internal id |
H: prefix, so outputs can be passed directly back as inputs. Bare API ids ('BTC') are also accepted.
Hyperliquid is a tradable venue on Scalar Field: perps (long/short) and spot pairs execute through
venue.trade() or
strategy.execute(). See
Trading on Hyperliquid for order semantics, funding, and connection steps.
Querying the Data
screenHyperliquidMarkets()
Discover and filter Hyperliquid markets with live prices, 24h volume, open interest, and current funding — the whole perp and/or spot universe in one call.
Strategy angle: this is the universe-selection step of almost any strategy. A momentum strategy screens for the biggest 24h movers with sufficient volume; a funding-carry strategy sorts by funding_rate to find perps paying the most to shorts; a market-making study filters by volume_24h_usd and open_interest to find liquid books worth quoting.
from scalarlib import screenHyperliquidMarkets
# Top perps by 24h volume
df = screenHyperliquidMarkets()
# Find BTC markets across perps and spot
df = screenHyperliquidMarkets(market_type='all', query='BTC')
# Funding-carry candidates: liquid perps with extreme funding
df = screenHyperliquidMarkets(min_volume=1_000_000, sort_by='funding_rate')
# Momentum candidates: biggest 24h movers
df = screenHyperliquidMarkets(sort_by='change_24h', limit=20)
# Feed a coin into the other functions
coin = df.iloc[0]['coin']
data = getHyperliquidOHLCV(coins=[coin], start='2026-01-01')
Parameters
| Parameter | Type | Required | Description |
|---|
market_type | str | No | 'perp' (default), 'spot', or 'all'. |
query | str | No | Case-insensitive substring match on coin id and name (e.g. 'BTC', 'sol'). |
min_volume | float | No | Minimum 24h notional volume in USD. |
min_open_interest | float | No | Minimum open interest in base units (perps only). |
sort_by | str | No | 'volume' (default), 'open_interest', 'change_24h', 'funding_rate'. Descending. |
limit | int | No | Maximum results (default 50). |
offset | int | No | Pagination offset (default 0). |
Return Schema
| Column | Type | Description |
|---|
coin | string | Canonical H:-prefixed ticker — pass to all other functions |
name | string | Human-readable name (resolved BASE/QUOTE for spot) |
market_type | string | 'perp' or 'spot' |
mark_price | float | Mark price |
mid_price | float | Mid price |
oracle_price | float | Oracle price (NaN for spot) |
funding_rate | float | Current hourly funding rate (NaN for spot) |
open_interest | float | Open interest in base units (NaN for spot) |
volume_24h_usd | float | 24h notional volume (USD) |
prev_day_price | float | Mark price 24h ago |
change_24h_pct | float | Percent change vs 24h ago |
max_leverage | int | Maximum leverage (NaN for spot) |
sz_decimals | int | Size precision decimals |
getHyperliquidOHLCV()
OHLCV candles for perp or spot coins, from 1-minute up to monthly bars. Sourced from the public candleSnapshot endpoint; the API returns at most the most recent ~5,000 candles per coin per request. Omit start and end for live mode (latest bar).
Strategy angle: the backbone of any systematic approach — backtest a moving-average crossover on daily bars, compute realized volatility for position sizing, or detect intraday breakouts on 5-minute candles. num_trades per bar is a useful activity filter that plain OHLCV feeds don’t give you: a price move on 10 trades means something different than the same move on 10,000.
from scalarlib import getHyperliquidOHLCV
# Daily bars for BTC perp
data = getHyperliquidOHLCV(coins=['H:BTC'], start='2026-01-01', end='2026-02-01')
df = data['H:BTC']
# Hourly bars (inferred from datetime format)
data = getHyperliquidOHLCV(coins=['H:BTC', 'H:ETH'],
start='2026-02-01T09:00:00', end='2026-02-01T18:00:00')
# 5-minute bars with explicit timeframe
data = getHyperliquidOHLCV(coins=['H:SOL'], start='2026-02-01', end='2026-02-02', timeframe='5min')
# Live mode — latest bar for each coin
data = getHyperliquidOHLCV(coins=['H:BTC', 'H:ETH'])
Parameters
| Parameter | Type | Required | Description |
|---|
coins | list of str | Yes | H:-prefixed tickers from screenHyperliquidMarkets(). Bare ids accepted. |
start | str | No | "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM:SS" (New York time). Omit for live mode. |
end | str | No | Same format as start. Date-only expands to end of day. Defaults to now. |
timeframe | str | No | 'day', 'hour', '1min'–'30min', or native intervals '1m', '3m', '5m', '15m', '30m', '1h', '2h', '4h', '8h', '12h', '1d', '3d', '1w', '1M'. Inferred from date format if omitted. |
Return Schema
Returns Dict[str, pd.DataFrame] keyed by coin. Each DataFrame:
| Column | Type | Description |
|---|
ts_recv | datetime64[ns, US/Eastern] | Bar open timestamp (New York time) |
ticker | string | Canonical H:-prefixed ticker |
open | float | Opening price (USD) |
high | float | High price |
low | float | Low price |
close | float | Closing price |
volume | float | Volume in base units |
num_trades | int | Number of trades in the bar |
getHyperliquidPriceAndBook()
Live mid price and aggregated L2 order book per coin. Mid prices for all coins come from one allMids call; books from the l2Book endpoint.
Strategy angle: the pre-trade sanity check. Before a strategy sizes an entry, walk the book to estimate slippage for your intended notional; a signal that looks great on close prices can be uneconomic once you account for a thin book. Book imbalance (bid depth vs ask depth) is also a short-horizon signal in its own right.
from scalarlib import getHyperliquidPriceAndBook
data = getHyperliquidPriceAndBook(coins=['H:BTC'])
info = data['H:BTC']
info['mid_price'] # 63909.5
info['asks'].iloc[0]['price'] # best ask
info['bids'].iloc[0]['price'] # best bid
# Estimate slippage for a $500k buy by walking the ask side
asks = info['asks']
asks['notional'] = asks['price'] * asks['size']
asks['cum_notional'] = asks['notional'].cumsum()
Parameters
| Parameter | Type | Required | Description |
|---|
coins | list of str | Yes | H:-prefixed tickers. Bare ids accepted. |
book_depth | int | No | Price levels per side (default 10). None = full book (up to 20 levels). |
Return Schema
Returns Dict[str, dict] keyed by coin:
| Field | Type | Description |
|---|
mid_price | float | Current mid price |
ts | datetime | Book snapshot timestamp (New York time, naive) |
bids | pd.DataFrame | Columns price, size, num_orders — best bid first |
asks | pd.DataFrame | Columns price, size, num_orders — best ask first |
getHyperliquidFunding()
Historical hourly funding rates for perps, from the fundingHistory endpoint. Rates are decimal hourly rates (e.g. 0.0000125 = 0.00125% per hour); funding on Hyperliquid accrues every hour.
Strategy angle: funding is both a carry source and a sentiment gauge. A funding-carry strategy shorts perps with persistently positive funding (longs pay shorts) while holding spot elsewhere, collecting the rate with limited price exposure. As a contrarian signal, extreme funding marks crowded positioning — spikes in positive funding often precede long squeezes. The premium column (mark vs oracle) tells you how stretched the perp is against its reference price.
from scalarlib import getHyperliquidFunding
# Last 7 days of BTC funding (default window)
df = getHyperliquidFunding(coins=['H:BTC'])
# Funding for multiple coins over a window
df = getHyperliquidFunding(coins=['H:BTC', 'H:ETH'], start='2026-06-01', end='2026-07-01')
# Annualized carry estimate from average hourly funding
df.groupby('coin')['funding_rate'].mean() * 24 * 365
Parameters
| Parameter | Type | Required | Description |
|---|
coins | list of str | Yes | H:-prefixed perp tickers. Spot markets have no funding. |
start | str | No | "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM:SS" (New York time). Defaults to 7 days ago. |
end | str | No | Same format. Date-only expands to end of day. Defaults to now. |
Return Schema
| Column | Type | Description |
|---|
ts_recv | datetime64[ns, US/Eastern] | Funding timestamp |
coin | string | Canonical H:-prefixed ticker |
funding_rate | float | Hourly funding rate (decimal) |
premium | float | Mark vs oracle premium at the time |
getHyperliquidPositions()
Open perp positions and spot balances for any wallet — positions on Hyperliquid are public on-chain data, so no authentication is needed. Combines the perp clearinghouse state and spot balance state in one DataFrame.
Strategy angle: the core of a whale-watching or copy-trading strategy. Take wallets from screenHyperliquidWallets(), snapshot their positions on a schedule, and trade on changes: a top-decile trader flipping from long to short ETH is a signal you cannot get from price data alone. liquidation_price across many large wallets also lets you map where forced selling would cascade.
from scalarlib import getHyperliquidPositions
df = getHyperliquidPositions(wallet='0x6e6f...')
# Perp positions only
perps = df[df['position_type'] == 'perp']
# Net unrealized PnL and short exposure
perps['unrealized_pnl'].sum()
shorts = perps[perps['size'] < 0]
Parameters
| Parameter | Type | Required | Description |
|---|
wallet | str | Yes | Wallet address, 0x-prefixed. Any address works. |
Return Schema
One row per open perp position or nonzero spot balance:
| Column | Type | Description |
|---|
wallet | string | Queried wallet address |
position_type | string | 'perp' or 'spot' |
coin | string | Canonical H:-prefixed ticker |
size | float | Position size (negative = short for perps; token balance for spot) |
entry_price | float | Average entry price (perp only) |
position_value | float | Current notional value (perp only) |
unrealized_pnl | float | Unrealized P&L (perp only) |
return_on_equity | float | Return on equity (perp only) |
liquidation_price | float | Liquidation price (perp only) |
margin_used | float | Margin allocated (perp only) |
leverage | float | Leverage value (perp only) |
leverage_type | string | 'cross' or 'isolated' (perp only) |
max_leverage | int | Maximum allowed leverage (perp only) |
funding_since_open | float | Cumulative funding paid since open; negative = received (perp only) |
hold | float | Amount locked in open orders (spot only) |
entry_notional | float | USD cost basis (spot only) |
getHyperliquidTrades()
Complete fill history for any wallet, from the userFills / userFillsByTime endpoints. Without start/end the API returns the wallet’s most recent ~2,000 fills; with a start time, up to 2,000 fills from that window.
Strategy angle: where copy-trading gets precise. Positions tell you what a trader holds; fills tell you when and how they built it — do they scale in, add on dips, cut losers fast? closed_pnl per fill lets you verify a wallet’s edge trade by trade before you commit capital to mirroring it, and the crossed flag separates urgent taker flow from patient maker flow.
Hyperliquid has no public market-wide trade tape over REST, so trade queries are wallet-scoped only (unlike getPolymarketTrades(), which can filter by market).
from scalarlib import getHyperliquidTrades
# Recent fills for a wallet
df = getHyperliquidTrades(wallet='0x6e6f...')
# BTC fills since a date
df = getHyperliquidTrades(wallet='0x6e6f...', coin='H:BTC', start='2026-06-01')
# Realized PnL over a window — verify the edge before copying
df = getHyperliquidTrades(wallet='0x6e6f...', start='2026-06-01', end='2026-07-01')
df['closed_pnl'].sum()
Parameters
| Parameter | Type | Required | Description |
|---|
wallet | str | Yes | Wallet address, 0x-prefixed. |
start | str | No | "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM:SS" (New York time). |
end | str | No | Same format. Only applied when start is provided. |
coin | str | No | Filter to a single coin ('H:BTC' or bare 'BTC'). |
side | str | No | 'BUY' or 'SELL'. |
limit | int | No | Maximum rows, newest first (default 1,000). |
Return Schema
| Column | Type | Description |
|---|
ts_recv | datetime64[ns, US/Eastern] | Fill timestamp |
coin | string | Canonical H:-prefixed ticker |
side | string | 'BUY' or 'SELL' |
price | float | Fill price (USD) |
size | float | Fill size in base units |
usd_value | float | price * size |
direction | string | e.g. 'Open Long', 'Close Short', 'Buy' |
closed_pnl | float | Realized P&L from this fill |
fee | float | Fee paid (negative = rebate) |
crossed | bool | True if the fill crossed the spread (taker) |
tx_hash | string | L1 transaction hash |
order_id | int | Order ID |
screenHyperliquidWallets()
Rank the full ~40,000-wallet universe by PnL, ROI, volume, or account value over daily, weekly, monthly, or all-time windows. Data comes from Hyperliquid’s stats leaderboard endpoint — the same source the official app’s leaderboard uses. The dataset is downloaded once and cached in-process for 10 minutes, so the first call pays a multi-second download and subsequent calls are instant.
Strategy angle: the discovery step of a copy-trading pipeline. Screen for wallets with high ROI and meaningful account value (to filter out lucky dust accounts), then feed them into getHyperliquidPositions() and getHyperliquidTrades() to validate consistency before mirroring. Comparing week vs all-time rankings also separates traders on a hot streak from durable performers.
from scalarlib import screenHyperliquidWallets
# Top 10 wallets by all-time PnL
df = screenHyperliquidWallets(limit=10)
# Best ROI this week among accounts with > $100k
df = screenHyperliquidWallets(time_period='week', sort_by='roi', min_account_value=100000)
# Copy-trading pipeline: screen -> positions -> fills
wallet = df.iloc[0]['wallet']
positions = getHyperliquidPositions(wallet=wallet)
fills = getHyperliquidTrades(wallet=wallet)
Parameters
| Parameter | Type | Required | Description |
|---|
time_period | str | No | 'all' (default), 'month', 'week', 'day'. |
sort_by | str | No | 'pnl' (default), 'roi', 'volume', 'account_value'. Descending. |
min_value | float | No | Minimum value of the sort_by metric. |
max_value | float | No | Maximum value of the sort_by metric. |
min_account_value | float | No | Minimum current account value in USD (independent of sort_by). |
limit | int | No | Maximum results (default 50). |
offset | int | No | Pagination offset (default 0). |
Return Schema
| Column | Type | Description |
|---|
rank | int | 1-based rank in the full leaderboard for the chosen sort/window |
wallet | string | 0x-prefixed address |
account_value | float | Current account value (USD) |
pnl | float | P&L over the selected window (USD) |
roi | float | Return over the window (decimal, 0.05 = 5%) |
volume | float | Notional volume over the window (USD) |
display_name | string | Public display name ('' if unset) |
Strategy Playbook
Concrete ways to combine these functions into a strategy:
- Funding carry.
screenHyperliquidMarkets(sort_by='funding_rate', min_volume=1_000_000) to find perps with extreme funding, getHyperliquidFunding() to confirm the rate is persistent rather than a one-hour spike, getHyperliquidPriceAndBook() to verify the book can absorb your size. Harvest the hourly payment with a hedged position.
- Copy-trading.
screenHyperliquidWallets(sort_by='roi', min_account_value=100_000) to shortlist traders, getHyperliquidTrades() to audit their realized PnL and style, then poll getHyperliquidPositions() on a schedule and mirror position changes.
- Crowding fade. Track funding and open interest together: rising OI plus rapidly rising positive funding means crowded longs. Use
getHyperliquidOHLCV() to time the mean-reversion entry when momentum stalls.
- Cross-venue signals. Hyperliquid perp funding and whale positioning in
H:BTC/H:ETH often lead sentiment in correlated assets — use them as inputs to strategies that execute in crypto OHLCV universes (X: tickers) or even Polymarket crypto markets.
