alchemyplatform · SahilAujla · Aug 7, 2026 · Aug 7, 2026 · Aug 7, 2026
@@ -7,4 +7,39 @@ description: "HyperCore private-preview documentation."
 
 # Markets, assets, and DEXes
 
-A market identifier selects a tradeable HyperCore market. Asset and DEX semantics must be sourced from the native metadata contract. This private-preview uses `BTC` only as an illustrative market identifier.
+## Market identifiers
+
+HyperCore coin strings are unambiguous across market types — the format tells you the type:
+
+| Form | Market type | Examples |
+| --- | --- | --- |
+| Readable name | Perpetual | `BTC`, `ETH`, `HYPE`, `SOL` |
+| `@index` | Spot | `@1`, `@107`, `@142` |
+| `#N` | Outcome market (HIP-4) | `#90` |
+| `dex:name` | HIP-3 DEX market | `xyz:SP500` |
+
+There is no overlap between forms: `BTC` is always the perpetual, and spot BTC is a separate `@index` coin. `PURR/USDC` is a documented spot-market exception with a readable name. Discover `@index` mappings through the native `meta` and `spotMeta` metadata endpoints.
+
+Coin strings are case-sensitive.
+
+## Market types and DEXes
+
+The `marketTypes` filter accepts `perp`, `spot`, `outcome`, or `*`. Its default is `["perp"]`, and the default never grows: request new types explicitly or pass `["*"]` to opt in to future types automatically.
+
+The `dex` selector is `main` for Hyperliquid perpetuals or a named DEX for HIP-3 deployments. Outcome markets carry two coins per outcome, one per side.
+
+## Price aggregation
+
+| Parameter | Accepted values | Effect |
+| --- | --- | --- |
+| `nSigFigs` | `2`, `3`, `4`, `5` | Significant figures used to bucket price levels |
+| `mantissa` | `2` or `5` | Mantissa step within the bucket. Valid only when `nSigFigs` is `5` |
+| `nLevels` | `1`, `10`, `20` (default), `50` | Levels returned per side |
+
+Aggregation rounds bids down and asks up. With `nSigFigs: 5` and `mantissa: 2`, a bid of `70325` becomes `70324` and an ask of `70325` becomes `70326`. When aggregation parameters are omitted, each distinct price level is reported individually.
+
+A snapshot and the diffs applied to it must use identical aggregation parameters, or the resulting book is invalid.
+
+## Level semantics
+
+A price level reports total resting size and an order count — `px`, `sz`, and `n`. One level may represent many orders; `n` is how many. Level-aggregated streams expose no order IDs and no user addresses. Order-level detail requires `l4BookUpdates`.
@@ -7,4 +7,49 @@ description: "HyperCore private-preview documentation."
 
 # Timestamps, cursors, and replay
 
-The intended contract uses Unix milliseconds and opaque cursors. Cursors order events within a subscription and are not business identifiers. Replay begins after the supplied cursor. Clients store and return cursors unmodified because their format may change.
+## Time
+
+All timestamps are Unix milliseconds.
+
+## Block height
+
+HyperCore produces a block roughly every 70 ms, and block numbers on the chain are sequential.
+
+Block-derived messages identify their source block by height or round. Whether a skipped height indicates a gap depends on the stream — block-complete streams expect continuity, change-driven streams do not. `bbo` emits only when the best bid or ask moves, and `l2Book` sends a market only when that market's book changed. Stateful diff streams use their own sequence fields for gap detection, described below.
+
+## Cursors
+
+On a replay-capable stream, a cursor marks a position in a subscription. It is opaque: store it and return it unmodified, because its format may change. Cursors are per subscription, not per connection — subscriptions sharing a connection resume independently, and replay resumes after the supplied cursor. `l2Book` and `bbo` carry no cursor.
+
+## Snapshot and diff streams
+
+The stateful market-data streams use two recovery models. This taxonomy does not classify event feeds such as fills, order updates, funding, and ledger events.
+
+**Complete-snapshot streams** — `l2Book` and `bbo`. Every message is self-contained and replaces prior state. There is no cursor and nothing to replay: after a disconnect, resubscribe and the next message re-establishes state.
+
+**Incremental streams** — `l2BookDiff`, `l4BookUpdates`, and `tpslUpdates`. Messages carry changes that chain onto previous state. These carry a cursor and support replay.
+
+> A message with `isSnapshot: true` replaces your local state. Any message without it is a diff that must chain onto your previous state. If continuity is broken, a fresh message with `isSnapshot: true` is pushed to you — there is no separate resynchronization message and no epoch to track.
+
+## Detecting gaps
+
+**Client-side detection**, on `l2BookDiff`: each per-market diff carries `seq` and `prev_seq`. If `prev_seq` does not match your current position for that market, you have a gap.
+
+**Server-side detection**, on `l4BookUpdates` and `tpslUpdates`: these carry no sequence fields. When continuity breaks, the service pushes a message with `isSnapshot: true` rather than requiring the client to detect the gap itself. A client on these streams has no gap-detection bookkeeping to implement.
+
+## Deduplicating on reconnect
+
+When resuming from a cursor, replayed and live messages may overlap. There is no single deduplication key across all streams. Deduplicate using the identity fields the stream actually documents:
+
+| Stream kind | Identity for deduplication |
+| --- | --- |
+| `l2BookDiff` | The per-market `seq` value |
+| `l4BookUpdates`, `tpslUpdates` | No client-side deduplication is required — a pushed snapshot replaces state |
+| Block streams | Block `height` or `round`, according to the API surface |
+| Event streams | The identity fields documented by that stream, such as `(time, txIndex)` where both are present |
+
+A cursor identifies a resume position, not an event. It is not itself a deduplication key.
+
+## Replay depth
+
+Replay depth is bounded by node block-data retention, currently approximately 48 hours. For block-derived streams, gaps that replay cannot bridge can be recovered with the block lookup methods.
@@ -7,6 +7,8 @@ description: "HyperCore private-preview documentation."
 
 # Historical data
 
