This a collection of extra documentation on the workings of Hyperliquid L1.

It is not exhaustive, rather it complements the Hyperliquid Docs.

For each section under Sources where the Parent is

  • Datastreams then entity is the Kafka Topic name
  • Snowflake then the entity is the table name

​
Assets

In a lot of the data sources, especially datastreams and tables in the raw schema you will find assets listed as a number.

This is how Hyperliquid refers to them. They are normally a trading Pair.

Where the asset is simply an index.

Perpetuals - index in the universe field returned by the meta response.

Spot - 10000 + index in the universe field returned by the spotMeta response.

For example, when submitting an order for PURR/USDC, the asset that should be used is 10000 because its asset index in the spot metadata is 0.

​
Spot

Spot Pairs are prefixed by an @

The Spot Pair PURR/USDC is the only one not referred to by an @index and instead you will see it referred by PURR/USDC

You can fetch the Hyperliquid Spot metadata here.

Samples

{
  "tokens": [
...
    {
      "name": "HYPE",
      "szDecimals": 2,
      "weiDecimals": 8,
      "index": 150,
      "tokenId": "0x0d01dc56dcaaca66ad901c959b4011ec",
      "isCanonical": false,
      "evmContract": null,
      "fullName": "Hyperliquid",
      "deployerTradingFeeShare": "0.0"
    }
...
  ],
  "universe": [
...
    {
      "tokens": [
        150,
        0
      ],
      "name": "@107",
      "index": 107,
      "isCanonical": false
    }
...
  ]
}

Looking at the universe section we can see a index 107 with name @107

@107 is what you will see in the hyperliquid data, and this refer to the trading pair HYPE/USDC

0 = USDC
150 = Hyper

​
Perpetuals

You can fetch the Hyperliquid Perpetual metadata here.

Perpetuals are easier than Spot, as the name is the Token which trades against USDC.

For example

  • HYPE will be HYPE/USDC.
  • BTC will be BTC/USDC

​
Orders

For order types and options see the hyperliquid docs

​
Market order fills

  • Sources
    • Datastreams
      • hyperliquid.orders
      • hyperliquid.fills
    • Snowflake
      • hyperliquid.raw.orders
  • Filter by:
    • status = 'filled'
    • type = 'market'

​
Limit order fills

  • Sources
    • Datasteam
      • hyperliquid.orders
      • hyperliquid.fills
    • Snowflake
      • hyperliquid.raw.orders
  • Filter by
    • status = 'filled'
    • type = 'limit'

​
What are TWAP Orders?

It is an order which is divided into multiple suborders over a period of time set by user.

A suborder is sent every 30 seconds during the course of the TWAP.

TWAP stands for Time-Weighted Average Price.

In hyperliquid TWAPs are executed automatically by the validators and as such they do not have a transaction hash, only the order to place a twap has a transaction hash. As such you will very often see trades and fills with 0x0000000000000000000000000000000000000000000000000000000000000000 as the transaction hash.

For trades this means one side of the trade is a TWAP.

For fill this means it is a TWAP fill.

​
Twap fills

  • Sources
    • Datastreams
      • hyperliquid.trades
      • hyperliquid.fills
    • Snowflake
      • hyperliquid.raw.transactions
  • Filter by
    • hash = '0x0000000000000000000000000000000000000000000000000000000000000000'

​
Twap Open

  • Sources
    • Datastreams
      • hyperliquid.transactions
    • Snowflake
      • hyperliquid.raw.transactions
  • Filter by
    • action:type = 'twapOrder'

​
Twap Cancel

  • Sources
    • Datastreams
      • hyperliquid.transactions
    • Snowflake
      • hyperliquid.raw.transactions
  • Filter by
    • action:type = 'twapCancel'

