Hyperliquid API

These are the Bitquery Hyperliquid API docs: how to query and stream trades, orders, the order book, candles, liquidations, funding and positions for every trader on the exchange, and how to read the full state of every account from snapshots.

Bitquery indexes Hyperliquid core (the L1 order-book exchange) and exposes it through the Hyperliquid cube on the streaming API. Every event dataset is available both as a GraphQL query and as a WebSocket subscription (real-time stream) — change query to subscription and drop limit/orderBy. The state cubes — CurrentPositions, MarkPrices and the eleven Snapshot* cubes — are query-only.

Video Tutorials

How far back the API goes

The Hyperliquid cubes serve a rolling window: about 30 days for Trades, Candles, PerpLiquidations, PerpFundings, Twaps, PriceUpdates and TraderLeverageUpdates, and about 7 days for the densest feeds — Orders, BookUpdates and SignedActions — and for the Snapshot* cubes (a new snapshot about every 12.5 minutes). That covers live streaming and recent history, which is what most bots, dashboards and monitoring need. See Data Coverage & Retention for the per-cube table.

A query without a Block: {Time: ...} filter covers a shorter default window: the last 30 minutes on Orders and BookUpdates, the last 24 hours on Trades and PriceUpdates. For data older than the window, use Parquet exports from the Bitquery Data Store (details on the Hyperliquid export page). Older ranges are available on request from sales@bitquery.io.

API Key Required

To query or stream data outside the Bitquery IDE, you need an API access token.

Follow the steps here: How to generate Bitquery API token ➤

Available datasets

query {
  Hyperliquid {
    BookUpdates            # order book deltas (new / change / remove)
    Candles                # OHLCV candles per market and interval
    CurrentPositions       # open position per trader and market (query only)
    MarkPrices             # latest mark price per HIP-3 market (query only)
    Orders                 # order lifecycle: open, filled, canceled, triggered, rejected
    PerpFundings           # per-trader funding payments
    PerpLiquidations       # perp liquidations
    PriceUpdates           # HIP-3 oracle and mark price updates
    SignedActions          # signed L1 actions: rejects and non-order actions
    TraderLeverageUpdates  # leverage / margin-mode changes
    Trades                 # fills with direction, fees, leverage, PnL, position size after
    Twaps                  # TWAP order lifecycle
    Snapshots              # snapshots: height and time (query only)
    SnapshotMarkets        # every market: prices, best bid / ask, open interest
    SnapshotPositions      # every open perp position: entry, margin, unrealized PnL
    SnapshotAccounts       # every account per perp dex: account value, margin
    SnapshotOrders         # order book with owners and waiting trigger orders
    SnapshotBalances       # every non-zero spot balance
    SnapshotLeverageSettings # leverage setting per account and market
    SnapshotVaults         # every vault: equity, followers, terms
    SnapshotVaultFollowers # every vault depositor
    SnapshotEarnReserves   # Earn pool per token: supplied, borrowed, rates
    SnapshotEarnPositions  # Earn supply and borrow per account
  }
}

Page	Cubes covered
Trades & Candles	Trades, Candles
Orders, Order Book & TWAPs	Orders, BookUpdates, Twaps
Mark Prices & Price Updates	MarkPrices, PriceUpdates
Liquidations, Funding, Positions & Leverage	PerpLiquidations, PerpFundings, CurrentPositions, TraderLeverageUpdates
Signed Actions	SignedActions
Snapshots	Snapshots, SnapshotMarkets, SnapshotPositions, SnapshotAccounts, SnapshotOrders, SnapshotBalances, SnapshotLeverageSettings, SnapshotVaults, SnapshotVaultFollowers, SnapshotEarnReserves, SnapshotEarnPositions

