Hyperliquid Liquidations, Funding, Positions & Leverage API

This page covers the perp risk cubes: PerpLiquidations, PerpFundings, CurrentPositions and TraderLeverageUpdates.

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 ➤

Liquidations

Each liquidation includes the liquidated user, the Method (market for open-market liquidation, backstop when the backstop vault takes over), the mark price at liquidation and the actual execution.

A forced fill has two sides and both are recorded: the liquidated account's own fill and the fill of every account that took the other side. All of them carry the same LiquidatedUser; Trader.Address tells them apart. Sign a liquidation fill by Execution.Side (Buy adds to the position, Sell subtracts), as for a trade. Position.SizeBefore and Position.Size are that account's signed size before and after the fill, and Execution.Index numbers the fill together with the trades of its block.

For every liquidation of one address, see Hyperliquid Liquidation History by Wallet.

Run it in the IDE: Hyperliquid Liquidations ➤

query {
  Hyperliquid {
    PerpLiquidations(limit: {count: 50}, orderBy: {descending: [Block_Time, Liquidation_Execution_Index]}) {
      Block { Time }
      Liquidation {
        Market { Symbol Kind }
        Method MarkPx Liquidator LiquidatedUser
        Trader { Address }
        Execution { Price Size Side Direction Index Hash }
        Position { Leverage IsCross Side SizeBefore Size }
        Fees { Fee FeeToken }
      }
    }
  }
}

Real-time liquidation alerts

Run it in the IDE: Hyperliquid Liquidations Stream ➤

subscription {
  Hyperliquid {
    PerpLiquidations {
      Block { Time }
      Liquidation {
        Market { Symbol }
        Method MarkPx LiquidatedUser
        Trader { Address }
        Execution { Price Size Side }
        Position { Leverage IsCross SizeBefore Size }
      }
    }
  }
}

Funding payments

PerpFundings records per-trader funding transfers at each hourly funding tick: the signed Amount (negative = the trader paid funding), the funding Rate applied and the position Size it applied to. A market whose funding rate is zero in an hour is not charged, so it has no rows for that tick.

Run it in the IDE: Hyperliquid Funding Payments ➤

query {
  Hyperliquid {
    PerpFundings(
      limit: {count: 50}
      orderBy: {descending: Block_Time}
      where: {Block: {Time: {since_relative: {hours_ago: 2}}}}
    ) {
      Block { Time }
      Funding {
        Market { Symbol Kind }
        Amount Rate Size
        Trader { Address }
      }
    }
  }
}

Filter to one wallet with where: {Funding: {Trader: {Address: {is: "0x..."}}}} to compute its total funding paid/received. The Hyperliquid Funding Payments API page has ready-made wallet queries: per-market totals, paid-only, date ranges and a live stream.

Current positions

CurrentPositions is a state cube: one row per trader and market with the latest position — signed Size (negative = short, "0" = closed), leverage, margin mode, and the Funding and RealizedPnl summed since the data window started (about 30 days back), not over the account's lifetime. It can be queried but not streamed.

• Size is exact for perps (native and HIP-3), even for a position opened before the data window: each hour the exchange charges funding on a market, it restates the size of every open position there, and the cube takes that size. A market whose funding rate is zero in an hour is not charged, so it is skipped that hour.
• Closed positions stay with Size "0"; skip them on the client.
• Spot and outcome balances are in the cube too, built only from trades inside the window. Filter Market: {IsPerp: true} for perps; note that PURR/USDC is a spot pair although its Kind reads perp.
• LastTime / LastBlock is the latest event of any kind on the position, the hourly funding included, so for an open perp position it is at least the last funding hour. LastTradeTime / LastTradeBlock is the account's last fill on that market (1970-01-01T00:00:00Z / 0 when it has none in the window).

Run it in the IDE: Hyperliquid Current Positions ➤

query {
  Hyperliquid {
    CurrentPositions(
      limit: {count: 50}
      orderBy: {descending: LastTradeTime}
      where: {Market: {Symbol: {is: "BTC"}}}
    ) {
      LastBlock
      LastTime
      LastTradeBlock
      LastTradeTime
      Market { Symbol Kind }
      Position { Size Leverage IsCross Funding RealizedPnl }
      Trader { Address }
    }
  }
}

Swap the filter to where: {Trader: {Address: {is: "0x..."}}, Market: {IsPerp: true}} to get every perp position of one trader.

For entry price, margin, unrealized PnL and funding over the position's life, and for the positions at a past moment, use SnapshotPositions: every open position from a snapshot, about every 12.5 minutes, kept 7 days. Market-wide open interest is on SnapshotMarkets.

Leverage updates

TraderLeverageUpdates fires whenever a trader changes leverage or switches between cross and isolated margin on a market.

Run it in the IDE: Hyperliquid Leverage Updates ➤

query {
  Hyperliquid {
    TraderLeverageUpdates(limit: {count: 50}, orderBy: {descending: Block_Time}) {
      Block { Time }
      LeverageUpdate {
        Leverage IsCross
        Market { Symbol }
        Trader { Address }
      }
    }
  }
}

PerpLiquidations, PerpFundings and TraderLeverageUpdates stream over WebSocket with the same shape — change query to subscription and drop limit/orderBy. CurrentPositions is query-only.

Related

• Liquidation History by Wallet
• Funding Payments by Wallet
• HIP-3 Stocks API — funding and liquidations on stock, index and commodity perps
• Track ZEC on Hyperliquid — positions, liquidations and funding for one market
• Snapshots API — every position, account, order and balance from snapshots