pmxtjs 2.33.4 → 2.34.0

package/dist/pmxt/models.d.ts

@@ -62,6 +62,8 @@ export interface UnifiedMarket {
     status?: string;
     /** On-chain contract / condition identifier where applicable (Polymarket conditionId, etc.). */
     contractAddress?: string;
+    /** The exchange/venue this market originates from (e.g. 'polymarket', 'kalshi'). Populated by the Router. */
+    sourceExchange?: string;
     /** ID of the parent event this market belongs to */
     eventId?: string;
     /** Convenience access to the Yes outcome for binary markets. */
@@ -375,6 +377,8 @@ export interface UnifiedEvent {
     category?: string;
     /** Event tags */
     tags?: string[];
+    /** The exchange/venue this event originates from (e.g. 'polymarket', 'kalshi'). Populated by the Router. */
+    sourceExchange?: string;
 }
 /**
  * Advanced criteria for filtering markets.
@@ -483,3 +487,65 @@ export interface SubscribedAddressSnapshot {
     /** Unix timestamp (ms) of this snapshot */
     timestamp: number;
 }
+/** Set-theoretic relation between two markets' resolution conditions. */
+export type MatchRelation = 'identity' | 'subset' | 'superset' | 'overlap' | 'disjoint';
+/** A cross-venue market match with relation classification. */
+export interface MatchResult {
+    /** The matched market on another venue. */
+    market: UnifiedMarket;
+    /** Set-theoretic relation between the source and matched market. */
+    relation: MatchRelation;
+    /** Confidence score (0.0 to 1.0). */
+    confidence: number;
+    /** Human-readable explanation of the match. */
+    reasoning?: string;
+    /** Best bid price on the matched venue (when includePrices=true). */
+    bestBid?: number;
+    /** Best ask price on the matched venue (when includePrices=true). */
+    bestAsk?: number;
+}
+/** A cross-venue event match with constituent market matches. */
+export interface EventMatchResult {
+    /** The matched event on another venue. */
+    event: UnifiedEvent;
+    /** Cross-venue market matches within this event. */
+    marketMatches: MatchResult[];
+}
+/** Side-by-side price comparison for a matched market. */
+export interface PriceComparison {
+    /** The matched market. */
+    market: UnifiedMarket;
+    /** Relation type (typically 'identity' for price comparisons). */
+    relation: MatchRelation;
+    /** Confidence score (0.0 to 1.0). */
+    confidence: number;
+    /** Human-readable explanation. */
+    reasoning?: string;
+    /** Best bid price on this venue. */
+    bestBid?: number;
+    /** Best ask price on this venue. */
+    bestAsk?: number;
+    /** The venue name (e.g. 'kalshi', 'polymarket'). */
+    venue: string;
+}
+/** A cross-venue arbitrage opportunity. */
+export interface ArbitrageOpportunity {
+    /** Market on the buy side. */
+    marketA: UnifiedMarket;
+    /** Market on the sell side. */
+    marketB: UnifiedMarket;
+    /** Price spread (sellPrice - buyPrice). */
+    spread: number;
+    /** Venue to buy on. */
+    buyVenue: string;
+    /** Venue to sell on. */
+    sellVenue: string;
+    /** Price to buy at. */
+    buyPrice: number;
+    /** Price to sell at. */
+    sellPrice: number;
+    /** The set-theoretic relation between the two markets (e.g. identity, subset). */
+    relation?: MatchRelation;
+    /** Match confidence score (0.0 to 1.0). */
+    confidence?: number;
+}

