pmxtjs 2.40.5 → 2.41.0

package/dist/esm/pmxt/client.d.ts

@@ -5,7 +5,7 @@
  * OpenAPI client, matching the Python API exactly.
  */
 import { Configuration, DefaultApi, ExchangeCredentials } from "../generated/src/index.js";
-import { Balance, BuiltOrder, CreateOrderParams, EventFetchParams, EventFilterCriteria, EventFilterFunction, ExecutionPriceResult, MarketFetchParams, MarketFilterCriteria, MarketFilterFunction, MarketOutcome, MyTradesParams, Order, OrderBook, OrderHistoryParams, PaginatedMarketsResult, Position, PriceCandle, SubscribedAddressSnapshot, SubscriptionOption, Trade, UnifiedEvent, UnifiedMarket, UserTrade } from "./models.js";
+import { Balance, BuiltOrder, CreateOrderParams, EventFetchParams, EventFilterCriteria, EventFilterFunction, ExecutionPriceResult, MarketFetchParams, MarketFilterCriteria, MarketFilterFunction, MarketOutcome, MyTradesParams, Order, OrderBook, OrderHistoryParams, PaginatedMarketsResult, Position, PriceCandle, SubscribedAddressSnapshot, SubscriptionOption, Trade, UnifiedEvent, UnifiedMarket, UserTrade, FirehoseEvent } from "./models.js";
 import { ServerManager } from "./server-manager.js";
 /**
  * Base exchange client options.
@@ -252,6 +252,26 @@ export declare abstract class Exchange {
      * ```
      */
     watchOrderBooks(outcomeIds: (string | MarketOutcome)[], limit?: number): Promise<Record<string, OrderBook>>;
+    /**
+     * Stream all orderbook updates across venues via the hosted WebSocket API.
+     *
+     * Returns a promise that resolves with the next book event.
+     * Call repeatedly in a loop to stream updates (CCXT Pro pattern).
+     * Requires hosted mode (`pmxtApiKey` set).
+     *
+     * @param venues - Optional venue filter (e.g. ["polymarket", "limitless"])
+     * @returns Next firehose event with source, symbol, and orderbook
+     *
+     * @example
+     * ```typescript
+     * const poly = new Polymarket({ pmxtApiKey: "pmxt_xxx" });
+     * while (true) {
+     *   const event = await poly.firehose();
+     *   console.log(event.source, event.symbol, event.orderbook.bids[0]);
+     * }
+     * ```
+     */
+    firehose(venues?: string[]): Promise<FirehoseEvent>;
     /**
      * Watch real-time trade updates via WebSocket.
      *

package/dist/esm/pmxt/client.js

@@ -188,9 +188,14 @@ export class Exchange {
                 this.api = new DefaultApi(this.config);
             }
             catch (error) {
-                throw new PmxtError(`Failed to start PMXT server: ${error}\n\n` +
+                const msg = `Failed to start PMXT server: ${error instanceof Error ? error.message : error}\n\n` +
                     `Please ensure 'pmxt-core' is installed: npm install -g pmxt-core\n` +
-                    `Or start the server manually: pmxt-server`);
+                    `Or start the server manually: pmxt-server`;
+                const pmxtError = new PmxtError(msg);
+                if (error instanceof Error) {
+                    pmxtError.cause = error;
+                }
+                throw pmxtError;
             }
         }
     }
@@ -289,8 +294,11 @@ export class Exchange {
         if (this._wsClient?.connected)
             return this._wsClient;
         const host = this.resolveBaseUrl();
-        const accessToken = this.serverManager.getAccessToken();
-        const client = new SidecarWsClient(host, accessToken || undefined);
+        const accessToken = this.isHosted
+            ? this.pmxtApiKey
+            : this.serverManager.getAccessToken();
+        const authParamName = this.isHosted ? "apiKey" : "token";
+        const client = new SidecarWsClient(host, accessToken || undefined, authParamName);
         try {
             // Trigger connection to validate the endpoint exists.
             // subscribe() calls ensureConnected internally, but we want
@@ -325,8 +333,12 @@ export class Exchange {
         try {
             return await ws.subscribe(this.exchangeName, method, args, this.getCredentials());
         }
-        catch {
-            return null;
+        catch (error) {
+            // Only fall back to HTTP for transport-level failures
+            if (error instanceof PmxtError && /connection failed|no websocket/i.test(error.message)) {
+                return null;
+            }
+            throw error;
         }
     }
     // Low-Level API Access
@@ -1423,8 +1435,11 @@ export class Exchange {
                     return result;
                 }
             }
-            catch {
-                // fall through to HTTP
+            catch (error) {
+                // Only fall through to HTTP for transport-level WS failures
+                if (!(error instanceof PmxtError) || !/connection failed|no websocket/i.test(error.message)) {
+                    throw error;
+                }
             }
         }
         // HTTP fallback
@@ -1450,7 +1465,7 @@ export class Exchange {
                 }
                 return result;
             }
-            return {};
+            throw new PmxtError("watchOrderBooks: unexpected response shape from server");
         }
         catch (error) {
             if (error instanceof PmxtError)
@@ -1458,6 +1473,41 @@ export class Exchange {
             throw new PmxtError(`Failed to watch order books: ${error}`);
         }
     }
+    /**
+     * Stream all orderbook updates across venues via the hosted WebSocket API.
+     *
+     * Returns a promise that resolves with the next book event.
+     * Call repeatedly in a loop to stream updates (CCXT Pro pattern).
+     * Requires hosted mode (`pmxtApiKey` set).
+     *
+     * @param venues - Optional venue filter (e.g. ["polymarket", "limitless"])
+     * @returns Next firehose event with source, symbol, and orderbook
+     *
+     * @example
+     * ```typescript
+     * const poly = new Polymarket({ pmxtApiKey: "pmxt_xxx" });
+     * while (true) {
+     *   const event = await poly.firehose();
+     *   console.log(event.source, event.symbol, event.orderbook.bids[0]);
+     * }
+     * ```
+     */
+    async firehose(venues) {
+        await this.initPromise;
+        if (!this.isHosted) {
+            throw new PmxtError("firehose() requires hosted mode (set pmxtApiKey)");
+        }
+        const args = venues ? [venues] : [];
+        const wsData = await this.watchViaWs("firehose", args);
+        if (wsData !== null) {
+            return {
+                source: wsData._source || "",
+                symbol: wsData._symbol || "",
+                orderbook: convertOrderBook(wsData),
+            };
+        }
+        throw new PmxtError("firehose() requires WebSocket transport — connection failed");
+    }
     /**
      * Watch real-time trade updates via WebSocket.
      *

package/dist/esm/pmxt/models.d.ts

@@ -112,6 +112,17 @@ export interface OrderBook {
     /** Unix timestamp (milliseconds) */
     timestamp?: number;
 }
