MarketLens Hyperliquid L4 WebSocket API 1.0.0

Every order, take profit, stop loss and liquidation price of a Hyperliquid coin, straight from our own Hyperliquid node, as it changes: each block's changes as one update.

See it live at marketlens.app/data/hyperliquid, which draws this same stream and has samples that read it in Python, TypeScript and Rust.

How a connection goes

Connect to a channel's address for a coin. You get a snapshot of each of its channels, then its deltas, each one block's changes. Every binary message is one Parquet file, a snapshot or a delta of one channel; its key-value metadata is its head (snapshot, channel, coin, epoch, seq, ts, below), its rows are orders.

  • A snapshot starts an epoch: replace that channel's book with it. A delta of another epoch than its channel's snapshot is void.
  • seq counts an epoch's deltas, per channel; a snapshot's is 0. A gap means a delta was missed: connect again for a fresh snapshot.
  • A later snapshot can come at any time, when the stream starts over: replace the channel's book again.

Rows

An order is known by its id; on liquidations, which have none, a position by its user. In a delta, a row with only its key removes what it's the key of, and removals come first; every other row adds an order, or replaces what had its key. Within each kind, rows are sorted by key.

Prices and sizes are Parquet decimals at the coin's own precision, the same in every file of the coin: a size has the coin's szDecimals, a price 6 decimals less those on a perp, 8 less on a spot pair, as Hyperliquid itself allows (its tick and lot sizes).

Pings

The server pings each connection every 2 s with a text message, {"ping":<n>}. Answer each with {"pong":<n>}, the same number: one unanswered for 6 s closes the connection. So does falling too far behind on reading.

Access

HYPE and BTC are free, with no key. Other coins need a key: ask us for one at @marketlens_app on X or on Discord, and send it as Authorization: Bearer <key>, or as ?key= from a browser, which can't set a WebSocket's headers. An unknown or revoked key is refused with 401; a coin the key doesn't reach, with 403.

Servers

  • wss://api.marketlens.app/data/hyperliquid/l4wssproduction

    Free for HYPE and BTC without a key; other coins with one.

    Security:
    • HTTP
      • Scheme: bearer

      A key, as Authorization: Bearer <key> on the handshake. Not needed for HYPE and BTC.

    • HTTP API key
      • Name: key
      • In: query

      The same key as ?key=, for a browser, which can't set a WebSocket's headers.

