Hyperliquid gRPC API
Versioned reference for Dwellir's Hyperliquid V3 raw feeds and market streams, with V2 compatibility guidance and Protocol Buffer contracts.
Hyperliquid RPC endpoint: endpoint URLs, plans and pricing.
For quiet filtered streams, proxy timeouts, recovery, and usage, see streaming troubleshooting.
Dwellir's Hyperliquid gRPC endpoint exposes the V3 raw-feed and typed market-streaming services alongside the V2 compatibility service. Use V3 for new integrations. Existing V2 clients can continue using their generated V2 stubs and the established method URLs in this reference.
Pricing and access
The gRPC add-on costs $299/month on an API plan, plus metered usage: each streamed message costs 1 API credit. The Dedicated Node Cluster starts at $4,000/month and 2 dedicated backend nodes, and includes both add-ons with unmetered access.
How the data surfaces fit together
The gRPC API is the live transport for raw node feeds and derived V3 market views. Start with How Hyperliquid works for the relationship between node files, order books, indexed products, and archives.
Versions and services
| Version | Service | Surface |
|---|---|---|
| V3 | hyperliquid_l1_gateway.v3.HyperliquidL1Gateway | Feed discovery plus eight raw streams and eight raw unary lookups |
| V3 | hyperliquid_l1_gateway.v3.MarketStreaming | Fourteen typed, live market streams |
| V2 | hyperliquid_l1_gateway.v2.HyperliquidL1Gateway | Compatibility surface for the fourteen established raw stream and unary methods |
Download the published contracts as v3.proto and v2.proto. Regenerate client stubs when you change versions; the V2 and V3 packages, request messages, and response messages are different.
curl -fsSLo v3.proto https://www.dwellir.com/docs/hyperliquid/grpc/v3.protoAuthentication
Connect over TLS and pass the API key in the x-api-key metadata header. Keep the endpoint and credential outside source control:
grpcurl -proto v3.proto \
-H "x-api-key: ${DWELLIR_API_KEY}" \
"${HYPERLIQUID_GRPC_ENDPOINT}" \
hyperliquid_l1_gateway.v3.HyperliquidL1Gateway/ListFeedsV3 raw-feed service
The V3 raw service declares seventeen RPCs: ListFeeds, eight server streams, and eight unary lookups.
| Feed concept | Stream | Unary | Source |
|---|---|---|---|
| Configured-feed discovery | ListFeeds | - | Gateway registry |
| Blocks | StreamBlocks | GetBlock | replica_cmds |
| Fills | StreamFills | GetFills | node_fills_by_block |
| Raw book diffs | StreamRawBookDiffs | GetRawBookDiffs | node_raw_book_diffs_by_block |
| Order statuses | StreamOrderStatuses | GetOrderStatuses | node_order_statuses_by_block |
| Miscellaneous events | StreamMiscEvents | GetMiscEvents | misc_events_by_block |
| TWAP statuses | StreamTwapStatuses | GetTwapStatuses | node_twap_statuses_by_block |
| Pre-consensus mempool transactions | StreamMempoolTxs | GetMempoolTxs | mempool_txs |
| Generated order-book snapshots | StreamOrderbookSnapshots | GetOrderbookSnapshot | Generated snapshot output |
StreamOrderbookSnapshots and GetOrderbookSnapshot are the public methods for generated order-book snapshots. Snapshots intentionally sit outside the raw-feed registry, so absence from ListFeeds does not describe their status. Snapshot availability and maximum response size vary by endpoint. Oversized responses return RESOURCE_EXHAUSTED.
The mempool feed carries signed transaction requests the node received before block inclusion. They are not guaranteed to land in a block. Mempool records have no block number, so the feed is positioned by receive time only and is not filterable. V2 has no mempool methods.
Shared request contract
All raw streams accept StreamRequest; all raw unary methods accept GetRequest.
message Position {
oneof position {
int64 timestamp = 1;
int64 block_number = 2;
int64 timestamp_ns = 3;
}
}
message Filter {
repeated FieldFilter fields = 1;
}
message FieldFilter {
string field = 1;
FilterOp op = 2;
repeated string values = 3;
}
message StreamRequest {
Position position = 1;
Filter filter = 2;
Progress progress = 3; // unset = no progress frames
}
message Progress {
uint32 interval_ms = 1; // 0 = feed default
}
message GetRequest {
Position position = 1;
Filter filter = 2;
}Position is inclusive. A positioned stream replays the selected record and all subsequent retained records, then tails live data. A positioned unary call returns the record at the requested block number or the nearest record at or after a timestamp.
Leave position unset to tail new records in a raw stream. For the seven registry feeds, an unpositioned unary call waits for the next record written after the call begins; it does not return the most recently stored record. The snapshot contract is different: an unpositioned snapshot stream sends the latest snapshot and then newer snapshots, while an unpositioned GetOrderbookSnapshot returns the latest existing snapshot.
V3 uses block_number and timestamp in Unix milliseconds. V2 uses block_height and timestamp_ms. The mempool feed accepts timestamp and timestamp_ns (Unix nanoseconds) instead of block_number; every other raw feed rejects timestamp_ns. ListFeeds.position_kinds lists the cursor kinds each feed accepts, and any other kind returns INVALID_ARGUMENT. In V3, explicitly setting any cursor to 0 returns INVALID_ARGUMENT; omit position for the unpositioned behavior. A Record.block_number is the sequential Hyperliquid block number and is never the potentially skipping HyperBFT consensus value in abci_block.round.
Filtering
The fills, raw-book-diffs, order-statuses, and TWAP-statuses feeds accept users, coins, and dexes field filters. A dexes value matches the coin's HIP-3 dex prefix exactly (xyz for xyz:BTC); an empty string selects coins without a dex prefix. Miscellaneous events accept users only. Blocks, mempool transactions, and order-book snapshots do not accept filters. Use ListFeeds.filter_fields as the deployed capability source for registry feeds.
- Constraints for separate fields use AND semantics.
- Values within one field use OR semantics.
- User addresses match case-insensitively.
- Coin identifiers match case-sensitively.
FILTER_OP_UNSPECIFIEDis treated asFILTER_OP_IN.- Unknown or duplicate fields, empty names, and empty value lists return
INVALID_ARGUMENT. - An unsupported operator returns
UNIMPLEMENTED.
Filtering preserves the raw block envelope and removes non-matching entries from its events array. A streaming filter skips records with zero matching events, so a tightly filtered stream can be silent for minutes; opt in to progress frames to keep it open and advance its resume cursor. A unary filter still returns the selected Record, with data containing an empty events array when no events match.
Raw response and recovery
message Record {
optional int64 block_number = 1;
optional int64 timestamp = 2;
bytes data = 3;
optional int64 timestamp_ns = 4;
StreamProgress progress = 5; // progress frames only
}data is the source record as bytes when no filter is applied. Cursor fields are optional because metadata extraction is best-effort; resume only from a cursor that is present. Mempool records always leave block_number unset; their timestamp is the receive time, and timestamp_ns carries the same time at nanosecond precision. Only the mempool feed sets timestamp_ns, and it is the exact resume cursor there because several mempool records can share one millisecond.
Streams carry no heartbeat frames unless they opt in to progress frames. UNAVAILABLE means no new records arrived before the stream timeout, or the stream failed mid-stream on the server; nothing before it was skipped. DEADLINE_EXCEEDED means the stream could not deliver records in time because the client read too slowly or stopped reading. DATA_LOSS means the stream lost records, for example because it fell behind the live feed, and it ends before sending any cursor past them. After any of these, reconnect from the last cursor received and the replay re-reads the gap. The one exception: a replay positioned by timestamp can skip a stored record whose timestamp does not parse, without an error.
A mempool record can exceed the default 4 MiB gRPC receive limit, so raise the client inbound message limit for that feed. A record over the limit fails the call with RESOURCE_EXHAUSTED from the client library; retrying does not fix it.
Available replay history varies by feed and endpoint. A cursor outside retained history returns NOT_FOUND; use the historical-data products for archival data. A RESOURCE_EXHAUSTED from the server means replay capacity is temporarily unavailable; retry with backoff. This also applies to filtered replay.
Progress frames
A raw stream can opt in to progress frames, an application-level heartbeat: in-band messages sent after each interval of silence. They keep a quiet filtered stream open through proxies with per-stream idle timers, which HTTP/2 keepalive pings do not reset, and advance the resume cursor through blocks the filter removed.
The blocks, fills, misc-events, order-statuses, raw-book-diffs, and TWAP-statuses feeds support them. ListFeeds reports support and interval bounds per feed in FeedInfo.progress.
- Opt-in. Set
StreamRequest.progress.interval_ms, the longest silence before a progress frame.0selects the feed default, currently 20 seconds within bounds of 10 to 60 seconds. An interval outside the bounds, orprogressonStreamOrderbookSnapshotsor a feed withoutFeedInfo.progress, returnsINVALID_ARGUMENT. - Acknowledgement. The response headers carry
x-progress-interval-mswith the applied interval. Through Dwellir's endpoint they arrive with the first message, not when the stream opens. If the header is absent, the request was not honored. - Frame shape. A progress frame sets
Record.progressand leavesdata,block_number, andtimestampunset. Checkprogressbefore treating a record as data. scanned_through. The inclusive cursor of the newest record the stream has examined, sent or removed by the filter. It is unset until the stream has examined a record.StreamProgress.timestampis the source time at that cursor in Unix milliseconds.- Resume. A set
scanned_throughis a valid resumePositionwith the same delivery guarantee as a data record's cursor. Resume is inclusive, so deduplicate on the cursor. Do not resume atscanned_through + 1: a block start above the latest block returnsINVALID_ARGUMENT. - Stall signal. An unchanged
scanned_throughacross frames means the feed is not advancing. Progress frames do not reset the stream timeout: after 60 seconds without new records, the stream closes withUNAVAILABLEand the messagestream idle. - Usage. Progress frames count toward metered usage.
Open a filtered stream with progress frames every 15 seconds:
grpcurl \
-import-path content/docs/hyperliquid/grpc \
-proto v3.proto \
-H "x-api-key: ${DWELLIR_API_KEY}" \
-d '{"filter":{"fields":[{"field":"users","values":["0x1234567890abcdef1234567890abcdef12345678"]}]},"progress":{"interval_ms":15000}}' \
"${HYPERLIQUID_GRPC_ENDPOINT}" \
hyperliquid_l1_gateway.v3.HyperliquidL1Gateway/StreamFillsWhile the user has no fills, the stream sends progress frames such as:
progress: {
scanned_through: { block_number: 1058647120 }
timestamp: 1785736840211
}V3 market-streaming service
MarketStreaming exposes fifteen typed subscriptions:
| Method | Opening behavior |
|---|---|
StreamL2Book | Current full L2 book, then coalesced full snapshots |
StreamBbo | Current top of book per requested coin, then changes |
StreamL2BookDiff | Full-book snapshot per coin, then ordered level diffs |
StreamL4Book | Full L4 snapshot for one coin, then native JSON diffs |
StreamL4OrderUpdates | Typed snapshot frame, then typed order diffs |
StreamTpslUpdates | TP/SL snapshot frame, then lifecycle diffs |
StreamTrades | Live-only normalized trades |
StreamAllFills | Live-only fills across the requested scope |
StreamUserFills | Live-only fills for one user |
StreamBuilderFills | Live-only builder-attributed fills |
StreamLiquidationFills | Live-only liquidation fills |
StreamOrderUpdates | Live-only order-status changes for the requested wallets |
StreamCandle | Current tracked bucket when available, otherwise the next execution |
StreamAllMids | Current full perp-mid map, then changed maps |
StreamActiveAssetCtx | Current context for one perp, then changes |
These are live subscriptions without historical backfill. One RPC represents one subscription; cancel its context to unsubscribe. Most stateful views open with current state, while trades, all fills-family streams, and order updates are live-only.
Snapshot-derived views (StreamL2Book, StreamBbo, StreamCandle, StreamAllMids, and StreamActiveAssetCtx) recover from subscriber lag in-band because a later frame supersedes dropped state. Incremental streams terminate with ABORTED on frame loss; reconnect and rebuild from their opening snapshot where provided. StreamL2BookDiff chains seq and prev_seq per coin. Typed L4, TP/SL, fills-family, and order-update streams expose a per-subscription sequence; a gap means loss.
Market streams carry no heartbeat frames, and an idle subscription can be healthy. INVALID_ARGUMENT identifies malformed requests, FAILED_PRECONDITION an unavailable feature, UNAVAILABLE a view that is not yet ready or whose latest upstream data is stale, ABORTED lost frames or reset state, and DEADLINE_EXCEEDED a consumer that did not drain promptly.
Prices and sizes are decimal strings. Times are Unix milliseconds. Coin identifiers use native, case-sensitive names such as BTC, @1, and #2. User addresses match case-insensitively. Frame-level time is block time, while per-order timestamp is placement time. StreamAllMids and StreamActiveAssetCtx have no block_number; their time identifies when the endpoint made the update available, not a block or upstream timestamp.
V2 compatibility
V2 retains the fourteen established raw methods and their feed-specific response messages. Its request cursor fields are timestamp_ms and block_height, and its pages remain at the same flat canonical URLs. V2 has no ListFeeds, shared Record, mempool methods, or V3 server-side raw filtering. Each overlapping method page keeps the V2 shape and adds its V3 equivalent.
Client guidance
- Generate stubs from the exact proto version you call.
- Attach
x-api-keymetadata on every RPC and use TLS. - Set deadlines on unary calls, especially unpositioned V3 raw calls that wait for the next record.
- Persist only present V3 cursors and replay inclusively after reconnecting; deduplicate the last committed cursor.
- Opt filtered raw streams in to progress frames when they pass through proxies with idle timeouts, and persist
scanned_throughas a cursor. - Drain streams continuously and reconnect with bounded exponential backoff for retryable statuses.
- Seed order-book reconstruction from a snapshot or another known state, then apply ordered diffs. Raw diffs alone are insufficient.
Complete client examples are available in the Dwellir gRPC examples repository. For help with deployment capabilities, contact support@dwellir.com.
hl_getLatestBlockNumber - Get Latest Block Number
Get the highest block number currently available for a HyperCore data stream via the JSON-RPC API.
ListFeeds - Discover V3 Raw Feeds
Discover the raw feeds available from a Hyperliquid V3 gRPC endpoint, including supported cursors and server-side filter fields.