+/**
+ * A single event from the firehose stream.
+ */
+export interface FirehoseEvent {
+    /** The venue this event originated from (e.g. "polymarket", "limitless") */
+    source: string;
+    /** The outcome token id / asset id */
+    symbol: string;
+    /** The order book snapshot */
+    orderbook: OrderBook;
+}
 /**
  * Result of an execution price calculation.
  */

package/dist/esm/pmxt/ws-client.d.ts

@@ -16,6 +16,7 @@ export declare class SidecarWsClient {
     private ws;
     private host;
     private accessToken;
+    private authParamName;
     private closed;
     /** requestId -> latest data payload */
     private dataStore;
@@ -24,7 +25,7 @@ export declare class SidecarWsClient {
     /** (method:symbolKey) -> requestId -- avoids duplicate subscribes */
     private activeSubs;
     private connectPromise;
-    constructor(host: string, accessToken?: string);
+    constructor(host: string, accessToken?: string, authParamName?: string);
     private ensureConnected;
     private connect;
     private getWebSocketConstructor;

package/dist/esm/pmxt/ws-client.js

@@ -17,6 +17,7 @@ export class SidecarWsClient {
     ws = null;
     host;
     accessToken;
+    authParamName;
     closed = false;
     /** requestId -> latest data payload */
     dataStore = new Map();
@@ -25,9 +26,10 @@ export class SidecarWsClient {
     /** (method:symbolKey) -> requestId -- avoids duplicate subscribes */
     activeSubs = new Map();
     connectPromise = null;
-    constructor(host, accessToken) {
+    constructor(host, accessToken, authParamName = "token") {
         this.host = host;
         this.accessToken = accessToken;
+        this.authParamName = authParamName;
     }
     // ------------------------------------------------------------------
     // Connection lifecycle
@@ -58,7 +60,7 @@ export class SidecarWsClient {
             }
             let url = `${scheme}://${hostPart}/ws`;
             if (this.accessToken) {
-                url = `${url}?token=${this.accessToken}`;
+                url = `${url}?${this.authParamName}=${this.accessToken}`;
             }
             // Use the ws package in Node.js, native WebSocket in browsers
             const WsConstructor = this.getWebSocketConstructor();
@@ -77,22 +79,30 @@ export class SidecarWsClient {
                     // Connection failed during handshake
                     reject(new PmxtError(`WebSocket connection failed: ${err.message || err}`));
                 }
+                else {
+                    // Post-handshake error — propagate to all pending subscribers
+                    const error = new PmxtError(`WebSocket error: ${err.message || err}`);
+                    for (const sub of this.subscriptions.values()) {
+                        if (sub.reject) {
+                            sub.reject(error);
+                            sub.reject = null;
+                            sub.resolve = null;
+                        }
+                    }
+                    this.closed = true;
+                    this.ws = null;
+                }
             };
             ws.onclose = () => {
                 this.closed = true;
                 this.ws = null;
             };
             ws.onmessage = (event) => {
-                try {
-                    const data = typeof event.data === "string"
-                        ? event.data
-                        : event.data.toString();
-                    const msg = JSON.parse(data);
-                    this.dispatch(msg);
-                }
-                catch {
-                    // Ignore unparseable frames
-                }
+                const raw = typeof event.data === "string"
+                    ? event.data
+                    : event.data.toString();
+                const msg = JSON.parse(raw);
+                this.dispatch(msg);
             };
         });
     }
@@ -101,14 +111,15 @@ export class SidecarWsClient {
         if (typeof globalThis !== "undefined" && globalThis.WebSocket) {
             return globalThis.WebSocket;
         }
-        // Node.js -- try to require ws
+        // Node.js -- require ws
         try {
             // Dynamic require to avoid bundler issues
             const wsModule = require("ws");
             return wsModule.default || wsModule;
         }
         catch {
-            return null;
+            throw new PmxtError("WebSocket support in Node.js requires the 'ws' package. " +
+                "Install it with: npm install ws");
         }
     }
     dispatch(msg) {

package/dist/pmxt/client.d.ts

@@ -5,7 +5,7 @@
  * OpenAPI client, matching the Python API exactly.
  */
 import { Configuration, DefaultApi, ExchangeCredentials } from "../generated/src/index.js";
-import { Balance, BuiltOrder, CreateOrderParams, EventFetchParams, EventFilterCriteria, EventFilterFunction, ExecutionPriceResult, MarketFetchParams, MarketFilterCriteria, MarketFilterFunction, MarketOutcome, MyTradesParams, Order, OrderBook, OrderHistoryParams, PaginatedMarketsResult, Position, PriceCandle, SubscribedAddressSnapshot, SubscriptionOption, Trade, UnifiedEvent, UnifiedMarket, UserTrade } from "./models.js";
+import { Balance, BuiltOrder, CreateOrderParams, EventFetchParams, EventFilterCriteria, EventFilterFunction, ExecutionPriceResult, MarketFetchParams, MarketFilterCriteria, MarketFilterFunction, MarketOutcome, MyTradesParams, Order, OrderBook, OrderHistoryParams, PaginatedMarketsResult, Position, PriceCandle, SubscribedAddressSnapshot, SubscriptionOption, Trade, UnifiedEvent, UnifiedMarket, UserTrade, FirehoseEvent } from "./models.js";
 import { ServerManager } from "./server-manager.js";
 /**
  * Base exchange client options.
@@ -252,6 +252,26 @@ export declare abstract class Exchange {
      * ```
      */
     watchOrderBooks(outcomeIds: (string | MarketOutcome)[], limit?: number): Promise<Record<string, OrderBook>>;
+    /**
+     * Stream all orderbook updates across venues via the hosted WebSocket API.
+     *
+     * Returns a promise that resolves with the next book event.
+     * Call repeatedly in a loop to stream updates (CCXT Pro pattern).
+     * Requires hosted mode (`pmxtApiKey` set).
+     *
+     * @param venues - Optional venue filter (e.g. ["polymarket", "limitless"])
+     * @returns Next firehose event with source, symbol, and orderbook
+     *
+     * @example
+     * ```typescript
+     * const poly = new Polymarket({ pmxtApiKey: "pmxt_xxx" });
+     * while (true) {
+     *   const event = await poly.firehose();
+     *   console.log(event.source, event.symbol, event.orderbook.bids[0]);
+     * }
+     * ```
+     */
+    firehose(venues?: string[]): Promise<FirehoseEvent>;
     /**
      * Watch real-time trade updates via WebSocket.
      *

package/dist/pmxt/client.js

@@ -191,9 +191,14 @@ class Exchange {
                 this.api = new index_js_1.DefaultApi(this.config);
             }
             catch (error) {
-                throw new errors_js_1.PmxtError(`Failed to start PMXT server: ${error}\n\n` +
+                const msg = `Failed to start PMXT server: ${error instanceof Error ? error.message : error}\n\n` +
                     `Please ensure 'pmxt-core' is installed: npm install -g pmxt-core\n` +
-                    `Or start the server manually: pmxt-server`);
+                    `Or start the server manually: pmxt-server`;
+                const pmxtError = new errors_js_1.PmxtError(msg);
+                if (error instanceof Error) {
+                    pmxtError.cause = error;
+                }
+                throw pmxtError;
             }
         }
     }
@@ -292,8 +297,11 @@ class Exchange {
         if (this._wsClient?.connected)
             return this._wsClient;
         const host = this.resolveBaseUrl();
-        const accessToken = this.serverManager.getAccessToken();
-        const client = new ws_client_js_1.SidecarWsClient(host, accessToken || undefined);
+        const accessToken = this.isHosted
+            ? this.pmxtApiKey
+            : this.serverManager.getAccessToken();
+        const authParamName = this.isHosted ? "apiKey" : "token";
+        const client = new ws_client_js_1.SidecarWsClient(host, accessToken || undefined, authParamName);
         try {
             // Trigger connection to validate the endpoint exists.
             // subscribe() calls ensureConnected internally, but we want
@@ -328,8 +336,12 @@ class Exchange {
         try {
             return await ws.subscribe(this.exchangeName, method, args, this.getCredentials());
         }
-        catch {
-            return null;
+        catch (error) {
+            // Only fall back to HTTP for transport-level failures
+            if (error instanceof errors_js_1.PmxtError && /connection failed|no websocket/i.test(error.message)) {
+                return null;
+            }
+            throw error;
         }
     }
     // Low-Level API Access
@@ -1426,8 +1438,11 @@ class Exchange {
                     return result;
                 }
             }
-            catch {
-                // fall through to HTTP
+            catch (error) {
+                // Only fall through to HTTP for transport-level WS failures
+                if (!(error instanceof errors_js_1.PmxtError) || !/connection failed|no websocket/i.test(error.message)) {
+                    throw error;
+                }
             }
         }
         // HTTP fallback
@@ -1453,7 +1468,7 @@ class Exchange {
                 }
                 return result;
             }
-            return {};
+            throw new errors_js_1.PmxtError("watchOrderBooks: unexpected response shape from server");
         }
         catch (error) {
             if (error instanceof errors_js_1.PmxtError)
@@ -1461,6 +1476,41 @@ class Exchange {
             throw new errors_js_1.PmxtError(`Failed to watch order books: ${error}`);
         }
     }
+    /**
+     * Stream all orderbook updates across venues via the hosted WebSocket API.
+     *
+     * Returns a promise that resolves with the next book event.
+     * Call repeatedly in a loop to stream updates (CCXT Pro pattern).
+     * Requires hosted mode (`pmxtApiKey` set).
+     *
+     * @param venues - Optional venue filter (e.g. ["polymarket", "limitless"])
+     * @returns Next firehose event with source, symbol, and orderbook
+     *
+     * @example
+     * ```typescript
+     * const poly = new Polymarket({ pmxtApiKey: "pmxt_xxx" });
+     * while (true) {
+     *   const event = await poly.firehose();
+     *   console.log(event.source, event.symbol, event.orderbook.bids[0]);
+     * }
+     * ```
+     */
+    async firehose(venues) {
+        await this.initPromise;
+        if (!this.isHosted) {
+            throw new errors_js_1.PmxtError("firehose() requires hosted mode (set pmxtApiKey)");
+        }
+        const args = venues ? [venues] : [];
+        const wsData = await this.watchViaWs("firehose", args);
+        if (wsData !== null) {
+            return {
+                source: wsData._source || "",
+                symbol: wsData._symbol || "",
+                orderbook: convertOrderBook(wsData),
+            };
+        }
+        throw new errors_js_1.PmxtError("firehose() requires WebSocket transport — connection failed");
+    }
     /**
      * Watch real-time trade updates via WebSocket.
      *

package/dist/pmxt/models.d.ts

@@ -112,6 +112,17 @@ export interface OrderBook {
     /** Unix timestamp (milliseconds) */
     timestamp?: number;
 }
+/**
+ * A single event from the firehose stream.
+ */
+export interface FirehoseEvent {
+    /** The venue this event originated from (e.g. "polymarket", "limitless") */
+    source: string;
+    /** The outcome token id / asset id */
+    symbol: string;
+    /** The order book snapshot */
+    orderbook: OrderBook;
+}
 /**
  * Result of an execution price calculation.
  */

package/dist/pmxt/ws-client.d.ts

@@ -16,6 +16,7 @@ export declare class SidecarWsClient {
     private ws;
     private host;
     private accessToken;
+    private authParamName;
     private closed;
     /** requestId -> latest data payload */
     private dataStore;
@@ -24,7 +25,7 @@ export declare class SidecarWsClient {
     /** (method:symbolKey) -> requestId -- avoids duplicate subscribes */
     private activeSubs;
     private connectPromise;
-    constructor(host: string, accessToken?: string);
+    constructor(host: string, accessToken?: string, authParamName?: string);
     private ensureConnected;
     private connect;
     private getWebSocketConstructor;

package/dist/pmxt/ws-client.js

@@ -20,6 +20,7 @@ class SidecarWsClient {
     ws = null;
     host;
     accessToken;
+    authParamName;
     closed = false;
     /** requestId -> latest data payload */
     dataStore = new Map();
@@ -28,9 +29,10 @@ class SidecarWsClient {
     /** (method:symbolKey) -> requestId -- avoids duplicate subscribes */
     activeSubs = new Map();
     connectPromise = null;
-    constructor(host, accessToken) {
+    constructor(host, accessToken, authParamName = "token") {
         this.host = host;
         this.accessToken = accessToken;
+        this.authParamName = authParamName;
     }
     // ------------------------------------------------------------------
     // Connection lifecycle
@@ -61,7 +63,7 @@ class SidecarWsClient {
             }
             let url = `${scheme}://${hostPart}/ws`;
             if (this.accessToken) {
-                url = `${url}?token=${this.accessToken}`;
+                url = `${url}?${this.authParamName}=${this.accessToken}`;
             }
             // Use the ws package in Node.js, native WebSocket in browsers
             const WsConstructor = this.getWebSocketConstructor();
@@ -80,22 +82,30 @@ class SidecarWsClient {
                     // Connection failed during handshake
                     reject(new errors_js_1.PmxtError(`WebSocket connection failed: ${err.message || err}`));
                 }
+                else {
+                    // Post-handshake error — propagate to all pending subscribers
+                    const error = new errors_js_1.PmxtError(`WebSocket error: ${err.message || err}`);
+                    for (const sub of this.subscriptions.values()) {
+                        if (sub.reject) {
+                            sub.reject(error);
+                            sub.reject = null;
+                            sub.resolve = null;
+                        }
+                    }
+                    this.closed = true;
+                    this.ws = null;
+                }
             };
             ws.onclose = () => {
                 this.closed = true;
                 this.ws = null;
             };
             ws.onmessage = (event) => {
-                try {
-                    const data = typeof event.data === "string"
-                        ? event.data
-                        : event.data.toString();
-                    const msg = JSON.parse(data);
-                    this.dispatch(msg);
-                }
-                catch {
-                    // Ignore unparseable frames
-                }
+                const raw = typeof event.data === "string"
+                    ? event.data
+                    : event.data.toString();
+                const msg = JSON.parse(raw);
+                this.dispatch(msg);
             };
         });
     }
@@ -104,14 +114,15 @@ class SidecarWsClient {
         if (typeof globalThis !== "undefined" && globalThis.WebSocket) {
             return globalThis.WebSocket;
         }
-        // Node.js -- try to require ws
+        // Node.js -- require ws
         try {
             // Dynamic require to avoid bundler issues
             const wsModule = require("ws");
             return wsModule.default || wsModule;
         }
         catch {
-            return null;
+            throw new errors_js_1.PmxtError("WebSocket support in Node.js requires the 'ws' package. " +
+                "Install it with: npm install ws");
         }
     }
     dispatch(msg) {

package/generated/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmxtjs",
-  "version": "2.40.5",
+  "version": "2.41.0",
   "description": "OpenAPI client for pmxtjs",
   "author": "OpenAPI-Generator",
   "repository": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmxtjs",
-  "version": "2.40.5",
+  "version": "2.41.0",
   "description": "Unified prediction market data API - The ccxt for prediction markets",
   "author": "PMXT Contributors",
   "repository": {
@@ -43,7 +43,8 @@
     "unified"
   ],
   "dependencies": {
-    "pmxt-core": "2.40.5"
+    "pmxt-core": "2.41.0",
+    "ws": "^8.18.0"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",

package/pmxt/client.ts

@@ -42,6 +42,7 @@ import {
     UnifiedEvent,
     UnifiedMarket,
     UserTrade,
+    FirehoseEvent,
 } from "./models.js";
 
 import { ServerManager } from "./server-manager.js";
@@ -296,11 +297,15 @@ export abstract class Exchange {
                 });
                 this.api = new DefaultApi(this.config);
             } catch (error) {
-                throw new PmxtError(
-                    `Failed to start PMXT server: ${error}\n\n` +
+                const msg =
+                    `Failed to start PMXT server: ${error instanceof Error ? error.message : error}\n\n` +
                     `Please ensure 'pmxt-core' is installed: npm install -g pmxt-core\n` +
-                    `Or start the server manually: pmxt-server`
-                );
+                    `Or start the server manually: pmxt-server`;
+                const pmxtError = new PmxtError(msg);
+                if (error instanceof Error) {
+                    (pmxtError as any).cause = error;
+                }
+                throw pmxtError;
             }
         }
     }
