Hyperliquid APIapp.hyperliquid.xyz ↗
Access Hyperliquid leaderboard rankings, perpetual and spot market data, live order books, trader positions, and delta-neutral strategy detection via a single API.
What is the Hyperliquid API?
This API exposes 7 endpoints covering the Hyperliquid decentralized exchange, from the full leaderboard of up to ~15,000 ranked traders to live order books and individual wallet positions. get_leaderboard returns each trader's PNL, ROI, and volume across four time windows, while get_all_perp_markets delivers real-time funding rates, open interest, and mark prices for every listed perpetual futures symbol.
curl -X GET 'https://api.parse.bot/scraper/29f3831a-dcb7-4687-b5e3-b564048f842c/get_leaderboard?window=allTime&min_value=0' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace app-hyperliquid-xyz-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Hyperliquid Trading Data API — bounded, re-runnable."""
from parse_apis.hyperliquid_trading_data_api import (
Hyperliquid, TimeWindow, SymbolNotFound
)
client = Hyperliquid()
# List perpetual markets with live pricing data.
for market in client.perpmarkets.list(limit=5):
print(market.symbol, market.mark_px, market.funding)
# Get the order book for BTC — typed resource with nested levels.
try:
book = client.orderbooks.get(symbol="BTC")
print(f"BTC book at {book.time}: {len(book.levels)} sides")
except SymbolNotFound as exc:
print(f"Symbol not found: {exc}")
# Top traders ranked by all-time PNL.
trader = client.toptraders.list(window=TimeWindow.ALL_TIME, limit=1).first()
if trader:
print(trader.eth_address, trader.pnl, trader.account_value)
# Fetch open positions for the top trader's address.
if trader:
positions = client.traderpositions.get(address=trader.eth_address)
print(f"Account value: {positions.margin_summary.account_value}")
# Spot market metadata.
spot_data = client.spotmarketdatas.get()
print(f"Spot pairs: {len(spot_data.universe)}, Tokens: {len(spot_data.tokens)}")
print("exercised: perpmarkets.list / orderbooks.get / toptraders.list / traderpositions.get / spotmarketdatas.get")
Fetch the leaderboard dataset including traders with their account values and performance across time windows (day, week, month, allTime). Returns up to ~15000 rows ranked by account value. Each row includes windowPerformances with PNL, ROI, and volume for each time window.
| Param | Type | Description |
|---|---|---|
| window | string | Time window filter for display context. Accepted values: allTime, 30d, 7d, 24h. |
| min_value | number | Minimum account value filter in USD. Rows with account value below this are excluded. |
{
"type": "object",
"fields": {
"leaderboardRows": "array of trader objects with ethAddress, accountValue, windowPerformances, displayName, prize"
},
"sample": {
"data": {
"leaderboardRows": [
{
"prize": 0,
"ethAddress": "0x85ecf584f25db6f146718b86d493e33c5af72052",
"displayName": null,
"accountValue": "53766664.0309550017",
"windowPerformances": [
[
"day",
{
"pnl": "-213440.9809189999",
"roi": "-0.0039540613",
"vlm": "1608229542.3800003529"
}
],
[
"week",
{
"pnl": "-1311185.4992220001",
"roi": "-0.0181759473",
"vlm": "13287891598.7899990082"
}
],
[
"month",
{
"pnl": "2974025.2610950004",
"roi": "0.03432125",
"vlm": "37254845181.9999923706"
}
]
]
}
]
},
"status": "success"
}
}About the Hyperliquid API
Leaderboard and Trader Analytics
get_leaderboard returns up to ~15,000 trader rows, each containing an ethAddress, accountValue, optional displayName, and a windowPerformances array covering allTime, 30d, 7d, and 24h windows. Each window entry includes pnl, roi, and vlm. You can pass min_value to filter out accounts below a USD threshold. get_top_traders builds on this by sorting by PNL for a specified window and returning a flat array capped by a limit parameter — useful when you only need the top 50 or 100 performers rather than the full dataset.
Market Data — Perpetuals and Spot
get_all_perp_markets requires no parameters and returns every perpetual futures symbol with markPx, midPx, funding (current funding rate), openInterest, dayNtlVlm (24-hour notional volume), prevDayPx, maxLeverage, and szDecimals. get_all_spot_markets covers the spot side, returning a tokens array with contract-level metadata (tokenId, weiDecimals, isCanonical, EVM-compatible fields) alongside a universe array that maps each trading pair to its constituent token indices.
Order Books and Open Positions
get_order_book accepts a symbol string (e.g. BTC, ETH, SOL) and returns 20 price levels on each side. Each level exposes px (price), sz (size), and n (number of orders at that level), along with a millisecond time timestamp. get_trader_open_positions takes a 0x-prefixed Ethereum wallet address and returns the full margin picture: accountValue, totalMarginUsed, withdrawable, crossMarginSummary, and an assetPositions array with per-symbol entry price, position size, and unrealized PNL.
Delta-Neutral Strategy Detection
identify_delta_neutral_traders analyzes the top 3 traders by volume for a given time window and flags accounts where overlapping spot and perpetual positions in the same asset produce a hedge ratio above 20%. The endpoint may return an empty array when no qualifying positions are found among the sampled traders.
The Hyperliquid API is a managed, monitored endpoint for app.hyperliquid.xyz — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when app.hyperliquid.xyz changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official app.hyperliquid.xyz API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Rank traders by all-time PNL using
get_top_tradersto build a copy-trading watchlist. - Monitor live funding rates and open interest across all perp symbols with
get_all_perp_marketsfor arbitrage screening. - Stream order book depth via
get_order_bookto track bid-ask spreads and liquidity at 20 levels per side. - Audit a wallet's margin exposure and unrealized PNL using
get_trader_open_positionsfor risk dashboards. - Detect delta-neutral traders with
identify_delta_neutral_tradersto study hedging behavior on-chain. - Filter leaderboard rows by
min_valueto study only accounts above a meaningful capital threshold. - Cross-reference spot token metadata from
get_all_spot_marketswith perp data to map full market coverage.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Hyperliquid have an official developer API?+
What does `get_leaderboard` return and how does filtering work?+
get_leaderboard returns an array of up to ~15,000 trader objects. Each object includes ethAddress, accountValue, displayName (when set), prize, and a windowPerformances array with pnl, roi, and vlm for each of the four time windows. Passing min_value drops any row whose accountValue falls below that USD amount. The window parameter provides a display-context hint but does not change which performance data is included in the response.Does the API return historical OHLCV candle data for perpetual markets?+
get_all_perp_markets, plus order book snapshots via get_order_book. Historical candle or trade history data is not included. You can fork this API on Parse and revise it to add an endpoint targeting historical market data.How many order book levels does `get_order_book` return, and what fields are included?+
get_order_book returns exactly 20 price levels on each side (bids and asks). Each level contains px (price as a string), sz (size), and n (number of orders aggregated at that level). The response also includes the coin symbol and a millisecond time timestamp.