robinhood-chain-sdk 0.9.0 → 0.11.0

package/README.md

@@ -15,6 +15,10 @@ Robinhood Chain (RHC) is an **Arbitrum Orbit L2, chain id 4663**. This SDK wraps
 
 The KOL→EVM mapping is unique to MadeOnSol: each tracked Solana KOL's Robinhood-Chain wallet is recovered by tracing their Solana→EVM bridge deposits (deBridge / Relay / Mayan / Wormhole), then attributed on-chain to the effective trading account (`tx.from`, or the ERC-4337 userOp sender when the trade was bundled). Robinhood Chain coverage is **bundled into every MadeOnSol tier at no extra cost — same `msk_` API key, same base URL** as the Solana product.
 
+> **New in 0.10.0 — named subscriptions: several independent subscriptions per socket.** `subscribe({ subId, channels, filters })`, `updateSubscription(subId, filters)`, `unsubscribe(subId)`, `getSubscriptions()` / `listSubscriptions()`. Each named subscription has its own channels and filters (the server caps the total per connection, default included: PRO 5, ULTRA 10, BUSINESS 20); frames carry `evt.sub_id`; an event matching several subscriptions is delivered once per subscription (dedupe per `(sub_id, id)`). Resume is per subscription with one commit for the connection. The plain `subscribe(channels, filters)` API is unchanged. See "Named subscriptions" in the stream section.
+
+> **Also in 0.10.0 — `rhc:token_prices` and enriched RHC trade payloads (WS Phase 2).** A tenth RHC channel, `rhc:token_prices` (PRO+, address-scoped): subscribe with `filters.addresses` (25 / 100 / 250 per connection on PRO / ULTRA / BUSINESS, rejected above the cap) and receive one `snapshot: true` frame per address, then ticks derived from the RHC trade feed at most once per address per 250 ms, each typed `RhcTokenPriceTick` with `quality` fresh | stale | unreliable and a `quality_reason`; a stale or unreliable price is never delivered as fresh. `rhc:dex_trade` / `rhc:dex_trade_unattributed` frames now carry additive enrichment, typed `RhcDexTradeEvent` / `RhcDexTradeUnattributedEvent`: exact `amount_in_raw` / `amount_out_raw` decimal strings (never floats), `token` + `quote` identity with decimals, `metadata_status`, `price_status` / `price_source` / `price_observed_at`, `mc_status` (why `mc_usd` is null) and `side` / `side_reason`. Every existing field keeps its name.
+
 > **New in 0.9.0 — stream recovery: resume cursor, de-duplication, honest gaps.** The managed stream now tracks the cursor `{ instance, seq, ts }` of the last frame your handlers finished and resumes after it on every reconnect (the v1 `resume` request, with an automatic fallback to `replay_since_seq` / `replay_since_ts` on older servers). Delivery is at-least-once, de-duplicated by event `id`; new lifecycle events `cursor`, `replay`, `gap` (what could not be recovered — a `seq` gap is never loss) and `fatal`. Close codes are handled: 4001 re-fetches the token (bounded), 4002 waits ≥ 60 s instead of looping every second, 4003 stops, 4008 resumes; the backoff resets only after a `subscribed` ack. Every server `warning` frame is emitted (incl. `channels_rejected` / `channels_revoked`). `StreamChannel` / `STREAM_CHANNELS` now list all nine RHC channels (adds `rhc:dex_trades_unattributed`, `rhc:new_tokens`, `rhc:token_locks`); `RhcPriceAlertEvaluation.mode` is `"event_driven" | "polled"` with the new optional `trigger` / `fallback_poll_seconds`. See the stream section's "Recovery" notes.
 
 > **New in 0.8.2 — mutation calls are no longer retried automatically (security fix, SDK-02).** A lost response or transient network error after a `POST`/`PATCH`/`DELETE` (rule create, watchlist change, `stream.rotate()`) used to retry automatically — which could duplicate a rule or rotate a token twice. Mutating calls (including the batch-read POST endpoints) now make exactly one attempt; `GET` retries/backoff (`maxRetries`) are unchanged. If a mutating call fails, check current state before deciding whether to retry by hand. No public API/type changes.