@@ -408,9 +413,12 @@ export abstract class Exchange {
         if (this._wsClient?.connected) return this._wsClient;
 
         const host = this.resolveBaseUrl();
-        const accessToken = this.serverManager.getAccessToken();
+        const accessToken = this.isHosted
+            ? this.pmxtApiKey
+            : this.serverManager.getAccessToken();
+        const authParamName = this.isHosted ? "apiKey" : "token";
 
-        const client = new SidecarWsClient(host, accessToken || undefined);
+        const client = new SidecarWsClient(host, accessToken || undefined, authParamName);
         try {
             // Trigger connection to validate the endpoint exists.
             // subscribe() calls ensureConnected internally, but we want
@@ -459,8 +467,12 @@ export abstract class Exchange {
                 args,
                 this.getCredentials() as Record<string, any> | undefined,
             );
-        } catch {
-            return null;
+        } catch (error) {
+            // Only fall back to HTTP for transport-level failures
+            if (error instanceof PmxtError && /connection failed|no websocket/i.test(error.message)) {
+                return null;
+            }
+            throw error;
         }
     }
 
@@ -1540,8 +1552,11 @@ export abstract class Exchange {
                     }
                     return result;
                 }
-            } catch {
-                // fall through to HTTP
+            } catch (error) {
+                // Only fall through to HTTP for transport-level WS failures
+                if (!(error instanceof PmxtError) || !/connection failed|no websocket/i.test(error.message)) {
+                    throw error;
+                }
             }
         }
 