-HyperCore is designed for deep historical coverage. Replay, recovery, corrections, and bulk export are first-class capabilities; exact coverage and retention will be published as the service is finalized.
+HyperCore is designed for deep historical coverage. Replay, recovery, corrections, and bulk export are first-class capabilities.
+
+Replay depth is bounded by node block-data retention, currently approximately 48 hours. For block-derived streams, gaps that replay cannot bridge can be recovered with the block lookup methods. Indexed historical APIs and bulk export are separate surfaces, and coverage varies by dataset.
 
 Existing native-compatible `/info` reads are available through the existing Hyperliquid endpoint and are node-bound in depth. Planned indexed historical APIs are a separate HyperCore product surface for deeper querying and export. Raw bulk exports are not equivalent to queryable API depth. Availability may differ by dataset and access mode.
@@ -16,7 +16,7 @@ HyperCore brings together real-time market and account events, native-compatible
     Subscribe to real-time exchange and account events.
   </Card>
   <Card title="gRPC streams" href="/docs/chains/hypercore-grpc/getting-started/overview">
-    Consume block and order-book streams through the intended RPC service.
+    Consume block and order-book streams through the gRPC service.
   </Card>
   <Card title="REST reference" href="/docs/data/hypercore/rest-api">
     Use native-compatible and enriched read operations.
@@ -37,6 +37,24 @@ HyperCore brings together real-time market and account events, native-compatible
 | Block lookup and bounded backfill | JSON-RPC |
 | Deep historical analysis and export | Historical APIs |
 
-## Contract notation
+## Connection details
 
 Connection details are provided for private-preview access.
+
+## Common tasks
+
+| I want to… | Use |
+| --- | --- |
+| Watch deposits, withdrawals, and transfers for an address | [userNonFundingLedgerUpdates](/docs/chains/websockets/hypercore/streams/user-non-funding-ledger-updates) |
+| Watch ledger activity across all addresses | [allUserNonFundingLedgerUpdates](/docs/chains/websockets/hypercore/streams/all-user-non-funding-ledger-updates) |
+| Track funding payments | [funding rates](/docs/chains/websockets/hypercore/streams/funding-rates) |
+| Display an order book | [l2Book](/docs/chains/websockets/hypercore/streams/l2-book) |
+| Maintain a live order book efficiently | [l2BookDiff](/docs/chains/websockets/hypercore/streams/l2-book-diff) |
+| Track prices and spreads only | [bbo](/docs/chains/websockets/hypercore/streams/bbo) |
+| Analyze order-level depth and queue position | [l4BookUpdates](/docs/chains/websockets/hypercore/streams/l4-book-updates) |
+| Monitor stop and take-profit orders | [tpslUpdates](/docs/chains/websockets/hypercore/streams/tpsl-updates) |
+| Watch fills for an address | [userFills](/docs/chains/websockets/hypercore/streams/user-fills) |
+| Index every block | [StreamBlocks](/docs/chains/hypercore-grpc/api-reference/stream-blocks) |
+| Look up a single block | [hl_getBlock](/docs/chains/hyperliquid/hypercore/json-rpc/overview) |
+| Backfill a block range after a gap | [hl_getBatchBlocks](/docs/chains/hyperliquid/hypercore/json-rpc/overview) |
+| Read account state on demand | [REST reference](/docs/data/hypercore/rest-api) |
@@ -7,10 +7,27 @@ description: "HyperCore private-preview documentation."
 
 # gRPC streaming
 
-## API reference
+HyperCore gRPC provides block streaming and order-book streaming at price-level,
+top-of-book, and order-level detail, plus trigger-order updates. Connection details and
+generated client configuration will be published as the service is finalized.
 
