@lifi/perps-sdk-provider-hyperliquid 1.1.0 → 1.3.0

package/src/websocket/HyperliquidWsProvider.ts

@@ -14,12 +14,15 @@ import {
 import {
   type MarketContext,
   type OpenOrder,
+  type OrderbookLevel,
+  type OrderbookResponse,
   OrderSide,
   OrderType,
   type Subscription,
   type TriggerOrder,
 } from '@lifi/perps-types'
-import { HYPERLIQUID_FEE_TIER_FALLBACK } from '../constants.js'
+import Big from 'big.js'
+import { HYPERLIQUID_FEE_TIER_FALLBACK, SPOT_MARKET_ID } from '../constants.js'
 import type {
   HlAssetPosition,
   HlOrderDetail,
@@ -27,14 +30,22 @@ import type {
   HlWsAllDexsAssetCtxsData,
   HlWsAllDexsClearinghouseStateData,
   HlWsCandleData,
+  HlWsCompressedL2Data,
   HlWsFastAssetCtx,
   HlWsL2BookData,
+  HlWsL2Data,
   HlWsMessage,
+  HlWsPacData,
   HlWsPerpAssetCtx,
+  HlWsPerpAssetCtxPayload,
+  HlWsSacData,
+  HlWsSpotAssetCtx,
   HlWsSpotStateData,
+  HlWsTrade,
   HlWsUserFillsData,
 } from '../types/index.js'
 import {
+  decodeCompressedJson,
   decodeFastAssetCtxs,
   isOpenAssetPosition,
   isTriggerOrder,
@@ -49,7 +60,7 @@ import {
   spotPriceById,
 } from '../utils/index.js'
 
-/** HL's `l2Book` returns at most this many levels per side (slow/default mode). */
+/** HL's compact `l2` snapshot carries 20 levels per side. */
 const HL_L2_BOOK_MAX_LEVELS_PER_SIDE = 20
 
 /**
@@ -85,14 +96,20 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
   private readonly client: PerpsSDKClient | undefined
   private readonly registry: MarketRegistry | undefined
   private perpCtxBySubDex = new Map<string, Record<string, HlWsPerpAssetCtx>>()
+  private spotCtxByMarketId: Record<string, HlWsSpotAssetCtx> = {}
+  private orderbookKeysByMarketId = new Map<string, Set<string>>()
+  private latestOrderbookByMarketId = new Map<string, OrderbookResponse>()
   // Latest mid/mark per `Market.id` from the high-frequency `fastAssetCtxs`
   // feed (all dexes, incl. builder/sub-dex coins). Merged incrementally —
-  // frames carry only changed coins — and overlaid onto the slower
-  // `allDexsAssetCtxs` context (which supplies oracle/funding/OI/metadata).
+  // frames carry only changed coins — and overlaid onto asset contexts that
+  // carry oracle/funding/OI/metadata.
   private fastCtxByMarketId: Record<string, HlWsFastAssetCtx> = {}
   // `fastAssetCtxs` payloads are base64 + raw-DEFLATE; decode is async, so
   // chain decodes to apply incremental frames in arrival order.
   private fastDecodeChain: Promise<void> = Promise.resolve()
+  private pacDecodeChain: Promise<void> = Promise.resolve()
+  private sacDecodeChain: Promise<void> = Promise.resolve()
+  private orderbookDecodeChain: Promise<void> = Promise.resolve()
 
   constructor(wsUrl: string, providerKey: string, client?: PerpsSDKClient) {
     super(
@@ -133,9 +150,8 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
 
     await this.registry?.sync()
 
-    // Markets context aggregates the all-dexs perp asset-context feed
-    // (oracle, funding, OI, metadata) with the high-frequency `fastAssetCtxs`
-    // feed, which supplies fast mid + mark for every market across all dexes.
+    // Markets context aggregates slower asset-context feeds with fast mid/mark
+    // ticks from `fastAssetCtxs`.
     if (sub.channel === 'marketsContext') {
       const entries = this.getMarketsContextSubEntries()
 
@@ -153,14 +169,21 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
           )
         }
         this.perpCtxBySubDex.clear()
+        this.spotCtxByMarketId = {}
         this.fastCtxByMarketId = {}
       }
     }
 
     // All other channels: single WS subscription per key
     const key = this.toKey(sub)
+    if (sub.channel === 'orderbook') {
+      this.claimOrderbookKey(sub.marketId, key)
+    }
     const payload = this.toHlPayload(sub)
     await this.registerSub(key, payload)
+    if (sub.channel === 'orderbook') {
+      this.registerOrderbook(sub.marketId, key)
+    }
 
     await this.rws.ready()
 
@@ -170,8 +193,14 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
         this.orderUpdatesKey = undefined
       }
       this.rws.send(
-        JSON.stringify({ method: 'unsubscribe', subscription: payload })
+        JSON.stringify({
+          method: 'unsubscribe',
+          subscription: payload,
+        })
       )
+      if (sub.channel === 'orderbook') {
+        this.releaseOrderbook(sub.marketId, key)
+      }
     }
   }
 
@@ -198,9 +227,28 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
     this.orderUpdatesKey = key
   }
 
+  private claimOrderbookKey(marketId: string, key: string): void {
+    const activeKeys = this.orderbookKeysByMarketId.get(marketId)
+    if (activeKeys === undefined) {
+      return
+    }
+
+    for (const activeKey of [...activeKeys]) {
+      if (activeKey === key) {
+        continue
+      }
+      if (!this.closeChannelIfIdle(activeKey)) {
+        throw new Error(
+          `Hyperliquid supports one orderbook aggregation per market per ` +
+            `provider instance. Unsubscribe ${activeKey} before subscribing ${key}.`
+        )
+      }
+    }
+  }
+
   /**
-   * Sub-key + payload pairs for the markets-context aggregation: the all-dexs
-   * perp asset-context feed (oracle/funding/OI/metadata) plus the compressed
+   * Sub-key + payload pairs for the markets-context aggregation: compressed
+   * all-perp (`pac`) and all-spot (`sac`) asset contexts plus the documented
    * `fastAssetCtxs` feed (high-frequency mid + mark across every dex).
    */
   private getMarketsContextSubEntries(): Array<{
@@ -208,14 +256,46 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
     payload: object
   }> {
     return [
-      { subKey: 'allDexsAssetCtxs', payload: { type: 'allDexsAssetCtxs' } },
+      { subKey: 'pac', payload: { type: 'pac' } },
+      { subKey: 'sac', payload: { type: 'sac' } },
       { subKey: 'fastAssetCtxs', payload: { type: 'fastAssetCtxs' } },
     ]
   }
 
+  private registerOrderbook(marketId: string, orderbookKey: string): void {
+    let activeKeys = this.orderbookKeysByMarketId.get(marketId)
+    if (activeKeys === undefined) {
+      activeKeys = new Set()
+      this.orderbookKeysByMarketId.set(marketId, activeKeys)
+    }
+
+    activeKeys.add(orderbookKey)
+  }
+
+  private releaseOrderbook(marketId: string, orderbookKey: string): void {
+    const activeKeys = this.orderbookKeysByMarketId.get(marketId)
+    if (activeKeys === undefined) {
+      return
+    }
+
+    activeKeys.delete(orderbookKey)
+    if (activeKeys.size > 0) {
+      return
+    }
+
+    this.orderbookKeysByMarketId.delete(marketId)
+  }
+
   protected override onClose(): void {
     this.perpCtxBySubDex.clear()
+    this.spotCtxByMarketId = {}
     this.fastCtxByMarketId = {}
+    this.orderbookKeysByMarketId.clear()
+    this.latestOrderbookByMarketId.clear()
+    this.fastDecodeChain = Promise.resolve()
+    this.pacDecodeChain = Promise.resolve()
+    this.sacDecodeChain = Promise.resolve()
+    this.orderbookDecodeChain = Promise.resolve()
     this.orderUpdatesKey = undefined
   }
 
@@ -230,9 +310,14 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
       case 'marketsContext':
         return 'marketsContext'
       case 'orderbook':
-        return `l2Book:${sub.marketId}`
+        return `l2:${sub.marketId}:${this.orderbookAggregationKey(
+          sub.marketId,
+          sub.priceStep
+        )}`
       case 'candle':
         return `candle:${sub.marketId}:${sub.interval}`
+      case 'trades':
+        return `trades:${sub.marketId}`
       case 'orderUpdates':
         return `orderUpdates:${sub.address.toLowerCase()}`
       case 'fills':
@@ -244,32 +329,61 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
     }
   }
 
+  private orderbookAggregation(
+    marketId: string,
+    priceStep: number | undefined
+  ): { nSigFigs?: number; mantissa?: number } {
+    if (priceStep === undefined) {
+      return {}
+    }
+    return priceStepToAggregation(
+      priceStep,
+      this.orderbookReferencePrice(marketId)
+    )
+  }
+
+  private orderbookAggregationKey(
+    marketId: string,
+    priceStep: number | undefined
+  ): string {
+    const aggregation = this.orderbookAggregation(marketId, priceStep)
+    const nSigFigs = aggregation.nSigFigs ?? null
+    const mantissa = aggregation.mantissa ?? null
+    if (nSigFigs === null && mantissa === null) {
+      return 'full'
+    }
+    return `s:${nSigFigs}:m:${mantissa}`
+  }
+
   private toHlPayload(sub: Subscription): object {
     switch (sub.channel) {
       case 'marketsContext':
         // Handled via getMarketsContextSubEntries in openChannel; never reaches
         // toHlPayload, but TS requires an exhaustive switch.
         return { type: 'allDexsAssetCtxs' }
-      case 'orderbook':
+      case 'orderbook': {
+        const aggregation = this.orderbookAggregation(
+          sub.marketId,
+          sub.priceStep
+        )
         return {
-          type: 'l2Book',
-          coin: sub.marketId,
-          // HL's l2Book ignores any level-count field; it returns up to 20
-          // levels/side and controls granularity via nSigFigs (+ mantissa,
-          // valid only when nSigFigs === 5).
-          ...(sub.priceStep !== undefined
-            ? priceStepToAggregation(
-                sub.priceStep,
-                this.mergedMids().get(sub.marketId) ?? Number.NaN
-              )
-            : {}),
+          type: 'l2',
+          c: sub.marketId,
+          s: aggregation.nSigFigs ?? null,
+          m: aggregation.mantissa ?? null,
         }
+      }
       case 'candle':
         return {
           type: 'candle',
           coin: sub.marketId,
           interval: sub.interval,
         }
+      case 'trades':
+        return {
+          type: 'trades',
+          coin: sub.marketId,
+        }
       case 'orderUpdates':
         return { type: 'orderUpdates', user: sub.address }
       case 'fills':
@@ -312,15 +426,27 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
         case 'allDexsAssetCtxs':
           this.handleAllDexsAssetCtxs(msg.data as HlWsAllDexsAssetCtxsData)
           break
+        case 'pac':
+          this.handlePac(msg.data as string)
+          break
+        case 'sac':
+          this.handleSac(msg.data as string)
+          break
         case 'fastAssetCtxs':
           this.handleFastAssetCtxs(msg.data as string)
           break
+        case 'l2':
+          this.handleL2(msg.data as HlWsL2Data)
+          break
         case 'l2Book':
           this.handleL2Book(msg.data as HlWsL2BookData)
           break
         case 'candle':
           this.handleCandle(msg.data as HlWsCandleData)
           break
+        case 'trades':
+          this.handleTrades(msg.data as HlWsTrade[])
+          break
         case 'orderUpdates':
           this.handleOrderUpdates(msg.data as HlOrderDetail[])
           break
@@ -342,14 +468,76 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
   }
 
   private handleAllDexsAssetCtxs(data: HlWsAllDexsAssetCtxsData) {
-    for (const [dex, ctxs] of data.assetCtxs) {
-      const byMarketId: Record<string, HlWsPerpAssetCtx> = {}
+    this.mergePerpAssetCtxEntries(allDexsAssetCtxEntries(data))
+    this.emitMarketsContext()
+  }
+
+  private handlePac(base64: string) {
+    this.pacDecodeChain = this.pacDecodeChain
+      .then(async () => {
+        this.mergePerpAssetCtxEntries(
+          await decodeCompressedJson<HlWsPacData>(base64)
+        )
+        this.emitMarketsContext()
+      })
+      .catch((error) => wsLog.handlerFailure(this.providerKey, error))
+  }
+
+  private mergePerpAssetCtxEntries(
+    entries: [string, HlWsPerpAssetCtxPayload[]][]
+  ) {
+    for (const [dex, ctxs] of entries) {
+      const previous = this.perpCtxBySubDex.get(dex || 'default')
+      const byMarketId: Record<string, HlWsPerpAssetCtx> = {
+        ...(previous ?? {}),
+      }
       for (const ctx of ctxs) {
-        byMarketId[ctx.coin] = ctx
+        const marketId = ctx.coin
+        if (marketId === undefined) {
+          continue
+        }
+        const merged = mergePerpAssetCtx(previous?.[marketId], marketId, ctx)
+        if (merged !== undefined) {
+          byMarketId[marketId] = merged
+        }
       }
       this.perpCtxBySubDex.set(dex || 'default', byMarketId)
     }
-    this.emitMarketsContext()
+  }
+
+  private handleSac(base64: string) {
+    this.sacDecodeChain = this.sacDecodeChain
+      .then(async () => {
+        const spotMarketIdBySacKey = this.spotMarketIdBySacKey()
+        const ctxs = await decodeCompressedJson<HlWsSacData>(base64)
+        for (const [sacKey, ctx] of Object.entries(ctxs)) {
+          const marketId = spotMarketIdBySacKey.get(sacKey)
+          if (marketId === undefined) {
+            continue
+          }
+          this.spotCtxByMarketId[marketId] = {
+            ...this.spotCtxByMarketId[marketId],
+            ...ctx,
+          }
+        }
+        this.emitMarketsContext()
+      })
+      .catch((error) => wsLog.handlerFailure(this.providerKey, error))
+  }
+
+  private spotMarketIdBySacKey(): Map<string, string> {
+    const map = new Map<string, string>()
+    for (const market of this.registry?.markets ?? []) {
+      if (market.categoryId !== SPOT_MARKET_ID) {
+        continue
+      }
+      map.set(market.id, market.id)
+      map.set(
+        `${market.baseAsset.displaySymbol}/${market.quoteAsset.displaySymbol}`,
+        market.id
+      )
+    }
+    return map
   }
 
   /**
@@ -375,11 +563,8 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
   }
 
   /**
-   * Build the all-markets context map: every perp asset context across sub-dexs
-   * (oracle/funding/OI/metadata), with mid + mark overlaid from the
-   * high-frequency `fastAssetCtxs` feed. A market present in `fastAssetCtxs` but
-   * without an asset-context frame yet (the aggregate feed is slow/idle) still
-   * gets a mid+mark entry, so price ticks without waiting on the aggregate.
+   * Build the all-markets context map from perp + spot asset contexts, with mid
+   * + mark overlaid from `fastAssetCtxs`.
    */
   private emitMarketsContext() {
     const data: Record<string, MarketContext> = {}
@@ -394,6 +579,23 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
         }
       }
     }
+    for (const [marketId, ctx] of Object.entries(this.spotCtxByMarketId)) {
+      const midPrice = toMarketContextString(ctx.midPx ?? ctx.markPx)
+      const markPrice = toMarketContextString(ctx.markPx)
+      if (midPrice === undefined || markPrice === undefined) {
+        continue
+      }
+      const fast = this.fastCtxByMarketId[marketId]
+      const emittedMarkPrice = fast?.markPx != null ? fast.markPx : markPrice
+      data[marketId] = {
+        marketId,
+        midPrice: fast?.midPx != null ? fast.midPx : midPrice,
+        markPrice: emittedMarkPrice,
+        prevDayPrice: toMarketContextString(ctx.prevDayPx),
+        volume24h: toMarketContextString(ctx.dayNtlVlm),
+        marketCap: toMarketCapString(emittedMarkPrice, ctx.circulatingSupply),
+      }
+    }
     for (const [marketId, fast] of Object.entries(this.fastCtxByMarketId)) {
       if (data[marketId] !== undefined) {
         continue
@@ -409,7 +611,7 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
     this.emit('marketsContext', { channel: 'marketsContext', data })
   }
 
-  /** Latest mid per `Market.id` across the perp ctx feed and `fastAssetCtxs`. */
+  /** Latest mid per `Market.id` across asset-context and fast feeds. */
   private mergedMids(): Map<string, number> {
     const map = new Map<string, number>()
     for (const byMarketId of this.perpCtxBySubDex.values()) {
@@ -418,6 +620,12 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
         map.set(id, Number(mid))
       }
     }
+    for (const [id, ctx] of Object.entries(this.spotCtxByMarketId)) {
+      const mid = ctx.midPx ?? ctx.markPx
+      if (mid != null) {
+        map.set(id, Number(mid))
+      }
+    }
     for (const [id, fast] of Object.entries(this.fastCtxByMarketId)) {
       const mid = fast.midPx ?? fast.markPx
       if (mid != null) {
@@ -427,21 +635,93 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
     return map
   }
 
+  private orderbookReferencePrice(marketId: string): number {
+    const mid = this.mergedMids().get(marketId)
+    if (mid !== undefined) {
+      return mid
+    }
+
+    const book = this.latestOrderbookByMarketId.get(marketId)
+    const bid = book?.bids[0]?.price
+    const ask = book?.asks[0]?.price
+    if (bid !== undefined && ask !== undefined) {
+      return (Number(bid) + Number(ask)) / 2
+    }
+
+    return Number.NaN
+  }
+
   private handleL2Book(data: HlWsL2BookData) {
-    this.emit(`l2Book:${data.coin}`, {
-      channel: 'orderbook',
-      data: {
-        provider: this.providerKey,
-        marketId: data.coin,
-        bids: data.levels[0]
-          .slice(0, HL_L2_BOOK_MAX_LEVELS_PER_SIDE)
-          .map((l) => ({ price: l.px, size: l.sz })),
-        asks: data.levels[1]
-          .slice(0, HL_L2_BOOK_MAX_LEVELS_PER_SIDE)
-          .map((l) => ({ price: l.px, size: l.sz })),
-        timestamp: data.time,
-      },
-    })
+    const book = {
+      provider: this.providerKey,
+      marketId: data.coin,
+      bids: data.levels[0]
+        .slice(0, HL_L2_BOOK_MAX_LEVELS_PER_SIDE)
+        .map((l) => ({ price: l.px, size: l.sz })),
+      asks: data.levels[1]
+        .slice(0, HL_L2_BOOK_MAX_LEVELS_PER_SIDE)
+        .map((l) => ({ price: l.px, size: l.sz })),
+      timestamp: data.time,
+    }
+    this.latestOrderbookByMarketId.set(data.coin, book)
+    this.emitOrderbook(data.coin, book)
+  }
+
+  private handleL2(data: HlWsL2Data) {
+    if (data.s !== undefined) {
+      this.handleL2Book(data.s)
+    }
+    if (data.u !== undefined) {
+      this.handleCompactL2Delta(data.u)
+    }
+    if (data.c === undefined) {
+      return
+    }
+    const compressed = data.c
+    this.orderbookDecodeChain = this.orderbookDecodeChain
+      .then(async () => {
+        this.handleCompactL2Delta(
+          await decodeCompressedJson<HlWsCompressedL2Data>(compressed)
+        )
+      })
+      .catch((error) => wsLog.handlerFailure(this.providerKey, error))
+  }
+
+  private handleCompactL2Delta(delta: HlWsCompressedL2Data) {
+    const previous = this.latestOrderbookByMarketId.get(delta.c)
+    if (previous === undefined) {
+      return
+    }
+
+    const book: OrderbookResponse = {
+      provider: this.providerKey,
+      marketId: delta.c,
+      bids: applyCompressedL2Side(
+        previous.bids,
+        delta.l[0],
+        delta.r?.[0] ?? [],
+        'bid'
+      ),
+      asks: applyCompressedL2Side(
+        previous.asks,
+        delta.l[1],
+        delta.r?.[1] ?? [],
+        'ask'
+      ),
+      timestamp: delta.t,
+    }
+    this.latestOrderbookByMarketId.set(delta.c, book)
+    this.emitOrderbook(delta.c, book)
+  }
+
+  private emitOrderbook(marketId: string, book: OrderbookResponse) {
+    const keys = this.orderbookKeysByMarketId.get(marketId)
+    if (keys === undefined) {
+      return
+    }
+    for (const key of keys) {
+      this.emit(key, { channel: 'orderbook', data: book })
+    }
   }
 
   private handleCandle(data: HlWsCandleData) {
@@ -458,6 +738,25 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
     })
   }
 
+  private handleTrades(data: HlWsTrade[]) {
+    for (const trade of data) {
+      this.emit(`trades:${trade.coin}`, {
+        channel: 'trades',
+        data: [
+          {
+            provider: this.providerKey,
+            marketId: trade.coin,
+            price: trade.px,
+            size: trade.sz,
+            timestamp: trade.time,
+            side: trade.side === 'B' ? 'buy' : 'sell',
+            id: trade.tid !== undefined ? String(trade.tid) : trade.hash,
+          },
+        ],
+      })
+    }
+  }
+
   private handleOrderUpdates(data: HlOrderDetail[]) {
     // Untagged frame: attributable only via the single-address invariant.
     const key = this.orderUpdatesKey
@@ -563,6 +862,117 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
 const isObject = (v: unknown): v is Record<string, unknown> =>
   typeof v === 'object' && v !== null
 
+const toMarketContextString = (value: unknown): string | undefined =>
+  typeof value === 'string' || typeof value === 'number'
+    ? String(value)
+    : undefined
+
+const toMarketCapString = (
+  price: unknown,
+  circulatingSupply: unknown
+): string | undefined => {
+  const priceString = toMarketContextString(price)
+  const supplyString = toMarketContextString(circulatingSupply)
+  if (priceString === undefined || supplyString === undefined) {
+    return undefined
+  }
+
+  try {
+    const parsedPrice = new Big(priceString)
+    const parsedSupply = new Big(supplyString)
+    if (parsedPrice.lte(0) || parsedSupply.lte(0)) {
+      return undefined
+    }
+    return parsedPrice.times(parsedSupply).toFixed()
+  } catch {
+    return undefined
+  }
+}
+
+function mergePerpAssetCtx(
+  previous: HlWsPerpAssetCtx | undefined,
+  marketId: string,
+  update: HlWsPerpAssetCtxPayload
+): HlWsPerpAssetCtx | undefined {
+  const funding = update.funding ?? previous?.funding
+  const openInterest = update.openInterest ?? previous?.openInterest
+  const dayNtlVlm = update.dayNtlVlm ?? previous?.dayNtlVlm
+  const prevDayPx = update.prevDayPx ?? previous?.prevDayPx
+  const markPx = update.markPx ?? previous?.markPx
+  const midPx = 'midPx' in update ? update.midPx : previous?.midPx
+  const oraclePx = update.oraclePx ?? previous?.oraclePx
+
+  if (
+    funding === undefined ||
+    openInterest === undefined ||
+    dayNtlVlm === undefined ||
+    prevDayPx === undefined ||
+    markPx === undefined ||
+    midPx === undefined ||
+    oraclePx === undefined
+  ) {
+    return undefined
+  }
+
+  return {
+    coin: marketId,
+    funding,
+    openInterest,
+    dayNtlVlm,
+    prevDayPx,
+    markPx,
+    midPx,
+    oraclePx,
+  }
+}
+
+function allDexsAssetCtxEntries(
+  data: HlWsAllDexsAssetCtxsData
+): [string, HlWsPerpAssetCtxPayload[]][] {
+  return data.assetCtxs ?? data.ctxs ?? []
+}
+
+function compactRemovalPrice(
+  levels: OrderbookLevel[],
+  value: number | string | { p: string }
+): string | undefined {
+  if (typeof value === 'number') {
+    return levels[value]?.price
+  }
+  return typeof value === 'string' ? value : value.p
+}
+
+function applyCompressedL2Side(
+  previous: OrderbookLevel[],
+  updates: HlWsCompressedL2Data['l'][number],
+  removals: NonNullable<HlWsCompressedL2Data['r']>[number],
+  side: 'bid' | 'ask'
+): OrderbookLevel[] {
+  const byPrice = new Map(previous.map((level) => [level.price, level.size]))
+  for (const removal of removals) {
+    const price = compactRemovalPrice(previous, removal)
+    if (price !== undefined) {
+      byPrice.delete(price)
+    }
+  }
+  for (const update of updates) {
+    if (Number(update.s) === 0) {
+      byPrice.delete(update.p)
+    } else {
+      byPrice.set(update.p, update.s)
+    }
+  }
+
+  return [...byPrice.entries()]
+    .map(([price, size]) => ({ price, size }))
+    .sort((a, b) =>
+      side === 'bid'
+        ? Number(b.price) - Number(a.price)
+        : Number(a.price) - Number(b.price)
+    )
+    .slice(0, HL_L2_BOOK_MAX_LEVELS_PER_SIDE)
+}
+
 /**
  * Minimal presence/type check of the channel-discriminating and required
  * fields the matching handler dereferences without its own guard. A frame
@@ -572,7 +982,7 @@ const isObject = (v: unknown): v is Record<string, unknown> =>
  */
 function isValidHlFrame(channel: string, data: unknown): boolean {
   // `fastAssetCtxs` carries a base64 string payload, not an object.
-  if (channel === 'fastAssetCtxs') {
+  if (channel === 'fastAssetCtxs' || channel === 'pac' || channel === 'sac') {
     return typeof data === 'string'
   }
   if (!isObject(data)) {
@@ -580,7 +990,7 @@ function isValidHlFrame(channel: string, data: unknown): boolean {
   }
   switch (channel) {
     case 'allDexsAssetCtxs':
-      return Array.isArray(data.assetCtxs)
+      return Array.isArray(data.assetCtxs) || Array.isArray(data.ctxs)
     case 'l2Book':
       return (
         typeof data.coin === 'string' &&
@@ -589,8 +999,12 @@ function isValidHlFrame(channel: string, data: unknown): boolean {
         Array.isArray(data.levels[1]) &&
         typeof data.time === 'number'
       )
+    case 'l2':
+      return typeof data.c === 'string' || isObject(data.s) || isObject(data.u)
     case 'candle':
       return typeof data.s === 'string' && typeof data.i === 'string'
+    case 'trades':
+      return Array.isArray(data)
     case 'orderUpdates':
       return Array.isArray(data)
     case 'userFills':