package/dist/pmxt/router.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Router — cross-venue intelligence layer.
+ *
+ * Search, match, compare prices, find hedges, and detect arbitrage across
+ * 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";
+/** Options for creating a Router. */
+export interface RouterOptions {
+    /** PMXT API key (required for hosted mode). */
+    pmxtApiKey?: string;
+    /** Override the base URL (defaults to hosted API). */
+    baseUrl?: string;
+    /** Start local sidecar (default: false). */
+    autoStartServer?: boolean;
+}
+/**
+ * Cross-venue intelligence layer.
+ *
+ * Search markets and events across every venue, find semantically
+ * equivalent markets on other platforms, compare prices, discover
+ * hedges, and scan for arbitrage — all from a single PMXT API key.
+ *
+ * @example
+ * ```typescript
+ * import pmxt from "pmxtjs";
+ *
+ * const router = new pmxt.Router({ pmxtApiKey: "pmxt_live_..." });
+ * const markets = await router.fetchMarkets({ query: "election" });
+ * const matches = await router.fetchMarketMatches({ market: markets[0] });
+ * ```
+ */
+export declare class Router extends Exchange {
+    constructor(options?: RouterOptions);
+    /**
+     * Find markets on other venues that correspond to a given market.
+     *
+     * @param params.market - A UnifiedMarket object (extracts marketId automatically).
+     * @param params.marketId - PMXT market ID.
+     * @param params.slug - Market slug (alternative to marketId).
+     * @param params.url - Market URL on the source venue.
+     * @param params.relation - Filter to a specific relation type.
+     * @param params.minConfidence - Minimum confidence threshold (0–1).
+     * @param params.limit - Maximum number of matches to return.
+     * @param params.includePrices - Attach live bestBid/bestAsk to each match.
+     */
+    fetchMarketMatches(params?: {
+        market?: UnifiedMarket;
+        marketId?: string;
+        slug?: string;
+        url?: string;
+        relation?: MatchRelation;
+        minConfidence?: number;
+        limit?: number;
+        includePrices?: boolean;
+    }): Promise<MatchResult[]>;
+    /**
+     * @deprecated Use {@link fetchMarketMatches} instead.
+     */
+    fetchMatches(params?: {
+        market?: UnifiedMarket;
+        marketId?: string;
+        slug?: string;
+        url?: string;
+        relation?: MatchRelation;
+        minConfidence?: number;
+        limit?: number;
+        includePrices?: boolean;
+    }): Promise<MatchResult[]>;
+    /**
+     * Match an entire event across venues.
+     *
+     * @param params.event - A UnifiedEvent object (extracts id automatically).
+     * @param params.eventId - PMXT event ID.
+     * @param params.slug - Event slug.
+     * @param params.relation - Filter market matches to a specific relation type.
+     * @param params.minConfidence - Minimum confidence threshold (0–1).
+     * @param params.limit - Maximum number of event matches to return.
+     * @param params.includePrices - Attach live prices to each market match.
+     */
+    fetchEventMatches(params?: {
+        event?: UnifiedEvent;
+        eventId?: string;
+        slug?: string;
+        relation?: MatchRelation;
+        minConfidence?: number;
+        limit?: number;
+        includePrices?: boolean;
+    }): Promise<EventMatchResult[]>;
+    /**
+     * Compare prices for the same market across venues.
+     *
+     * @param params.market - A UnifiedMarket object (extracts marketId automatically).
+     * @param params.marketId - PMXT market ID.
+     * @param params.slug - Market slug.
+     * @param params.url - Market URL.
+     */
+    compareMarketPrices(params?: {
+        market?: UnifiedMarket;
+        marketId?: string;
+        slug?: string;
+        url?: string;
+    }): Promise<PriceComparison[]>;
+    /**
+     * Find markets that partially hedge a position.
+     *
+     * @param params.market - A UnifiedMarket object (extracts marketId automatically).
+     * @param params.marketId - PMXT market ID.
+     * @param params.slug - Market slug.
+     * @param params.url - Market URL.
+     */
+    fetchHedges(params?: {
+        market?: UnifiedMarket;
+        marketId?: string;
+        slug?: string;
+        url?: string;
+    }): Promise<PriceComparison[]>;
+    /**
+     * Scan for cross-venue arbitrage opportunities.
+     *
+     * @param params.minSpread - Only return pairs with spread >= this value.
+     * @param params.category - Filter source markets by category.
+     * @param params.limit - Max source markets to scan (default: 50).
+     * @param params.relations - Relation types to include (default: ['identity']).
+     */
+    fetchArbitrage(params?: {
+        minSpread?: number;
+        category?: string;
+        limit?: number;
+        relations?: MatchRelation[];
+    }): Promise<ArbitrageOpportunity[]>;
+}

package/dist/pmxt/router.js

