@hypurrquant/perp-ws 0.15.0 → 0.16.0

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  */
 /**
  * Every perp-cli venue id. "ondo" and "qfex" are included for type stability but have no perp-cli/ws
- * codec until 0.15.1 (there is no `ondo` / `qfex` export to pass to createVenueStream yet).
+ * codec (planned, not yet available: there is no `ondo` / `qfex` export to pass to createVenueStream).
  */
 type VenueId = "pacifica" | "hyperliquid" | "lighter" | "aster" | "lighter-rh" | "ondo" | "arcus" | "qfex";
 declare const VENUE_IDS: readonly VenueId[];
@@ -74,6 +74,10 @@ declare class WsError extends Error {
         remediation?: string;
         details?: Record<string, unknown>;
     });
+    /** `structured.code` — the same place as `code` on error events (`e.code`). */
+    get code(): WsErrorCode;
+    /** `structured.remediation` — the same place as `remediation` on error events; null when none. */
+    get remediation(): string | null;
 }
 /** Structural check: a PerpError (CLI) or a WsError — anything carrying `structured.{code,message}`. */
 declare function isPerpError(e: unknown): e is {
@@ -109,6 +113,11 @@ interface WsLike {
         wasClean?: boolean;
     }) => void) | null;
     onerror: ((ev: unknown) => void) | null;
