Data Guide

Understanding the hyperliquid DEX and data characteristics

This section is 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, theset 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

Funding Rates and Fees

Historical Rates

Historical Funding Rates are available in hyperliquid.raw.perpetual_market_asset_contexts

Example Data

TIMESTAMP	COIN	DAY_BASE_VOLUME	DAY_NATURAL_VOLUME	OPEN_INTEREST	FUNDING	PREMIUM	IMPACT_PRICES	MARK_PRICE	MID_PRICE	ORACLE_PRICE	PREVIOUS_DAY_PRICE	MAX_LEVERAGE	_CREATED_AT	_UPDATED_AT
2025-09-12 00:15:00.000	SYRUP	4762555.0000000000	2159913.4026699993	11635584.0000000000	0.0000862455	0.0011820433	[“0.464999”, “0.465207”]	0.4650300000	0.4651100000	0.4644500000	0.4431300000	3	2025-09-12 00:16:10.342	2025-09-12 00:16:10.342
2025-09-12 00:15:00.000	MAV	6811783.0000000000	471417.9629660000	4238730.0000000000	0.0000125000	-0.0001864601	[“0.069577”, “0.069707”]	0.0696310000	0.0696570000	0.0697200000	0.0635690000	3	2025-09-12 00:16:10.342	2025-09-12 00:16:10.342
2025-09-12 00:15:00.000	PYTH	29175950.0000000000	5101855.4974899963	27527772.0000000000	0.0000098288	-0.0006291059	[“0.179335”, “0.179507”]	0.1795000000	0.1794650000	0.1796200000	0.1697300000	5	2025-09-12 00:16:10.342	2025-09-12 00:16:10.342

Fees

Fees are available in streams and as historical data.

Historical

Historical Funding Fees are available in hyperliquid.raw.misc_events

Example Data

Query: select * from hyperliquid.raw.misc_events where event:Funding is not null limit 3;

HASH	TIME	EVENT	_CREATED_AT	_UPDATED_AT
0x0000000000000000000000000000000000000000000000000000000000000000	2025-08-04 09:00:00.057	{"Funding": {"coin": "PENGU", "funding_amount": "0.000029", "funding_rate": "-0.0000076137", "szi": "109.0", "user": "0xffff407e5770f000ec93bc008d81b59acb505672"}}	2025-08-04 09:17:23.414	2025-08-04 10:47:28.542
0x0000000000000000000000000000000000000000000000000000000000000000	2025-08-21 09:00:00.023	{"Funding": {"coin": "HYPE", "funding_amount": "14.595776", "funding_rate": "0.0000271144", "szi": "-13000.0", "user": "0xfffafff1445fb2d469b7f2d87fb3eadb8b1aa87e"}}	2025-08-21 09:06:09.769	2025-08-21 10:48:14.265
0x0000000000000000000000000000000000000000000000000000000000000000	2025-08-31 13:00:00.000	{"Funding": {"coin": "kPEPE", "funding_amount": "-0.005145", "funding_rate": "0.0000125", "szi": "41658.0", "user": "0xffff407e5770f000ec93bc008d81b59acb505672"}}	2025-08-31 13:17:38.764	2025-08-31 15:17:37.427

Streams

Funding Fees are streamed in hyperliquid.misc_events

Example Payload

{
  "payload": {
    "hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "inner": {
      "Funding": {
        "coin": "BTC",
        "funding_amount": "0.049819",
        "funding_rate": "0.0000125",
        "szi": "-0.0355",
        "user": "0xee963ef70d2e0468bf63630071c6968ae5e3074e"
      }
    },
    "time": "2025-09-10T11:00:00.127249976"
  },
  "source": "source"
}

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 or the L4 Orderbook snapshot.

L2 Orderbook snapshot

L4 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

Trade Ids

Trade ids are not guaranteed to be unique.

Trade ids are a 50bit hash of the buyer and seller order ids.

For a unique id use coin, timestamp and trade id for trades and additionally user for fills.

Orders explained

The trading engine does not emit the orders in the same way that it does for fills, nor are they bound to trading engine timestamps.

They are not 1-1. For every order with the status filled you may not find a counter order with the status filled.

We’ll pick the only order with this timestamp that has the status filled.

At a first glace we’d expect to see another order with the status filled as well. (buyer and seller)

But this is not the case let’s see why.

select *
from hyperliquid.raw.orders 
where date_trunc('millisecond', status_change_timestamp) = '2025-09-03 05:46:43.881'::timestamp_ntz and status = 'filled';

It’s a filled order. If you across the timestamp, you will find it is the only filled order.

So let’s take the order id and find the corresponding fill.

select * from hyperliquid.raw.fills where order_id = '151749521496';

From there we get the trade id (See trade ids section for caveats info on trade ids)

select * from hyperliquid.raw.fills where trade_id = '879183392645577';

Now we should see two fills, so get the order id from the other fill, the counter order

select * from hyperliquid.raw.orders where order_id = '151749449008';

We found the counter order.

But we don’t have a filled status; you can see it was opened then cancelled.

This is because the time in force is Alo

• It went into the order book
• Got a partial fill (you can see the size is less on the cancelled than the open)
• It was cancelled, so as to not remove liquidity from the order book.

Time in Force Explained

Alo

The ALO (Add Liquidity Only) time-in-force option works similarly to “Post Only” on other exchanges.

How ALO Works

• When you place an order with ALO, the system ensures that your order will only add liquidity to the order book.
• If your order would immediately match with an existing order (thus taking liquidity), Hyperliquid will automatically cancel it instead of executing.
• This prevents you from accidentally paying taker fees, guaranteeing that you only act as a maker.

GTC

GTC (Good ’Til Canceled)

• A GTC order will remain active on the order book until it is either filled or manually canceled by you.
• It does not expire automatically, regardless of how much time passes.
• This is the default time-in-force on most exchanges, including Hyperliquid.
• Useful if you want your order to stay in the market and wait for execution, even if it takes hours or days.

IOC

IOC (Immediate or Cancel)

• An IOC order must be filled immediately (fully or partially) when it reaches the order book.
• Any portion of the order that cannot be instantly matched will be canceled right away.
• This makes IOC useful when you want to execute as much as possible instantly, but don’t want leftover orders sitting on the book.
• Traders often use IOC for quick entries/exits or to avoid resting exposure on the book.