@@ -0,0 +1,375 @@
+"use strict";
+/**
+ * Router — cross-venue intelligence layer.
+ *
+ * Search, match, compare prices, find hedges, and detect arbitrage across
+ * every venue PMXT supports. Only requires a PMXT API key.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Router = void 0;
+const client_js_1 = require("./client.js");
+function convertMarket(raw) {
+    const outcomes = (raw.outcomes || []).map((o) => ({
+        outcomeId: o.outcomeId,
+        marketId: o.marketId,
+        label: o.label,
+        price: o.price,
+        priceChange24h: o.priceChange24h,
+        metadata: o.metadata,
+    }));
+    const convertOutcome = (o) => o ? ({
+        outcomeId: o.outcomeId,
+        marketId: o.marketId,
+        label: o.label,
+        price: o.price,
+        priceChange24h: o.priceChange24h,
+        metadata: o.metadata,
+    }) : undefined;
+    return {
+        marketId: raw.marketId,
+        title: raw.title,
+        slug: raw.slug,
+        outcomes,
+        volume24h: raw.volume24h || 0,
+        liquidity: raw.liquidity || 0,
+        url: raw.url,
+        description: raw.description,
+        resolutionDate: raw.resolutionDate ? new Date(raw.resolutionDate) : undefined,
+        volume: raw.volume,
+        openInterest: raw.openInterest,
+        image: raw.image,
+        category: raw.category,
+        tags: raw.tags,
+        tickSize: raw.tickSize,
+        status: raw.status,
+        contractAddress: raw.contractAddress,
+        sourceExchange: raw.sourceExchange,
+        eventId: raw.eventId,
+        yes: convertOutcome(raw.yes),
+        no: convertOutcome(raw.no),
+        up: convertOutcome(raw.up),
+        down: convertOutcome(raw.down),
+    };
+}
+function convertEvent(raw) {
+    return {
+        id: raw.id,
+        title: raw.title,
+        description: raw.description,
+        slug: raw.slug,
+        markets: (raw.markets || []).map(convertMarket),
+        volume24h: raw.volume24h,
+        volume: raw.volume,
+        url: raw.url,
+        image: raw.image,
+        category: raw.category,
+        tags: raw.tags,
+        sourceExchange: raw.sourceExchange,
+    };
+}
+function parseMatchResult(raw) {
+    const marketData = raw.market || {};
+    return {
+        market: convertMarket(marketData),
+        relation: raw.relation || 'identity',
+        confidence: raw.confidence || 0,
+        reasoning: raw.reasoning,
+        bestBid: raw.bestBid ?? marketData.bestBid,
+        bestAsk: raw.bestAsk ?? marketData.bestAsk,
+    };
+}
+/**
+ * Cross-venue intelligence layer.
+ *
+ * Search markets and events across every venue, find semantically
+ * equivalent markets on other platforms, compare prices, discover
+ * hedges, and scan for arbitrage — all from a single PMXT API key.
+ *
+ * @example
+ * ```typescript
+ * import pmxt from "pmxtjs";
+ *
+ * const router = new pmxt.Router({ pmxtApiKey: "pmxt_live_..." });
+ * const markets = await router.fetchMarkets({ query: "election" });
+ * const matches = await router.fetchMarketMatches({ market: markets[0] });
+ * ```
+ */
+class Router extends client_js_1.Exchange {
+    constructor(options = {}) {
+        super("router", options);
+    }
+    // ------------------------------------------------------------------
+    // Matching
+    // ------------------------------------------------------------------
+    /**
+     * Find markets on other venues that correspond to a given market.
+     *
+     * @param params.market - A UnifiedMarket object (extracts marketId automatically).
+     * @param params.marketId - PMXT market ID.
+     * @param params.slug - Market slug (alternative to marketId).
+     * @param params.url - Market URL on the source venue.
+     * @param params.relation - Filter to a specific relation type.
+     * @param params.minConfidence - Minimum confidence threshold (0–1).
+     * @param params.limit - Maximum number of matches to return.
+     * @param params.includePrices - Attach live bestBid/bestAsk to each match.
+     */
+    async fetchMarketMatches(params = {}) {
+        await this.initPromise;
+        const query = {};
+        const marketId = params.marketId ?? params.market?.marketId;
+        if (marketId)
+            query.marketId = marketId;
+        if (params.slug)
+            query.slug = params.slug;
+        if (params.url)
+            query.url = params.url;
+        if (params.relation)
+            query.relation = params.relation;
+        if (params.minConfidence !== undefined)
+            query.minConfidence = params.minConfidence;
+        if (params.limit !== undefined)
+            query.limit = params.limit;
+        if (params.includePrices)
+            query.includePrices = true;
+        try {
+            const json = await this.sidecarReadRequest('fetchMatches', query, [query]);
+            const data = this.handleResponse(json);
+            if (!data)
+                return [];
+            return data.map(parseMatchResult);
+        }
+        catch (error) {
+            if (error instanceof Error)
+                throw error;
+            throw new Error(`Failed to fetchMarketMatches: ${error}`);
+        }
+    }
+    /**
+     * @deprecated Use {@link fetchMarketMatches} instead.
+     */
+    async fetchMatches(params = {}) {
+        console.warn('[pmxt] fetchMatches is deprecated, use fetchMarketMatches instead');
+        return this.fetchMarketMatches(params);
+    }
+    /**
+     * Match an entire event across venues.
+     *
+     * @param params.event - A UnifiedEvent object (extracts id automatically).
+     * @param params.eventId - PMXT event ID.
+     * @param params.slug - Event slug.
+     * @param params.relation - Filter market matches to a specific relation type.
+     * @param params.minConfidence - Minimum confidence threshold (0–1).
+     * @param params.limit - Maximum number of event matches to return.
+     * @param params.includePrices - Attach live prices to each market match.
+     */
+    async fetchEventMatches(params = {}) {
+        await this.initPromise;
+        const query = {};
+        const eventId = params.eventId ?? params.event?.id;
+        if (eventId)
+            query.eventId = eventId;
+        if (params.slug)
+            query.slug = params.slug;
+        if (params.relation)
+            query.relation = params.relation;
+        if (params.minConfidence !== undefined)
+            query.minConfidence = params.minConfidence;
+        if (params.limit !== undefined)
+            query.limit = params.limit;
+        if (params.includePrices)
+            query.includePrices = true;
+        try {
+            const json = await this.sidecarReadRequest('fetchEventMatches', query, [query]);
+            const data = this.handleResponse(json);
+            if (!data)
+                return [];
+            return data.map((entry) => ({
+                event: convertEvent(entry.event || {}),
+                marketMatches: (entry.marketMatches || []).map(parseMatchResult),
+            }));
+        }
+        catch (error) {
+            if (error instanceof Error)
+                throw error;
+            throw new Error(`Failed to fetchEventMatches: ${error}`);
+        }
+    }
+    // ------------------------------------------------------------------
+    // Price comparison
+    // ------------------------------------------------------------------
+    /**
+     * Compare prices for the same market across venues.
+     *
+     * @param params.market - A UnifiedMarket object (extracts marketId automatically).
+     * @param params.marketId - PMXT market ID.
+     * @param params.slug - Market slug.
+     * @param params.url - Market URL.
+     */
+    async compareMarketPrices(params = {}) {
+        await this.initPromise;
+        const query = {};
+        const marketId = params.marketId ?? params.market?.marketId;
+        if (marketId)
+            query.marketId = marketId;
+        if (params.slug)
+            query.slug = params.slug;
+        if (params.url)
+            query.url = params.url;
+        try {
+            const url = `${this.config.basePath}/api/${this.exchangeName}/compareMarketPrices`;
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
+                body: JSON.stringify({ args: [query], credentials: this.getCredentials() }),
+            });
+            if (!response.ok) {
+                const body = await response.json().catch(() => ({}));
+                if (body.error && typeof body.error === 'object') {
+                    const { fromServerError } = await Promise.resolve().then(() => __importStar(require('./errors.js')));
+                    throw fromServerError(body.error);
+                }
+                throw new Error(body.error?.message || response.statusText);
+            }
+            const json = await response.json();
+            const data = this.handleResponse(json);
+            if (!data)
+                return [];
+            return data.map((r) => ({
+                market: convertMarket(r.market || {}),
+                relation: r.relation || 'identity',
+                confidence: r.confidence || 0,
+                reasoning: r.reasoning,
+                bestBid: r.bestBid,
+                bestAsk: r.bestAsk,
+                venue: r.venue || '',
+            }));
+        }
+        catch (error) {
+            if (error instanceof Error)
+                throw error;
+            throw new Error(`Failed to compareMarketPrices: ${error}`);
+        }
+    }
+    // ------------------------------------------------------------------
+    // Hedging
+    // ------------------------------------------------------------------
+    /**
+     * Find markets that partially hedge a position.
+     *
+     * @param params.market - A UnifiedMarket object (extracts marketId automatically).
+     * @param params.marketId - PMXT market ID.
+     * @param params.slug - Market slug.
+     * @param params.url - Market URL.
+     */
+    async fetchHedges(params = {}) {
+        await this.initPromise;
+        const query = {};
+        const marketId = params.marketId ?? params.market?.marketId;
+        if (marketId)
+            query.marketId = marketId;
+        if (params.slug)
+            query.slug = params.slug;
+        if (params.url)
+            query.url = params.url;
+        try {
+            const json = await this.sidecarReadRequest('fetchHedges', query, [query]);
+            const data = this.handleResponse(json);
+            if (!data)
+                return [];
+            return data.map((r) => ({
+                market: convertMarket(r.market || {}),
+                relation: r.relation || 'identity',
+                confidence: r.confidence || 0,
+                reasoning: r.reasoning,
+                bestBid: r.bestBid,
+                bestAsk: r.bestAsk,
+                venue: r.venue || '',
+            }));
+        }
+        catch (error) {
+            if (error instanceof Error)
+                throw error;
+            throw new Error(`Failed to fetchHedges: ${error}`);
+        }
+    }
+    // ------------------------------------------------------------------
+    // Arbitrage
+    // ------------------------------------------------------------------
+    /**
+     * Scan for cross-venue arbitrage opportunities.
+     *
+     * @param params.minSpread - Only return pairs with spread >= this value.
+     * @param params.category - Filter source markets by category.
+     * @param params.limit - Max source markets to scan (default: 50).
+     * @param params.relations - Relation types to include (default: ['identity']).
+     */
+    async fetchArbitrage(params = {}) {
+        await this.initPromise;
+        const query = {};
+        if (params.minSpread !== undefined)
+            query.minSpread = params.minSpread;
+        if (params.category)
+            query.category = params.category;
+        if (params.limit !== undefined)
+            query.limit = params.limit;
+        if (params.relations && params.relations.length > 0) {
+            query.relations = params.relations.join(',');
+        }
+        try {
+            const json = await this.sidecarReadRequest('fetchArbitrage', query, [query]);
+            const data = this.handleResponse(json);
+            if (!data)
+                return [];
+            return data.map((r) => ({
+                marketA: convertMarket(r.marketA || {}),
+                marketB: convertMarket(r.marketB || {}),
+                spread: r.spread || 0,
+                buyVenue: r.buyVenue || '',
+                sellVenue: r.sellVenue || '',
+                buyPrice: r.buyPrice || 0,
+                sellPrice: r.sellPrice || 0,
+                relation: r.relation,
+                confidence: r.confidence,
+            }));
+        }
+        catch (error) {
+            if (error instanceof Error)
+                throw error;
+            throw new Error(`Failed to fetchArbitrage: ${error}`);
+        }
+    }
+}
+exports.Router = Router;