@@ -247,9 +251,11 @@ const { events, has_more, next_before, coverage } = await client.lpEvents({ toke
 for (const ev of events) {
   if (ev.provider_is_token_deployer) console.warn("deployer pulled liquidity:", ev.tx_hash, ev.dex, ev.token_amount_raw);
 }
-console.log(coverage.adds_persisted); // false — always
+console.log(coverage.events); // ["remove"] — the default request is removals only
 ```
 
+Since 2026-09-23 `action: "add" | "pool_created" | "all"` opts into liquidity adds (kept 7 days) and pool creations, and every row carries the depth fields `tick_lower` / `tick_upper`, `liquidity_delta`, `in_range`, `active_liquidity_delta`, `active_share` (v3/v4), `share_of_reserves` (v2) and `material` — null where the pool state was unknown and on older rows.
+
 > **Removals ONLY.** Liquidity adds are not persisted (v4 adds share the topic and are dropped at decode; v2/v3 `Mint` is not subscribed), so every row is `event: "remove"` and an empty page means "no removals seen", never "no liquidity activity" — the `coverage` block spells this out. Amounts are **raw uint256 decimal strings** (`liquidity`, `amount0` / `amount1`, plus pre-resolved `token_amount_raw` / `quote_token` / `quote_amount_raw`) — do not `Number()` them; v4 rows carry `liquidity` only because the pool manager emits no token amounts. Filters: `token`, `pool` (v2/v3 address or v4 bytes32 poolId), `provider`, `dex`. Data since 2026-08-05.
 
 ## Token intelligence — `client.tokens`
@@ -579,7 +585,7 @@ await client.kol.firstTouchSubscriptions.update(subscription.id, { filters: {} }
 
 ## Streaming — `client.stream` (PRO+)
 
-Managed WebSocket with token fetch on every (re)connect, auto-reconnect with backoff, heartbeat liveness, and typed events. Stream tokens **never expire** (since 2026-08-27) — there is no refresh timer; `client.stream.getToken()` returns the same token every call (`expires_at` / `next_refresh_at` are always `null`), and `getToken({ rotate: true })` replaces it (the old one keeps working for 60 s). Nine RHC channels:
+Managed WebSocket with token fetch on every (re)connect, auto-reconnect with backoff, heartbeat liveness, and typed events. Stream tokens **never expire** (since 2026-08-27) — there is no refresh timer; `client.stream.getToken()` returns the same token every call (`expires_at` / `next_refresh_at` are always `null`), and `getToken({ rotate: true })` replaces it (the old one keeps working for 60 s). Eleven RHC channels:
 
 | Channel | Emits | Tier | Scope |
 |---|---|---|---|
@@ -591,7 +597,17 @@ Managed WebSocket with token fetch on every (re)connect, auto-reconnect with bac
 | `rhc:price_alert:events` | `rhc:price_alert:dip`, `rhc:price_alert:recovery` | PRO+ | user-scoped; event-driven off each trade (a few seconds), not sub-second |
 | `rhc:kol:coordination` | `rhc:kol:coordination` | PRO+ | user-scoped — only **your** rules' fires |
 | `rhc:kol:first_touches` | `rhc:kol:first_touch` | PRO+ | broadcast — ULTRA gates only the first-touch *subscription CRUD*, not this channel |
-| `rhc:token_locks` | `rhc:token_lock` | PRO+ | broadcast — a token lock / vesting contract created on chain |
+| `rhc:token_locks` | `rhc:token_lock` (+ `rhc:token_unlock_upcoming`, `rhc:token_unlock_available` with `filters.lifecycle: true`) | PRO+ | broadcast — a token lock / vesting contract created on chain; opt-in unlock-schedule events (claims / cancels are not observable on RHC) |
+| `rhc:token_prices` | `rhc:token_price` | PRO+ | **address-scoped** — `filters.addresses` required (25 / 100 / 250 per connection); one `snapshot: true` frame per address, then ≤ 1 tick per address per 250 ms with `quality` fresh / stale / unreliable + reason (`RhcTokenPriceTick`); no `seq` / `id` |
+| `rhc:lp_events` | `rhc:lp_event` | **ULTRA+** | broadcast — liquidity `add` / `remove` / `pool_created` on tracked Uniswap v2/v3/v4 pools with `in_range`, `active_share`, `share_of_reserves`, `material` (`RhcLpStreamEvent`); filters `RhcLpEventsFilters`; durable resume |
+
+**Liquidity events and lock schedule (server 2026-09-23).** `rhc:lp_events` frames carry raw `amount0` / `amount1` strings (null on v4), the position range and, for v3/v4, `in_range` / `active_liquidity_delta` / `active_share` — a share of liquidity at the current price, not of TVL (an out-of-range removal is `active_share: 0`); v2 carries `share_of_reserves`; `material: true` = a removal of ≥ 25 %. When the pool's tick was not known the active fields are `null` with `active_share_reason: "pool_state_unknown"` — never guessed. `provider` is usually the router / position manager. No USD field. On `rhc:token_locks`, `filters.lifecycle: true` adds `rhc:token_unlock_upcoming` (within 24 h) and `rhc:token_unlock_available` (passed within 30 min — **claimable per the schedule, not claimed**; `withdrawals_tracked: false`).
+
+```ts
+const lp = client.stream.connect();
+lp.subscribe({ subId: "rugs", channels: ["rhc:lp_events"], filters: { actions: ["remove"], material_only: true } });
+lp.on("rhc:lp_event", (e: RhcLpStreamEvent) => console.log(e.dex, e.pool, e.action, e.active_share ?? e.share_of_reserves));
+```
 
 > **Deprecated:** `rhc:trades` was never a real channel — 0.4.0 subscribers got a `channels_rejected` warning and silence. The server now accepts it as an alias of `rhc:dex_trades` (and acks it under the canonical name), and the SDK keeps the literal marked `@deprecated` so 0.4.0 code compiles. Use `rhc:dex_trades`.
 
@@ -639,6 +655,22 @@ stream.on("gap", (g) => console.warn("may be missing:", g.reasons, g.skipped));
 stream.on("fatal", (f) => console.error("stream stopped:", f.code, f.reason));
 ```
 
+### Named subscriptions *(new in 0.10.0)*
+
+One socket can hold several independent subscriptions, each with its own channels and filters; the server caps the total per connection, the default one included (PRO 5, ULTRA 10, BUSINESS 20). `subscribe(channels, filters)` stays the connection's `"default"` subscription and its wire is unchanged; `subscribe({ subId, channels, filters })` opens a named one (`subId`: 1-64 characters of `A-Z a-z 0-9 _ . -`). A frame delivered under a named subscription carries `evt.sub_id`. **An event that matches several subscriptions is delivered once per matching subscription**, each copy stamped with its `sub_id`: the client dedupes per `(sub_id, id)`, so the same event can legitimately reach a handler twice, under two sub_ids. Filters of one subscription never affect another. `updateSubscription(subId, filters)` REPLACES that subscription's filters (`"default"` addresses the plain one), `unsubscribe(subId)` removes it, `getSubscriptions()` is the local view and `listSubscriptions()` asks the server (`list` / `subscriptions`). Server refusals arrive as `warning` frames carrying the `sub_id` and one of `invalid_sub_id`, `too_many_subscriptions`, `unknown_sub_id`, `invalid_filters`, `channels_rejected`, `channels_revoked`, `replay_in_progress`; a subscription refused as `too_many_subscriptions` or `invalid_sub_id` is dropped locally so reconnects stop re-requesting it. Lifecycle events `updated` and `unsubscribed` surface the server acks.
+
+**Resume with several subscriptions** is per subscription: on every reconnect each subscription is re-sent with the same cursor, the server serves one replay per subscription, one after another (`replay_start` … `replay_end` each carry the `sub_id`; live frames are held until the last one ends), and the cursor commits once ALL of them have ended, at the smallest `last_seq` / `last_ts` across them. The `replay` event lists `subscriptions` and the raw `ends` per subscription; a gap's `channels` entries are keyed `sub_id/channel` for named subscriptions, and an incomplete retryable replay is retried for those subscriptions only. Against an older server that ignores `sub_id`, the client emits `warning` `named_subscriptions_unsupported` once.
+
+```ts
+const stream = client.stream.connect();
+stream.subscribe({ subId: "kol-buys", channels: ["rhc:kol_trades"], filters: { action: "buy" } });
+stream.subscribe({ subId: "firehose", channels: ["rhc:dex_trades"], filters: {} });
+stream.on("rhc:kol_trade", (t, evt) => console.log(evt!.sub_id, t)); // "kol-buys"
+stream.updateSubscription("kol-buys", { action: "buy" });
+console.log(await stream.listSubscriptions()); // [{ subId, channels, filters }, …]
+stream.unsubscribe("firehose");
+```
+
 ## Error handling
 
 Every method throws `RobinhoodError` on a non-2xx response, with `.status`, `.body`, `.message`, and `.requestId` (the API's `_rid` — include it when reporting issues). GET requests retry network failures, rate-limits (`429`) and transient server errors (`5xx`) up to `maxRetries`, with exponential backoff and `Retry-After` / `X-RateLimit-Reset` hints.

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { RobinhoodStream } from "./stream.js";
 import type { StreamClientOptions } from "./stream.js";
 export { RobinhoodStream, STREAM_CHANNELS } from "./stream.js";
-export type { StreamClientOptions, StreamChannel, StreamEventName, StreamEvent, StreamLifecycleEvent, StreamWarning, StreamCursor, StreamReplayResult, StreamGap, StreamFatal, StreamTokenLike, } from "./stream.js";
+export type { StreamClientOptions, StreamChannel, StreamEventName, StreamEvent, StreamLifecycleEvent, StreamWarning, StreamCursor, StreamReplayResult, StreamGap, StreamFatal, StreamSubscription, StreamSubscribeOptions, StreamTokenLike, } from "./stream.js";
 /** Robinhood Chain — Arbitrum Orbit L2, chain id 4663. */
 export declare const CHAIN_ID = 4663;
 /** Thrown for any non-2xx API response (and exhausted network retries). */
@@ -369,17 +369,26 @@ export interface RhcLpEventsParams {
     provider?: string;
     /** Filter by DEX version. */
     dex?: UniswapVersion;
+    /**
+     * Which actions to return (2026-09-23). Default `"remove"` = the historical
+     * removals-only feed, unchanged. `"add"` (kept 7 days), `"pool_created"` or
+     * `"all"` opt into rows persisted since the WS Phase 3 producer.
+     */
+    action?: RhcLpAction | "all";
     /** Opaque cursor from `next_before` (same (block_time,id) keyset as /rhc/trades). */
     before?: string;
 }
+/** A liquidity action on Robinhood Chain. */
+export type RhcLpAction = "add" | "remove" | "pool_created";
 /**
- * One liquidity REMOVAL from `/rhc/lp-events`. Every row is `event: "remove"` —
- * adds are not persisted. Amounts are raw on-chain uint256 integers as decimal
- * STRINGS; v4 rows carry `liquidity` only (the pool manager emits no token
- * amounts), so `amount0` / `amount1` / `token_amount_raw` are null there.
+ * One liquidity event from `/rhc/lp-events`. Without `action` every row is
+ * `event: "remove"` (the default feed is removals only). Amounts are raw
+ * on-chain uint256 integers as decimal STRINGS; v4 rows carry `liquidity` only
+ * (the pool manager emits no token amounts), so `amount0` / `amount1` /
+ * `token_amount_raw` are null there.
  */
 export interface RhcLpEvent {
-    event: "remove";
+    event: RhcLpAction;
     pool: string;
     dex: UniswapVersion;
     fee_tier: number | null;
@@ -411,6 +420,116 @@ export interface RhcLpEvent {
     block_time: string;
     tx_hash: string;
     log_index: number;
+    tick_lower?: number | null;
+    tick_upper?: number | null;
+    /** Signed liquidity change (v3/v4), int256 as string. */
+    liquidity_delta?: string | null;
+    /** tick_lower <= current tick < tick_upper just before the event; null = tick unknown. */
+    in_range?: boolean | null;
+    /** liquidity_delta when in range, "0" out of range. */
+    active_liquidity_delta?: string | null;
+    /** |active delta| / active liquidity before (v3/v4); 0 out of range; adds can exceed 1. */
+    active_share?: number | null;
+    /** v2 only: amount / reserve before (from the pair's Sync). */
+    share_of_reserves?: number | null;
+    /** true = a removal of ≥ 25 % of reserves / active liquidity; null for adds, creations and unknown shares. */
+    material?: boolean | null;
+}
+/** Why `active_share` is null / not the relevant share. */
+export type RhcLpActiveShareReason = "pool_created" | "not_concentrated" | "pool_state_unknown" | "no_active_liquidity";
+/**
+ * `rhc:lp_event` frame `data` (WS channel `rhc:lp_events`, ULTRA / BUSINESS,
+ * 2026-09-23). Frame id = `rhc:lp_event:<tx_hash>:<log_index>`. Every key is
+ * always present (null when unknown). `in_range` / `active_*` are null with
+ * `active_share_reason: "pool_state_unknown"` when the pool's tick was not
+ * known — never guessed. `provider` is usually a router / position manager,
+ * not the beneficial owner. No USD field.
+ */
+export interface RhcLpStreamEvent {
+    chain: Chain;
+    action: RhcLpAction;
+    dex: UniswapVersion;
+    pool: string;
+    token_address: string | null;
+    token: {
+        address: string | null;
+        symbol: string | null;
+        decimals: number | null;
+    };
+    token0: string | null;
+    token1: string | null;
+    provider: string | null;
+    liquidity: string | null;
+    /** NULL on v4 — ModifyLiquidity reports no token amounts. */
+    amount0: string | null;
+    amount1: string | null;
+    tick_lower: number | null;
+    tick_upper: number | null;
+    liquidity_delta: string | null;
+    in_range: boolean | null;
+    active_liquidity_delta: string | null;
+    active_share: number | null;
+    active_share_reason: RhcLpActiveShareReason | null;
+    share_of_reserves: number | null;
+    material: boolean | null;
+    block_number: number | null;
+    block_time: string | null;
+    tx_hash: string;
+    log_index: number | null;
+}
+/** Per-subscription filters for `rhc:lp_events` (all optional, AND; invalid values reject the channel). */
+export interface RhcLpEventsFilters {
+    addresses?: string[];
+    pools?: string[];
+    dexes?: UniswapVersion[];
+    actions?: RhcLpAction[];
+    material_only?: boolean;
+    /** 0..1000 — only events whose relevant share (reserves on v2, active on v3/v4) is known and ≥ this. */
+    min_share?: number;
+}
+/** Unlock-schedule event names on `rhc:token_locks` (only with `filters.lifecycle: true`). */
+export type RhcTokenLockLifecycleEventName = "rhc:token_unlock_upcoming" | "rhc:token_unlock_available";
+/**
+ * Filters that switch `rhc:token_locks` to lifecycle mode. Claims, extensions
+ * and cancels are NOT observable on Robinhood Chain — only the unlock schedule.
+ */
+export interface RhcTokenLockLifecycleFilters {
+    lifecycle: true;
+    events?: RhcTokenLockLifecycleEventName[];
+    unlock_kinds?: Array<"cliff" | "final" | "tranche">;
+    /** Token scope for creates AND lifecycle (≤ 500); applied only with `lifecycle: true`. */
+    addresses?: string[];
+}
+/**
+ * `rhc:token_unlock_upcoming` (the lock's NEXT unlock, when it is within 24 h) /
+ * `rhc:token_unlock_available` (passed within the last 30 min — claimable PER
+ * THE SCHEDULE, NOT claimed). Frame id = `<event>:<event_key>`.
+ */
+export interface RhcTokenUnlockScheduleEvent {
+    event_key: string;
+    lock_id: string;
+    token_address: string;
+    family: string;
+    observed_at: string | null;
+    unlock_at: string;
+    unlock_kind: "cliff" | "final" | "tranche";
+    amount_raw: string | null;
+    amount_reason: string | null;
+    unlocked_total_raw: string | null;
+    release_model: "at_end" | "linear" | "tranched";
+    claimable?: true;
+    chain: Chain;
+    locker: string | null;
+    kind: string | null;
+    subject: string | null;
+    lp_kind: string | null;
+    lp_pool: string | null;
+    sender: string | null;
+    recipient: string | null;
+    locked_amount_raw: string | null;
+    amount_unit: string | null;
+    decimals: number | null;
+    withdrawals_tracked: false;
 }
 export interface RhcLpEventsResponse {
     chain: Chain;
@@ -419,10 +538,11 @@ export interface RhcLpEventsResponse {
     has_more: boolean;
     /** Opaque pagination cursor; pass back as `before`. */
     next_before: string | null;
-    /** Honesty block: `events: ["remove"]`, `adds_persisted: false`, note, since. */
+    /** Honesty block: the actions this response covers (["remove"] by default), adds_persisted, note, since. */
     coverage: {
         events: string[];
-        adds_persisted: boolean;
+        adds_persisted: boolean | null;
+        adds_retention_days?: number;
         note: string;
         since: string;
     };
@@ -1995,6 +2115,130 @@ export interface RhcPriceAlertEvent {
     delivered: boolean;
     delivered_at: string | null;
 }
+/** One side of a swap as the server resolved it. `decimals` null = not yet enriched. */
+export interface RhcSideIdentity {
+    address: string | null;
+    symbol: string | null;
+    decimals: number | null;
+}
+/** known: decimals AND symbol resolved · pending: token seen, enrichment queued · unknown: never seen. */
+export type RhcMetadataStatus = "known" | "pending" | "unknown";
+/** fresh: swap-derived quote inside the producer's 60-min freshness rule · stale: priced through the v4 pool-state fallback · none: unpriced. */
+export type RhcPriceStatus = "fresh" | "stale" | "none";
+export type RhcPriceSource = "swap_quote" | "pool_state_quote";
+/** Why `mc_usd` is null (or "ok"). `liquidity_gate` = MC exceeded pool TVL x 50,000, the same gate that nulls the stored MC. */
+export type RhcMcStatus = "ok" | "no_price" | "no_supply" | "dust" | "ceiling" | "liquidity_gate" | "no_liquidity";
+export type RhcSideReason = "both_sides_quote" | "no_recognized_quote";
+/**
+ * `rhc:dex_trade` frame `data` (channel `rhc:dex_trades`, ULTRA+). Every field
+ * that existed before 2026-09-22 keeps its name; the block from
+ * `amount_in_raw` down is the additive enrichment. `*_raw` amounts are uint256
+ * as EXACT decimal strings — never parse them into a float. A KOL trade also
+ * appears on `rhc:kol_trades` with the same `tx_hash` + `log_index` (different
+ * event id). The durable backfill rebuilds every key it can and lists the rest
+ * in the frame's `missing` (liquidity_usd, quote.usd, quote.observed_at).
+ */
+export interface RhcDexTradeEvent {
+    chain: "robinhood";
+    token_address: string;
+    token_symbol: string | null;
+    action: "buy" | "sell";
+    dex: string;
+    pool: string;
+    eth_amount: number | null;
+    price_usd: number | null;
+    mc_usd: number | null;
+    /** Pool TVL at broadcast (null = not yet tracked, never "zero"). */
+    liquidity_usd: number | null;
+    trader: string | null;
+    tx_hash: string;
+    log_index: number;
+    block_number: number;
+    traded_at: string;
+    amount_in_raw: string | null;
+    amount_out_raw: string | null;
+    token_amount_raw: string | null;
+    quote_amount_raw: string | null;
+    token: RhcSideIdentity;
+    quote: RhcSideIdentity & {
+        usd: number | null;
+        observed_at: string | null;
+    };
+    token_decimals: number | null;
+    quote_decimals: number | null;
+    metadata_status: RhcMetadataStatus;
+    price_status: RhcPriceStatus;
+    price_source: RhcPriceSource | null;
+    /** ISO block time of the print the price was observed at; null when unpriced. */
+    price_observed_at: string | null;
+    mc_status: RhcMcStatus | null;
+    /** `action` when a canonical quote (WETH / ETH / USDG / VIRTUAL or an equity quote) defines "the token", else null. */
+    side: "buy" | "sell" | null;
+    side_reason: RhcSideReason | null;
+    launchpad: string | null;
+}
+/** `rhc:dex_trade_unattributed` frame `data` (channel `rhc:dex_trades_unattributed`, ULTRA+). Raw legs plus per-leg identity; never a buy/sell side. */
+export interface RhcDexTradeUnattributedEvent {
+    chain: "robinhood";
+    dex: string;
+    pool: string;
+    token_in: string;
+    token_out: string;
+    amount_in: string | number | null;
+    amount_out: string | number | null;
+    liquidity_usd: number | null;
+    trader: string | null;
+    tx_hash: string;
+    log_index: number;
+    block_number: number;
+    traded_at: string;
+    amount_in_raw: string | null;
+    amount_out_raw: string | null;
+    token_in_meta: RhcSideIdentity;
+    token_out_meta: RhcSideIdentity;
+    metadata_status: RhcMetadataStatus;
+    price_status: "none";
+    price_source: null;
+    price_observed_at: null;
+    side: null;
+    side_reason: RhcSideReason;
+}
+/** Why a tick is not `fresh`. Every rule reuses a server-side pricing guard; none is client-tunable. */
+export type RhcTickQualityReason = "no_price" | "dust_trade" | "curve_live" | "state_quote_fallback" | "low_liquidity" | "price_age" | "mc_ceiling";
+/**
+ * `rhc:token_price` frame `data` (channel `rhc:token_prices`, PRO+, address-
+ * scoped). On subscribe every address first gets ONE frame with
+ * `snapshot: true` (the current price row; `source: "rhc_token_prices"`), then
+ * ticks derived from the RHC trade feed (`source: "rhc-dex-stream:trade"`),
+ * at most one per address per 250 ms with the latest value. A `stale` or
+ * `unreliable` price is only ever delivered with its flag — treat `quality`
+ * as part of the price. State stream: no `seq` / `id`, not replayed; a resume
+ * sends a fresh snapshot.
+ */
+export interface RhcTokenPriceTick {
+    chain: "robinhood";
+    address: string;
+    symbol: string | null;
+    price_usd: number | null;
+    /** ETH-denominated price; present on snapshots, null on trade-derived ticks. */
+    price_native: number | null;
+    market_cap_usd: number | null;
+    liquidity_usd: number | null;
+    source_pool: string | null;
+    source_dex: string | null;
+    /** ISO block time of the print (tick) or the last trade (snapshot). */
+    observed_at: string | null;
+    /** Age of `observed_at` when the frame was built (ms). */
+    price_age_ms: number | null;
+    quality: "fresh" | "stale" | "unreliable";
+    quality_reason: RhcTickQualityReason | null;
+    price_source: RhcPriceSource | null;
+    /** The print this tick came from; null on a snapshot. */
+    tx_hash: string | null;
+    log_index: number | null;
+    block_number: number | null;
+    source: "rhc_token_prices" | "rhc-dex-stream:trade";
+}
 export interface RhcPriceAlertEventsResponse {
     chain: Chain;
     events: RhcPriceAlertEvent[];