@@ -1571,13 +1586,52 @@ export abstract class Exchange {
                 }
                 return result;
             }
-            return {};
+            throw new PmxtError("watchOrderBooks: unexpected response shape from server");
         } catch (error) {
             if (error instanceof PmxtError) throw error;
             throw new PmxtError(`Failed to watch order books: ${error}`);
         }
     }
 
+    /**
+     * Stream all orderbook updates across venues via the hosted WebSocket API.
+     *
+     * Returns a promise that resolves with the next book event.
+     * Call repeatedly in a loop to stream updates (CCXT Pro pattern).
+     * Requires hosted mode (`pmxtApiKey` set).
+     *
+     * @param venues - Optional venue filter (e.g. ["polymarket", "limitless"])
+     * @returns Next firehose event with source, symbol, and orderbook
+     *
+     * @example
+     * ```typescript
+     * const poly = new Polymarket({ pmxtApiKey: "pmxt_xxx" });
+     * while (true) {
+     *   const event = await poly.firehose();
+     *   console.log(event.source, event.symbol, event.orderbook.bids[0]);
+     * }
+     * ```
+     */
+    async firehose(venues?: string[]): Promise<FirehoseEvent> {
+        await this.initPromise;
+
+        if (!this.isHosted) {
+            throw new PmxtError("firehose() requires hosted mode (set pmxtApiKey)");
+        }
+
+        const args: any[] = venues ? [venues] : [];
+        const wsData = await this.watchViaWs("firehose", args);
+        if (wsData !== null) {
+            return {
+                source: (wsData as any)._source || "",
+                symbol: (wsData as any)._symbol || "",
+                orderbook: convertOrderBook(wsData),
+            };
+        }
+
+        throw new PmxtError("firehose() requires WebSocket transport — connection failed");
+    }
+
     /**
      * Watch real-time trade updates via WebSocket.
      *

package/pmxt/models.ts

@@ -153,6 +153,20 @@ export interface OrderBook {
     timestamp?: number;
 }
 
+/**
+ * A single event from the firehose stream.
+ */
+export interface FirehoseEvent {
+    /** The venue this event originated from (e.g. "polymarket", "limitless") */
+    source: string;
+
+    /** The outcome token id / asset id */
+    symbol: string;
+
+    /** The order book snapshot */
+    orderbook: OrderBook;
+}
+
 /**
  * Result of an execution price calculation.
  */