Guide	What it covers
Track Order Flow by Wallet	Market-maker tracking, cancel-to-fill ratios, wallet-level order lifecycles using L3 data
Funding Payments by Wallet	Every funding payment a wallet paid or received, per-market totals, date ranges
Liquidation History by Wallet	Every liquidation of one address, backstop liquidations, live alerts
Vaults API	Vaults ranked by volume and PnL, vault fills, HLP deposits and withdrawals, vault liquidations
TWAP Orders & Child Fills	Join a TWAP order to every child fill it produced
HIP-3 Stocks API	S&P 500, US stock and commodity perps deployed through HIP-3
Prediction Markets API	HIP-4 outcome markets: names and answers, odds, top markets by volume, holders of each side
Track ZEC on Hyperliquid	Positions, liquidations, funding and whale trades for one market
Bitquery vs Hyperliquid's free data	What the native Info API and s3://hyperliquid-archive do and don't cover

Hyperliquid Info API vs Bitquery

The native Hyperliquid API is built for trading your own account. Bitquery is built for seeing the whole market:

Capability	Hyperliquid native WS	Bitquery
Scope of user data (orders, fills, funding, TWAPs, positions)	Any single address you already know, one subscription each, at most 10 users per IP — no market-wide stream of orders, funding, TWAPs or positions	Every trader on the exchange in one stream, or filter to any list of addresses
Order book	l2Book, aggregated (L2), 5–20 levels max	L3 (market-by-order) deltas, unlimited depth, order id + trader address on every order
Liquidations	Per-address only, via userEvents — no exchange-wide feed	All liquidations exchange-wide, with liquidated user, method, mark price, leverage
Open positions	Per-address snapshot (clearinghouseState) — cannot enumerate or rank the market	Whole market queryable (CurrentPositions): every open position, sortable and filterable; SnapshotPositions adds entry price, margin and unrealized PnL every ~12.5 minutes, with 7 days of history
Account state	Margin, spot balances and open orders per address (clearinghouseState, spotClearinghouseState, openOrders), current only	Every account at once from snapshots: margin per dex, spot balances, resting and trigger orders with owners, vaults and their depositors, Earn
Historical data	Live + snapshot only; separate REST with pagination limits. The public s3://hyperliquid-archive bucket holds L2 book snapshots and asset contexts, updated roughly monthly with no completeness guarantee; raw node fills and events sit in the requester-pays s3://hl-mainnet-node-data bucket; no candles	Same GraphQL query for history and live stream over a rolling window (~30 days; ~7 days for orders, book updates and signed actions). Older history is available as Parquet exports from the Data Store
Filtering	Per-coin or per-user only	Any field: market, trader, side, size, leverage, status
Fill context	Rich (PnL, direction) only on per-user feeds; the public trades feed carries price, size, side and the two addresses, without direction, fees or PnL	Direction, fees, leverage, position size before and after, realized PnL and execution order on every fill, market-wide
Raw L1 actions	Not exposed	SignedActions: action type, signer vs user (agent wallets), bundle, broadcaster
Delivery	WebSocket only; reconnect/gap handling yours; some feeds base64+DEFLATE encoded	GraphQL WS + Kafka (protobuf, offsets, consumer groups, no gaps), plus Parquet exports (download from S3 or R2, or custom delivery to your bucket or warehouse)
Subscription model	One subscription per coin / per user, per-connection limits	One stream can carry everything unfiltered, or a list of values on any filter field (many markets or wallets in one stream); runs 1,000+ concurrent streams at scale
Rate limits and keys	Per-IP weight limits on the REST Info API, per-connection subscription caps on WS; one API wallet per account	Limits are per plan, not per IP; one Bitquery key covers every market and wallet
Latency at market scale	Fast for a single coin/user feed, but covering the whole market means hundreds of subscriptions, client-side merging and rate limits	Lowest latency for the entire market in one pipeline — Kafka delivers every event exchange-wide, keyed by block, with no fan-out to assemble

Markets: perp, spot and HIP-3

Every cube carries a Market object that identifies the instrument:

