pmxt-core 2.44.4 → 2.44.6

package/dist/feeds/binance/binance-feed.js

@@ -6,12 +6,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.BinanceFeed = void 0;
 const ws_1 = __importDefault(require("ws"));
 const logger_1 = require("../../utils/logger");
+const errors_1 = require("../../errors");
 const base_feed_1 = require("../base-feed");
 const types_1 = require("./types");
 const normalizer_1 = require("./normalizer");
 class BinanceFeed extends base_feed_1.BaseDataFeed {
     name = 'binance';
     description = 'Binance spot trade firehose via obdata relay';
+    has = {
+        loadMarkets: true,
+        fetchTicker: true,
+        fetchTickers: true,
+        watchTicker: true,
+        fetchOHLCV: false,
+        fetchOrderBook: false,
+    };
     wsUrl;
     apiKey;
     reconnectIntervalMs;
@@ -23,7 +32,7 @@ class BinanceFeed extends base_feed_1.BaseDataFeed {
     connectionPromise = null;
     constructor(config = {}, options) {
         super(options);
-        this.wsUrl = config.wsUrl ?? types_1.BINANCE_RELAY_DEFAULTS.wsUrl;
+        this.wsUrl = config.wsUrl ?? process.env.BINANCE_RELAY_WS_URL ?? types_1.BINANCE_RELAY_DEFAULTS.wsUrl;
         this.apiKey = config.apiKey ?? process.env.OBDATA_API_KEY ?? '';
         this.reconnectIntervalMs = config.reconnectIntervalMs ?? types_1.BINANCE_RELAY_DEFAULTS.reconnectIntervalMs;
     }
@@ -117,10 +126,10 @@ class BinanceFeed extends base_feed_1.BaseDataFeed {
         };
     }
     async fetchOHLCVImpl(_symbol, _timeframe, _since, _limit) {
-        throw new Error('BinanceFeed: OHLCV not available via trade relay');
+        throw new errors_1.NotSupported('BinanceFeed does not support fetchOHLCV via the configured trade relay.', this.name);
     }
     async fetchOrderBookImpl(_symbol, _limit) {
-        throw new Error('BinanceFeed: Order book not available via trade relay');
+        throw new errors_1.NotSupported('BinanceFeed does not support fetchOrderBook via the configured trade relay.', this.name);
     }
     // -- Internal --
     async ensureConnected() {
@@ -130,10 +139,11 @@ class BinanceFeed extends base_feed_1.BaseDataFeed {
     }
     establishConnection() {
         return new Promise((resolve, reject) => {
-            const url = this.apiKey
-                ? `${this.wsUrl}?key=${this.apiKey}`
-                : this.wsUrl;
-            const ws = new ws_1.default(url);
+            const relayUrl = this.validateRelayWsUrl();
+            if (this.apiKey) {
+                relayUrl.searchParams.set('key', this.apiKey);
+            }
+            const ws = new ws_1.default(relayUrl.toString());
             const connectionTimeout = setTimeout(() => {
                 ws.close();
                 this.ws = null;
@@ -203,5 +213,22 @@ class BinanceFeed extends base_feed_1.BaseDataFeed {
             }
         }, this.reconnectIntervalMs);
     }
+    validateRelayWsUrl() {
+        const rawUrl = this.wsUrl.trim();
+        if (!rawUrl) {
+            throw new errors_1.ExchangeNotAvailable('BinanceFeed requires BINANCE_RELAY_WS_URL to fetch live ticker data.', this.name);
+        }
+        let url;
+        try {
+            url = new URL(rawUrl);
+        }
+        catch {
+            throw new errors_1.ExchangeNotAvailable('BinanceFeed requires BINANCE_RELAY_WS_URL to be a valid WebSocket URL.', this.name);
+        }
+        if (url.protocol !== 'ws:' && url.protocol !== 'wss:') {
+            throw new errors_1.ExchangeNotAvailable('BinanceFeed requires BINANCE_RELAY_WS_URL to use ws:// or wss://.', this.name);
+        }
+        return url;
+    }
 }
 exports.BinanceFeed = BinanceFeed;

package/dist/feeds/chainlink/chainlink-feed.d.ts

@@ -4,6 +4,18 @@ import { ChainlinkFeedConfig } from './types';
 export declare class ChainlinkFeed extends BaseDataFeed {
     readonly name = "chainlink";
     readonly description = "Chainlink price feeds (ETH, BTC, XRP, SOL) on Polygon via pmxt-ohlc";
+    readonly has: {
+        readonly loadMarkets: true;
+        readonly fetchTicker: true;
+        readonly fetchTickers: true;
+        readonly watchTicker: true;
+        readonly fetchOHLCV: false;
+        readonly fetchOrderBook: false;
+        readonly fetchOracleRound: true;
+        readonly fetchOracleHistory: true;
+        readonly fetchHistoricalPrices: true;
+    };
+    private readonly baseUrl;
     private readonly client;
     private readonly wsUrl;
     private readonly wsApiKey;
@@ -32,7 +44,9 @@ export declare class ChainlinkFeed extends BaseDataFeed {
         order?: 'asc' | 'desc';
     }): Promise<Ticker[]>;
     private ensureConnected;
+    private ensureRestConfigured;
     private establishConnection;
+    private validateWsUrl;
     private handleMessage;
     private scheduleReconnect;
 }

package/dist/feeds/chainlink/chainlink-feed.js

@@ -8,11 +8,24 @@ const ws_1 = __importDefault(require("ws"));
 const axios_1 = __importDefault(require("axios"));
 const base_feed_1 = require("../base-feed");
 const logger_1 = require("../../utils/logger");
+const errors_1 = require("../../errors");
 const types_1 = require("./types");
 const normalizer_1 = require("./normalizer");
 class ChainlinkFeed extends base_feed_1.BaseDataFeed {
     name = 'chainlink';
     description = 'Chainlink price feeds (ETH, BTC, XRP, SOL) on Polygon via pmxt-ohlc';
+    has = {
+        loadMarkets: true,
+        fetchTicker: true,
+        fetchTickers: true,
+        watchTicker: true,
+        fetchOHLCV: false,
+        fetchOrderBook: false,
+        fetchOracleRound: true,
+        fetchOracleHistory: true,
+        fetchHistoricalPrices: true,
+    };
+    baseUrl;
     client;
     wsUrl;
     wsApiKey;
@@ -25,13 +38,14 @@ class ChainlinkFeed extends base_feed_1.BaseDataFeed {
     connectionPromise = null;
     constructor(config, options) {
         super(options);
-        const baseURL = config.baseUrl ?? types_1.CHAINLINK_DEFAULTS.baseUrl;
+        const baseURL = config.baseUrl ?? process.env.CHAINLINK_API_URL ?? types_1.CHAINLINK_DEFAULTS.baseUrl;
+        this.baseUrl = baseURL;
         this.client = axios_1.default.create({
             baseURL,
             headers: { 'X-API-Key': config.apiKey },
             timeout: 10_000,
         });
-        this.wsUrl = config.wsUrl ?? types_1.CHAINLINK_DEFAULTS.wsUrl;
+        this.wsUrl = config.wsUrl ?? process.env.CHAINLINK_WS_URL ?? types_1.CHAINLINK_DEFAULTS.wsUrl;
         this.wsApiKey = config.wsApiKey ?? config.apiKey;
         this.reconnectIntervalMs = config.reconnectIntervalMs ?? types_1.CHAINLINK_DEFAULTS.reconnectIntervalMs;
     }
@@ -87,6 +101,7 @@ class ChainlinkFeed extends base_feed_1.BaseDataFeed {
         const cached = this.latestTickers.get(symbol.toUpperCase());
         if (cached)
             return cached;
+        this.ensureRestConfigured();
         const token = types_1.TOKEN_BY_PAIR.get(symbol.toUpperCase());
         if (!token) {
             throw new Error(`Unsupported Chainlink symbol: ${symbol}. Supported: ${types_1.SUPPORTED_TOKENS.map((t) => t.pair).join(', ')}`);
@@ -101,6 +116,7 @@ class ChainlinkFeed extends base_feed_1.BaseDataFeed {
     }
     // -- CCXT: fetchTickers --
     async fetchTickersImpl(symbols) {
+        this.ensureRestConfigured();
         const { data } = await this.client.get('/v1/chainlink/latest-prices');
         const now = Date.now();
         const requested = symbols
@@ -133,15 +149,16 @@ class ChainlinkFeed extends base_feed_1.BaseDataFeed {
     }
     // -- CCXT: fetchOHLCV (not supported) --
     async fetchOHLCVImpl(_symbol, _timeframe, _since, _limit) {
-        throw new Error('Chainlink feed does not provide OHLCV candles. ' +
-            'Use fetchOracleHistory() for raw AnswerUpdated records.');
+        throw new errors_1.NotSupported('Chainlink feed does not provide OHLCV candles. ' +
+            'Use fetchOracleHistory() for raw AnswerUpdated records.', this.name);
     }
     // -- CCXT: fetchOrderBook (not applicable) --
     async fetchOrderBookImpl(_symbol, _limit) {
-        throw new Error('Chainlink oracle feeds do not have order books.');
+        throw new errors_1.NotSupported('Chainlink oracle feeds do not have order books.', this.name);
     }
     // -- pmxt extensions: Oracle --
     async fetchOracleRound(params) {
+        this.ensureRestConfigured();
         const token = types_1.TOKEN_BY_PAIR.get(params.feed.toUpperCase());
         if (!token) {
             throw new Error(`Unsupported Chainlink feed: ${params.feed}. Supported: ${types_1.SUPPORTED_TOKENS.map((t) => t.pair).join(', ')}`);
@@ -153,6 +170,7 @@ class ChainlinkFeed extends base_feed_1.BaseDataFeed {
         return (0, normalizer_1.normalizePriceRecordToOracleRound)(data.data[0]);
     }
     async fetchOracleHistory(params) {
+        this.ensureRestConfigured();
         const token = types_1.TOKEN_BY_PAIR.get(params.feed.toUpperCase());
         if (!token) {
             throw new Error(`Unsupported Chainlink feed: ${params.feed}. Supported: ${types_1.SUPPORTED_TOKENS.map((t) => t.pair).join(', ')}`);
@@ -161,6 +179,7 @@ class ChainlinkFeed extends base_feed_1.BaseDataFeed {
         return data.data.map(normalizer_1.normalizePriceRecordToOracleRound);
     }
     async fetchHistoricalPrices(symbol, opts) {
+        this.ensureRestConfigured();
         const token = types_1.TOKEN_BY_PAIR.get(symbol.toUpperCase());
         if (!token) {
             throw new Error(`Unsupported Chainlink symbol: ${symbol}. Supported: ${types_1.SUPPORTED_TOKENS.map((t) => t.pair).join(', ')}`);
@@ -183,10 +202,29 @@ class ChainlinkFeed extends base_feed_1.BaseDataFeed {
             return;
         await this.connect();
     }
+    ensureRestConfigured() {
+        const rawUrl = this.baseUrl.trim();
+        if (!rawUrl) {
+            throw new errors_1.ExchangeNotAvailable('ChainlinkFeed requires CHAINLINK_API_URL to fetch oracle data.', this.name);
+        }
+        let url;
+        try {
+            url = new URL(rawUrl);
+        }
+        catch {
+            throw new errors_1.ExchangeNotAvailable('ChainlinkFeed requires CHAINLINK_API_URL to be a valid HTTP URL.', this.name);
+        }
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            throw new errors_1.ExchangeNotAvailable('ChainlinkFeed requires CHAINLINK_API_URL to use http:// or https://.', this.name);
+        }
+    }
     establishConnection() {
         return new Promise((resolve, reject) => {
-            const url = `${this.wsUrl}?key=${this.wsApiKey}`;
-            const ws = new ws_1.default(url);
+            const wsUrl = this.validateWsUrl();
+            if (this.wsApiKey) {
+                wsUrl.searchParams.set('key', this.wsApiKey);
+            }
+            const ws = new ws_1.default(wsUrl.toString());
             const connectionTimeout = setTimeout(() => {
                 ws.close();
                 this.ws = null;
@@ -220,6 +258,23 @@ class ChainlinkFeed extends base_feed_1.BaseDataFeed {
             });
         });
     }
+    validateWsUrl() {
+        const rawUrl = this.wsUrl.trim();
+        if (!rawUrl) {
+            throw new errors_1.ExchangeNotAvailable('ChainlinkFeed requires CHAINLINK_WS_URL to stream live oracle data.', this.name);
+        }
+        let url;
+        try {
+            url = new URL(rawUrl);
+        }
+        catch {
+            throw new errors_1.ExchangeNotAvailable('ChainlinkFeed requires CHAINLINK_WS_URL to be a valid WebSocket URL.', this.name);
+        }
+        if (url.protocol !== 'ws:' && url.protocol !== 'wss:') {
+            throw new errors_1.ExchangeNotAvailable('ChainlinkFeed requires CHAINLINK_WS_URL to use ws:// or wss://.', this.name);
+        }
+        return url;
+    }
     handleMessage(data) {
         const text = typeof data === 'string' ? data : data.toString();
         let msg;

package/dist/feeds/interfaces.d.ts

@@ -1,7 +1,11 @@
 import { Ticker, Tickers, OHLCV, OrderBook, Market, FundingRate, FundingRates, OracleRound, OracleParams, Dictionary } from './types';
+export type DataFeedCapability = 'loadMarkets' | 'fetchTicker' | 'fetchTickers' | 'watchTicker' | 'fetchOHLCV' | 'fetchOrderBook' | 'watchOrderBook' | 'fetchFundingRate' | 'fetchFundingRates' | 'fetchOracleRound' | 'fetchOracleHistory' | 'fetchHistoricalPrices';
+export type DataFeedCapabilityValue = true | false | 'emulated';
+export type DataFeedCapabilities = Readonly<Partial<Record<DataFeedCapability, DataFeedCapabilityValue>>>;
 export interface IDataFeed {
     readonly name: string;
     readonly description: string;
+    readonly has?: DataFeedCapabilities;
     loadMarkets(reload?: boolean): Promise<Dictionary<Market>>;
     fetchTicker(symbol: string): Promise<Ticker>;
     fetchTickers(symbols?: string[]): Promise<Tickers>;
@@ -13,6 +17,12 @@ export interface IDataFeed {
     fetchFundingRates?(symbols?: string[]): Promise<FundingRates>;
     fetchOracleRound?(params: OracleParams): Promise<OracleRound>;
     fetchOracleHistory?(params: OracleParams): Promise<OracleRound[]>;
+    fetchHistoricalPrices?(symbol: string, opts?: {
+        fromTimestamp?: number;
+        untilTimestamp?: number;
+        maxSize?: number;
+        order?: 'asc' | 'desc';
+    }): Promise<Ticker[]>;
     connect?(): Promise<void>;
     close?(): Promise<void>;
 }

package/dist/router/Router.d.ts

@@ -4,6 +4,7 @@ import type { RouterOptions, MatchResult, EventMatchResult, PriceComparison, Arb
 export declare class Router extends PredictionMarketExchange {
     private readonly client;
     private readonly exchanges;
+    private readonly localExchanges;
     constructor(options: RouterOptions);
     get name(): string;
     protected fetchMarketsImpl(params?: MarketFetchParams): Promise<UnifiedMarket[]>;
@@ -28,6 +29,14 @@ export declare class Router extends PredictionMarketExchange {
     fetchMatchedPrices(params?: FetchMatchedPricesParams): Promise<MatchedPricePair[]>;
     /** @deprecated Use {@link fetchMatchedMarkets} instead. */
     fetchArbitrage(params?: FetchArbitrageParams): Promise<ArbitrageOpportunity[]>;
+    private getLocalExchange;
+    /**
+     * Local mock IDs are sidecar-only fixtures. Hosted match endpoints do not
+     * know them, so resolve them locally when possible and avoid opaque hosted
+     * "not found" responses.
+     */
+    private resolveLocalMockMarketLookup;
+    private resolveLocalMockEventLookup;
     private fetchArbitrageInternal;
     /**
      * Bulk arbitrage via `GET /v0/arbitrage`. One round-trip.

package/dist/router/Router.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Router = void 0;
 const BaseExchange_1 = require("../BaseExchange");
+const errors_1 = require("../errors");
 const logger_1 = require("../utils/logger");
 const client_1 = require("./client");
 // ---------------------------------------------------------------------------
@@ -28,13 +29,82 @@ function mergeOrderBooks(books) {
     };
 }
 // ---------------------------------------------------------------------------
+const MOCK_MARKET_OR_OUTCOME_ID_RE = /^(mock-m\d+)(?:-(?:yes|no|\d+))?$/;
+const MOCK_EVENT_ID_RE = /^mock-event-\d+$/;
+class LocalRouterMatchLookupUnsupported extends errors_1.BaseError {
+    constructor(kind, identifier) {
+        super(`LOCAL_MATCH_LOOKUP_UNSUPPORTED: Router match lookup for local mock ${kind} ` +
+            `"${identifier}" cannot be served by the hosted match catalog. ` +
+            `Configure RouterOptions.localExchanges.mock when using Router in-process; ` +
+            `the /api/router sidecar endpoint resolves bundled mock IDs locally and returns [] because mock fixtures have no hosted cross-venue matches.`, 501, 'LOCAL_MATCH_LOOKUP_UNSUPPORTED', false, 'Router');
+    }
+}
+function sourceExchangeIsMock(sourceExchange) {
+    return typeof sourceExchange === 'string' && sourceExchange.toLowerCase() === 'mock';
+}
+function lookupString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function mockMarketIdFromLocalId(id) {
+    const value = lookupString(id);
+    if (!value)
+        return undefined;
+    return value.match(MOCK_MARKET_OR_OUTCOME_ID_RE)?.[1];
+}
+function isMockEventId(id) {
+    const value = lookupString(id);
+    return value !== undefined && MOCK_EVENT_ID_RE.test(value);
+}
+function isMockUrl(url, resource) {
+    const value = lookupString(url);
+    if (!value)
+        return false;
+    try {
+        const parsed = new URL(value);
+        return parsed.hostname === 'mock.pmxt.dev' && parsed.pathname.startsWith(`/${resource}/`);
+    }
+    catch {
+        return value.includes(`mock.pmxt.dev/${resource}/`);
+    }
+}
+function describeMarketLookup(params) {
+    return params.market?.marketId
+        ?? lookupString(params.marketId)
+        ?? lookupString(params.slug)
+        ?? lookupString(params.url)
+        ?? 'unknown';
+}
+function describeEventLookup(params) {
+    return params.event?.id
+        ?? lookupString(params.eventId)
+        ?? lookupString(params.slug)
+        ?? 'unknown';
+}
+function isLocalMockMarketLookup(params) {
+    return sourceExchangeIsMock(params.market?.sourceExchange)
+        || mockMarketIdFromLocalId(params.market?.marketId) !== undefined
+        || mockMarketIdFromLocalId(params.marketId) !== undefined
+        || mockMarketIdFromLocalId(params.slug) !== undefined
+        || isMockUrl(params.url, 'market');
+}
+function isLocalMockEventLookup(params) {
+    return sourceExchangeIsMock(params.event?.sourceExchange)
+        || isMockEventId(params.event?.id)
+        || isMockEventId(params.eventId)
+        || isMockEventId(params.slug);
+}
+function findByUrl(items, url) {
+    return items.find((item) => item.url === url);
+}
 class Router extends BaseExchange_1.PredictionMarketExchange {
     client;
     exchanges;
+    localExchanges;
     constructor(options) {
         super({ apiKey: options.apiKey });
         this.client = new client_1.PmxtApiClient(options.apiKey, options.baseUrl);
         this.exchanges = options.exchanges ?? {};
+        this.localExchanges = options.localExchanges ?? options.exchanges ?? {};
         this.rateLimit = 100;
     }
     get name() {
@@ -126,7 +196,10 @@ class Router extends BaseExchange_1.PredictionMarketExchange {
     // -----------------------------------------------------------------------
     async fetchMarketMatches(params = {}) {
         if (params.market && !params.marketId) {
-            if (params.market.slug && !params.slug) {
+            if (sourceExchangeIsMock(params.market.sourceExchange)) {
+                params = { ...params, marketId: params.market.marketId };
+            }
+            else if (params.market.slug && !params.slug) {
                 params = { ...params, slug: params.market.slug };
             }
             else {
@@ -139,6 +212,9 @@ class Router extends BaseExchange_1.PredictionMarketExchange {
         if (!hasIdentifier) {
             return this.fetchMarketMatchesBrowse(params);
         }
+        if (await this.resolveLocalMockMarketLookup(params)) {
+            return [];
+        }
         // Lookup mode: find matches for a specific market.
         const response = await this.client.getMarketMatches(params);
         const matches = response.matches ?? [];
@@ -172,7 +248,10 @@ class Router extends BaseExchange_1.PredictionMarketExchange {
     // -----------------------------------------------------------------------
     async fetchEventMatches(params = {}) {
         if (params.event && !params.eventId) {
-            if (params.event.slug && !params.slug) {
+            if (sourceExchangeIsMock(params.event.sourceExchange)) {
+                params = { ...params, eventId: params.event.id };
+            }
+            else if (params.event.slug && !params.slug) {
                 params = { ...params, slug: params.event.slug };
             }
             else {
@@ -185,6 +264,9 @@ class Router extends BaseExchange_1.PredictionMarketExchange {
             const results = await this.client.browseEventMatches(params);
             return Array.isArray(results) ? results : [];
         }
+        if (await this.resolveLocalMockEventLookup(params)) {
+            return [];
+        }
         // Lookup mode: find matches for a specific event.
         const response = await this.client.getEventMatches(params);
         return response.matches ?? [];
@@ -278,6 +360,75 @@ class Router extends BaseExchange_1.PredictionMarketExchange {
         logger_1.logger.warn('fetchArbitrage is deprecated, use fetchMatchedPrices instead');
         return this.fetchArbitrageInternal(params);
     }
+    getLocalExchange(name) {
+        const target = name.toLowerCase();
+        for (const [key, exchange] of Object.entries(this.localExchanges)) {
+            if (key.toLowerCase() === target || exchange.name.toLowerCase() === target) {
+                return exchange;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Local mock IDs are sidecar-only fixtures. Hosted match endpoints do not
+     * know them, so resolve them locally when possible and avoid opaque hosted
+     * "not found" responses.
+     */
+    async resolveLocalMockMarketLookup(params) {
+        if (!isLocalMockMarketLookup(params))
+            return false;
+        const identifier = describeMarketLookup(params);
+        const mock = this.getLocalExchange('mock');
+        if (!mock) {
+            throw new LocalRouterMatchLookupUnsupported('market', identifier);
+        }
+        if (params.market && sourceExchangeIsMock(params.market.sourceExchange)) {
+            return true;
+        }
+        const localMarketId = mockMarketIdFromLocalId(params.marketId)
+            ?? mockMarketIdFromLocalId(params.slug);
+        if (localMarketId) {
+            await mock.fetchMarket({ marketId: localMarketId });
+            return true;
+        }
+        const url = lookupString(params.url);
+        if (url && isMockUrl(url, 'market')) {
+            const markets = await mock.fetchMarkets();
+            if (!findByUrl(markets, url)) {
+                throw new errors_1.MarketNotFound(url, mock.name);
+            }
+            return true;
+        }
+        return true;
+    }
+    async resolveLocalMockEventLookup(params) {
+        if (!isLocalMockEventLookup(params))
+            return false;
+        const identifier = describeEventLookup(params);
+        const mock = this.getLocalExchange('mock');
+        if (!mock) {
+            throw new LocalRouterMatchLookupUnsupported('event', identifier);
+        }
+        if (params.event && sourceExchangeIsMock(params.event.sourceExchange)) {
+            return true;
+        }
+        const localEventId = isMockEventId(params.eventId) ? params.eventId
+            : isMockEventId(params.slug) ? params.slug
+                : undefined;
+        if (localEventId) {
+            await mock.fetchEvent({ eventId: localEventId });
+            return true;
+        }
+        const url = lookupString(params.url);
+        if (url && isMockUrl(url, 'event')) {
+            const events = await mock.fetchEvents();
+            if (!findByUrl(events, url)) {
+                throw new errors_1.EventNotFound(url, mock.name);
+            }
+            return true;
+        }
+        return true;
+    }
     async fetchArbitrageInternal(params) {
         // Try the dedicated bulk endpoint first (single DB query).
         try {

package/dist/router/types.d.ts

@@ -6,6 +6,11 @@ export interface RouterOptions {
     baseUrl?: string;
     /** Exchange instances for cross-venue orderbook aggregation. Keyed by exchange name (e.g. 'polymarket', 'kalshi'). */
     exchanges?: Record<string, PredictionMarketExchange>;
+    /**
+     * Local exchange instances used only to resolve sidecar-only fixture IDs
+     * before hosted catalog match lookups. Does not affect orderbook routing.
+     */
+    localExchanges?: Record<string, PredictionMarketExchange>;
 }
 export interface MatchResult {
     market: UnifiedMarket;

package/dist/server/app.d.ts

@@ -1,4 +1,5 @@
 import { Express } from "express";
+import { Server as HttpServer } from "http";
 import { createWebSocketHandler, CreateWebSocketHandlerOptions } from "./ws-handler";
 /**
  * Options accepted by {@link createApp}.
@@ -33,12 +34,25 @@ export interface CreateAppOptions {
  * wrap the sidecar in their own auth / quota / usage middleware and serve
  * it as part of a larger Express application.
  *
- * The returned app registers:
+ * The returned app registers HTTP routes only:
  *   - `GET  /health`
  *   - (optional) the built-in `x-pmxt-access-token` auth check
  *   - `POST /api/:exchange/:method`
  *   - the error handler
  *
+ * WebSocket upgrades do not pass through Express routing. Local servers
+ * created from this app can expose `/ws` by attaching the WebSocket endpoint
+ * to the underlying HTTP server:
+ *
+ * ```ts
+ * import { createApp, attachWebSocketEndpoint } from 'pmxt-core';
+ *
+ * const accessToken = process.env.PMXT_ACCESS_TOKEN;
+ * const app = createApp({ accessToken });
+ * const server = app.listen(4000, "127.0.0.1");
+ * attachWebSocketEndpoint(server, { accessToken });
+ * ```
+ *
  * Usage:
  * ```ts
  * import express from 'express';
@@ -51,6 +65,16 @@ export interface CreateAppOptions {
  * ```
  */
 export declare function createApp(options?: CreateAppOptions): Express;
+export type WebSocketEndpoint = ReturnType<typeof createWebSocketHandler>;
+/**
+ * Attach the PMXT streaming WebSocket endpoint to an HTTP server.
+ *
+ * Use this with servers built from `createApp()` when you need `/ws` support
+ * for watchOrderBook, watchOrderBooks, or watchTrades. The access token should
+ * match the one passed to `createApp()` so HTTP and WebSocket requests share
+ * the same local auth policy.
+ */
+export declare function attachWebSocketEndpoint(server: HttpServer, options?: CreateWebSocketHandlerOptions): WebSocketEndpoint;
 /**
  * Start the PMXT sidecar server on the given port with the built-in
  * access-token auth middleware enabled. Returns the underlying
@@ -59,6 +83,6 @@ export declare function createApp(options?: CreateAppOptions): Express;
  * Automatically attaches a WebSocket endpoint at `/ws` for streaming
  * methods (watchOrderBook, watchOrderBooks, watchTrades).
  */
-export declare function startServer(port: number, accessToken: string): Promise<import("node:http").Server<typeof import("node:http").IncomingMessage, typeof import("node:http").ServerResponse>>;
+export declare function startServer(port: number, accessToken: string): Promise<HttpServer<typeof import("node:http").IncomingMessage, typeof import("node:http").ServerResponse>>;
 export { createWebSocketHandler };
 export type { CreateWebSocketHandlerOptions };