package/pmxt/ws-client.ts

@@ -36,6 +36,7 @@ export class SidecarWsClient {
     private ws: WebSocket | null = null;
     private host: string;
     private accessToken: string | undefined;
+    private authParamName: string;
     private closed = false;
 
     /** requestId -> latest data payload */
@@ -47,9 +48,10 @@ export class SidecarWsClient {
 
     private connectPromise: Promise<void> | null = null;
 
-    constructor(host: string, accessToken?: string) {
+    constructor(host: string, accessToken?: string, authParamName: string = "token") {
         this.host = host;
         this.accessToken = accessToken;
+        this.authParamName = authParamName;
     }
 
     // ------------------------------------------------------------------
@@ -81,7 +83,7 @@ export class SidecarWsClient {
 
             let url = `${scheme}://${hostPart}/ws`;
             if (this.accessToken) {
-                url = `${url}?token=${this.accessToken}`;
+                url = `${url}?${this.authParamName}=${this.accessToken}`;
             }
 
             // Use the ws package in Node.js, native WebSocket in browsers
@@ -103,6 +105,18 @@ export class SidecarWsClient {
                 if (!this.ws) {
                     // Connection failed during handshake
                     reject(new PmxtError(`WebSocket connection failed: ${err.message || err}`));
+                } else {
+                    // Post-handshake error — propagate to all pending subscribers
+                    const error = new PmxtError(`WebSocket error: ${err.message || err}`);
+                    for (const sub of this.subscriptions.values()) {
+                        if (sub.reject) {
+                            sub.reject(error);
+                            sub.reject = null;
+                            sub.resolve = null;
+                        }
+                    }
+                    this.closed = true;
+                    this.ws = null;
                 }
             };
 
@@ -112,15 +126,11 @@ export class SidecarWsClient {
             };
 
             ws.onmessage = (event: any) => {
-                try {
-                    const data = typeof event.data === "string"
-                        ? event.data
-                        : event.data.toString();
-                    const msg: WsMessage = JSON.parse(data);
-                    this.dispatch(msg);
-                } catch {
-                    // Ignore unparseable frames
-                }
+                const raw = typeof event.data === "string"
+                    ? event.data
+                    : event.data.toString();
+                const msg: WsMessage = JSON.parse(raw);
+                this.dispatch(msg);
             };
         });
     }
@@ -130,13 +140,16 @@ export class SidecarWsClient {
         if (typeof globalThis !== "undefined" && (globalThis as any).WebSocket) {
             return (globalThis as any).WebSocket;
         }
-        // Node.js -- try to require ws
+        // Node.js -- require ws
         try {
             // Dynamic require to avoid bundler issues
             const wsModule = require("ws");
             return wsModule.default || wsModule;
         } catch {
-            return null;
+            throw new PmxtError(
+                "WebSocket support in Node.js requires the 'ws' package. " +
+                "Install it with: npm install ws"
+            );
         }
     }