Hyperliquid WebSocket Trades and Candles: Snapshot, Dedupe Key, and Finality

• Public trades messages are documented as WsTrade[], but the supplied documentation does not document an isSnapshot flag for that feed.
• The supplied WsTrade documentation recommends (block_time, coin, tid) for a globally unique trade id.
• A community report in Hyperliquid Python SDK issue 326 observed an initial batch of recent trades without isSnapshot. The reported workaround is to deduplicate public trades using (time, coin, tid); that tuple is not the official global uniqueness recommendation.
• Candle pushes should be treated as the current state of the interval being streamed. The supplied documentation does not document a candle finality flag or revision guarantee, and the issue reports no explicit finalization signal.

What the WebSocket documentation specifies

As of Nov. 15, 2026, the public Hyperliquid WebSocket subscriptions page documents the following relevant behavior:

• A successful subscription is acknowledged with a message whose channel is subscriptionResponse.
• The subscription ack provides a snapshot of previous data for time-series data, such as user fills. Those snapshot messages are tagged with isSnapshot: true.
• For streaming user endpoints such as WsUserFills and WsUserFundings, the first message has isSnapshot: true, and subsequent streaming updates have isSnapshot: false.
• Public trades use this subscription shape:

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

The documented data format is WsTrade[].

• The WsTrade definition includes the note: “For a globally unique trade id, use (block_time, coin, tid).”
• Candles use this subscription shape:

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

Supported intervals listed on the page include 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 12h, 1d, 3d, 1w, and 1M. The documented data format is Candle[].

The documentation does not show an isSnapshot field for public trades, nor a candle finality flag in the supplied subscriptions page.

Community-reported behavior in issue 326

• In the commenter’s tests, the first trades message after the subscriptionResponse ack held the 30 most recent trades.
• That initial trades batch had no isSnapshot field, unlike userFills, userFundings, userTwapSliceFills, and userTwapHistory.
• Because there is no explicit snapshot boundary, the commenter recommends deduplicating public trades using the reported key (time, coin, tid).
• The same reported key can also handle overlap after a reconnect.
• The candle subscription streams the candle that is still open. Each push should be treated as the current state of that interval, not a final value.
• The issue leaves the exact semantics of WsTrade.time unresolved in the supplied sources; the sources do not confirm whether it is exactly block_time converted to Unix milliseconds or which event assigns it.

Reference client handling

The following examples are reference pseudocode based on the documented subscription shapes and the official WsTrade recommendation. They are not tested output.

Deduplicate public trades

seen_trades = set()

def handle_trades(trades):
    for trade in trades:
        # Official WsTrade docs recommend (block_time, coin, tid) for global uniqueness.
        key = (trade["block_time"], trade["coin"], trade["tid"])

        if key in seen_trades:
            continue

        seen_trades.add(key)
        process_trade(trade)

Use the same seen_trades set across reconnects if you want to avoid replaying trades that were already processed before the disconnect.

If your feed exposes time rather than block_time, the community report used (time, coin, tid) as a reported workaround; verify the field semantics before relying on it.

Treat candles as mutable interval state

current_candles = {}

def handle_candle(candle):
    open_time = candle["t"]
    current_candles[open_time] = candle
    update_ui_or_store(candle)

Because the supplied sources do not document a finality flag, do not mark a candle as final merely because a push arrived or because the interval boundary has passed. If your system requires finalized candles, use a separate finalization rule or data source that you can verify.

Sources

• Hyperliquid WebSocket subscriptions documentation
• Hyperliquid Python SDK issue 326: WsTrade.time, trades snapshots, and candle finality

Related

• Hyperliquid API Websocket Guide for Developers (2026)
• Hyperliquid WebSocket Subscriptions: Message Formats, Types, and Examples
• Hyperliquid Python SDK: Fix WebSocket Reconnect Subscription Drops and Duplicates (2026)

Affiliate disclosure

This article includes a Hyperliquid referral link. If you sign up through it, we may receive a commission.

Continue with Hyperliquid

Browse the Hyperliquid guide hub for the complete user journey.