perp-cli 0.14.2 → 0.15.0

package/dist/ws/index.d.ts

@@ -0,0 +1,959 @@
+/**
+ * Venue ids and networks for perp-cli/ws. A local copy (src/ws imports only src/ws/**), kept in
+ * line with src/exchanges/venue-types.ts by a parity test. Ids are stable.
+ */
+/**
+ * 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).
+ */
+type VenueId = "pacifica" | "hyperliquid" | "lighter" | "aster" | "lighter-rh" | "ondo" | "arcus" | "qfex";
+declare const VENUE_IDS: readonly VenueId[];
+type Network = "mainnet" | "testnet";
+
+/**
+ * perp-cli/ws error leaf module (no imports). `WsErrorCode` ⊂ the CLI's `ErrorCode`; status and
+ * retryable match src/errors.ts ERROR_CODES (parity test). The CLI's classifyError accepts a
+ * WsError structurally (isPerpError).
+ */
+declare const WS_ERROR_CODES: {
+    readonly WS_PROTOCOL_ERROR: {
+        readonly status: 502;
+        readonly retryable: false;
+    };
+    readonly WS_AUTH_FAILED: {
+        readonly status: 401;
+        readonly retryable: false;
+    };
+    readonly SUBSCRIPTION_LIMIT: {
+        readonly status: 400;
+        readonly retryable: false;
+    };
+    readonly STREAM_OVERFLOW: {
+        readonly status: 507;
+        readonly retryable: false;
+    };
+    readonly CAPABILITY_UNSUPPORTED: {
+        readonly status: 400;
+        readonly retryable: false;
+    };
+    readonly EXCHANGE_UNREACHABLE: {
+        readonly status: 503;
+        readonly retryable: true;
+    };
+    readonly INVALID_PARAMS: {
+        readonly status: 400;
+        readonly retryable: false;
+    };
+    readonly RATE_LIMITED: {
+        readonly status: 429;
+        readonly retryable: true;
+    };
+    readonly EXCHANGE_ERROR: {
+        readonly status: 502;
+        readonly retryable: true;
+    };
+    readonly SYMBOL_NOT_FOUND: {
+        readonly status: 404;
+        readonly retryable: false;
+    };
+};
+type WsErrorCode = keyof typeof WS_ERROR_CODES;
+interface WsStructuredError {
+    code: WsErrorCode;
+    message: string;
+    status: number;
+    retryable: boolean;
+    exchange?: string;
+    remediation?: string;
+    details?: Record<string, unknown>;
+}
+declare class WsError extends Error {
+    readonly structured: WsStructuredError;
+    constructor(code: WsErrorCode, message: string, opts?: {
+        exchange?: string;
+        remediation?: string;
+        details?: Record<string, unknown>;
+    });
+}
+/** Structural check: a PerpError (CLI) or a WsError — anything carrying `structured.{code,message}`. */
+declare function isPerpError(e: unknown): e is {
+    structured: {
+        code: string;
+        message: string;
+    };
+};
+
+/**
+ * perp-cli/ws public types (plan ws-0.14.4 §4). @experimental through 0.15.x (stable from 0.16.0 after consumer sign-off): breaking changes
+ * only in a minor bump; every event carries `schema: 1`.
+ *
+ * Null rules (§3): unknown = null. A field the venue never sent is null; a field the latest frame
+ * did not carry keeps its last value with a per-field `asOf`. `Dec` = the venue's JSON value as a
+ * string (a JSON string verbatim, a JSON number via String(value) — precision bounded by JSON
+ * parsing). The one documented exception is Lighter's WS funding, sent in PERCENT per hour and
+ * converted to a fraction by an exact decimal shift (no float).
+ */
+
+type Dec = string;
+interface WsLike {
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((ev?: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((ev: {
+        code: number;
+        reason: string;
+        wasClean?: boolean;
+    }) => void) | null;
+    onerror: ((ev: unknown) => void) | null;
+}
+type WsFactory = (url: string) => WsLike;
+type FetchLike = (input: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}>;
+interface CloseReason {
+    code: WsErrorCode | "CLIENT_CLOSE";
+    message: string;
+    wsCode: number | null;
+    remediation: string | null;
+}
+/** @experimental 0.15.x (stable from 0.16.0 after consumer sign-off) */
+type ConnectionState = {
+    status: "idle";
+} | {
+    status: "connecting";
+    attempt: number;
+}
+/** Several sockets (Pacifica): `sockets` live ones; `pending` = sockets still opening for the first time
+ * (just added, waiting on the new-connection budget, or retrying a failed first handshake) — their subscriptions are not ready yet. */
+ | {
+    status: "live";
+    since: number;
+    sockets: number;
+    pending?: number;
+} | {
+    status: "stale";
+    since: number;
+    silentMs: number;
+    channel: string | null;
+} | {
+    status: "reconnecting";
+    attempt: number;
+    inMs: number;
+    reason: CloseReason;
+} | {
+    status: "closed";
+    reason: CloseReason;
+};
+type Canonicalize = (venue: VenueId, m: {
+    venueSymbol: string;
+    dex: string | null;
+    base: string;
+    quote: string | null;
+}) => string | null;
+type Source = "ws" | "snapshot" | `rest:${string}` | "venue-definition";
+type RateKind = "lastSettled" | "accruing" | "predicted";
+/** @experimental 0.15.x (stable from 0.16.0 after consumer sign-off) */
+interface MarketDirectoryEntry {
+    venue: VenueId;
+    dex: string | null;
+    symbol: string;
+    venueSymbol: string;
+    base: string;
+    quote: string | null;
+    canonical: string | null;
+    rateIntervalHours: number | null;
+    settlementIntervalHours: number | null;
+    source: Source;
+}
+type MarketField = "mark" | "index" | "bestBid" | "bestAsk" | "last" | "rate" | "predictedRate" | "nextFundingTime" | "fundingInterval" | "openInterest" | "volume24hNotional";
+interface FundingState {
+    rate: Dec | null;
+    rateKind: RateKind | null;
+    rateSource: Source | null;
+    rateIntervalHours: number | null;
+    settlementIntervalHours: number | null;
+    intervalSource: Source | null;
+    nextFundingTime: number | null;
+    /** Always kind "predicted". */
+    predictedRate: Dec | null;
+    /** QFEX out of hours → rate null + true. null when the venue has no such concept. */
+    marketClosed: boolean | null;
+}
+/** @experimental 0.15.x (stable from 0.16.0 after consumer sign-off) */
+interface MarketUpdate {
+    type: "market";
+    schema: 1;
+    venue: VenueId;
+    dex: string | null;
+    symbol: string;
+    venueSymbol: string;
+    quote: string | null;
+    canonical: string | null;
+    mark: Dec | null;
+    index: Dec | null;
+    bestBid: Dec | null;
+    bestAsk: Dec | null;
+    last: Dec | null;
+    funding: FundingState;
+    openInterest: {
+        value: Dec | null;
+        unit: "base" | "usd" | null;
+        sides: "one" | "both" | null;
+    };
+    volume24hNotional: Dec | null;
+    venueTs: number | null;
+    recvTs: number;
+    source: Source;
+    changed: ReadonlyArray<MarketField>;
+    asOf: Partial<Record<MarketField, number>>;
+}
+/** @experimental 0.15.x (stable from 0.16.0 after consumer sign-off) */
+interface BboUpdate {
+    type: "bbo";
+    schema: 1;
+    venue: VenueId;
+    dex: string | null;
+    symbol: string;
+    bid: Dec | null;
+    bidSize: Dec | null;
+    ask: Dec | null;
+    askSize: Dec | null;
+    venueTs: number | null;
+    recvTs: number;
+}
+interface BookUpdate {
+    type: "book";
+    schema: 1;
+    venue: VenueId;
+    symbol: string;
+    bids: [Dec, Dec][];
+    asks: [Dec, Dec][];
+    seq: string | null;
+    venueTs: number | null;
+    recvTs: number;
+    source: Source;
+    depth: number;
+}
+interface TradeUpdate {
+    type: "trade";
+    schema: 1;
+    venue: VenueId;
+    symbol: string;
+    price: Dec;
+    size: Dec;
+    side: "buy" | "sell" | null;
+    tradeId: string | null;
+    venueTs: number | null;
+    recvTs: number;
+}
+type UserChannel = "account" | "positions" | "orders" | "fills";
+interface PositionRow {
+    symbol: string;
+    dex: string | null;
+    side: "long" | "short" | null;
+    /** Absolute size in base units. */
+    size: Dec | null;
+    entryPrice: Dec | null;
+    /** Mark price is not part of every venue's position stream; join MarketUpdate by symbol. */
+    markPrice: Dec | null;
+    positionValue: Dec | null;
+    unrealizedPnl: Dec | null;
+    liquidationPrice: Dec | null;
+    marginUsed: Dec | null;
+    leverage: Dec | null;
+    venueTs: number | null;
+}
+interface OrderRow {
+    orderId: string;
+    clientId: string | null;
+    symbol: string;
+    dex: string | null;
+    side: "buy" | "sell" | null;
+    type: string | null;
+    /** Venue status string, verbatim. */
+    status: string | null;
+    price: Dec | null;
+    size: Dec | null;
+    filled: Dec | null;
+    remaining: Dec | null;
+    reduceOnly: boolean | null;
+    createdAt: number | null;
+    updatedAt: number | null;
+}
+interface FillRow {
+    /** Venue fill key (HL tid, Pacifica h:i, Lighter trade_id, Arcus tradeId). With `side` and `orderId` it is the dedupe key. */
+    fillId: string;
+    /** The client order id of the filled order when the fill frame carries it (see the capability notes per venue). */
+    clientId: string | null;
+    symbol: string;
+    dex: string | null;
+    side: "buy" | "sell" | null;
+    price: Dec | null;
+    size: Dec | null;
+    /** Fee amount in `feeToken` (negative = rebate). */
+    fee: Dec | null;
+    feeToken: string | null;
+    closedPnl: Dec | null;
+    orderId: string | null;
+    liquidity: "maker" | "taker" | null;
+    time: number | null;
+}
+/** @experimental 0.15.x (stable from 0.16.0 after consumer sign-off) */
+type UserUpdate = {
+    type: "account";
+    schema: 1;
+    venue: VenueId;
+    /** HL: one account per perp dex ("" native → null); other venues null. */
+    dex: string | null;
+    equity: Dec | null;
+    available: Dec | null;
+    marginUsed: Dec | null;
+    unrealizedPnl: Dec | null;
+    venueTs: number | null;
+    source: Source;
+    recvTs: number;
+}
+/** The full current position set (snapshot + merged deltas). snapshot = it came from (or coalesced) a venue snapshot. */
+ | {
+    type: "positions";
+    schema: 1;
+    venue: VenueId;
+    snapshot: boolean;
+    positions: PositionRow[];
+    source: Source;
+    recvTs: number;
+}
+/**
+ * The current OPEN order set (snapshot + merged deltas). `complete`: the set is known to be every open
+ * order — true once the venue sent a snapshot for every part of it; false for venues without an
+ * order snapshot (Pacifica: refetch over REST; the library cannot be told) and after a refetch gap.
+ */
+ | {
+    type: "orders";
+    schema: 1;
+    venue: VenueId;
+    snapshot: boolean;
+    complete: boolean;
+    orders: OrderRow[];
+    source: Source;
+    recvTs: number;
+}
+/** One live fill (de-duplicated in-library). */
+ | {
+    type: "fill";
+    schema: 1;
+    venue: VenueId;
+    snapshot: false;
+    fillId: string;
+    fill: FillRow;
+    source: Source;
+    recvTs: number;
+}
+/**
+ * A venue fill SNAPSHOT (HL / Arcus replay recent fills on every (re)subscribe; up to 2000 on HL) as ONE
+ * event: only fills not seen before, oldest venue order preserved. Never split, so it cannot overflow
+ * a subscription buffer. Empty snapshots (everything already seen) are not emitted.
+ */
+ | {
+    type: "fills";
+    schema: 1;
+    venue: VenueId;
+    snapshot: true;
+    fills: FillRow[];
+    source: Source;
+    recvTs: number;
+};
+/** @experimental 0.15.x (stable from 0.16.0 after consumer sign-off) */
+type UserRef = {
+    venue: "hyperliquid";
+    address: `0x${string}`;
+} | {
+    venue: "pacifica";
+    account: string;
+} | {
+    venue: "lighter" | "lighter-rh";
+    accountIndex: number;
+}
+/** KNOWN GAP in 0.15.0: Aster user channels are not implemented (CAPABILITY_UNSUPPORTED); 0.15.1. */
+ | {
+    venue: "aster";
+    user: `0x${string}`;
+    signer: `0x${string}`;
+}
+/** subaccount null = the venue default account (0). */
+ | {
+    venue: "arcus";
+    address: `0x${string}`;
+    subaccount: number | null;
+} | {
+    venue: "ondo";
+    keyId: string;
+} | {
+    venue: "qfex";
+    publicKey: string;
+    accountId: string;
+};
+interface TypedData {
+    domain: Record<string, unknown>;
+    types: Record<string, Array<{
+        name: string;
+        type: string;
+    }>>;
+    primaryType: string;
+    message: Record<string, unknown>;
+}
+/**
+ * Async credentials; the library never holds keys (only short-lived tokens it is handed).
+ * @experimental 0.15.x (stable from 0.16.0 after consumer sign-off)
+ */
+interface CredentialProvider {
+    user(): Promise<UserRef>;
+    /** Ondo login, QFEX auth (secret stays with the provider). Lowercase hex. */
+    hmacSha256?(message: string): Promise<string>;
+    /** Aster V3 USER_STREAM (API-wallet signer). */
+    signTypedData?(td: TypedData): Promise<`0x${string}`>;
+    /** Lighter auth token (a read-only `ro:` token is recommended in browsers). Re-called at 80 % of its TTL. */
+    authToken?(req: {
+        purpose: string;
+        maxTtlSec: number;
+    }): Promise<{
+        token: string;
+        expiresAt: number;
+    }>;
+}
+/** @experimental 0.15.x (stable from 0.16.0 after consumer sign-off) */
+type StreamControl = {
+    type: "state";
+    venue: VenueId;
+    state: ConnectionState;
+} | {
+    type: "gap";
+    venue: VenueId;
+    channel: string;
+    symbol: string | null;
+    expected: string | null;
+    got: string | null;
+    action: "resnapshot" | "refetch-required";
+} | {
+    type: "error";
+    venue: VenueId;
+    code: WsErrorCode;
+    message: string;
+    remediation: string | null;
+    /** Redacted excerpt (≤ 200 chars) of the offending frame, or null. */
+    raw: string | null;
+    fatal: boolean;
+    /** Structured context, when the code has any (e.g. SYMBOL_NOT_FOUND: the missing canonicals). */
+    details?: StreamErrorDetails;
+};
+/**
+ * `details` of a `{ type: "error" }` control. SYMBOL_NOT_FOUND (non-fatal, kind:"allMarkets" with
+ * `canonicals`): `missing` = requested canonicals with no market on this venue (the others are
+ * subscribed); `suggestions` = per missing canonical, close directory canonicals (may be empty).
+ */
+interface StreamErrorDetails {
+    missing?: string[];
+    suggestions?: Record<string, string[]>;
+}
+interface StreamLog {
+    ts: number;
+    venue: VenueId;
+    level: "info" | "warn" | "error";
+    event: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+/** @experimental 0.15.x (stable from 0.16.0 after consumer sign-off) */
+interface VenueWsCapabilities {
+    /** true = works from a browser page (Origin/CORS checked, Phase 0); "in-page-secrets" = needs allowInPageSecrets. */
+    browser: boolean | "in-page-secrets";
+    networks: Record<Network, boolean>;
+    channels: {
+        allMarkets: boolean;
+        market: boolean;
+        bbo: boolean;
+        book: boolean;
+        trades: boolean;
+        user: boolean;
+    };
+    /** Market fields this venue publishes over WS (or via a labelled REST source). false → always null. */
+    fields: Record<Exclude<MarketField, "rate">, boolean>;
+    /** Why a field or channel is null / unsupported. */
+    notes: Record<string, string>;
+}
+/**
+ * All-market state, optionally narrowed (pass at most one of the two filters). With `canonicals`,
+ * the ones this venue lists are subscribed and the rest are reported once as a non-fatal
+ * `{ type: "error", code: "SYMBOL_NOT_FOUND", fatal: false, details: { missing, suggestions } }`;
+ * only when none exist does `ready` reject INVALID_PARAMS.
+ * - `symbols`: this venue's DIRECTORY symbols, exact and case-sensitive (`BTC` on hyperliquid, `BTCUSDT`
+ *   on aster, `BTC-USD` on arcus) — see stream.markets();
+ * - `canonicals`: canonical names (`"BTC"`, HIP-3 `"xyz:TSLA"`) → every directory market whose canonical
+ *   (opts.canonicalize, default USD-like quotes collapse) matches, e.g. aster BTCUSDT + BTCUSD1. Use it
+ *   for the same subscription on several venues.
+ */
+interface AllMarketsTarget {
+    kind: "allMarkets";
+    symbols?: string[];
+    canonicals?: string[];
+}
+type MarketTarget = AllMarketsTarget | {
+    kind: "user";
+    channels: UserChannel[];
+} | {
+    kind: "market";
+    symbol: string;
+    channels: Array<"market" | "bbo" | "book" | "trades">;
+};
+/** @experimental 0.15.x (stable from 0.16.0 after consumer sign-off) */
+interface VenueStreamOptions {
+    network?: Network;
+    /** hyperliquid: HIP-3 dexes to include. Default [] = native only. */
+    hip3Dexes?: string[] | "all";
+    /** Default: globalThis.WebSocket, resolved at call time (perp-cli/ws/node supplies `ws`). */
+    transport?: WsFactory;
+    /** Default: globalThis.fetch, resolved at call time. */
+    fetch?: FetchLike;
+    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). */
+    allowInPageSecrets?: boolean;
+    /** ≤ venue limits. */
+    budget?: {
+        maxSubscriptions?: number;
+        maxSockets?: number;
+        newConnectionsPerMin?: number;
+    };
+    /** Overrides the per-venue default for every public channel. */
+    staleAfterMs?: number;
+    /** Default: document.visibilityState when present, else none. */
+    visibility?: {
+        hidden(): boolean;
+        onChange(cb: () => void): () => void;
+    } | null;
+    /** Default { maxAttempts: null, baseMs: 1000, maxMs: 30000 }. */
+    reconnect?: {
+        maxAttempts: number | null;
+        baseMs: number;
+        maxMs: number;
+    };
+    /** Async-iterator buffer per subscription (default 1024). */
+    buffer?: {
+        size: number;
+    };
+    /** Receives redacted entries only. */
+    logger?: (e: StreamLog) => void;
+    clock?: () => number;
+}
+/** @experimental 0.15.x (stable from 0.16.0 after consumer sign-off) */
+interface Subscription<E> extends AsyncIterable<E | StreamControl> {
+    /** Unbuffered callback. Returns an unsubscribe-from-callback function. */
+    on(cb: (e: E | StreamControl) => void): () => void;
+    readonly status: "pending" | "active" | "rejected" | "closed";
+    /** Resolves once every wire channel is acknowledged; rejects with a WsError. */
+    readonly ready: Promise<void>;
+    /** The wire unsubscribe is sent only when the ref-count reaches 0. */
+    unsubscribe(): Promise<void>;
+}
+interface VenueStream {
+    readonly venue: VenueId;
+    readonly network: Network;
+    readonly state: ConnectionState;
+    readonly capabilities: VenueWsCapabilities;
+    subscribe(t: AllMarketsTarget): Subscription<MarketUpdate>;
+    subscribe(t: {
+        kind: "market";
+        symbol: string;
+        channels: Array<"market" | "bbo" | "book" | "trades">;
+    }): Subscription<MarketUpdate | BboUpdate | BookUpdate | TradeUpdate>;
+    subscribe(t: {
+        kind: "user";
+        channels: UserChannel[];
+    }): Subscription<UserUpdate>;
+    onState(cb: (s: ConnectionState) => void): () => void;
+    /** The market directory (REST bootstrap, loaded once). */
+    markets(): Promise<MarketDirectoryEntry[]>;
+    /** Venue `staleAfterMs` of the all-market channel (used by the funding comparator). */
+    readonly staleAfterMs: number;
+    close(): Promise<void>;
+}
+/** A wire subscription (one venue channel). `key` is unique per venue. */
+interface WireSub {
+    key: string;
+    /** Silence beyond this → `stale`; 2× → forced reconnect. null = no stale check. */
+    staleAfterMs: number | null;
+    params: Record<string, unknown>;
+    /** Needs an auth token from CredentialProvider.authToken (sent with the subscribe). */
+    auth?: {
+        purpose: string;
+        maxTtlSec: number;
+    };
+    /** Per-socket channel group for venue caps (limits.perGroup), e.g. Pacifica "bbo" ≤ 20. */
+    group?: string;
+    /** Non-replayable channels: gap{action:"refetch-required"} after a reconnect / at subscribe. */
+    gaps?: {
+        onReconnect?: Array<"fills" | "orders">;
+        onSubscribe?: Array<"orders">;
+    };
+}
+/** A user-state change decoded from one frame. `scope` partitions snapshots (HL: per dex). */
+type UserDelta = {
+    kind: "account";
+    snapshot: boolean;
+    dex: string | null;
+    equity?: Dec | null;
+    available?: Dec | null;
+    marginUsed?: Dec | null;
+    unrealizedPnl?: Dec | null;
+    venueTs: number | null;
+}
+/** snapshot: replace every row in `scope`; else upsert rows and remove `remove` keys (symbol). */
+ | {
+    kind: "positions";
+    snapshot: boolean;
+    scope: string;
+    rows: PositionRow[];
+    remove: string[];
+}
+/** snapshot: replace every open order in `scope`; else upsert rows and remove `remove` order ids. */
+ | {
+    kind: "orders";
+    snapshot: boolean;
+    scope: string;
+    rows: OrderRow[];
+    remove: string[];
+} | {
+    kind: "fills";
+    snapshot: boolean;
+    fills: FillRow[];
+};
+/** A partial market patch: a key present = the frame carried it (its value may be null). */
+interface MarketPatch {
+    symbol: string;
+    venueTs: number | null;
+    mark?: Dec | null;
+    index?: Dec | null;
+    bestBid?: Dec | null;
+    bestAsk?: Dec | null;
+    last?: Dec | null;
+    rate?: Dec | null;
+    predictedRate?: Dec | null;
+    nextFundingTime?: number | null;
+    openInterest?: Dec | null;
+    volume24hNotional?: Dec | null;
+}
+type DecodedEvent = {
+    t: "market";
+    wire: string;
+    patches: MarketPatch[];
+}
+/** seq: a venue ordering number for the wire's snapshots (frames below the last seen are stale and dropped; equal is applied). */
+ | {
+    t: "user";
+    wire: string;
+    deltas: UserDelta[];
+    seq?: number | null;
+}
+/** seq: a venue ordering number (only drops out-of-order/duplicate frames; never a gap signal). */
+ | {
+    t: "bbo";
+    wire: string;
+    symbol: string;
+    seq: number | null;
+    bid: Dec | null;
+    bidSize: Dec | null;
+    ask: Dec | null;
+    askSize: Dec | null;
+    venueTs: number | null;
+} | {
+    t: "ack";
+    wire: string | null;
+    reqId: number | null;
+    unsubscribe: boolean;
+} | {
+    t: "pong";
+}
+/** An allowlisted, documented control frame with nothing to do (e.g. "connected"). */
+ | {
+    t: "ignore";
+    what: string;
+} | {
+    t: "error";
+    code: WsErrorCode;
+    message: string;
+    wire: string | null;
+    fatal: boolean;
+    remediation: string | null;
+    /** The request id the error answers (venues that echo it, e.g. Aster). */
+    reqId?: number;
+};
+interface CodecDirectory {
+    entries: MarketDirectoryEntry[];
+    /** Codec-private lookup data (e.g. HL positional universes, Lighter market ids). */
+    data: unknown;
+    /** Non-fatal problems in the bootstrap responses (e.g. malformed rows), surfaced as error events. */
+    warnings?: string[];
+}
+interface CodecContext {
+    network: Network;
+    fetch: FetchLike;
+    restUrl: string;
+    hip3Dexes: string[] | "all";
+    canonicalize: Canonicalize;
+    clock: () => number;
+}
+/** Per-symbol funding metadata a codec attaches (static or from a labelled REST source). */
+interface FundingMeta {
+    rateKind: RateKind | null;
+    rateSource: Source | null;
+    rateIntervalHours: number | null;
+    settlementIntervalHours: number | null;
+    intervalSource: Source | null;
+    /** When a labelled REST interval was fetched; null for a static (venue-definition) interval. */
+    intervalAsOf: number | null;
+    marketClosed: boolean | null;
+}
+interface LabelledRefresh {
+    /** e.g. "rest:/fapi/v3/fundingInfo" */
+    source: `rest:${string}`;
+    everyMs: number;
+    /** Re-fetch and apply into the codec's directory data; throws WsError on failure; resolves to warnings. */
+    run(ctx: CodecContext, dir: CodecDirectory): Promise<string[]>;
+}
+/** @experimental 0.15.x (stable from 0.16.0 after consumer sign-off) */
+interface VenueCodec {
+    readonly venue: VenueId;
+    readonly capabilities: VenueWsCapabilities;
+    /** Wire URL, or null (network unsupported → CAPABILITY_UNSUPPORTED). */
+    url(network: Network): string | null;
+    restUrl(network: Network): string | null;
+    /** Redaction: secret JSON keys and URL path/query patterns. */
+    readonly secretKeys: readonly string[];
+    readonly secretUrlPatterns: readonly RegExp[];
+    /** App-level ping, or null (server protocol pings only). */
+    readonly ping: {
+        message: string;
+        everyMs: number;
+    } | null;
+    /** Venue limits. */
+    readonly limits: {
+        subscriptionsPerSocket: number;
+        newConnectionsPerMin: number;
+        outboundPerMin: number;
+        /** Per-socket caps per WireSub.group. */
+        perGroup?: Record<string, number>;
+        /** Sockets one stream may open to spread channels over the per-socket caps. Absent = 1 (the
+         * venue's limits are per IP, so extra sockets would not add room). */
+        maxSockets?: number;
+    };
+    /** true → the venue drops the socket (no error frame) on an invalid subscribe (HL). */
+    readonly closesOnBadSubscribe: boolean;
+    readonly staleAfterMs: number;
+    readonly openInterest: {
+        unit: "base" | "usd" | null;
+        sides: "one" | "both" | null;
+    };
+    loadDirectory(ctx: CodecContext): Promise<CodecDirectory>;
+    readonly refresh: LabelledRefresh | null;
+    fundingMeta(entry: MarketDirectoryEntry, dir: CodecDirectory): FundingMeta;
+    /** Wire channels for a target; throws WsError(INVALID_PARAMS / CAPABILITY_UNSUPPORTED). */
+    wiresFor(target: Exclude<MarketTarget, {
+        kind: "user";
+    }>, dir: CodecDirectory, staleOverrideMs: number | null): WireSub[];
+    /** User channels, or null when this release does not support them (→ CAPABILITY_UNSUPPORTED). */
+    readonly user: {
+        /** Auth needs a signing secret in the page (gated by allowInPageSecrets in browsers). */
+        inPageSecrets: boolean;
+        wires(ref: UserRef, channels: UserChannel[], dir: CodecDirectory): WireSub[];
+    } | null;
+    /** `auth`: the token for a WireSub with `auth`, else null. */
+    encodeSubscribe(w: WireSub, reqId: number, auth: string | null): string;
+    encodeUnsubscribe(w: WireSub, reqId: number): string;
+    /** Pure decode of one text frame. Throws nothing: problems are `error` events. */
+    decode(text: string, dir: CodecDirectory, recvTs: number): DecodedEvent[];
+}
+
+/**
+ * createVenueStream (§4): directory bootstrap, ref-counted wire subscriptions, dispatch of decoded
+ * frames into merged market state, labelled REST refresh, error/state fan-out. Socket lifecycle is in
+ * connection.ts; venue specifics are in the codec.
+ *
+ * Sockets: one per stream unless the codec's limits.maxSockets allows more (per-socket venue caps,
+ * e.g. Pacifica 20 per channel). Each wire lives on one socket (first fit under subscriptionsPerSocket
+ * and limits.perGroup); a socket reconnects and resubscribes its own wires, and frames count only on the
+ * socket their wire lives on. The stream state is the aggregate of its sockets (aggregateState); one
+ * socket stopping for good (reconnects exhausted) closes the stream.
+ */
+
+/** @experimental 0.15.x (stable from 0.16.0 after consumer sign-off) */
+declare function createVenueStream(codec: VenueCodec, opts?: VenueStreamOptions): VenueStream;
+
+/** Default market canonicalization (injectable via opts.canonicalize / comparator canonicalize). */
+
+/**
+ * Quotes that collapse to "<BASE>". USDG is included because lighter-rh and Arcus settle in USDG
+ * (USD-pegged); a caller who wants them apart passes its own `canonicalize`.
+ */
+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).
+ */
+declare const defaultCanonicalize: Canonicalize;
+
+/**
+ * Funding comparator + toHourly/toApr (§4). Compares like-for-like rate kinds: a leg without the
+ * requested kind has rate null and `kindUnavailable: true` (never substituted). Rates stay raw (Dec,
+ * per the venue's interval); annualize only with toApr.
+ *
+ * kind:
+ *  - "current" (default): each leg's `rate`; rows whose legs differ in rateKind → mixedKinds.
+ *  - "predicted": predictedRate (or rate when its kind is "predicted").
+ *  - "lastSettled" / "accruing": rate only when its kind matches.
+ *  - "next": the forward-looking rate per venue — accruing when published, else predicted.
+ *    A venue with only a lastSettled rate is flagged (kindUnavailable), not substituted.
+ */
+
+type ComparatorKind = RateKind | "current" | "next";
+interface FundingLeg {
+    venue: VenueId;
+    dex: string | null;
+    symbol: string;
+    quote: string | null;
+    mark: Dec | null;
+    /** The rate of the requested kind, in the venue's interval (funding.rateIntervalHours). */
+    rate: Dec | null;
+    rateKind: RateKind | null;
+    /** The venue does not publish the requested kind for this market (rate is null, not substituted). */
+    kindUnavailable: boolean;
+    funding: MarketUpdate["funding"];
+    fundingVerified: boolean;
+    asOf: number | null;
+    stale: boolean;
+}
+interface FundingRow {
+    canonical: string;
+    mixedKinds: boolean;
+    legs: FundingLeg[];
+}
+interface FundingComparatorOptions {
+    streams: VenueStream[];
+    /** Minimum venues with a non-null rate for a row to be listed (default 2). */
+    minVenues?: number;
+    /** Canonical allowlist. */
+    include?: string[];
+    canonicalize?: Canonicalize;
+    kind?: ComparatorKind;
+    /** Leg stale when the stream ≠ live or now − asOf > this (default 2 × venue staleAfterMs; Arcus 3×). */
+    staleAfterMs?: number;
+    /** Stream control events (state / error) of the underlying subscriptions, and errors thrown by
+     * a comparator `subscribe` listener (`listener-error`; the other listeners still run). */
+    onControl?: (c: StreamControl | ComparatorListenerError) => void;
+    clock?: () => number;
+}
+interface ComparatorListenerError {
+    type: "listener-error";
+    message: string;
+}
+interface FundingComparator {
+    rows(): FundingRow[];
+    subscribe(cb: (rows: FundingRow[], changed: string[]) => void): () => void;
+    close(): void;
+}
+/** @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) */
+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;
+
+/**
+ * Hyperliquid codec (§6.1). All markets = ONE `allDexsAssetCtxs` subscription (every dex), filtered
+ * client-side by opts.hip3Dexes. Its ctx arrays are POSITIONAL (no coin): index i = meta{dex}.universe[i]
+ * — the directory loads meta per selected dex and every frame is length-checked (mismatch →
+ * WS_PROTOCOL_ERROR for that dex, never mis-assigned). kind:"market" uses `activeAssetCtx{coin}`.
+ * An unknown coin in a subscribe makes HL drop the socket (no error frame) → coins are validated
+ * against the directory before sending (closesOnBadSubscribe).
+ *
+ * Docs: hyperliquid.gitbook.io …/api/websocket/subscriptions; Phase 0 fixtures in
+ * src/__tests__/fixtures/ws/hyperliquid/.
+ */
+
+declare const hyperliquid: VenueCodec;
+
+/**
+ * Pacifica codec (§6.1). All markets = `prices` (one subscription, every ~3 s). funding = last
+ * settled hourly rate, next_funding = predicted (Phase 0: == REST funding_rate history). open_interest
+ * is base units; volume_24h USD. No bid/ask in `prices` (bbo channel, Phase 2).
+ * An unknown symbol is acked with no data and no error frame → symbols are validated first.
+ * The directory is the `instrument_type: "perpetual"` rows of GET /info (spot rows such as SOL-USDC are
+ * also in /info and `prices`). A row without instrument_type cannot be classified: it is left out and
+ * reported as a directory warning (non-fatal EXCHANGE_ERROR on each subscription; the other markets stream).
+ * Every wire carries `group` = its channel `source` (venue cap: 20 per channel per connection; the stream
+ * spreads further ones over more sockets, venue-static.ts).
+ *
+ * Docs: docs.pacifica.fi/api-documentation/api/websocket; fixtures in
+ * src/__tests__/fixtures/ws/pacifica/.
+ */
+
+declare const pacifica: VenueCodec;
+
+/**
+ * Lighter / Lighter RH codec (§6.1). All markets = `market_stats/all`: the first frame
+ * (`subscribed/market_stats`) has every market, then `update/market_stats` ~1 s with ONLY the
+ * changed markets (each entry complete) → merged per market.
+ *
+ * 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).
+ * 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.
+ *
+ * Docs: apidocs.lighter.xyz/docs/websocket-reference; fixtures src/__tests__/fixtures/ws/lighter{,-rh}/.
+ */
+
+declare const lighter: VenueCodec;
+/** Lighter RH: separate directory (different market ids); USDG collateral. */
+declare const lighterRh: VenueCodec;
+
+/**
+ * Aster codec (§6.1, public only in 0.15.0). 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`
+ * (hourly refresh; missing → null). OI and the predicted rate are not published (null).
+ * The directory is exchangeInfo (all quotes; base/quote never parsed from the suffix). markPrice@arr
+ * also carries symbols that exchangeInfo does not list (delisted/hidden, no base/quote metadata):
+ * those are learnt from rest:/fapi/v3/premiumIndex at bootstrap and skipped by documented rule.
+ * Unknown stream names are accepted silently by the venue → only fixed stream names are used.
+ *
+ * Docs: github.com/asterdex/api-docs (V3 futures); fixtures src/__tests__/fixtures/ws/aster/.
+ */
+
+declare const aster: VenueCodec;
+
+/**
+ * Arcus codec (§6.1, C1). All markets = ONE `markets` subscription: a full all-market snapshot
+ * (`subscribed`, then `channel_data` every ~5 s and on funding apply). It carries markPrice (no
+ * oraclePrices subscription needed), fundingRate = last applied (lastSettled; Phase 0: == REST
+ * /v1/fundingRates latest), nextFundingRate = predicted, nextFundingAt in unix SECONDS, openInterest
+ * base (one side), volume24hNotional USD (volume24h is base).
+ * Errors are {type:"error", message} with no channel/id.
+ *
+ * Docs: docs.arcus.xyz/api-reference/market-data/markets; fixtures src/__tests__/fixtures/ws/arcus/.
+ */
+
+declare const arcus: VenueCodec;
+
+export { type AllMarketsTarget, type BboUpdate, type BookUpdate, type Canonicalize, type CloseReason, type CodecContext, type CodecDirectory, type ComparatorKind, type ComparatorListenerError, type ConnectionState, type CredentialProvider, type Dec, type DecodedEvent, type FetchLike, type FillRow, type FundingComparator, type FundingComparatorOptions, type FundingLeg, type FundingMeta, type FundingRow, type FundingState, type LabelledRefresh, type MarketDirectoryEntry, type MarketField, type MarketPatch, type MarketTarget, type MarketUpdate, type Network, type OrderRow, type PositionRow, type RateKind, type Source, type StreamControl, type StreamErrorDetails, type StreamLog, type Subscription, type TradeUpdate, type TypedData, USD_LIKE_QUOTES, type UserChannel, type UserDelta, type UserRef, type UserUpdate, VENUE_IDS, type VenueCodec, type VenueId, type VenueStream, type VenueStreamOptions, type VenueWsCapabilities, WS_ERROR_CODES, type WireSub, WsError, type WsErrorCode, type WsFactory, type WsLike, type WsStructuredError, arcus, aster, createFundingComparator, createVenueStream, defaultCanonicalize, hyperliquid, isPerpError, lighter, lighterRh, pacifica, toApr, toHourly };