Hyperliquid gRPC and WebSocket troubleshooting

Start with the endpoint and subscription type. HyperEVM, HyperCore Info, order-book WebSocket, and gRPC expose different APIs.

Which endpoint should I use?

An eth_subscribe request belongs to HyperEVM JSON-RPC. An l4Book subscription belongs to the order-book service.

Use the endpoint's documented authentication. gRPC uses TLS and x-api-key metadata. WebSocket and HTTP connection examples appear in their respective references.

Why does a symbol return no data?

Use the exact market identifier, including case and any decentralized exchange prefix. A HIP-3 market such as xyz:TSLA is distinct from an unprefixed symbol.

Discover perpetual markets with meta, deployed exchanges with perpDexs, and spot markets with spotMeta.

Specify the relevant exchange when the Info method requires it. A human-readable ticker is not always the feed's market identifier.

Current metadata describes current markets. Historical research needs metadata from the period under study, including listings, delistings, and asset-index mappings.

Can I subscribe to several markets with one key?

Yes. Send separate subscriptions on the order-book WebSocket connection using each subscription's documented parameters.

V3 gRPC methods use their own coin selectors. Check the method reference before moving a WebSocket subscription shape into gRPC.

Using several keys or connections does not multiply an account's shared throughput limit. See request counting.

Why is a filtered gRPC stream quiet or disconnected?

V3 raw-feed filters skip records with zero matching events. Silence can mean that the selected user or market has no matching events.

Raw streams carry no heartbeat frames. HTTP/2 keepalive pings test connection liveness; they do not create matching application records.

An intermediary can enforce a response idle timeout even when transport keepalive succeeds. A 504 alone does not prove that your filter is invalid.

Check the client deadline, proxy timeout, and gRPC status. Compare a short unfiltered stream with the same feed to separate filter silence from feed inactivity.

Reconnect with backoff after transient failures. Use the last processed cursor when the method supports replay.

How do I resume without losing or double-counting records?

V3 raw-feed positions are inclusive. Resume from the last processed Record.block_number or Record.timestamp, then deduplicate the repeated record.

Commit a cursor after processing and storing the whole record. Preserve event identity within each block when downstream writes can partially succeed.

Cursor fields are optional. Do not invent a zero cursor when metadata is absent.

Replay retention varies by feed and endpoint. NOT_FOUND can mean the requested position is outside retained history; use the archive for older data.

Typed market streams are live-only. After an L2/L4 disconnect, resubscribe and rebuild from the opening snapshot before applying new diffs.

WebSocket subscriptions belong to a connection. Send them again after reconnecting. A new connection does not inherit previous subscriptions.

Why is the connection fast but the data old?

Measure connection time and data freshness separately. A fast handshake does not establish the age of a snapshot or update.

Record the source block timestamp, block number, and your local receipt time. Synchronize your clock before calculating wall-clock lag.

Compare the same market and block across sources. A difference in arrival time can come from source state, replay, processing, or the network path.

An old opening snapshot requires updates to reach current state. If updates stop, reconnect and rebuild the book rather than trading on stale state.

How is streaming usage counted?

Each delivered gRPC message counts toward metered usage. Message count differs from fill count because one raw record can contain several events.

WebSocket usage includes sent and received messages. Several subscriptions can increase usage through several delivered updates.

Filtering reduces delivered matching records. It does not multiply your account's limit or extend replay retention.

For method-specific counting, see rate limits and the selected API reference.

Does peering provide the same service as an API subscription?

No. Peering provides gossip connectivity for a node you operate. Your node still needs its own storage, synchronization, and local API services.

Reserved peers carry blocks and the full mempool. They do not promise validator priority or an earlier view than every other subscriber.

The two reserved peers use separate hosts in one selected region. This provides host redundancy; it does not provide geographic redundancy.

See peering requirements and setup for static public IP addresses, ports, and node configuration.

How do I validate a historical research dataset?

Use archive research and validation. It covers manifests, timestamps, TWAP joins, liquidations, snapshots, account state, and data-use rights.

For access and HTTP errors, use RPC troubleshooting.