+    /**
+     * Optional: settles once the underlying socket is fully closed (no timer or socket left). The
+     * Node transport sets it; `stream.close()` awaits it (bounded) so the process is idle afterwards.
+     */
+    readonly whenClosed?: Promise<void>;
 }
 type WsFactory = (url: string) => WsLike;
 type FetchLike = (input: string, init?: {
@@ -384,7 +393,7 @@ type UserRef = {
     venue: "lighter" | "lighter-rh";
     accountIndex: number;
 }
-/** KNOWN GAP in 0.15.0: Aster user channels are not implemented (CAPABILITY_UNSUPPORTED); 0.15.1. */
+/** KNOWN GAP: Aster user channels are not implemented (CAPABILITY_UNSUPPORTED; planned, not yet available). */
  | {
     venue: "aster";
     user: `0x${string}`;
@@ -527,7 +536,7 @@ interface VenueStreamOptions {
     canonicalize?: Canonicalize;
     /** Needed for kind:"user". */
     credentials?: CredentialProvider;
-    /** Default false. Required for user channels whose auth needs a signing secret in the page (Aster/Ondo/QFEX, 0.15.1). */
+    /** Default false. Required for user channels whose auth needs a signing secret in the page (Aster / Ondo / QFEX — planned, not yet available). */
     allowInPageSecrets?: boolean;
     /** ≤ venue limits. */
     budget?: {
@@ -807,8 +816,8 @@ declare function createVenueStream(codec: VenueCodec, opts?: VenueStreamOptions)
  */
 declare const USD_LIKE_QUOTES: ReadonlySet<string>;
 /**
- * HIP-3 (dex set) → "<dex>:<BASE>". A USD-like quote → "<BASE>". Any other quote, or an unknown
- * quote (null), → null (not comparable by default).
+ * HIP-3 (dex set) → "<dex>:<BASE>". An ambiguous ticker (isUnclassifiedTicker) → null. A USD-like
+ * quote → "<BASE>". Any other quote, or an unknown quote (null), → null (not comparable by default).
  */
 declare const defaultCanonicalize: Canonicalize;
 
@@ -871,9 +880,17 @@ interface FundingComparator {
     subscribe(cb: (rows: FundingRow[], changed: string[]) => void): () => void;
     close(): void;
 }
-/** @experimental 0.15.x (stable from 0.16.0 after consumer sign-off) */
+/**
+ * Rate per hour as a FRACTION (0.0000125 = 0.00125 %/h): `rate / rateIntervalHours`.
+ * @experimental 0.15.x (stable from 0.16.0 after consumer sign-off)
+ */
 declare function toHourly(rate: Dec | null, rateIntervalHours: number | null): number | null;
-/** @experimental 0.15.x (stable from 0.16.0 after consumer sign-off) */
+/**
+ * Simple annualized rate as a FRACTION, not a percent: `toHourly × 24 × 365` (0.0000125/h → 0.1095,
+ * i.e. 10.95 %). The CLI's `annualizedPct` (`arb scan --rates`, MCP `get_funding_rates`) is the same
+ * quantity in PERCENT (10.95): multiply `toApr` by 100 to compare the two.
+ * @experimental 0.15.x (stable from 0.16.0 after consumer sign-off)
+ */
 declare function toApr(rate: Dec | null, rateIntervalHours: number | null): number | null;
 /** @experimental 0.15.x (stable from 0.16.0 after consumer sign-off) */
 declare function createFundingComparator(opts: FundingComparatorOptions): FundingComparator;
@@ -916,7 +933,11 @@ declare const pacifica: VenueCodec;
  *
  * Units (Phase 0, the key correction): WS `funding_rate` (last settled) and `current_funding_rate`
  * (predicted) are PERCENT per 1 h → converted to a fraction by an exact 2-place decimal shift,
- * rateIntervalHours = settlementIntervalHours = 1. `open_interest` is USD notional (not base).
+ * rateIntervalHours = settlementIntervalHours = 1. `open_interest` is USD notional (not base) and
+ * one side — INFERRED, not documented by the venue: WS open_interest / mark = REST orderBookDetails
+ * `open_interest` (base) (2026-10-19, BTC: 174.88 M USD / 82,387 = 2,122.7 BTC), and the venue's
+ * exchangeMetrics open_interest — a DAILY snapshot, two days old when compared — was ≈ 2× the
+ * current one-side figure (336.6 M USD).
  * Errors arrive as {error:{code,message}} with no channel field (matched by the channel name in
  * the message). Spot markets (market_type "spot" in /api/v1/orderBooks) are not perps and skipped.
  *
@@ -928,7 +949,7 @@ declare const lighter: VenueCodec;
 declare const lighterRh: VenueCodec;
 
 /**
- * Aster codec (§6.1, public only in 0.15.0). One combined-stream socket (`/stream`, frames
+ * Aster codec (§6.1, public channels only). One combined-stream socket (`/stream`, frames
  * {stream, data}) with `!markPrice@arr@1s` (every symbol, 1 s) + `!ticker@arr` (only changed symbols).
  * r = accruing current-period rate (Phase 0: == premiumIndex.lastFundingRate ≠ last settled).
  * The funding interval is per market from the LABELLED REST source `rest:/fapi/v3/fundingInfo`

package/dist/index.js

@@ -37,6 +37,14 @@ var WsError = class extends Error {
       ...opts?.details !== void 0 ? { details: opts.details } : {}
     };
   }
+  /** `structured.code` — the same place as `code` on error events (`e.code`). */
+  get code() {
+    return this.structured.code;
+  }
+  /** `structured.remediation` — the same place as `remediation` on error events; null when none. */
+  get remediation() {
+    return this.structured.remediation === void 0 ? null : this.structured.remediation;
+  }
 };
 function isPerpError(e) {
   if (e === null || typeof e !== "object") return false;
@@ -45,11 +53,89 @@ function isPerpError(e) {
   return typeof s.code === "string" && typeof s.message === "string";
 }
 
+// src/ws/unclassified.ts
+var UNCLASSIFIED_TICKERS = {
+  hyperliquid: /* @__PURE__ */ new Set(["SPX"]),
+  aster: /* @__PURE__ */ new Set(["SPX"]),
+  pacifica: /* @__PURE__ */ new Set(["SPX", "BP", "CHIP"]),
+  lighter: /* @__PURE__ */ new Set(["BB", "BOT", "WEN", "QNT", "SPX"])
+};
+var LIGHTER_RH_CLASS = {
+  // crypto
+  BTC: "crypto",
+  ETH: "crypto",
+  SOL: "crypto",
+  HYPE: "crypto",
+  ZEC: "crypto",
+  LIT: "crypto",
+  VVV: "crypto",
+  SUI: "crypto",
+  NEAR: "crypto",
+  XRP: "crypto",
+  CASHCAT: "crypto",
+  PONS: "crypto",
+  // commodity (canonical via EXPLICIT_CANONICAL: XAU → GOLD, XAG → SILVER)
+  XAU: "commodity",
+  XAG: "commodity",
+  // etf
+  SPY: "etf",
+  QQQ: "etf",
+  SOXL: "etf",
+  SLV: "etf",
+  USO: "etf",
+  SGOV: "etf",
+  // equity
+  AAPL: "equity",
+  AMZN: "equity",
+  GOOGL: "equity",
+  META: "equity",
+  MSFT: "equity",
+  NVDA: "equity",
+  TSLA: "equity",
+  AMD: "equity",
+  INTC: "equity",
+  MU: "equity",
+  TSM: "equity",
+  ORCL: "equity",
+  PLTR: "equity",
+  COIN: "equity",
+  CRCL: "equity",
+  CRWV: "equity",
+  BABA: "equity",
+  SNDK: "equity",
+  SMCI: "equity",
+  SOFI: "equity",
+  AMC: "equity",
+  RGTI: "equity",
+  QBTS: "equity",
+  CLSK: "equity",
+  IREN: "equity",
+  WULF: "equity",
+  LUNR: "equity",
+  ASTS: "equity",
+  BE: "equity",
+  USAR: "equity",
+  SPCX: "equity",
+  SKHY: "equity",
+  // pre-IPO / private (explicit-only canonical → null unless mapped)
+  OPENAI: "preIpo",
+  ANTHROPIC: "preIpo",
+  SHEIN: "preIpo",
+  ANSEM: "preIpo",
+  AI: "preIpo"
+};
+function isUnclassifiedTicker(venue, base) {
+  const up = base.toUpperCase();
+  if (venue === "lighter-rh") return LIGHTER_RH_CLASS[up] === void 0;
+  return UNCLASSIFIED_TICKERS[venue]?.has(up) === true;
+}
+
 // src/ws/canonical.ts
 var USD_LIKE_QUOTES = /* @__PURE__ */ new Set(["USDT", "USD1", "USDC", "USD", "USDG"]);
-var defaultCanonicalize = (_venue, m) => {
+var defaultCanonicalize = (venue, m) => {
   const base = m.base.toUpperCase();
   if (m.dex !== null && m.dex !== "") return `${m.dex}:${base}`;
+  if (isUnclassifiedTicker(venue, base)) return null;
   if (m.quote === null) return null;
   return USD_LIKE_QUOTES.has(m.quote.toUpperCase()) ? base : null;
 };
@@ -122,6 +208,7 @@ var Connection = class {
     this.sendQueue = [];
     this.sendTimer = null;
     this.reconnectTimer = null;
+    this.closing = /* @__PURE__ */ new Set();
     this.staleTimer = null;
     this.pingTimer = null;
     this.awaitingPongSince = null;
@@ -446,15 +533,26 @@ var Connection = class {
         ws.close(code, reason);
       } catch {
       }
+      if (ws.whenClosed !== void 0) {
+        const p = ws.whenClosed;
+        this.closing.add(p);
+        void p.then(() => {
+          this.closing.delete(p);
+        });
+      }
     }
   }
+  /** Settles when every socket this connection closed is fully gone (transports that report it). */
+  drained() {
+    return Promise.all(Array.from(this.closing)).then(() => void 0);
+  }
 };
 function stateDetails(s) {
   const { status: _status, ...rest } = s;
   return rest;
 }
 function closedError(venue) {
-  return new WsError("INVALID_PARAMS", `${venue} stream is closed`, { exchange: venue, remediation: "Create a new stream" });
+  return new WsError("INVALID_PARAMS", `${venue} stream is closed`, { exchange: venue, remediation: "Create a new stream", details: { closeReason: "CLIENT_CLOSE" } });
 }
 
 // src/ws/market-state.ts
@@ -972,6 +1070,7 @@ function checkCodec(codec) {
     throw new WsError("INVALID_PARAMS", `createVenueStream: first argument must be a venue codec (${problem})`, { remediation: CODEC_REMEDIATION });
   }
 }
+var CLOSE_DRAIN_MS = 2e3;
 function suggestCanonicals(missing, entries) {
   const m = missing.toUpperCase();
   const out = entries.filter((e) => e.canonical !== null && (e.canonical.toUpperCase() === m || e.base.toUpperCase() === m || e.canonical.toUpperCase().endsWith(`:${m}`))).map((e) => e.canonical);
@@ -979,7 +1078,7 @@ function suggestCanonicals(missing, entries) {
 }
 function suggestSymbols(missing, entries) {
   const m = missing.toUpperCase();
-  const out = entries.filter((e) => e.symbol.toUpperCase() === m || e.canonical !== null && e.canonical.toUpperCase() === m || e.base.toUpperCase() === m).map((e) => e.symbol);
+  const out = entries.filter((e) => e.symbol.toUpperCase() === m || e.canonical !== null && (e.canonical.toUpperCase() === m || e.base.toUpperCase() === m)).map((e) => e.symbol);
   return Array.from(new Set(out)).slice(0, 5);
 }
 var EVENT_CHANNEL = { account: "account", positions: "positions", orders: "orders", fill: "fills", fills: "fills" };
@@ -1738,7 +1837,7 @@ function createVenueStream(codec, opts = {}) {
     }
     if (target.kind === "market") {
       const channels = target.channels;
-      const valid = `Use channels ${MARKET_CHANNELS.map((c) => `"${c}"`).join(" / ")} (book and trades arrive in 0.15.1)`;
+      const valid = `Use channels ${MARKET_CHANNELS.map((c) => `"${c}"`).join(" / ")} (book and trades: planned, not yet available)`;
       if (!Array.isArray(channels) || channels.length === 0) {
         throw wsError("INVALID_PARAMS", 'kind "market" needs at least one channel', valid);
       }
@@ -1749,7 +1848,7 @@ function createVenueStream(codec, opts = {}) {
         throw wsError(
           "CAPABILITY_UNSUPPORTED",
           `${venue} channel(s) ${later.join(", ")} are not available in this release`,
-          'Use channels "market" / "bbo" (book and trades arrive in 0.15.1)'
+          'Use channels "market" / "bbo" (book and trades: planned, not yet available)'
         );
       }
       if (target.channels.includes("bbo") && !codec.capabilities.channels.bbo) {
@@ -2063,6 +2162,14 @@ function createVenueStream(codec, opts = {}) {
         sub.end();
       }
       stateListeners.clear();
+      let bound = null;
+      await Promise.race([
+        Promise.all(shards.map((sh) => sh.conn.drained())),
+        new Promise((resolve) => {
+          bound = setTimeout(resolve, CLOSE_DRAIN_MS);
+        })
+      ]);
+      if (bound !== null) clearTimeout(bound);
     }
   };
   return stream;
@@ -2424,6 +2531,23 @@ function mulDecimalInt(s, n, shift) {
   const abs2 = (neg ? -product : product).toString();
   return shiftDecimal(`${neg ? "-" : ""}${abs2}`, shift - frac.length);
 }
+function sumDecimals(values) {
+  let scale = 0;
+  const parts = [];
+  for (const v of values) {
+    const m = DECIMAL_RE.exec(v);
+    if (m === null || m[4] !== void 0 || m[2] === "" && (m[3] === void 0 || m[3] === "")) return void 0;
+    const frac = m[3] === void 0 ? "" : m[3];
+    const digits = `${m[2]}${frac}`.replace(/^0+(?=\d)/, "");
+    parts.push({ int: BigInt(digits === "" ? "0" : digits) * (m[1] === "-" ? -1n : 1n), scale: frac.length });
+    if (frac.length > scale) scale = frac.length;
+  }
+  let total = 0n;
+  for (const p of parts) total += p.int * 10n ** BigInt(scale - p.scale);
+  const neg = total < 0n;
+  const abs2 = (neg ? -total : total).toString();
+  return shiftDecimal(`${neg ? "-" : ""}${abs2}`, -scale);
+}
 
 // src/ws/codecs/common.ts
 function isObj(v) {
@@ -2504,9 +2628,9 @@ function capabilities(p) {
     channels: { allMarkets: true, market: true, bbo: true, book: false, trades: false, user: p.user },
     fields: p.fields,
     notes: {
-      book: "Not in this release (0.15.1)",
-      trades: "Not in this release (0.15.1)",
-      ...p.user ? {} : { user: "Not in this release (0.15.1)" },
+      book: "Planned, not yet available",
+      trades: "Planned, not yet available",
+      ...p.user ? {} : { user: "Planned, not yet available" },
       ...p.notes
     }
   };
@@ -2746,6 +2870,16 @@ var SIDE = { B: "buy", A: "sell" };
 function abs(d) {
   return d === null ? null : d.replace(/^-/, "");
 }
+function accountUnrealized(rows, bad) {
+  if (bad.includes("assetPositions") || bad.includes("assetPositions[]")) return null;
+  const values = [];
+  for (const r of rows) {
+    if (r.unrealizedPnl === null) return null;
+    values.push(r.unrealizedPnl);
+  }
+  const sum = sumDecimals(values);
+  return sum === void 0 ? null : sum;
+}
 function decodeClearinghouse(d) {
   if (!isObj(d) || typeof d.dex !== "string" || !isObj(d.clearinghouseState)) return [protocolError("hyperliquid clearinghouseState frame without dex/clearinghouseState")];
   const wire = `clearinghouseState:${d.dex}`;
@@ -2788,8 +2922,10 @@ function decodeClearinghouse(d) {
       equity: ms === null ? null : dec(ms, "accountValue", bad),
       available: dec(cs, "withdrawable", bad),
       marginUsed: ms === null ? null : dec(ms, "totalMarginUsed", bad),
-      unrealizedPnl: null
-      // not in clearinghouseState (per-position only)
+      // clearinghouseState has no account-level unrealizedPnl, but the frame carries every
+      // position of this dex with its own `unrealizedPnl`: the account value is their exact sum
+      // ("0" with no position). null when any position's value is missing (unknown, never guessed).
+      unrealizedPnl: accountUnrealized(rows, bad)
     },
     { kind: "positions", snapshot: true, scope: d.dex, rows, remove: [] }
   ];
@@ -3284,6 +3420,11 @@ function decodeBbo2(d) {
   return out;
 }
 
+// src/ws/lighter-market.ts
+function isLighterMarketLive(row) {
+  return row.status === "active" && row.is_frozen !== true;
+}
+
 // src/ws/codecs/lighter.ts
 var ALL2 = "market_stats/all";
 var ORDERS_TOKEN_TTL_SEC = 3600;
@@ -3292,6 +3433,10 @@ var ZERO = /^-?0*(\.0*)?$/;
 function bookSide(o, key, bad) {
   return o[key] === "" ? null : readDec(o, key, bad);
 }
+function lastTrade(o, bad) {
+  const v = readDec(o, "last_trade_price", bad);
+  return v !== void 0 && v !== null && ZERO.test(v) ? null : v;
+}
 function percentToFraction(o, key, bad) {
   const v = readDec(o, key, bad);
   if (v === void 0 || v === null) return v;
@@ -3324,7 +3469,7 @@ function makeLighter(venue, quote) {
       notes: {
         rate: "WS funding is PERCENT per 1 h on the wire; emitted as a fraction per 1 h",
         nextFundingTime: "Hourly settlement rule (venue-definition)",
-        openInterest: "USD notional (Phase 0), sides not stated by the venue",
+        openInterest: "USD notional, one side \u2014 inferred, not documented by the venue (= REST orderBookDetails open_interest, base, \xD7 mark; the venue's exchangeMetrics kind=open_interest, a daily snapshot, read \u2248 2\xD7 when compared with the current value)",
         user: "By accountIndex. user_stats / account_all_positions / account_all_trades need no auth; account_all_orders needs CredentialProvider.authToken (re-called at 80 % TTL). account_all_trades does not replay \u2192 gap refetch-required for fills after a reconnect",
         clientId: "orders: client_order_id; fills: ask_/bid_client_id_str of our side; 0 = no client id \u2192 null",
         liquidationPrice: 'liquidation_price; "0" (no liquidation price, e.g. well-covered cross margin) \u2192 null, as in the CLI REST path',
@@ -3341,7 +3486,7 @@ function makeLighter(venue, quote) {
     limits: S5.limits,
     closesOnBadSubscribe: false,
     staleAfterMs: S5.staleAfterMs,
-    openInterest: { unit: "usd", sides: null },
+    openInterest: { unit: "usd", sides: "one" },
     refresh: null,
     async loadDirectory(ctx) {
       const raw = await fetchJson(ctx.fetch, venue, `${ctx.restUrl}/api/v1/orderBooks`);
@@ -3359,6 +3504,10 @@ function makeLighter(venue, quote) {
           continue;
         }
         idToSymbol.set(id, m.symbol);
+        if (!isLighterMarketLive(m)) {
+          nonPerp.add(id);
+          continue;
+        }
         entries.push({
           venue,
           dex: null,
@@ -3494,7 +3643,7 @@ function decodeStats(venue, f, d, recvTs) {
       index: readDec(r, "index_price", bad),
       bestBid: bookSide(r, "best_bid_price", bad),
       bestAsk: bookSide(r, "best_ask_price", bad),
-      last: readDec(r, "last_trade_price", bad),
+      last: lastTrade(r, bad),
       rate: percentToFraction(r, "funding_rate", bad),
       predictedRate: percentToFraction(r, "current_funding_rate", bad),
       openInterest: readDec(r, "open_interest", bad),
@@ -3710,6 +3859,14 @@ function decodeTicker(venue, wire, f, d) {
   return out;
 }
 
+// src/ws/aster-market.ts
+function isAsterListedPerpetual(row) {
+  return row.contractType === "PERPETUAL" && row.status === "TRADING";
+}
+function asterMatchable(row) {
+  return row.quoteAsset === "USDT";
+}
+
 // src/ws/codecs/aster.ts
 var S3 = VENUE_STATIC.aster;
 var MARK = "!markPrice@arr@1s";
@@ -3757,7 +3914,7 @@ var aster = {
       openInterest: "Not on WS (REST only)",
       fundingInterval: `Labelled REST source ${FUNDING_INFO}, refreshed hourly; missing \u2192 null`,
       volume24hNotional: "!ticker@arr q (quote-asset volume)",
-      user: 'KNOWN GAP in 0.15.0: no Aster user channels (signed USER_STREAM listenKey) \u2014 kind:"user" rejects CAPABILITY_UNSUPPORTED; arrives in 0.15.1',
+      user: 'KNOWN GAP: no Aster user channels (signed USER_STREAM listenKey) \u2014 kind:"user" rejects CAPABILITY_UNSUPPORTED; planned, not yet available',
       bbo: "<symbol>@bookTicker; `u` orders frames (non-contiguous)"
     }
   }),
@@ -3797,6 +3954,7 @@ var aster = {
       if (!isObj(s) || typeof s.symbol !== "string" || typeof s.baseAsset !== "string") {
         throw badShape("aster", "exchangeInfo symbol without symbol/baseAsset");
       }
+      if (!isAsterListedPerpetual(s)) continue;
       const quote = typeof s.quoteAsset === "string" && s.quoteAsset !== "" ? s.quoteAsset : null;
       listed.add(s.symbol);
       const hours = intervals.get(s.symbol);
@@ -3807,7 +3965,8 @@ var aster = {
         venueSymbol: s.symbol,
         base: s.baseAsset,
         quote,
-        canonical: ctx.canonicalize("aster", { venueSymbol: s.symbol, dex: null, base: s.baseAsset, quote }),
+        // Only the USDT listing is matchable (asterMatchable — the CLI rule): BTCUSD1 is never a second BTC leg.
+        canonical: asterMatchable(s) ? ctx.canonicalize("aster", { venueSymbol: s.symbol, dex: null, base: s.baseAsset, quote }) : null,
         rateIntervalHours: hours === void 0 ? null : hours,
         settlementIntervalHours: hours === void 0 ? null : hours,
         source: "rest:/fapi/v3/exchangeInfo"
@@ -3930,6 +4089,11 @@ function decodeArr(wire, data2, d, fn) {
   return out;
 }
 
+// src/ws/arcus-market.ts
+function isArcusOnlineMarket(row) {
+  return row.status === "ONLINE";
+}
+
 // src/ws/codecs/arcus.ts
 var S4 = VENUE_STATIC.arcus;
 var MARKETS = "markets";
@@ -3980,6 +4144,7 @@ var arcus = {
       if (!isObj(m) || typeof m.marketDisplayName !== "string" || typeof m.marketId !== "number" || typeof m.baseAsset !== "string") {
         throw badShape("arcus", "market without marketDisplayName/marketId/baseAsset");
       }
+      if (!isArcusOnlineMarket(m)) continue;
       const quote = typeof m.quoteAsset === "string" ? m.quoteAsset : null;
       idToSymbol.set(String(m.marketId), m.marketDisplayName);
       entries.push({

package/dist/node.d.ts

@@ -4,7 +4,7 @@
  */
 /**
  * Every perp-cli venue id. "ondo" and "qfex" are included for type stability but have no perp-cli/ws
- * codec until 0.15.1 (there is no `ondo` / `qfex` export to pass to createVenueStream yet).
+ * codec (planned, not yet available: there is no `ondo` / `qfex` export to pass to createVenueStream).
  */
 type VenueId = "pacifica" | "hyperliquid" | "lighter" | "aster" | "lighter-rh" | "ondo" | "arcus" | "qfex";
 declare const VENUE_IDS: readonly VenueId[];
@@ -74,6 +74,10 @@ declare class WsError extends Error {
         remediation?: string;
         details?: Record<string, unknown>;
     });
+    /** `structured.code` — the same place as `code` on error events (`e.code`). */
+    get code(): WsErrorCode;
+    /** `structured.remediation` — the same place as `remediation` on error events; null when none. */
+    get remediation(): string | null;
 }
 /** Structural check: a PerpError (CLI) or a WsError — anything carrying `structured.{code,message}`. */
 declare function isPerpError(e: unknown): e is {
@@ -109,6 +113,11 @@ interface WsLike {
         wasClean?: boolean;
     }) => void) | null;
     onerror: ((ev: unknown) => void) | null;
+    /**
+     * Optional: settles once the underlying socket is fully closed (no timer or socket left). The
+     * Node transport sets it; `stream.close()` awaits it (bounded) so the process is idle afterwards.
+     */
+    readonly whenClosed?: Promise<void>;
 }
 type WsFactory = (url: string) => WsLike;
 type FetchLike = (input: string, init?: {
@@ -384,7 +393,7 @@ type UserRef = {
     venue: "lighter" | "lighter-rh";
     accountIndex: number;
 }
-/** KNOWN GAP in 0.15.0: Aster user channels are not implemented (CAPABILITY_UNSUPPORTED); 0.15.1. */
+/** KNOWN GAP: Aster user channels are not implemented (CAPABILITY_UNSUPPORTED; planned, not yet available). */
  | {
     venue: "aster";
     user: `0x${string}`;
@@ -527,7 +536,7 @@ interface VenueStreamOptions {
     canonicalize?: Canonicalize;
     /** Needed for kind:"user". */
     credentials?: CredentialProvider;
-    /** Default false. Required for user channels whose auth needs a signing secret in the page (Aster/Ondo/QFEX, 0.15.1). */
+    /** Default false. Required for user channels whose auth needs a signing secret in the page (Aster / Ondo / QFEX — planned, not yet available). */
     allowInPageSecrets?: boolean;
     /** ≤ venue limits. */
     budget?: {
@@ -792,8 +801,8 @@ interface VenueCodec {
  */
 declare const USD_LIKE_QUOTES: ReadonlySet<string>;
 /**
- * HIP-3 (dex set) → "<dex>:<BASE>". A USD-like quote → "<BASE>". Any other quote, or an unknown
- * quote (null), → null (not comparable by default).
+ * HIP-3 (dex set) → "<dex>:<BASE>". An ambiguous ticker (isUnclassifiedTicker) → null. A USD-like
+ * quote → "<BASE>". Any other quote, or an unknown quote (null), → null (not comparable by default).
  */
 declare const defaultCanonicalize: Canonicalize;
 
@@ -856,9 +865,17 @@ interface FundingComparator {
     subscribe(cb: (rows: FundingRow[], changed: string[]) => void): () => void;
     close(): void;
 }
-/** @experimental 0.15.x (stable from 0.16.0 after consumer sign-off) */
+/**
+ * Rate per hour as a FRACTION (0.0000125 = 0.00125 %/h): `rate / rateIntervalHours`.
+ * @experimental 0.15.x (stable from 0.16.0 after consumer sign-off)
+ */
 declare function toHourly(rate: Dec | null, rateIntervalHours: number | null): number | null;
-/** @experimental 0.15.x (stable from 0.16.0 after consumer sign-off) */
+/**
+ * Simple annualized rate as a FRACTION, not a percent: `toHourly × 24 × 365` (0.0000125/h → 0.1095,
+ * i.e. 10.95 %). The CLI's `annualizedPct` (`arb scan --rates`, MCP `get_funding_rates`) is the same
+ * quantity in PERCENT (10.95): multiply `toApr` by 100 to compare the two.
+ * @experimental 0.15.x (stable from 0.16.0 after consumer sign-off)
+ */
 declare function toApr(rate: Dec | null, rateIntervalHours: number | null): number | null;
 /** @experimental 0.15.x (stable from 0.16.0 after consumer sign-off) */
 declare function createFundingComparator(opts: FundingComparatorOptions): FundingComparator;
@@ -901,7 +918,11 @@ declare const pacifica: VenueCodec;
  *
  * Units (Phase 0, the key correction): WS `funding_rate` (last settled) and `current_funding_rate`
  * (predicted) are PERCENT per 1 h → converted to a fraction by an exact 2-place decimal shift,
- * rateIntervalHours = settlementIntervalHours = 1. `open_interest` is USD notional (not base).
+ * rateIntervalHours = settlementIntervalHours = 1. `open_interest` is USD notional (not base) and
+ * one side — INFERRED, not documented by the venue: WS open_interest / mark = REST orderBookDetails
+ * `open_interest` (base) (2026-10-19, BTC: 174.88 M USD / 82,387 = 2,122.7 BTC), and the venue's
+ * exchangeMetrics open_interest — a DAILY snapshot, two days old when compared — was ≈ 2× the
+ * current one-side figure (336.6 M USD).
  * Errors arrive as {error:{code,message}} with no channel field (matched by the channel name in
  * the message). Spot markets (market_type "spot" in /api/v1/orderBooks) are not perps and skipped.
  *
@@ -913,7 +934,7 @@ declare const lighter: VenueCodec;
 declare const lighterRh: VenueCodec;
 
 /**
- * Aster codec (§6.1, public only in 0.15.0). One combined-stream socket (`/stream`, frames
+ * Aster codec (§6.1, public channels only). One combined-stream socket (`/stream`, frames
  * {stream, data}) with `!markPrice@arr@1s` (every symbol, 1 s) + `!ticker@arr` (only changed symbols).
  * r = accruing current-period rate (Phase 0: == premiumIndex.lastFundingRate ≠ last settled).
  * The funding interval is per market from the LABELLED REST source `rest:/fapi/v3/fundingInfo`

package/dist/node.js

@@ -29,6 +29,14 @@ var WsError = class extends Error {
       ...opts?.details !== void 0 ? { details: opts.details } : {}
     };
   }
+  /** `structured.code` — the same place as `code` on error events (`e.code`). */
+  get code() {
+    return this.structured.code;
+  }
+  /** `structured.remediation` — the same place as `remediation` on error events; null when none. */
+  get remediation() {
+    return this.structured.remediation === void 0 ? null : this.structured.remediation;
+  }
 };
 function isPerpError(e) {
   if (e === null || typeof e !== "object") return false;
@@ -37,11 +45,89 @@ function isPerpError(e) {
   return typeof s.code === "string" && typeof s.message === "string";
 }
 
+// src/ws/unclassified.ts
+var UNCLASSIFIED_TICKERS = {
+  hyperliquid: /* @__PURE__ */ new Set(["SPX"]),
+  aster: /* @__PURE__ */ new Set(["SPX"]),
+  pacifica: /* @__PURE__ */ new Set(["SPX", "BP", "CHIP"]),
+  lighter: /* @__PURE__ */ new Set(["BB", "BOT", "WEN", "QNT", "SPX"])
+};
+var LIGHTER_RH_CLASS = {
+  // crypto
+  BTC: "crypto",
+  ETH: "crypto",
+  SOL: "crypto",
+  HYPE: "crypto",
+  ZEC: "crypto",
+  LIT: "crypto",
+  VVV: "crypto",
+  SUI: "crypto",
+  NEAR: "crypto",
+  XRP: "crypto",
+  CASHCAT: "crypto",
+  PONS: "crypto",
+  // commodity (canonical via EXPLICIT_CANONICAL: XAU → GOLD, XAG → SILVER)
+  XAU: "commodity",
+  XAG: "commodity",
+  // etf
+  SPY: "etf",
+  QQQ: "etf",
+  SOXL: "etf",
+  SLV: "etf",
+  USO: "etf",
+  SGOV: "etf",
+  // equity
+  AAPL: "equity",
+  AMZN: "equity",
+  GOOGL: "equity",
+  META: "equity",
+  MSFT: "equity",
+  NVDA: "equity",
+  TSLA: "equity",
+  AMD: "equity",
+  INTC: "equity",
+  MU: "equity",
+  TSM: "equity",
+  ORCL: "equity",
+  PLTR: "equity",
+  COIN: "equity",
+  CRCL: "equity",
+  CRWV: "equity",
+  BABA: "equity",
+  SNDK: "equity",
+  SMCI: "equity",
+  SOFI: "equity",
+  AMC: "equity",
+  RGTI: "equity",
+  QBTS: "equity",
+  CLSK: "equity",
+  IREN: "equity",
+  WULF: "equity",
+  LUNR: "equity",
+  ASTS: "equity",
+  BE: "equity",
+  USAR: "equity",
+  SPCX: "equity",
+  SKHY: "equity",
+  // pre-IPO / private (explicit-only canonical → null unless mapped)
+  OPENAI: "preIpo",
+  ANTHROPIC: "preIpo",
+  SHEIN: "preIpo",
+  ANSEM: "preIpo",
+  AI: "preIpo"
+};
+function isUnclassifiedTicker(venue, base) {
+  const up = base.toUpperCase();
+  if (venue === "lighter-rh") return LIGHTER_RH_CLASS[up] === void 0;
+  return UNCLASSIFIED_TICKERS[venue]?.has(up) === true;
+}
+
 // src/ws/canonical.ts
 var USD_LIKE_QUOTES = /* @__PURE__ */ new Set(["USDT", "USD1", "USDC", "USD", "USDG"]);
-var defaultCanonicalize = (_venue, m) => {
+var defaultCanonicalize = (venue, m) => {
   const base = m.base.toUpperCase();
   if (m.dex !== null && m.dex !== "") return `${m.dex}:${base}`;
+  if (isUnclassifiedTicker(venue, base)) return null;
   if (m.quote === null) return null;
   return USD_LIKE_QUOTES.has(m.quote.toUpperCase()) ? base : null;
 };
@@ -114,6 +200,7 @@ var Connection = class {
     this.sendQueue = [];
     this.sendTimer = null;
     this.reconnectTimer = null;
+    this.closing = /* @__PURE__ */ new Set();
     this.staleTimer = null;
     this.pingTimer = null;
     this.awaitingPongSince = null;
@@ -438,15 +525,26 @@ var Connection = class {
         ws.close(code, reason);
       } catch {
       }
+      if (ws.whenClosed !== void 0) {
+        const p = ws.whenClosed;
+        this.closing.add(p);
+        void p.then(() => {
+          this.closing.delete(p);
+        });
+      }
     }
   }
+  /** Settles when every socket this connection closed is fully gone (transports that report it). */
+  drained() {
+    return Promise.all(Array.from(this.closing)).then(() => void 0);
+  }
 };
 function stateDetails(s) {
   const { status: _status, ...rest } = s;
   return rest;
 }
 function closedError(venue) {
-  return new WsError("INVALID_PARAMS", `${venue} stream is closed`, { exchange: venue, remediation: "Create a new stream" });
+  return new WsError("INVALID_PARAMS", `${venue} stream is closed`, { exchange: venue, remediation: "Create a new stream", details: { closeReason: "CLIENT_CLOSE" } });
 }
 
 // src/ws/ids.ts
@@ -976,6 +1074,7 @@ function checkCodec(codec) {
     throw new WsError("INVALID_PARAMS", `createVenueStream: first argument must be a venue codec (${problem})`, { remediation: CODEC_REMEDIATION });
   }
 }
+var CLOSE_DRAIN_MS = 2e3;
 function suggestCanonicals(missing, entries) {
   const m = missing.toUpperCase();
   const out = entries.filter((e) => e.canonical !== null && (e.canonical.toUpperCase() === m || e.base.toUpperCase() === m || e.canonical.toUpperCase().endsWith(`:${m}`))).map((e) => e.canonical);
@@ -983,7 +1082,7 @@ function suggestCanonicals(missing, entries) {
 }
 function suggestSymbols(missing, entries) {
   const m = missing.toUpperCase();
-  const out = entries.filter((e) => e.symbol.toUpperCase() === m || e.canonical !== null && e.canonical.toUpperCase() === m || e.base.toUpperCase() === m).map((e) => e.symbol);
+  const out = entries.filter((e) => e.symbol.toUpperCase() === m || e.canonical !== null && (e.canonical.toUpperCase() === m || e.base.toUpperCase() === m)).map((e) => e.symbol);
   return Array.from(new Set(out)).slice(0, 5);
 }
 var EVENT_CHANNEL = { account: "account", positions: "positions", orders: "orders", fill: "fills", fills: "fills" };
@@ -1742,7 +1841,7 @@ function createVenueStream(codec, opts = {}) {
     }
     if (target.kind === "market") {
       const channels = target.channels;
-      const valid = `Use channels ${MARKET_CHANNELS.map((c) => `"${c}"`).join(" / ")} (book and trades arrive in 0.15.1)`;
+      const valid = `Use channels ${MARKET_CHANNELS.map((c) => `"${c}"`).join(" / ")} (book and trades: planned, not yet available)`;
       if (!Array.isArray(channels) || channels.length === 0) {
         throw wsError("INVALID_PARAMS", 'kind "market" needs at least one channel', valid);
       }
@@ -1753,7 +1852,7 @@ function createVenueStream(codec, opts = {}) {
         throw wsError(
           "CAPABILITY_UNSUPPORTED",
           `${venue} channel(s) ${later.join(", ")} are not available in this release`,
-          'Use channels "market" / "bbo" (book and trades arrive in 0.15.1)'
+          'Use channels "market" / "bbo" (book and trades: planned, not yet available)'
         );
       }
       if (target.channels.includes("bbo") && !codec.capabilities.channels.bbo) {
@@ -2067,6 +2166,14 @@ function createVenueStream(codec, opts = {}) {
         sub.end();
       }
       stateListeners.clear();
+      let bound = null;
+      await Promise.race([
+        Promise.all(shards.map((sh) => sh.conn.drained())),
+        new Promise((resolve) => {
+          bound = setTimeout(resolve, CLOSE_DRAIN_MS);
+        })
+      ]);
+      if (bound !== null) clearTimeout(bound);
     }
   };
   return stream;
@@ -2428,6 +2535,23 @@ function mulDecimalInt(s, n, shift) {
   const abs2 = (neg ? -product : product).toString();
   return shiftDecimal(`${neg ? "-" : ""}${abs2}`, shift - frac.length);
 }
+function sumDecimals(values) {
+  let scale = 0;
+  const parts = [];
+  for (const v of values) {
+    const m = DECIMAL_RE.exec(v);
+    if (m === null || m[4] !== void 0 || m[2] === "" && (m[3] === void 0 || m[3] === "")) return void 0;
+    const frac = m[3] === void 0 ? "" : m[3];
+    const digits = `${m[2]}${frac}`.replace(/^0+(?=\d)/, "");
+    parts.push({ int: BigInt(digits === "" ? "0" : digits) * (m[1] === "-" ? -1n : 1n), scale: frac.length });
+    if (frac.length > scale) scale = frac.length;
+  }
+  let total = 0n;
+  for (const p of parts) total += p.int * 10n ** BigInt(scale - p.scale);
+  const neg = total < 0n;
+  const abs2 = (neg ? -total : total).toString();
+  return shiftDecimal(`${neg ? "-" : ""}${abs2}`, -scale);
+}
 
 // src/ws/codecs/common.ts
 function isObj(v) {
@@ -2508,9 +2632,9 @@ function capabilities(p) {
     channels: { allMarkets: true, market: true, bbo: true, book: false, trades: false, user: p.user },
     fields: p.fields,
     notes: {
-      book: "Not in this release (0.15.1)",
-      trades: "Not in this release (0.15.1)",
-      ...p.user ? {} : { user: "Not in this release (0.15.1)" },
+      book: "Planned, not yet available",
+      trades: "Planned, not yet available",
+      ...p.user ? {} : { user: "Planned, not yet available" },
       ...p.notes
     }
   };
@@ -2750,6 +2874,16 @@ var SIDE = { B: "buy", A: "sell" };
 function abs(d) {
   return d === null ? null : d.replace(/^-/, "");
 }
+function accountUnrealized(rows, bad) {
+  if (bad.includes("assetPositions") || bad.includes("assetPositions[]")) return null;
+  const values = [];
+  for (const r of rows) {
+    if (r.unrealizedPnl === null) return null;
+    values.push(r.unrealizedPnl);
+  }
+  const sum = sumDecimals(values);
+  return sum === void 0 ? null : sum;
+}
 function decodeClearinghouse(d) {
   if (!isObj(d) || typeof d.dex !== "string" || !isObj(d.clearinghouseState)) return [protocolError("hyperliquid clearinghouseState frame without dex/clearinghouseState")];
   const wire = `clearinghouseState:${d.dex}`;
@@ -2792,8 +2926,10 @@ function decodeClearinghouse(d) {
       equity: ms === null ? null : dec(ms, "accountValue", bad),
       available: dec(cs, "withdrawable", bad),
       marginUsed: ms === null ? null : dec(ms, "totalMarginUsed", bad),
-      unrealizedPnl: null
-      // not in clearinghouseState (per-position only)
+      // clearinghouseState has no account-level unrealizedPnl, but the frame carries every
+      // position of this dex with its own `unrealizedPnl`: the account value is their exact sum
+      // ("0" with no position). null when any position's value is missing (unknown, never guessed).
+      unrealizedPnl: accountUnrealized(rows, bad)
     },
     { kind: "positions", snapshot: true, scope: d.dex, rows, remove: [] }
   ];
@@ -3288,6 +3424,11 @@ function decodeBbo2(d) {
   return out;
 }
 
+// src/ws/lighter-market.ts
+function isLighterMarketLive(row) {
+  return row.status === "active" && row.is_frozen !== true;
+}
+
 // src/ws/codecs/lighter.ts
 var ALL2 = "market_stats/all";
 var ORDERS_TOKEN_TTL_SEC = 3600;
@@ -3296,6 +3437,10 @@ var ZERO = /^-?0*(\.0*)?$/;
 function bookSide(o, key, bad) {
   return o[key] === "" ? null : readDec(o, key, bad);
 }
+function lastTrade(o, bad) {
+  const v = readDec(o, "last_trade_price", bad);
+  return v !== void 0 && v !== null && ZERO.test(v) ? null : v;
+}
 function percentToFraction(o, key, bad) {
   const v = readDec(o, key, bad);
   if (v === void 0 || v === null) return v;
@@ -3328,7 +3473,7 @@ function makeLighter(venue, quote) {
       notes: {
         rate: "WS funding is PERCENT per 1 h on the wire; emitted as a fraction per 1 h",
         nextFundingTime: "Hourly settlement rule (venue-definition)",
-        openInterest: "USD notional (Phase 0), sides not stated by the venue",
+        openInterest: "USD notional, one side \u2014 inferred, not documented by the venue (= REST orderBookDetails open_interest, base, \xD7 mark; the venue's exchangeMetrics kind=open_interest, a daily snapshot, read \u2248 2\xD7 when compared with the current value)",
         user: "By accountIndex. user_stats / account_all_positions / account_all_trades need no auth; account_all_orders needs CredentialProvider.authToken (re-called at 80 % TTL). account_all_trades does not replay \u2192 gap refetch-required for fills after a reconnect",
         clientId: "orders: client_order_id; fills: ask_/bid_client_id_str of our side; 0 = no client id \u2192 null",
         liquidationPrice: 'liquidation_price; "0" (no liquidation price, e.g. well-covered cross margin) \u2192 null, as in the CLI REST path',
@@ -3345,7 +3490,7 @@ function makeLighter(venue, quote) {
     limits: S5.limits,
     closesOnBadSubscribe: false,
     staleAfterMs: S5.staleAfterMs,
-    openInterest: { unit: "usd", sides: null },
+    openInterest: { unit: "usd", sides: "one" },
     refresh: null,
     async loadDirectory(ctx) {
       const raw = await fetchJson(ctx.fetch, venue, `${ctx.restUrl}/api/v1/orderBooks`);
@@ -3363,6 +3508,10 @@ function makeLighter(venue, quote) {
           continue;
         }
         idToSymbol.set(id, m.symbol);
+        if (!isLighterMarketLive(m)) {
+          nonPerp.add(id);
+          continue;
+        }
         entries.push({
           venue,
           dex: null,
@@ -3498,7 +3647,7 @@ function decodeStats(venue, f, d, recvTs) {
       index: readDec(r, "index_price", bad),
       bestBid: bookSide(r, "best_bid_price", bad),
       bestAsk: bookSide(r, "best_ask_price", bad),
-      last: readDec(r, "last_trade_price", bad),
+      last: lastTrade(r, bad),
       rate: percentToFraction(r, "funding_rate", bad),
       predictedRate: percentToFraction(r, "current_funding_rate", bad),
       openInterest: readDec(r, "open_interest", bad),
@@ -3714,6 +3863,14 @@ function decodeTicker(venue, wire, f, d) {
   return out;
 }
 
+// src/ws/aster-market.ts
+function isAsterListedPerpetual(row) {
+  return row.contractType === "PERPETUAL" && row.status === "TRADING";
+}
+function asterMatchable(row) {
+  return row.quoteAsset === "USDT";
+}
+
 // src/ws/codecs/aster.ts
 var S3 = VENUE_STATIC.aster;
 var MARK = "!markPrice@arr@1s";
@@ -3761,7 +3918,7 @@ var aster = {
       openInterest: "Not on WS (REST only)",
       fundingInterval: `Labelled REST source ${FUNDING_INFO}, refreshed hourly; missing \u2192 null`,
       volume24hNotional: "!ticker@arr q (quote-asset volume)",
-      user: 'KNOWN GAP in 0.15.0: no Aster user channels (signed USER_STREAM listenKey) \u2014 kind:"user" rejects CAPABILITY_UNSUPPORTED; arrives in 0.15.1',
+      user: 'KNOWN GAP: no Aster user channels (signed USER_STREAM listenKey) \u2014 kind:"user" rejects CAPABILITY_UNSUPPORTED; planned, not yet available',
       bbo: "<symbol>@bookTicker; `u` orders frames (non-contiguous)"
     }
   }),
@@ -3801,6 +3958,7 @@ var aster = {
       if (!isObj(s) || typeof s.symbol !== "string" || typeof s.baseAsset !== "string") {
         throw badShape("aster", "exchangeInfo symbol without symbol/baseAsset");
       }
+      if (!isAsterListedPerpetual(s)) continue;
       const quote = typeof s.quoteAsset === "string" && s.quoteAsset !== "" ? s.quoteAsset : null;
       listed.add(s.symbol);
       const hours = intervals.get(s.symbol);
@@ -3811,7 +3969,8 @@ var aster = {
         venueSymbol: s.symbol,
         base: s.baseAsset,
         quote,
-        canonical: ctx.canonicalize("aster", { venueSymbol: s.symbol, dex: null, base: s.baseAsset, quote }),
+        // Only the USDT listing is matchable (asterMatchable — the CLI rule): BTCUSD1 is never a second BTC leg.
+        canonical: asterMatchable(s) ? ctx.canonicalize("aster", { venueSymbol: s.symbol, dex: null, base: s.baseAsset, quote }) : null,
         rateIntervalHours: hours === void 0 ? null : hours,
         settlementIntervalHours: hours === void 0 ? null : hours,
         source: "rest:/fapi/v3/exchangeInfo"
@@ -3934,6 +4093,11 @@ function decodeArr(wire, data2, d, fn) {
   return out;
 }
 
+// src/ws/arcus-market.ts
+function isArcusOnlineMarket(row) {
+  return row.status === "ONLINE";
+}
+
 // src/ws/codecs/arcus.ts
 var S4 = VENUE_STATIC.arcus;
 var MARKETS = "markets";
@@ -3984,6 +4148,7 @@ var arcus = {
       if (!isObj(m) || typeof m.marketDisplayName !== "string" || typeof m.marketId !== "number" || typeof m.baseAsset !== "string") {
         throw badShape("arcus", "market without marketDisplayName/marketId/baseAsset");
       }
+      if (!isArcusOnlineMarket(m)) continue;
       const quote = typeof m.quoteAsset === "string" ? m.quoteAsset : null;
       idToSymbol.set(String(m.marketId), m.marketDisplayName);
       entries.push({
@@ -4322,6 +4487,7 @@ function loadWs() {
   return wsModule;
 }
 var DEFAULT_MAX_PAYLOAD = 16 * 1024 * 1024;
+var CLOSE_FLUSH_MS = 250;
 function createNodeTransport(opts = {}) {
   const maxPayload = opts.maxPayload ?? DEFAULT_MAX_PAYLOAD;
   if (!Number.isSafeInteger(maxPayload) || maxPayload <= 0) {
@@ -4331,12 +4497,34 @@ function createNodeTransport(opts = {}) {
   return (url) => {
     const ws = new WebSocket(url, { maxPayload });
     ws.on("error", () => void 0);
+    let terminateTimer = null;
+    const whenClosed = new Promise((resolve) => {
+      ws.once("close", () => {
+        if (terminateTimer !== null) {
+          clearTimeout(terminateTimer);
+          terminateTimer = null;
+        }
+        resolve();
+      });
+    });
     const like = {
+      whenClosed,
       get readyState() {
         return ws.readyState;
       },
       send: (data2) => ws.send(data2),
-      close: (code, reason) => ws.close(code, reason),
+      // The close frame is sent, then the socket is destroyed at once: `ws` would otherwise keep a
+      // 30 s close-handshake timer (and the TCP socket) alive until the server answers, so the
+      // process was not idle after stream.close() (conformance ws:all:close-timers).
+      close: (code, reason) => {
+        ws.close(code, reason);
+        if (terminateTimer === null && ws.readyState !== ws.CLOSED) {
+          terminateTimer = setTimeout(() => {
+            terminateTimer = null;
+            ws.terminate();
+          }, CLOSE_FLUSH_MS);
+        }
+      },
       onopen: null,
       onmessage: null,
       onclose: null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypurrquant/perp-ws",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Live market, funding and account WebSocket streams for perp DEXes (Hyperliquid incl. HIP-3, Pacifica, Lighter, Lighter RH, Aster, Arcus) — zero-dependency browser + Node library, the same code as perp-cli/ws",
   "type": "module",
   "exports": {