​
Staking Activity

  • Sources
    • Datastream
      • hyperliquid.misc_events
    • Snowflake
      • hyperliquid.raw.misc_events
  • Filter by
    • inner: { CDeposit for deposits
    • inner: { CWithdrawal for withdrawals

​
Liquidations

There are two types of liquidations in hyperliquid.

Market Liquidations

This is when Hyperliquid places an order to sell (for longs) and buy (for shorts) a user’s position on the market.

HLP Vault Liquidations

This is a last effort, when the above Market Liquidations fails, ie due to lack of liquidity. In this case the HLP Vault acquires the position, and takes the loss (if any).

​
Market Liquidations

  • Datastreams
    • hyperliquid.fills
  • Snowflake
    • hyperliquid.raw.fills

​
Market Liquidation Example

{
...
  "liquidation": {
    "liquidatedUser": "0x444591887598c8ce607e8315daa61ead3dc0e912",
    "markPx": "2.3725",
    "method": "market"
  },
...
}

This will be wrapped in a payload key

{
  "payload": [
    "0x4e8ffa69c78d7a067e1795fbe16a5c80c90b6c05",
    {
      "closedPnl": "-9.94483",
      "coin": "ETH",
      "crossed": false,
      "dir": "Liquidated Isolated Long",
      "fee": "0.0",
      "feeToken": "USDC",
      "hash": "0x13286c0383f6dbbf94db0425f954ba0205a300395397739c419f7da34f95f99d",
      "liquidation": {
        "liquidatedUser": "0x4e8ffa69c78d7a067e1795fbe16a5c80c90b6c05",
        "markPx": "2323.3",
        "method": "backstop"
      },
      "oid": 104754754832,
      "px": "2316.0",
      "side": "A",
      "startPosition": "0.1037",
      "sz": "0.1037",
      "tid": 361622066638684,
      "time": 1750541100096
    }
  ],
  "source": "source"
}

​
HLP Vault Liquidations

  • Sources
    • Datastreams
      • hyperliquid.misc_events
      • hyperliquid.fills
    • Snowflake
      • hyperliquid.raw.misc_events
      • hyperliquid.raw.fills

The HLP Vault Liquidation shows up in both the misc events and the fills.

In the fills it will show up with both sides, and one side being the HLP Vault.

​
Fills

Liquidated User Fill

{
  "payload": [
    "0x4e8ffa69c78d7a067e1795fbe16a5c80c90b6c05",
    {
      "closedPnl": "-9.94483",
      "coin": "ETH",
      "crossed": false,
      "dir": "Liquidated Isolated Long",
      "fee": "0.0",
      "feeToken": "USDC",
      "hash": "0x13286c0383f6dbbf94db0425f954ba0205a300395397739c419f7da34f95f99d",
      "liquidation": {
        "liquidatedUser": "0x4e8ffa69c78d7a067e1795fbe16a5c80c90b6c05",
        "markPx": "2323.3",
        "method": "backstop"
      },
      "oid": 104754754832,
      "px": "2316.0",
      "side": "A",
      "startPosition": "0.1037",
      "sz": "0.1037",
      "tid": 361622066638684,
      "time": 1750541100096
    }
  ],
  "source": "source"
}

HLP Vault Fill

{
  "payload": [
    "0xb0a55f13d22f66e6d495ac98113841b2326e9540",
    {
      "closedPnl": "0.0",
      "coin": "ETH",
      "crossed": true,
      "dir": "Liquidated Isolated Long",
      "fee": "0.0",
      "feeToken": "USDC",
      "hash": "0x13286c0383f6dbbf94db0425f954ba0205a300395397739c419f7da34f95f99d",
      "liquidation": {
        "liquidatedUser": "0x4e8ffa69c78d7a067e1795fbe16a5c80c90b6c05",
        "markPx": "2323.3",
        "method": "backstop"
      },
      "oid": 104754754832,
      "px": "2316.0",
      "side": "B",
      "startPosition": "7177.3205",
      "sz": "0.1037",
      "tid": 361622066638684,
      "time": 1750541100096
    }
  ],
  "source": "source"
}

​
Misc Events

{
  "payload": {
    "hash": "0x13286c0383f6dbbf94db0425f954ba0205a300395397739c419f7da34f95f99d",
    "inner": {
      "LedgerUpdate": {
        "delta": {
          "accountValue": "0.756264",
          "leverageType": "Isolated",
          "liquidatedNtlPos": "240.92621",
          "liquidatedPositions": [
            {
              "coin": "ETH",
              "szi": "0.1037"
            }
          ],
          "type": "liquidation"
        },
        "users": [
          "0x4e8ffa69c78d7a067e1795fbe16a5c80c90b6c05"
        ]
      }
    },
    "time": "2025-06-21T21:25:00.096291909"
  },
  "source": "source"
}

​
Order Book

The easiest way to keep an updated order book is to read from the Datastream orders and applying it to a snapshot of the L2 Orderbook.

L2 Orderbook snapshot

Once you have the snapshot, you can use the orders datastream to update the snapshot.

All the possible order statuses can be found in the Hyperliquid Docs

We are working on providing an L4 Orderbook snapshot.