pmxtjs 2.43.25 → 2.44.1

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

@@ -157,6 +157,14 @@ export declare abstract class Exchange {
      * never use the GET read path.
      */
     protected sidecarPostRequest(methodName: string, args: unknown[]): Promise<any>;
+    /**
+     * Read a hosted catalog endpoint directly.
+     *
+     * Hosted-only Router APIs such as matched clusters are not part of the
+     * core sidecar method namespace. They live under /v0 and return their own
+     * response envelopes, so callers intentionally receive the raw JSON body.
+     */
+    protected catalogReadRequest(path: string, query?: Record<string, unknown>): Promise<any>;
     loadMarkets(reload?: boolean): Promise<Record<string, UnifiedMarket>>;
     fetchMarkets(params?: MarketFetchParams): Promise<UnifiedMarket[]>;
     fetchMarketsPaginated(params?: any): Promise<PaginatedMarketsResult>;

package/dist/esm/pmxt/client.js

@@ -484,6 +484,29 @@ export class Exchange {
         }
         return response.json();
     }
+    /**
+     * Read a hosted catalog endpoint directly.
+     *
+     * Hosted-only Router APIs such as matched clusters are not part of the
+     * core sidecar method namespace. They live under /v0 and return their own
+     * response envelopes, so callers intentionally receive the raw JSON body.
+     */
+    async catalogReadRequest(path, query = {}) {
+        const qs = buildSidecarQueryString(query);
+        const url = `${this.resolveBaseUrl()}${path}${qs ? `?${qs}` : ''}`;
+        const response = await this.fetchWithRetry(url, {
+            method: 'GET',
+            headers: this.getAuthHeaders(),
+        });
+        if (!response.ok) {
+            const body = await response.json().catch(() => ({}));
+            if (body.error && typeof body.error === "object") {
+                throw fromServerError(body.error);
+            }
+            throw new PmxtError(body.error?.message || response.statusText);
+        }
+        return response.json();
+    }
     // BEGIN GENERATED METHODS
     async loadMarkets(reload = false) {
         await this.initPromise;

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

@@ -639,6 +639,96 @@ export interface EventMatchResult extends Readonly<UnifiedEvent> {
     /** Cross-venue market matches within this event. */
     marketMatches: MatchResult[];
 }
+export type MatchedClusterSort = 'volume' | 'confidence';
+/** Shared filters for matched market/event cluster discovery. */
+export interface MatchedClusterFilterParams {
+    /** Text search across cluster titles. */
+    query?: string;
+    /** Filter both sides of matched edges by category. */
+    category?: string;
+    /** Comma-separated relation filter. */
+    relations?: MatchRelation | MatchRelation[] | string;
+    /** Single relation filter. Alias for relations. */
+    relation?: MatchRelation;
+    /** Minimum match confidence score (0.0 to 1.0). */
+    minConfidence?: number;
+    /** Venue allow-list. */
+    venues?: string | string[];
+    /** Venue deny-list. */
+    excludeVenues?: string | string[];
+    /** Minimum number of venues required in a cluster. */
+    minVenues?: number;
+    /** Require live orderbook coverage on matched edges. */
+    withOrderbook?: boolean;
+    /** Only include matches updated after this timestamp. */
+    updatedSince?: string | Date;
+    /** Include the pairwise match edges used to build each cluster. */
+    includeRawMatches?: boolean;
+    /** Cluster sort order. */
+    sort?: MatchedClusterSort;
+    /** Maximum clusters to return. */
+    limit?: number;
+    /** Pagination offset. */
+    offset?: number;
+    /** Maximum pairwise edges to scan before clustering. */
+    edgeLimit?: number;
+}
+/** Parameters for fetching matched market clusters. */
+export interface FetchMatchedMarketClustersParams extends MatchedClusterFilterParams {
+    /** Pass a UnifiedMarket directly instead of marketId/slug/url. */
+    market?: UnifiedMarket;
+    /** Anchor the response to a specific market ID. */
+    marketId?: string;
+    /** Anchor the response to a specific market slug. */
+    slug?: string;
+    /** Anchor the response to a specific market URL. */
+    url?: string;
+}
+/** Parameters for fetching matched event clusters. */
+export interface FetchMatchedEventClustersParams extends MatchedClusterFilterParams {
+    /** Pass a UnifiedEvent directly instead of eventId/slug/url. */
+    event?: UnifiedEvent;
+    /** Anchor the response to a specific event ID. */
+    eventId?: string;
+    /** Anchor the response to a specific event slug. */
+    slug?: string;
+    /** Anchor the response to a specific event URL. */
+    url?: string;
+}
+/** Pairwise edge used to build a matched market cluster. */
+export interface MatchedMarketClusterEdge {
+    marketAId: string;
+    marketBId: string;
+    relation: MatchRelation;
+    confidence: number;
+}
+/** Pairwise edge used to build a matched event cluster. */
+export interface MatchedEventClusterEdge extends MatchedMarketClusterEdge {
+    eventAId: string;
+    eventBId: string;
+}
+/** Connected cluster of semantically matched markets across venues. */
+export interface MatchedMarketCluster {
+    clusterId: string;
+    canonicalTitle: string | null;
+    category?: string | null;
+    relations: MatchRelation[];
+    confidence: number;
+    volume24h: number;
+    markets: UnifiedMarket[];
+    rawMatches?: MatchedMarketClusterEdge[];
+}
+/** Connected cluster of semantically matched events across venues. */
+export interface MatchedEventCluster {
+    clusterId: string;
+    canonicalTitle: string | null;
+    category?: string | null;
+    relations: MatchRelation[];
+    confidence: number;
+    volume24h: number;
+    events: UnifiedEvent[];
+    rawMatches?: MatchedEventClusterEdge[];
+}
 /** Side-by-side price comparison for a matched market. */
 export interface PriceComparison {
     /** The matched market. */

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

@@ -5,7 +5,7 @@
  * every venue PMXT supports. Only requires a PMXT API key.
  */
 import { Exchange } from "./client.js";
-import { MatchResult, MatchRelation, EventMatchResult, PriceComparison, ArbitrageOpportunity, UnifiedMarket, UnifiedEvent } from "./models.js";
+import { MatchResult, MatchRelation, EventMatchResult, FetchMatchedEventClustersParams, FetchMatchedMarketClustersParams, MatchedEventCluster, MatchedMarketCluster, PriceComparison, ArbitrageOpportunity, UnifiedMarket, UnifiedEvent } from "./models.js";
 /** Options for creating a Router. */
 export interface RouterOptions {
     /** PMXT API key (required for hosted mode). */
@@ -78,6 +78,20 @@ export declare class Router extends Exchange {
         limit?: number;
         includePrices?: boolean;
     }): Promise<EventMatchResult[]>;
+    /**
+     * Fetch connected clusters of semantically matched markets across venues.
+     *
+     * @param marketOrParams - A UnifiedMarket, or an options object.
+     */
+    fetchMatchedMarketClusters(market: UnifiedMarket): Promise<MatchedMarketCluster[]>;
+    fetchMatchedMarketClusters(params?: FetchMatchedMarketClustersParams): Promise<MatchedMarketCluster[]>;
+    /**
+     * Fetch connected clusters of semantically matched events across venues.
+     *
+     * @param eventOrParams - A UnifiedEvent, or an options object.
+     */
+    fetchMatchedEventClusters(event: UnifiedEvent): Promise<MatchedEventCluster[]>;
+    fetchMatchedEventClusters(params?: FetchMatchedEventClustersParams): Promise<MatchedEventCluster[]>;
     /**
      * Compare prices for the same market across venues.
      *

package/dist/esm/pmxt/router.js

@@ -13,6 +13,8 @@ function convertMarket(raw) {
         label: o.label,
         price: o.price,
         priceChange24h: o.priceChange24h,
+        bestBid: o.bestBid,
+        bestAsk: o.bestAsk,
         metadata: o.metadata,
     }));
     const convertOutcome = (o) => o ? ({
@@ -21,6 +23,8 @@ function convertMarket(raw) {
         label: o.label,
         price: o.price,
         priceChange24h: o.priceChange24h,
+        bestBid: o.bestBid,
+        bestAsk: o.bestAsk,
         metadata: o.metadata,
     }) : undefined;
     return {
@@ -79,6 +83,58 @@ function parseMatchResult(raw) {
         sourceMarket: raw.sourceMarket ? convertMarket(raw.sourceMarket) : undefined,
     };
 }
+function normalizeQueryValue(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    return value;
+}
+function appendQuery(query, key, value) {
+    if (value !== undefined && value !== null && value !== '') {
+        query[key] = normalizeQueryValue(value);
+    }
+}
+function addClusterFilters(query, params) {
+    appendQuery(query, 'query', params.query);
+    appendQuery(query, 'category', params.category);
+    appendQuery(query, 'relations', params.relations);
+    appendQuery(query, 'relation', params.relation);
+    appendQuery(query, 'minConfidence', params.minConfidence);
+    appendQuery(query, 'venues', params.venues);
+    appendQuery(query, 'excludeVenues', params.excludeVenues);
+    appendQuery(query, 'minVenues', params.minVenues);
+    appendQuery(query, 'withOrderbook', params.withOrderbook);
+    appendQuery(query, 'updatedSince', params.updatedSince);
+    appendQuery(query, 'includeRawMatches', params.includeRawMatches);
+    appendQuery(query, 'sort', params.sort);
+    appendQuery(query, 'limit', params.limit);
+    appendQuery(query, 'offset', params.offset);
+    appendQuery(query, 'edgeLimit', params.edgeLimit);
+}
+function extractCatalogArray(raw) {
+    if (Array.isArray(raw))
+        return raw;
+    if (Array.isArray(raw?.data))
+        return raw.data;
+    return [];
+}
+function isUnifiedMarket(value) {
+    return Boolean(value && 'marketId' in value && 'title' in value);
+}
+function isUnifiedEvent(value) {
+    return Boolean(value && 'id' in value && 'title' in value && 'markets' in value);
+}
+function parseMatchedMarketCluster(raw) {
+    return {
+        ...raw,
+        markets: (raw.markets || []).map(convertMarket),
+    };
+}
+function parseMatchedEventCluster(raw) {
+    return {
+        ...raw,
+        events: (raw.events || []).map(convertEvent),
+    };
+}
 /**
  * Cross-venue intelligence layer.
  *
@@ -172,6 +228,52 @@ export class Router extends Exchange {
             throw new Error(`Failed to fetchEventMatches: ${error}`);
         }
     }
+    async fetchMatchedMarketClusters(marketOrParams = {}) {
+        const params = isUnifiedMarket(marketOrParams)
+            ? { market: marketOrParams }
+            : marketOrParams;
+        await this.initPromise;
+        const query = {};
+        const marketId = params.marketId ?? params.market?.marketId;
+        const slug = params.slug ?? (!marketId ? params.market?.slug : undefined);
+        const url = params.url ?? (!marketId && !slug ? params.market?.url : undefined);
+        appendQuery(query, 'marketId', marketId);
+        appendQuery(query, 'slug', slug);
+        appendQuery(query, 'url', url);
+        addClusterFilters(query, params);
+        try {
+            const raw = await this.catalogReadRequest('/v0/matched-market-clusters', query);
+            return extractCatalogArray(raw).map(parseMatchedMarketCluster);
+        }
+        catch (error) {
+            if (error instanceof Error)
+                throw error;
+            throw new Error(`Failed to fetchMatchedMarketClusters: ${error}`);
+        }
+    }
+    async fetchMatchedEventClusters(eventOrParams = {}) {
+        const params = isUnifiedEvent(eventOrParams)
+            ? { event: eventOrParams }
+            : eventOrParams;
+        await this.initPromise;
+        const query = {};
+        const eventId = params.eventId ?? params.event?.id;
+        const slug = params.slug ?? (!eventId ? params.event?.slug : undefined);
+        const url = params.url ?? (!eventId && !slug ? params.event?.url : undefined);
+        appendQuery(query, 'eventId', eventId);
+        appendQuery(query, 'slug', slug);
+        appendQuery(query, 'url', url);
+        addClusterFilters(query, params);
+        try {
+            const raw = await this.catalogReadRequest('/v0/matched-event-clusters', query);
+            return extractCatalogArray(raw).map(parseMatchedEventCluster);
+        }
+        catch (error) {
+            if (error instanceof Error)
+                throw error;
+            throw new Error(`Failed to fetchMatchedEventClusters: ${error}`);
+        }
+    }
     async compareMarketPrices(marketOrParams = {}) {
         const params = 'title' in marketOrParams ? { market: marketOrParams } : marketOrParams;
         await this.initPromise;

package/dist/pmxt/client.d.ts

@@ -157,6 +157,14 @@ export declare abstract class Exchange {
      * never use the GET read path.
      */
     protected sidecarPostRequest(methodName: string, args: unknown[]): Promise<any>;
+    /**
+     * Read a hosted catalog endpoint directly.
+     *
+     * Hosted-only Router APIs such as matched clusters are not part of the
+     * core sidecar method namespace. They live under /v0 and return their own
+     * response envelopes, so callers intentionally receive the raw JSON body.
+     */
+    protected catalogReadRequest(path: string, query?: Record<string, unknown>): Promise<any>;
     loadMarkets(reload?: boolean): Promise<Record<string, UnifiedMarket>>;
     fetchMarkets(params?: MarketFetchParams): Promise<UnifiedMarket[]>;
     fetchMarketsPaginated(params?: any): Promise<PaginatedMarketsResult>;

package/dist/pmxt/client.js

@@ -487,6 +487,29 @@ class Exchange {
         }
         return response.json();
     }
+    /**
+     * Read a hosted catalog endpoint directly.
+     *
+     * Hosted-only Router APIs such as matched clusters are not part of the
+     * core sidecar method namespace. They live under /v0 and return their own
+     * response envelopes, so callers intentionally receive the raw JSON body.
+     */
+    async catalogReadRequest(path, query = {}) {
+        const qs = buildSidecarQueryString(query);
+        const url = `${this.resolveBaseUrl()}${path}${qs ? `?${qs}` : ''}`;
+        const response = await this.fetchWithRetry(url, {
+            method: 'GET',
+            headers: this.getAuthHeaders(),
+        });
+        if (!response.ok) {
+            const body = await response.json().catch(() => ({}));
+            if (body.error && typeof body.error === "object") {
+                throw (0, errors_js_1.fromServerError)(body.error);
+            }
+            throw new errors_js_1.PmxtError(body.error?.message || response.statusText);
+        }
+        return response.json();
+    }
     // BEGIN GENERATED METHODS
     async loadMarkets(reload = false) {
         await this.initPromise;

package/dist/pmxt/models.d.ts

@@ -639,6 +639,96 @@ export interface EventMatchResult extends Readonly<UnifiedEvent> {
     /** Cross-venue market matches within this event. */
     marketMatches: MatchResult[];
 }
+export type MatchedClusterSort = 'volume' | 'confidence';
+/** Shared filters for matched market/event cluster discovery. */
+export interface MatchedClusterFilterParams {
+    /** Text search across cluster titles. */
+    query?: string;
+    /** Filter both sides of matched edges by category. */
+    category?: string;
+    /** Comma-separated relation filter. */
+    relations?: MatchRelation | MatchRelation[] | string;
+    /** Single relation filter. Alias for relations. */
+    relation?: MatchRelation;
+    /** Minimum match confidence score (0.0 to 1.0). */
+    minConfidence?: number;
+    /** Venue allow-list. */
+    venues?: string | string[];
+    /** Venue deny-list. */
+    excludeVenues?: string | string[];
+    /** Minimum number of venues required in a cluster. */
+    minVenues?: number;
+    /** Require live orderbook coverage on matched edges. */
+    withOrderbook?: boolean;
+    /** Only include matches updated after this timestamp. */
+    updatedSince?: string | Date;
+    /** Include the pairwise match edges used to build each cluster. */
+    includeRawMatches?: boolean;
+    /** Cluster sort order. */
+    sort?: MatchedClusterSort;
+    /** Maximum clusters to return. */
+    limit?: number;
+    /** Pagination offset. */
+    offset?: number;
+    /** Maximum pairwise edges to scan before clustering. */
+    edgeLimit?: number;
+}
+/** Parameters for fetching matched market clusters. */
+export interface FetchMatchedMarketClustersParams extends MatchedClusterFilterParams {
+    /** Pass a UnifiedMarket directly instead of marketId/slug/url. */
+    market?: UnifiedMarket;
+    /** Anchor the response to a specific market ID. */
+    marketId?: string;
+    /** Anchor the response to a specific market slug. */
+    slug?: string;
+    /** Anchor the response to a specific market URL. */
+    url?: string;
+}
+/** Parameters for fetching matched event clusters. */
+export interface FetchMatchedEventClustersParams extends MatchedClusterFilterParams {
+    /** Pass a UnifiedEvent directly instead of eventId/slug/url. */
+    event?: UnifiedEvent;
+    /** Anchor the response to a specific event ID. */
+    eventId?: string;
+    /** Anchor the response to a specific event slug. */
+    slug?: string;
+    /** Anchor the response to a specific event URL. */
+    url?: string;
+}
+/** Pairwise edge used to build a matched market cluster. */
+export interface MatchedMarketClusterEdge {
+    marketAId: string;
+    marketBId: string;
+    relation: MatchRelation;
+    confidence: number;
+}
+/** Pairwise edge used to build a matched event cluster. */
+export interface MatchedEventClusterEdge extends MatchedMarketClusterEdge {
+    eventAId: string;
+    eventBId: string;
+}
+/** Connected cluster of semantically matched markets across venues. */
+export interface MatchedMarketCluster {
+    clusterId: string;
+    canonicalTitle: string | null;
+    category?: string | null;
+    relations: MatchRelation[];
+    confidence: number;
+    volume24h: number;
+    markets: UnifiedMarket[];
+    rawMatches?: MatchedMarketClusterEdge[];
+}
+/** Connected cluster of semantically matched events across venues. */
+export interface MatchedEventCluster {
+    clusterId: string;
+    canonicalTitle: string | null;
+    category?: string | null;
+    relations: MatchRelation[];
+    confidence: number;
+    volume24h: number;
+    events: UnifiedEvent[];
+    rawMatches?: MatchedEventClusterEdge[];
+}
 /** Side-by-side price comparison for a matched market. */
 export interface PriceComparison {
     /** The matched market. */

package/dist/pmxt/router.d.ts

@@ -5,7 +5,7 @@
  * every venue PMXT supports. Only requires a PMXT API key.
  */
 import { Exchange } from "./client.js";
-import { MatchResult, MatchRelation, EventMatchResult, PriceComparison, ArbitrageOpportunity, UnifiedMarket, UnifiedEvent } from "./models.js";
+import { MatchResult, MatchRelation, EventMatchResult, FetchMatchedEventClustersParams, FetchMatchedMarketClustersParams, MatchedEventCluster, MatchedMarketCluster, PriceComparison, ArbitrageOpportunity, UnifiedMarket, UnifiedEvent } from "./models.js";
 /** Options for creating a Router. */
 export interface RouterOptions {
     /** PMXT API key (required for hosted mode). */
@@ -78,6 +78,20 @@ export declare class Router extends Exchange {
         limit?: number;
         includePrices?: boolean;
     }): Promise<EventMatchResult[]>;
+    /**
+     * Fetch connected clusters of semantically matched markets across venues.
+     *
+     * @param marketOrParams - A UnifiedMarket, or an options object.
+     */
+    fetchMatchedMarketClusters(market: UnifiedMarket): Promise<MatchedMarketCluster[]>;
+    fetchMatchedMarketClusters(params?: FetchMatchedMarketClustersParams): Promise<MatchedMarketCluster[]>;
+    /**
+     * Fetch connected clusters of semantically matched events across venues.
+     *
+     * @param eventOrParams - A UnifiedEvent, or an options object.
+     */
+    fetchMatchedEventClusters(event: UnifiedEvent): Promise<MatchedEventCluster[]>;
+    fetchMatchedEventClusters(params?: FetchMatchedEventClustersParams): Promise<MatchedEventCluster[]>;
     /**
      * Compare prices for the same market across venues.
      *

package/dist/pmxt/router.js

@@ -49,6 +49,8 @@ function convertMarket(raw) {
         label: o.label,
         price: o.price,
         priceChange24h: o.priceChange24h,
+        bestBid: o.bestBid,
+        bestAsk: o.bestAsk,
         metadata: o.metadata,
     }));
     const convertOutcome = (o) => o ? ({
@@ -57,6 +59,8 @@ function convertMarket(raw) {
         label: o.label,
         price: o.price,
         priceChange24h: o.priceChange24h,
+        bestBid: o.bestBid,
+        bestAsk: o.bestAsk,
         metadata: o.metadata,
     }) : undefined;
     return {
@@ -115,6 +119,58 @@ function parseMatchResult(raw) {
         sourceMarket: raw.sourceMarket ? convertMarket(raw.sourceMarket) : undefined,
     };
 }
+function normalizeQueryValue(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    return value;
+}
+function appendQuery(query, key, value) {
+    if (value !== undefined && value !== null && value !== '') {
+        query[key] = normalizeQueryValue(value);
+    }
+}
+function addClusterFilters(query, params) {
+    appendQuery(query, 'query', params.query);
+    appendQuery(query, 'category', params.category);
+    appendQuery(query, 'relations', params.relations);
+    appendQuery(query, 'relation', params.relation);
+    appendQuery(query, 'minConfidence', params.minConfidence);
+    appendQuery(query, 'venues', params.venues);
+    appendQuery(query, 'excludeVenues', params.excludeVenues);
+    appendQuery(query, 'minVenues', params.minVenues);
+    appendQuery(query, 'withOrderbook', params.withOrderbook);
+    appendQuery(query, 'updatedSince', params.updatedSince);
+    appendQuery(query, 'includeRawMatches', params.includeRawMatches);
+    appendQuery(query, 'sort', params.sort);
+    appendQuery(query, 'limit', params.limit);
+    appendQuery(query, 'offset', params.offset);
+    appendQuery(query, 'edgeLimit', params.edgeLimit);
+}
+function extractCatalogArray(raw) {
+    if (Array.isArray(raw))
+        return raw;
+    if (Array.isArray(raw?.data))
+        return raw.data;
+    return [];
+}
+function isUnifiedMarket(value) {
+    return Boolean(value && 'marketId' in value && 'title' in value);
+}
+function isUnifiedEvent(value) {
+    return Boolean(value && 'id' in value && 'title' in value && 'markets' in value);
+}
+function parseMatchedMarketCluster(raw) {
+    return {
+        ...raw,
+        markets: (raw.markets || []).map(convertMarket),
+    };
+}
+function parseMatchedEventCluster(raw) {
+    return {
+        ...raw,
+        events: (raw.events || []).map(convertEvent),
+    };
+}
 /**
  * Cross-venue intelligence layer.
  *
@@ -208,6 +264,52 @@ class Router extends client_js_1.Exchange {
             throw new Error(`Failed to fetchEventMatches: ${error}`);
         }
     }
+    async fetchMatchedMarketClusters(marketOrParams = {}) {
+        const params = isUnifiedMarket(marketOrParams)
+            ? { market: marketOrParams }
+            : marketOrParams;
+        await this.initPromise;
+        const query = {};
+        const marketId = params.marketId ?? params.market?.marketId;
+        const slug = params.slug ?? (!marketId ? params.market?.slug : undefined);
+        const url = params.url ?? (!marketId && !slug ? params.market?.url : undefined);
+        appendQuery(query, 'marketId', marketId);
+        appendQuery(query, 'slug', slug);
+        appendQuery(query, 'url', url);
+        addClusterFilters(query, params);
+        try {
+            const raw = await this.catalogReadRequest('/v0/matched-market-clusters', query);
+            return extractCatalogArray(raw).map(parseMatchedMarketCluster);
+        }
+        catch (error) {
+            if (error instanceof Error)
+                throw error;
+            throw new Error(`Failed to fetchMatchedMarketClusters: ${error}`);
+        }
+    }
+    async fetchMatchedEventClusters(eventOrParams = {}) {
+        const params = isUnifiedEvent(eventOrParams)
+            ? { event: eventOrParams }
+            : eventOrParams;
+        await this.initPromise;
+        const query = {};
+        const eventId = params.eventId ?? params.event?.id;
+        const slug = params.slug ?? (!eventId ? params.event?.slug : undefined);
+        const url = params.url ?? (!eventId && !slug ? params.event?.url : undefined);
+        appendQuery(query, 'eventId', eventId);
+        appendQuery(query, 'slug', slug);
+        appendQuery(query, 'url', url);
+        addClusterFilters(query, params);
+        try {
+            const raw = await this.catalogReadRequest('/v0/matched-event-clusters', query);
+            return extractCatalogArray(raw).map(parseMatchedEventCluster);
+        }
+        catch (error) {
+            if (error instanceof Error)
+                throw error;
+            throw new Error(`Failed to fetchMatchedEventClusters: ${error}`);
+        }
+    }
     async compareMarketPrices(marketOrParams = {}) {
         const params = 'title' in marketOrParams ? { market: marketOrParams } : marketOrParams;
         await this.initPromise;

package/generated/package.json

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

package/package.json

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

package/pmxt/client.ts

@@ -632,6 +632,30 @@ export abstract class Exchange {
         return response.json();
     }
 
+    /**
+     * Read a hosted catalog endpoint directly.
+     *
+     * Hosted-only Router APIs such as matched clusters are not part of the
+     * core sidecar method namespace. They live under /v0 and return their own
+     * response envelopes, so callers intentionally receive the raw JSON body.
+     */
+    protected async catalogReadRequest(path: string, query: Record<string, unknown> = {}): Promise<any> {
+        const qs = buildSidecarQueryString(query);
+        const url = `${this.resolveBaseUrl()}${path}${qs ? `?${qs}` : ''}`;
+        const response = await this.fetchWithRetry(url, {
+            method: 'GET',
+            headers: this.getAuthHeaders(),
+        });
+        if (!response.ok) {
+            const body = await response.json().catch(() => ({}));
+            if (body.error && typeof body.error === "object") {
+                throw fromServerError(body.error);
+            }
+            throw new PmxtError(body.error?.message || response.statusText);
+        }
+        return response.json();
+    }
+
     // BEGIN GENERATED METHODS
 
     async loadMarkets(reload: boolean = false): Promise<Record<string, UnifiedMarket>> {

package/pmxt/models.ts

@@ -861,6 +861,124 @@ export interface EventMatchResult extends Readonly<UnifiedEvent> {
     marketMatches: MatchResult[];
 }
 
+export type MatchedClusterSort = 'volume' | 'confidence';
+
+/** Shared filters for matched market/event cluster discovery. */
+export interface MatchedClusterFilterParams {
+    /** Text search across cluster titles. */
+    query?: string;
+
+    /** Filter both sides of matched edges by category. */
+    category?: string;
+
+    /** Comma-separated relation filter. */
+    relations?: MatchRelation | MatchRelation[] | string;
+
+    /** Single relation filter. Alias for relations. */
+    relation?: MatchRelation;
+
+    /** Minimum match confidence score (0.0 to 1.0). */
+    minConfidence?: number;
+
+    /** Venue allow-list. */
+    venues?: string | string[];
+
+    /** Venue deny-list. */
+    excludeVenues?: string | string[];
+
+    /** Minimum number of venues required in a cluster. */
+    minVenues?: number;
+
+    /** Require live orderbook coverage on matched edges. */
+    withOrderbook?: boolean;
+
+    /** Only include matches updated after this timestamp. */
+    updatedSince?: string | Date;
+
+    /** Include the pairwise match edges used to build each cluster. */
+    includeRawMatches?: boolean;
+
+    /** Cluster sort order. */
+    sort?: MatchedClusterSort;
+
+    /** Maximum clusters to return. */
+    limit?: number;
+
+    /** Pagination offset. */
+    offset?: number;
+
+    /** Maximum pairwise edges to scan before clustering. */
+    edgeLimit?: number;
+}
+
+/** Parameters for fetching matched market clusters. */
+export interface FetchMatchedMarketClustersParams extends MatchedClusterFilterParams {
+    /** Pass a UnifiedMarket directly instead of marketId/slug/url. */
+    market?: UnifiedMarket;
+
+    /** Anchor the response to a specific market ID. */
+    marketId?: string;
+
+    /** Anchor the response to a specific market slug. */
+    slug?: string;
+
+    /** Anchor the response to a specific market URL. */
+    url?: string;
+}
+
+/** Parameters for fetching matched event clusters. */
+export interface FetchMatchedEventClustersParams extends MatchedClusterFilterParams {
+    /** Pass a UnifiedEvent directly instead of eventId/slug/url. */
+    event?: UnifiedEvent;
+
+    /** Anchor the response to a specific event ID. */
+    eventId?: string;
+
+    /** Anchor the response to a specific event slug. */
+    slug?: string;
+
+    /** Anchor the response to a specific event URL. */
+    url?: string;
+}
+
+/** Pairwise edge used to build a matched market cluster. */
+export interface MatchedMarketClusterEdge {
+    marketAId: string;
+    marketBId: string;
+    relation: MatchRelation;
+    confidence: number;
+}
+
+/** Pairwise edge used to build a matched event cluster. */
+export interface MatchedEventClusterEdge extends MatchedMarketClusterEdge {
+    eventAId: string;
+    eventBId: string;
+}
+
+/** Connected cluster of semantically matched markets across venues. */
+export interface MatchedMarketCluster {
+    clusterId: string;
+    canonicalTitle: string | null;
+    category?: string | null;
+    relations: MatchRelation[];
+    confidence: number;
+    volume24h: number;
+    markets: UnifiedMarket[];
+    rawMatches?: MatchedMarketClusterEdge[];
+}
+
+/** Connected cluster of semantically matched events across venues. */
+export interface MatchedEventCluster {
+    clusterId: string;
+    canonicalTitle: string | null;
+    category?: string | null;
+    relations: MatchRelation[];
+    confidence: number;
+    volume24h: number;
+    events: UnifiedEvent[];
+    rawMatches?: MatchedEventClusterEdge[];
+}
+
 /** Side-by-side price comparison for a matched market. */
 export interface PriceComparison {
     /** The matched market. */

package/pmxt/router.ts

@@ -11,6 +11,10 @@ import {
     MatchResult,
     MatchRelation,
     EventMatchResult,
+    FetchMatchedEventClustersParams,
+    FetchMatchedMarketClustersParams,
+    MatchedEventCluster,
+    MatchedMarketCluster,
     PriceComparison,
     ArbitrageOpportunity,
     UnifiedMarket,
@@ -24,6 +28,8 @@ function convertMarket(raw: any): UnifiedMarket {
         label: o.label,
         price: o.price,
         priceChange24h: o.priceChange24h,
+        bestBid: o.bestBid,
+        bestAsk: o.bestAsk,
         metadata: o.metadata,
     }));
 
@@ -33,6 +39,8 @@ function convertMarket(raw: any): UnifiedMarket {
         label: o.label,
         price: o.price,
         priceChange24h: o.priceChange24h,
+        bestBid: o.bestBid,
+        bestAsk: o.bestAsk,
         metadata: o.metadata,
     }) : undefined;
 
@@ -95,6 +103,79 @@ function parseMatchResult(raw: any): MatchResult {
     };
 }
 
+function normalizeQueryValue(value: unknown): unknown {
+    if (value instanceof Date) return value.toISOString();
+    return value;
+}
+
+function appendQuery(query: Record<string, unknown>, key: string, value: unknown): void {
+    if (value !== undefined && value !== null && value !== '') {
+        query[key] = normalizeQueryValue(value);
+    }
+}
+
+function addClusterFilters(query: Record<string, unknown>, params: {
+    query?: string;
+    category?: string;
+    relations?: MatchRelation | MatchRelation[] | string;
+    relation?: MatchRelation;
+    minConfidence?: number;
+    venues?: string | string[];
+    excludeVenues?: string | string[];
+    minVenues?: number;
+    withOrderbook?: boolean;
+    updatedSince?: string | Date;
+    includeRawMatches?: boolean;
+    sort?: string;
+    limit?: number;
+    offset?: number;
+    edgeLimit?: number;
+}): void {
+    appendQuery(query, 'query', params.query);
+    appendQuery(query, 'category', params.category);
+    appendQuery(query, 'relations', params.relations);
+    appendQuery(query, 'relation', params.relation);
+    appendQuery(query, 'minConfidence', params.minConfidence);
+    appendQuery(query, 'venues', params.venues);
+    appendQuery(query, 'excludeVenues', params.excludeVenues);
+    appendQuery(query, 'minVenues', params.minVenues);
+    appendQuery(query, 'withOrderbook', params.withOrderbook);
+    appendQuery(query, 'updatedSince', params.updatedSince);
+    appendQuery(query, 'includeRawMatches', params.includeRawMatches);
+    appendQuery(query, 'sort', params.sort);
+    appendQuery(query, 'limit', params.limit);
+    appendQuery(query, 'offset', params.offset);
+    appendQuery(query, 'edgeLimit', params.edgeLimit);
+}
+
+function extractCatalogArray(raw: any): any[] {
+    if (Array.isArray(raw)) return raw;
+    if (Array.isArray(raw?.data)) return raw.data;
+    return [];
+}
+
+function isUnifiedMarket(value: UnifiedMarket | FetchMatchedMarketClustersParams): value is UnifiedMarket {
+    return Boolean(value && 'marketId' in value && 'title' in value);
+}
+
+function isUnifiedEvent(value: UnifiedEvent | FetchMatchedEventClustersParams): value is UnifiedEvent {
+    return Boolean(value && 'id' in value && 'title' in value && 'markets' in value);
+}
+
+function parseMatchedMarketCluster(raw: any): MatchedMarketCluster {
+    return {
+        ...raw,
+        markets: (raw.markets || []).map(convertMarket),
+    };
+}
+
+function parseMatchedEventCluster(raw: any): MatchedEventCluster {
+    return {
+        ...raw,
+        events: (raw.events || []).map(convertEvent),
+    };
+}
+
 /** Options for creating a Router. */
 export interface RouterOptions {
     /** PMXT API key (required for hosted mode). */
@@ -262,6 +343,72 @@ export class Router extends Exchange {
         }
     }
 
+    /**
+     * Fetch connected clusters of semantically matched markets across venues.
+     *
+     * @param marketOrParams - A UnifiedMarket, or an options object.
+     */
+    async fetchMatchedMarketClusters(market: UnifiedMarket): Promise<MatchedMarketCluster[]>;
+    async fetchMatchedMarketClusters(params?: FetchMatchedMarketClustersParams): Promise<MatchedMarketCluster[]>;
+    async fetchMatchedMarketClusters(
+        marketOrParams: UnifiedMarket | FetchMatchedMarketClustersParams = {},
+    ): Promise<MatchedMarketCluster[]> {
+        const params: FetchMatchedMarketClustersParams = isUnifiedMarket(marketOrParams)
+            ? { market: marketOrParams }
+            : marketOrParams;
+        await this.initPromise;
+
+        const query: Record<string, unknown> = {};
+        const marketId = params.marketId ?? params.market?.marketId;
+        const slug = params.slug ?? (!marketId ? params.market?.slug : undefined);
+        const url = params.url ?? (!marketId && !slug ? params.market?.url : undefined);
+        appendQuery(query, 'marketId', marketId);
+        appendQuery(query, 'slug', slug);
+        appendQuery(query, 'url', url);
+        addClusterFilters(query, params);
+
+        try {
+            const raw = await this.catalogReadRequest('/v0/matched-market-clusters', query);
+            return extractCatalogArray(raw).map(parseMatchedMarketCluster);
+        } catch (error) {
+            if (error instanceof Error) throw error;
+            throw new Error(`Failed to fetchMatchedMarketClusters: ${error}`);
+        }
+    }
+
+    /**
+     * Fetch connected clusters of semantically matched events across venues.
+     *
+     * @param eventOrParams - A UnifiedEvent, or an options object.
+     */
+    async fetchMatchedEventClusters(event: UnifiedEvent): Promise<MatchedEventCluster[]>;
+    async fetchMatchedEventClusters(params?: FetchMatchedEventClustersParams): Promise<MatchedEventCluster[]>;
+    async fetchMatchedEventClusters(
+        eventOrParams: UnifiedEvent | FetchMatchedEventClustersParams = {},
+    ): Promise<MatchedEventCluster[]> {
+        const params: FetchMatchedEventClustersParams = isUnifiedEvent(eventOrParams)
+            ? { event: eventOrParams }
+            : eventOrParams;
+        await this.initPromise;
+
+        const query: Record<string, unknown> = {};
+        const eventId = params.eventId ?? params.event?.id;
+        const slug = params.slug ?? (!eventId ? params.event?.slug : undefined);
+        const url = params.url ?? (!eventId && !slug ? params.event?.url : undefined);
+        appendQuery(query, 'eventId', eventId);
+        appendQuery(query, 'slug', slug);
+        appendQuery(query, 'url', url);
+        addClusterFilters(query, params);
+
+        try {
+            const raw = await this.catalogReadRequest('/v0/matched-event-clusters', query);
+            return extractCatalogArray(raw).map(parseMatchedEventCluster);
+        } catch (error) {
+            if (error instanceof Error) throw error;
+            throw new Error(`Failed to fetchMatchedEventClusters: ${error}`);
+        }
+    }
+
     // ------------------------------------------------------------------
     // Price comparison
     // ------------------------------------------------------------------