package/generated/.openapi-generator/FILES

@@ -35,10 +35,10 @@ docs/FetchEventMatches200Response.md
 docs/FetchEventMatchesParams.md
 docs/FetchEvents200Response.md
 docs/FetchMarket200Response.md
+docs/FetchMarketMatches200Response.md
+docs/FetchMarketMatchesParams.md
 docs/FetchMarkets200Response.md
 docs/FetchMarketsPaginated200Response.md
-docs/FetchMatches200Response.md
-docs/FetchMatchesParams.md
 docs/FetchMyTrades200Response.md
 docs/FetchOHLCV200Response.md
 docs/FetchOpenOrders200Response.md
@@ -128,10 +128,10 @@ src/models/FetchEventMatches200Response.ts
 src/models/FetchEventMatchesParams.ts
 src/models/FetchEvents200Response.ts
 src/models/FetchMarket200Response.ts
+src/models/FetchMarketMatches200Response.ts
+src/models/FetchMarketMatchesParams.ts
 src/models/FetchMarkets200Response.ts
 src/models/FetchMarketsPaginated200Response.ts
-src/models/FetchMatches200Response.ts
-src/models/FetchMatchesParams.ts
 src/models/FetchMyTrades200Response.ts
 src/models/FetchOHLCV200Response.ts
 src/models/FetchOpenOrders200Response.ts

package/generated/docs/ArbitrageOpportunity.md

@@ -13,6 +13,8 @@ Name | Type
 `sellVenue` | string
 `buyPrice` | number
 `sellPrice` | number
+`relation` | string
+`confidence` | number
 
 ## Example
 
@@ -28,6 +30,8 @@ const example = {
   "sellVenue": null,
   "buyPrice": null,
   "sellPrice": null,
+  "relation": null,
+  "confidence": null,
 } satisfies ArbitrageOpportunity
 
 console.log(example)

package/generated/docs/CompareMarketPricesRequest.md

@@ -6,7 +6,7 @@
 
 Name | Type
 ------------ | -------------
-`args` | [Array<FetchMatchesParams>](FetchMatchesParams.md)
+`args` | [Array<FetchMarketMatchesParams>](FetchMarketMatchesParams.md)
 `credentials` | [ExchangeCredentials](ExchangeCredentials.md)
 
 ## Example