Hyperliquid Trades & Candles API

This page covers the Trades and Candles cubes: every fill on Hyperliquid with full execution context, and OHLCV candles per market and interval.

The video shows how a trading bot combines the trades, liquidations, funding and orders streams over one WebSocket.

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 ➤

Latest trades

Each fill carries the execution (price, size, side, aggressor flag, place in the block), the position it changed (leverage, margin mode, size before and after, realized PnL) and fees. For perps Direction is Open Long, Open Short, Close Long, Close Short, or Long > Short / Short > Long when one fill flips the position through flat; spot and outcome fills read Buy / Sell.

Run it in the IDE: Hyperliquid Latest Trades ➤

query {
  Hyperliquid {
    Trades(
      limit: {count: 50}
      orderBy: {descending: [Block_Time, Trade_Execution_Index]}
      where: {Block: {Time: {since_relative: {minutes_ago: 10}}}}
    ) {
      Block { Number Time }
      Trade {
        Market { Symbol CoinRaw Kind IsPerp Protocol }
        Execution { Price Size Side Direction IsAggressor Index Oid Tid Hash }
        Fees { Fee FeeToken BuilderFee }
        IsTwap
        Position { Leverage IsCross Side SizeBefore Size RealizedPnl }
        Trader { Address Vault Signer }
      }
    }
  }
}

Notes on the payload:

• Every row of one block shares Block.Time. Execution.Index is the fill's place in its block — the execution order, from 1, one sequence across the trades and liquidations of the block — so order fills by [Block_Time, Trade_Execution_Index] as above.
• Execution.Tid identifies the match: the maker and the taker of one fill share it, so pair the two sides on (Block.Number, Market.CoinRaw, Tid). It is a hash, not a sequence — never order fills by it. Oid is the order id that got filled, Hash the transaction hash (all zeroes on TWAP fills).
• Fees.Fee is in FeeToken (usually USDC); a negative fee is a maker rebate.
• Position.SizeBefore and Position.Size are the account's signed position size before and after the fill (negative = short); RealizedPnl is the PnL realized by this fill.
• Rows written before about 09:40 UTC on 13 October 2026 have Index 0 and an empty Position.Size.
• IsTwap: true marks fills produced by a TWAP order (see TWAPs).
• Prediction market fills (Kind: outcome) carry the market's names under Market { Outcome { Headline Title SideTitle } }; see the Prediction Markets API.

Trades of one market

Run it in the IDE: Hyperliquid BTC Perp Trades ➤

query {
  Hyperliquid {
    Trades(
      limit: {count: 50}
      orderBy: {descending: Block_Time}
      where: {Trade: {Market: {Symbol: {is: "BTC"}}}}
    ) {
      Block { Time }
      Trade {
        Execution { Price Size Side Direction IsAggressor }
        Position { Leverage IsCross RealizedPnl }
        Trader { Address }
      }
    }
  }
}

Filter by trader instead with where: {Trade: {Trader: {Address: {is: "0x..."}}}}. Without a Block: {Time: ...} filter, Trades covers the last 24 hours; add one (e.g. since_relative: {days_ago: 7}) to reach further back within the ~30-day window.

Real-time trades stream

Run it in the IDE: Hyperliquid Trades Stream ➤

subscription {
  Hyperliquid {
    Trades {
      Block { Number Time }
      Trade {
        Market { Symbol Kind IsPerp }
        Execution { Price Size Side Direction IsAggressor Index Oid Tid }
        Fees { Fee FeeToken }
        IsTwap
        Position { Leverage IsCross Side Size RealizedPnl }
        Trader { Address }
      }
    }
  }
}

OHLCV candles

The Candles cube provides OHLCV per market and interval. Interval.Time.Duration is the candle length in seconds — 60, 300, 900 or 3600 — and Start the interval open time. OHLCV values are floats. Bars are built from taker fills, so each fill counts once in Volume (in base units); Open and Close are the first and last fill of the bar in execution order (block, then Execution.Index).

Run it in the IDE: Hyperliquid BTC OHLCV Candles ➤

query {
  Hyperliquid {
    Candles(
      limit: {count: 60}
      orderBy: {descending: Interval_Time_Start}
      where: {Market: {Symbol: {is: "BTC"}}, Interval: {Time: {Duration: {eq: 60}}}}
    ) {
      Interval { Time { Start Duration } }
      Market { Symbol Kind CoinRaw }
      Ohlc { Open High Low Close Volume }
    }
  }
}

HIP-3 markets get candles too — e.g. where: {Market: {CoinRaw: {is: "xyz:AAPL"}}} for the tokenized-stock market. Filter on CoinRaw when a ticker exists on more than one market (BTC and hyna:BTC).

Real-time candle stream

Run it in the IDE: Hyperliquid Candles Stream ➤

subscription {
  Hyperliquid {
    Candles(where: {Market: {Symbol: {is: "BTC"}}}) {
      Interval { Time { Start Duration } }
      Market { Symbol Kind }
      Ohlc { Open High Low Close Volume }
    }
  }
}

Remove the Symbol filter to stream candle updates for every market.

Related

• HIP-3 Stocks API — trades and candles for S&P 500, US stock and commodity perps
• Prediction Markets API — top HIP-4 markets by volume, live outcome trades
• TWAP Orders & Child Fills — join fills with IsTwap: true to their parent TWAP
• Track ZEC on Hyperliquid — whale trades and candles for one market