Operations

  • RECEIVE /order_book/{coin}

    The order book: every resting order, bids and asks, at its price. Each delta is one block's changes; its ts is the block's time on Hyperliquid's chain.

    The order book's snapshot, then each block's delta.

    Operation IDreceiveOrderBook

    Available only on servers:

    object
    coinstring
    required

    Hyperliquid's name for the coin, the rest of the path, as it is: HYPE, BTC, a builder dex's xyz:XYZ100, a spot pair's @107 or PURR/USDC.

      Examples values:
    • "HYPE"
    • "BTC"

    Accepts one of the following messages:

    • #0Order book file

      A snapshot or delta of the order book, as one Parquet file.

      Message IDfile
      array<object>

      A file's rows. Parquet, one row group, Snappy compressed:

      id            optional int64 (INTEGER(64, false))
      ts            optional int64 (TIMESTAMP(MILLIS, true))
      price         optional int64 (DECIMAL(18, p))
      size          optional int64 (DECIMAL(18, s))
      user          optional fixed_len_byte_array(20)
      position_size optional int64 (DECIMAL(18, s))
      

      p and s are the coin's price and size decimals. A row with only its key (id, or user on liquidations) removes; the others add.

      object

      A file's head, its Parquet key-value metadata: every value a string.

      Examples

    • #1Ping

      Every 2 s, as text: answer it with a pong.

      Message IDping
      object

      Examples

  • SEND /order_book/{coin}

    The order book: every resting order, bids and asks, at its price. Each delta is one block's changes; its ts is the block's time on Hyperliquid's chain.

    A pong for each ping.

    Operation IDanswerOrderBookPings

    Available only on servers:

    object
    coinstring
    required

    Hyperliquid's name for the coin, the rest of the path, as it is: HYPE, BTC, a builder dex's xyz:XYZ100, a spot pair's @107 or PURR/USDC.

      Examples values:
    • "HYPE"
    • "BTC"

    Accepts the following message:

    Pong

    Each ping's answer, as text, with its number: within 6 s, or the connection is closed.

    Message IDpong
    object

    Examples

  • RECEIVE /tpsl/{coin}

    Take profits and stop losses waiting to trigger, each at its trigger price, as two channels on one connection: take_profits and stop_losses, each with its own snapshot and seq. They aren't in the order book until they trigger.

    One of size 0 is a position's: it closes the whole position, and its position_size is that position's size as of the block, signed like size (0 if there's none it would close). It's empty on every other order.

    The take profits' and the stop losses' snapshots, then each one's deltas.

    Operation IDreceiveTpsl

    Available only on servers:

    object
    coinstring
    required

    Hyperliquid's name for the coin, the rest of the path, as it is: HYPE, BTC, a builder dex's xyz:XYZ100, a spot pair's @107 or PURR/USDC.

      Examples values:
    • "HYPE"
    • "BTC"

    Accepts one of the following messages:

    • #0Take profits or stop losses file

      A snapshot or delta of `take_profits` or `stop_losses`, as one Parquet file.

      Message IDfile
      array<object>

      A file's rows. Parquet, one row group, Snappy compressed:

      id            optional int64 (INTEGER(64, false))
      ts            optional int64 (TIMESTAMP(MILLIS, true))
      price         optional int64 (DECIMAL(18, p))
      size          optional int64 (DECIMAL(18, s))
      user          optional fixed_len_byte_array(20)
      position_size optional int64 (DECIMAL(18, s))
      

      p and s are the coin's price and size decimals. A row with only its key (id, or user on liquidations) removes; the others add.

      object

      A file's head, its Parquet key-value metadata: every value a string.

      Examples

    • #1Ping

      Every 2 s, as text: answer it with a pong.

      Message IDping
      object

      Examples

  • SEND /tpsl/{coin}

    Take profits and stop losses waiting to trigger, each at its trigger price, as two channels on one connection: take_profits and stop_losses, each with its own snapshot and seq. They aren't in the order book until they trigger.

    One of size 0 is a position's: it closes the whole position, and its position_size is that position's size as of the block, signed like size (0 if there's none it would close). It's empty on every other order.

    A pong for each ping.

    Operation IDanswerTpslPings

    Available only on servers:

    object
    coinstring
    required

    Hyperliquid's name for the coin, the rest of the path, as it is: HYPE, BTC, a builder dex's xyz:XYZ100, a spot pair's @107 or PURR/USDC.

      Examples values:
    • "HYPE"
    • "BTC"

    Accepts the following message:

    Pong

    Each ping's answer, as text, with its number: within 6 s, or the connection is closed.

    Message IDpong
    object

    Examples

  • RECEIVE /liquidations/{coin}

    Every open position that has a liquidation price, at that price, sized by the position: a long's a bid, below the price; a short's an ask, above it, its size negative. A position opened, changed or closed shows within about a second of its trade, and every position is refreshed each 15 s.

    A row is a position, known by its user: price its liquidation price, size the position, ts when it last changed; no id. The head's ts is when its prices were taken.

    The positions' snapshot, then each change.

    Operation IDreceiveLiquidations

    Available only on servers:

    object
    coinstring
    required

    Hyperliquid's name for the coin, the rest of the path, as it is: HYPE, BTC, a builder dex's xyz:XYZ100, a spot pair's @107 or PURR/USDC.

      Examples values:
    • "HYPE"
    • "BTC"

    Accepts one of the following messages:

    • #0Liquidations file

      A snapshot or delta of the positions at their liquidation prices, as one Parquet file.

      Message IDfile
      array<object>

      A file's rows. Parquet, one row group, Snappy compressed:

      id            optional int64 (INTEGER(64, false))
      ts            optional int64 (TIMESTAMP(MILLIS, true))
      price         optional int64 (DECIMAL(18, p))
      size          optional int64 (DECIMAL(18, s))
      user          optional fixed_len_byte_array(20)
      position_size optional int64 (DECIMAL(18, s))
      

      p and s are the coin's price and size decimals. A row with only its key (id, or user on liquidations) removes; the others add.

      object

      A file's head, its Parquet key-value metadata: every value a string.

      Examples

    • #1Ping

      Every 2 s, as text: answer it with a pong.

      Message IDping
      object

      Examples

  • SEND /liquidations/{coin}

    Every open position that has a liquidation price, at that price, sized by the position: a long's a bid, below the price; a short's an ask, above it, its size negative. A position opened, changed or closed shows within about a second of its trade, and every position is refreshed each 15 s.

    A row is a position, known by its user: price its liquidation price, size the position, ts when it last changed; no id. The head's ts is when its prices were taken.

    A pong for each ping.

    Operation IDanswerLiquidationsPings

    Available only on servers:

    object
    coinstring
    required

    Hyperliquid's name for the coin, the rest of the path, as it is: HYPE, BTC, a builder dex's xyz:XYZ100, a spot pair's @107 or PURR/USDC.

      Examples values:
    • "HYPE"
    • "BTC"

    Accepts the following message:

    Pong

    Each ping's answer, as text, with its number: within 6 s, or the connection is closed.

    Message IDpong
    object

    Examples

Messages

  • #1Order book file

    A snapshot or delta of the order book, as one Parquet file.

    Message IDorderBookFile
    array<object>

    A file's rows. Parquet, one row group, Snappy compressed:

    id            optional int64 (INTEGER(64, false))
    ts            optional int64 (TIMESTAMP(MILLIS, true))
    price         optional int64 (DECIMAL(18, p))
    size          optional int64 (DECIMAL(18, s))
    user          optional fixed_len_byte_array(20)
    position_size optional int64 (DECIMAL(18, s))
    

    p and s are the coin's price and size decimals. A row with only its key (id, or user on liquidations) removes; the others add.

    object

    A file's head, its Parquet key-value metadata: every value a string.

  • #2Take profits or stop losses file

    A snapshot or delta of `take_profits` or `stop_losses`, as one Parquet file.

    Message IDtpslFile
    array<object>

    A file's rows. Parquet, one row group, Snappy compressed:

    id            optional int64 (INTEGER(64, false))
    ts            optional int64 (TIMESTAMP(MILLIS, true))
    price         optional int64 (DECIMAL(18, p))
    size          optional int64 (DECIMAL(18, s))
    user          optional fixed_len_byte_array(20)
    position_size optional int64 (DECIMAL(18, s))
    

    p and s are the coin's price and size decimals. A row with only its key (id, or user on liquidations) removes; the others add.

    object

    A file's head, its Parquet key-value metadata: every value a string.

  • #3Liquidations file

    A snapshot or delta of the positions at their liquidation prices, as one Parquet file.

    Message IDliquidationsFile
    array<object>

    A file's rows. Parquet, one row group, Snappy compressed:

    id            optional int64 (INTEGER(64, false))
    ts            optional int64 (TIMESTAMP(MILLIS, true))
    price         optional int64 (DECIMAL(18, p))
    size          optional int64 (DECIMAL(18, s))
    user          optional fixed_len_byte_array(20)
    position_size optional int64 (DECIMAL(18, s))
    

    p and s are the coin's price and size decimals. A row with only its key (id, or user on liquidations) removes; the others add.

    object

    A file's head, its Parquet key-value metadata: every value a string.

  • #4Ping

    Every 2 s, as text: answer it with a pong.

    Message IDping
    object
  • #5Pong

    Each ping's answer, as text, with its number: within 6 s, or the connection is closed.

    Message IDpong
    object

Schemas

  • object

    A file's head, its Parquet key-value metadata: every value a string.

  • array<object>

    A file's rows. Parquet, one row group, Snappy compressed:

    id            optional int64 (INTEGER(64, false))
    ts            optional int64 (TIMESTAMP(MILLIS, true))
    price         optional int64 (DECIMAL(18, p))
    size          optional int64 (DECIMAL(18, s))
    user          optional fixed_len_byte_array(20)
    position_size optional int64 (DECIMAL(18, s))
    

    p and s are the coin's price and size decimals. A row with only its key (id, or user on liquidations) removes; the others add.

  • object