Hyperliquid WebSocket Subscriptions: Message Formats, Types, and Examples

Subscription message

The subscription message format is:

{
  "method": "subscribe",
  "subscription": {
    "type": "<subscription_type>"
  }
}

The subscription object must include the type-specific properties for the feed you want.

For time-series data, such as user fills, the subscription acknowledgement can include a snapshot of previous data. Snapshot messages are tagged with isSnapshot: true. If you have already processed the previous messages, you can ignore the snapshot.

Supported subscription types

The following subscription types are documented in the source.

Example subscription messages

The examples below are constructed from the documented subscription formats.

Subscribe to all mid prices:

{
  "method": "subscribe",
  "subscription": {
    "type": "allMids",
    "dex": "<dex>"
  }
}

Subscribe to notifications for a user:

{
  "method": "subscribe",
  "subscription": {
    "type": "notification",
    "user": "<address>"
  }
}

Subscribe to candle updates:

{
  "method": "subscribe",
  "subscription": {
    "type": "candle",
    "coin": "<coin_symbol>",
    "interval": "1m"
  }
}

Subscribe to order book updates:

{
  "method": "subscribe",
  "subscription": {
    "type": "l2Book",
    "coin": "<coin_symbol>"
  }
}

Subscribe to user fills:

{
  "method": "subscribe",
  "subscription": {
    "type": "userFills",
    "user": "<address>"
  }
}

Response and data formats

For a successful subscription, the server responds with a message whose channel property is "subscriptionResponse". The data field contains the original subscription.

After that, the server sends messages with the channel property set to the corresponding subscription type, for example "allMids", and the data field contains the subscribed data.

For streaming user endpoints such as WsUserFills and WsUserFundings, the first message has isSnapshot: true, and subsequent streaming updates have isSnapshot: false.

Other documented behavior includes:

• WsUserFills: fills snapshot followed by streaming fills.
• WsUserFundings: funding payments snapshot followed by funding payments on the hour.
• WsUserNonFundingLedgerUpdates: ledger updates not including funding payments, such as withdrawals, deposits, transfers, and liquidations.
• WsBbo: BBO updates are sent only if the BBO changes on a block.

User address pitfall

For account-data subscriptions, pass the actual address of the master or sub-account you want to query. A common pitfall is using an agent wallet address, which can lead to an empty result.

fastAssetCtxs decoding

The fastAssetCtxs feed returns base64-encoded and compressed WsFastAssetCtxs data. The docs specify this decode order:

1. Base64-decode to bytes.
2. Decompress as a raw DEFLATE stream, RFC 1951. There is no zlib RFC 1950 or gzip RFC 1952 wrapper.
3. UTF-8 decode and parse as JSON.

• Python: zlib.decompress(b, wbits=-15)
• Browsers: new DecompressionStream("deflate-raw")
• Node: fflate.inflateSync

q1ZyCnFWsqpWyk0syg6oULJSsjQ3NTDQM1Wq1VFyDfFAkTI2MzXQMwJLVVRWWfmFuTiiyBuamOoZKdXWAgA=

Decoded result:

{
  "BTC": {
    "markPx": "97500.5"
  },
  "ETH": {
    "markPx": "3650.25"
  },
  "xyz:NVDA": {
    "markPx": "145.2"
  }
}

The first fastAssetCtxs message is a snapshot. Subsequent messages contain only coins that have updated, and fields with no updates are omitted.

Unsubscribing

To stop receiving a feed, send the unsubscribe message described in the docs. The subscription object should match the original subscription message so the server can identify the feed.

Unsubscribing from one feed does not affect other active subscriptions. To unsubscribe from multiple feeds, send multiple unsubscribe messages, each with the appropriate subscription details.

Related references

• Hyperliquid API Websocket Guide for Developers (2026)
• Hyperliquid Websocket Reconnect Fix 2026
• Hyperliquid API Rate Limits & User Limits (2026)
• Hyperliquid API Error Responses: Troubleshooting Guide

Create a Hyperliquid account

This article contains a Hyperliquid referral link. If you sign up, we may earn a commission. The offer provides a 4% fee discount on the first $25M of volume per account. Vaults and sub-accounts are excluded.

Continue with Hyperliquid

Browse the Hyperliquid guide hub for the complete user journey.