-This preview documents block and order-book gRPC streams. Connection details and generated client configuration will be published as the service is finalized. [StreamBlocks](/docs/chains/hypercore-grpc/api-reference/stream-blocks) is the most fully specified stream today; the order-book streams remain earlier design proposals.
+## Available streams
+
+| Stream | Delivers |
+| --- | --- |
+| [StreamBlocks](/docs/chains/hypercore-grpc/api-reference/stream-blocks) | Raw blocks, one message per block |
+| [StreamL2Book](/docs/chains/hypercore-grpc/api-reference/stream-l2-book) | Aggregated price-level snapshots |
+| [StreamL2BookDiff](/docs/chains/hypercore-grpc/api-reference/stream-l2-book-diff) | Incremental price-level changes |
+| [StreamL4BookUpdates](/docs/chains/hypercore-grpc/api-reference/stream-l4-book-updates) | Per-order changes with queue position |
+| [StreamBboBook](/docs/chains/hypercore-grpc/api-reference/stream-bbo-book) | Top-of-book best bid and offer |
+| [StreamTpslUpdates](/docs/chains/hypercore-grpc/api-reference/stream-tpsl-updates) | Take-profit and stop-loss order lifecycle |
 
 ## Choosing a transport
 
-WebSocket and gRPC can expose the same market data through different transports. Use [WebSocket streams](/docs/chains/websockets/hypercore) when integrating with the subscription envelope, and use [gRPC streams](/docs/chains/hypercore-grpc/getting-started/overview) when integrating with the RPC service definition. For L2 books, [l2Book](/docs/chains/websockets/hypercore/streams/l2-book) and [l2BookDiff](/docs/chains/websockets/hypercore/streams/l2-book-diff) describe complementary snapshot and diff representations.
+WebSocket and gRPC can expose the same market data through different transports. Use
+[WebSocket streams](/docs/chains/websockets/hypercore) when integrating with the
+subscription envelope, and use [gRPC streams](/docs/chains/hypercore-grpc/getting-started/overview)
+when integrating with the RPC service definition. For L2 books,
+[l2Book](/docs/chains/websockets/hypercore/streams/l2-book) and
+[l2BookDiff](/docs/chains/websockets/hypercore/streams/l2-book-diff) describe
+complementary snapshot and diff representations.
@@ -5,25 +5,72 @@ description: "HyperCore private-preview documentation."
 
 <Markdown src="../shared/preview-notice-september.mdx" />
 
-# StreamBboBook
+# Stream BBO book
 
-## Intended RPC
+`StreamBboBook` delivers the top-of-book best bid and offer when either side changes.
+This is ideal for live price and spread displays, routing decisions, and applications
+where full depth is wasted bandwidth.
 
-`rpc StreamBboBook(StreamBboBookRequest) returns (stream BboBookEnvelope);`
+> The contract below is proposed and will be confirmed before general availability.
 
-Carries best-bid-and-offer book data. For the WebSocket representation, see [bbo](/docs/chains/websockets/hypercore/streams/bbo).
+## Overview
 
-## Intended message
+* Emitted only when the best bid or the best ask changes for a market
+* Top of book only — use `StreamL2Book` for depth
+* A null side means there are no resting orders on that side
+* Every message is complete, so there is nothing to replay
 
-The envelope below is illustrative and non-binding: its field names, field numbers, scalar types, payload type names, and finality semantics remain provisional. It makes no wire-compatibility promise.
+## Request structure
 
 ```proto
-message BboBookEnvelope {
-  string cursor = 1;
-  uint64 sequence = 2;
-  bool is_final = 3;
-  BboBookPayload best_bid_offer = 4;
+message StreamBboBookRequest {
+  repeated string coins = 1;
+  repeated string market_types = 2;
 }
 ```
 
-The service will publish the request and payload message definitions.
+### Coins
+
+**Field**: `coins`
+**Type**: `repeated string`
+
+Markets to subscribe to. Empty means all markets.
+
+### Market types
+
+**Field**: `market_types`
+**Type**: `repeated string`
+
+Accepted values are `perp`, `spot`, `outcome`, or `*`. The default is `["perp"]`, so
+spot and outcome markets are not delivered unless requested. The default never grows:
+add new market types explicitly, or pass `["*"]` to opt in to future types automatically.
+This field is rejected when combined with an explicit `coins` list.
+
+## Response structure
+
+```proto
+message BboBookUpdate {
+  string coin = 1;
+  uint64 height = 2;
+  uint64 time = 3;
+  Level bid = 4;
+  Level ask = 5;
+}
+```
+
+### Key fields
+
+**`coin`**: Market symbol.
+
+**`height`**: Block number.
+
+**`time`**: Block timestamp in milliseconds.
+
+**`bid`**: The best bid as a `Level` (`px`, `sz`, `n`). Null when there are no resting bids.
+
+**`ask`**: The best ask as a `Level` (`px`, `sz`, `n`). Null when there are no resting asks.
+
+## When to use BBO
+
+Use this stream for spread monitoring, price displays, routing decisions, and any case
+where full depth is wasted bandwidth.