Field	Meaning	Example values
Symbol	Human-readable market symbol; not unique — the same ticker can be a native perp and several HIP-3 markets	BTC, HYPE/USDC, AAPL
CoinRaw	Raw Hyperliquid coin id, unique per market: a plain name for native perps, @<n> for spot, #<n> for outcome markets, and HIP-3 markets prefixed with their deployer namespace	BTC, @107, #108130, xyz:SMSN, mkts:AAPL
Kind	Market class	perp, hip3, spot, outcome
IsPerp	true for perpetual markets (native and HIP-3)	true / false
Protocol	HIP-3 deployer namespace; hypercore for native markets	xyz, mkts, hypercore
MaxLeverage	Maximum leverage allowed on the market; set on native perps, 0 elsewhere	40
Outcome	Prediction markets only: Headline (the market), Title (the answer), SideTitle (the side), Question { ... }	BTC above 78521 at 2026-10-31 06:00 UTC?, Yes

HIP-3 markets are builder-deployed perps — tokenized stocks (mkts:AAPL), indices (xyz:KR200, para:TOTAL2) and other synthetic assets trade alongside native Hyperliquid perps and appear in the same cubes with Kind: hip3. See the HIP-3 Stocks API for queries. Outcome markets (Kind: outcome) are HIP-4 prediction markets priced between 0 and 1, named under Market { Outcome { ... } }; see the Prediction Markets API. Filter on CoinRaw when you mean one market.

The spot pair PURR/USDC is filed with Kind: perp and IsPerp: true because its id is a plain name; it is a spot market.

ChainId is hyperliquid-core on all event cubes.

Common fields

• Block { Number Time } — Hyperliquid L1 block height and timestamp; filter with Block: {Time: {since_relative: {minutes_ago: 5}}} or absolute since/till.
• Order inside a block — every event of a block shares Block.Time, so sort by Index within it: Trade.Execution.Index and Liquidation.Execution.Index give the execution order (one sequence across the trades and liquidations of a block, from 1), Order.Index the order of status updates, BookUpdate.Index the order of book deltas. For example orderBy: {descending: [Block_Time, Trade_Execution_Index]}. Execution.Tid is a fill identifier (shared by the maker and taker rows of one fill), not a sequence. Fills and order updates written before about 09:40 UTC on 2026-10-13 have Index 0.
• Trader { Address Vault Signer Broadcaster SignedAt } — the account behind an event. Vault is set when the action is performed on behalf of a vault; Signer is the signing key (may be an agent/API wallet distinct from Address).
• Numeric amounts (price, size, PnL, fees) are returned as strings at native precision; candle OHLCV values are floats.

WebSocket streams

Any event query becomes a live stream over wss://streaming.bitquery.io/graphql (transport graphql-transport-ws):

subscription {
  Hyperliquid {
    Trades {
      Block { Time }
      Trade {
        Market { Symbol }
        Execution { Price Size Side Direction }
      }
    }
  }
}

See WebSocket subscriptions for connection details.

Kafka streams (protobuf)

For the lowest latency, the same data is available as Kafka streams:

Topic	Protobuf schema
hyperliquid.candles.proto	CandlesBlockMessage in hyperliquid/candles.proto
hyperliquidcore.messages.proto	HyperliquidCoreBlockMessage in hyperliquid/hyperliquid_block_message.proto

A block can arrive as several hyperliquidcore.messages.proto messages (for example fills and order statuses separately); each carries BlockNumber and BlockTime. See Kafka Streaming Concepts for access and consumer setup.

Historical data (Parquet exports)

For backtesting and research — trades with realized PnL, liquidations, L4 order book updates, the full order lifecycle, oracle prices and hourly funding — Bitquery delivers the same data as Parquet exports from the Bitquery Data Store (technical details) for S3, Snowflake, BigQuery, Athena, or DuckDB. The Parquet files and the live streams share field definitions, so backtest and production code decode identically.