pmxt-core 2.47.0 → 2.48.1

package/dist/exchanges/probable/index.d.ts

@@ -2,6 +2,9 @@ import { PredictionMarketExchange, MarketFetchParams, EventFetchParams, Exchange
 import { UnifiedMarket, UnifiedEvent, OrderBook, PriceCandle, Trade, UserTrade, Order, Position, Balance, CreateOrderParams } from '../../types';
 import { ProbableWebSocketConfig } from './websocket';
 export declare class ProbableExchange extends PredictionMarketExchange {
+    protected readonly capabilityOverrides: {
+        fetchSeries: false;
+    };
     private auth?;
     private ws?;
     private wsConfig?;

package/dist/exchanges/probable/index.js

@@ -16,6 +16,9 @@ const normalizer_1 = require("./normalizer");
 const logger_1 = require("../../utils/logger");
 const BSC_USDT_ADDRESS = '0x55d398326f99059fF775485246999027B3197955';
 class ProbableExchange extends BaseExchange_1.PredictionMarketExchange {
+    capabilityOverrides = {
+        fetchSeries: false,
+    };
     auth;
     ws;
     wsConfig;
@@ -78,6 +81,10 @@ class ProbableExchange extends BaseExchange_1.PredictionMarketExchange {
         return filtered;
     }
     async fetchEventsImpl(params) {
+        // Venue does not expose a series concept; honoring `params.series` by
+        // returning [] rather than ignoring the filter.
+        if (params.series !== undefined)
+            return [];
         const rawEvents = await this.fetcher.fetchRawEvents(params);
         const events = rawEvents
             .map((raw) => this.normalizer.normalizeEvent(raw))

package/dist/exchanges/smarkets/index.d.ts

@@ -3,6 +3,7 @@ import { UnifiedMarket, UnifiedEvent, OrderBook, Trade, UserTrade, Balance, Orde
 export declare class SmarketsExchange extends PredictionMarketExchange {
     protected readonly capabilityOverrides: {
         fetchPositions: "emulated";
+        fetchSeries: false;
     };
     private auth?;
     private loginPromise;

package/dist/exchanges/smarkets/index.js

@@ -16,6 +16,7 @@ const logger_1 = require("../../utils/logger");
 class SmarketsExchange extends BaseExchange_1.PredictionMarketExchange {
     capabilityOverrides = {
         fetchPositions: 'emulated',
+        fetchSeries: false,
     };
     auth;
     loginPromise = null;
@@ -149,6 +150,10 @@ class SmarketsExchange extends BaseExchange_1.PredictionMarketExchange {
         return allMarkets.slice(offset, offset + limit);
     }
     async fetchEventsImpl(params) {
+        // Venue does not expose a series concept; honoring `params.series` by
+        // returning [] rather than ignoring the filter.
+        if (params.series !== undefined)
+            return [];
         const rawEvents = await this.fetcher.fetchRawEvents(params);
         const limit = params?.limit || 250000;
         const query = (params?.query || '').toLowerCase();

package/dist/exchanges/suibets/index.d.ts

@@ -33,6 +33,7 @@ export declare class SuiBetsExchange extends PredictionMarketExchange {
         fetchPositions: true;
         watchOrderBook: false;
         watchTrades: false;
+        fetchSeries: false;
     };
     private readonly config;
     private readonly fetcher;

package/dist/exchanges/suibets/index.js

@@ -34,6 +34,7 @@ class SuiBetsExchange extends BaseExchange_1.PredictionMarketExchange {
         fetchPositions: true,
         watchOrderBook: false,
         watchTrades: false,
+        fetchSeries: false,
     };
     config;
     fetcher;
@@ -72,6 +73,10 @@ class SuiBetsExchange extends BaseExchange_1.PredictionMarketExchange {
             .filter((m) => m !== null);
     }
     async fetchEventsImpl(params) {
+        // Venue does not expose a series concept; honoring `params.series` by returning [] rather than ignoring the filter.
+        if (params.series !== undefined) {
+            return [];
+        }
         const raw = await this.fetcher.fetchRawEvents(params);
         return raw
             .map(r => this.normalizer.normalizeEvent(r))

package/dist/router/Router.d.ts

@@ -1,5 +1,5 @@
-import { PredictionMarketExchange, type MarketFetchParams, type EventFetchParams } from '../BaseExchange';
-import type { UnifiedMarket, UnifiedEvent, OrderBook } from '../types';
+import { PredictionMarketExchange, type MarketFetchParams, type EventFetchParams, type SeriesFetchParams } from '../BaseExchange';
+import type { UnifiedMarket, UnifiedEvent, UnifiedSeries, OrderBook } from '../types';
 import type { RouterOptions, MatchResult, EventMatchResult, PriceComparison, ArbitrageOpportunity, MatchedMarketPair, MatchedPricePair, FetchMarketMatchesParams, FetchMatchesParams, FetchEventMatchesParams, FetchArbitrageParams, FetchMatchedMarketsParams, FetchMatchedPricesParams } from './types';
 export declare class Router extends PredictionMarketExchange {
     private readonly client;
@@ -9,6 +9,33 @@ export declare class Router extends PredictionMarketExchange {
     get name(): string;
     protected fetchMarketsImpl(params?: MarketFetchParams): Promise<UnifiedMarket[]>;
     protected fetchEventsImpl(params?: EventFetchParams): Promise<UnifiedEvent[]>;
+    /**
+     * Fan out fetchEvents({series: venueSeriesId}) to each venue in the
+     * mapping, collect all results, and tag each event with its sourceExchange.
+     */
+    private fetchEventsForMappedSeries;
+    /**
+     * Cross-venue series fetch.
+     *
+     * - If `params.id` matches a normalized id in SERIES_MAP, returns a single
+     *   synthesized `UnifiedSeries` whose `events` is the concatenation of
+     *   `fetchEvents({series: venueSeriesId})` results from each mapped venue.
+     * - Otherwise fans out `fetchSeries(params)` to all venue instances with
+     *   `has.fetchSeries !== false`, collects, and returns deduplicated results
+     *   tagged with their `sourceExchange`.
+     */
+    protected fetchSeriesImpl(params: SeriesFetchParams): Promise<UnifiedSeries[]>;
+    /**
+     * Build a single synthesized `UnifiedSeries` from the SERIES_MAP entry by
+     * fetching events from all mapped venues and concatenating them.
+     */
+    private fetchSynthesizedSeries;
+    /**
+     * Fan out `fetchSeries(params)` to all venue instances whose
+     * `has.fetchSeries` is not `false`. Tag each result with its originating
+     * venue name.
+     */
+    private fanOutFetchSeries;
     fetchOrderBook(outcomeId: string, limit?: number, params?: Record<string, any>): Promise<OrderBook>;
     fetchMarketMatches(params?: FetchMarketMatchesParams): Promise<MatchResult[]>;
     /**

package/dist/router/Router.js

@@ -5,6 +5,7 @@ const BaseExchange_1 = require("../BaseExchange");
 const errors_1 = require("../errors");
 const logger_1 = require("../utils/logger");
 const client_1 = require("./client");
+const series_map_1 = require("./series-map");
 // ---------------------------------------------------------------------------
 // Orderbook merge utilities
 // ---------------------------------------------------------------------------
@@ -127,6 +128,18 @@ class Router extends BaseExchange_1.PredictionMarketExchange {
         return response;
     }
     async fetchEventsImpl(params) {
+        // When a normalized series id is requested, fan out to each mapped venue
+        // using the venue-native series id and aggregate the results.
+        if (params?.series !== undefined) {
+            const normalized = params.series;
+            const entry = series_map_1.SERIES_MAP.find((e) => e.id === normalized);
+            if (entry !== undefined) {
+                return this.fetchEventsForMappedSeries(entry.venues, params);
+            }
+            // Not a known normalized id — fall through and pass the raw value to
+            // the hosted search endpoint (single-venue callers using vendor-native
+            // ids still work).
+        }
         const response = await this.client.searchEvents({
             query: params?.query,
             category: params?.category,
@@ -138,6 +151,138 @@ class Router extends BaseExchange_1.PredictionMarketExchange {
         }
         return response;
     }
+    /**
+     * Fan out fetchEvents({series: venueSeriesId}) to each venue in the
+     * mapping, collect all results, and tag each event with its sourceExchange.
+     */
+    async fetchEventsForMappedSeries(venueMap, baseParams) {
+        const venueEntries = Object.entries(venueMap);
+        if (venueEntries.length === 0)
+            return [];
+        const fetchResults = await Promise.all(venueEntries.map(async ([venueName, venueSeriesId]) => {
+            const exchange = this.localExchanges[venueName];
+            if (!exchange) {
+                logger_1.logger.debug(`Router.fetchEventsForMappedSeries: no exchange instance for venue "${venueName}", skipping`);
+                return [];
+            }
+            try {
+                const events = await exchange.fetchEvents({
+                    ...baseParams,
+                    series: venueSeriesId,
+                });
+                return events.map((ev) => ({
+                    ...ev,
+                    sourceExchange: ev.sourceExchange ?? venueName,
+                }));
+            }
+            catch (error) {
+                logger_1.logger.warn(`Router.fetchEventsForMappedSeries: fetchEvents failed for venue "${venueName}" ` +
+                    `series "${venueSeriesId}": ${error instanceof Error ? error.message : String(error)}`);
+                return [];
+            }
+        }));
+        return fetchResults.flat();
+    }
+    // -----------------------------------------------------------------------
+    // Cross-venue series (series-map + fan-out)
+    // -----------------------------------------------------------------------
+    /**
+     * Cross-venue series fetch.
+     *
+     * - If `params.id` matches a normalized id in SERIES_MAP, returns a single
+     *   synthesized `UnifiedSeries` whose `events` is the concatenation of
+     *   `fetchEvents({series: venueSeriesId})` results from each mapped venue.
+     * - Otherwise fans out `fetchSeries(params)` to all venue instances with
+     *   `has.fetchSeries !== false`, collects, and returns deduplicated results
+     *   tagged with their `sourceExchange`.
+     */
+    async fetchSeriesImpl(params) {
+        const requestedId = params.id;
+        if (requestedId !== undefined) {
+            const entry = series_map_1.SERIES_MAP.find((e) => e.id === requestedId);
+            if (entry !== undefined) {
+                return this.fetchSynthesizedSeries(entry, params);
+            }
+        }
+        return this.fanOutFetchSeries(params);
+    }
+    /**
+     * Build a single synthesized `UnifiedSeries` from the SERIES_MAP entry by
+     * fetching events from all mapped venues and concatenating them.
+     */
+    async fetchSynthesizedSeries(entry, params) {
+        const venueEntries = Object.entries(entry.venues);
+        const eventsPerVenue = await Promise.all(venueEntries.map(async ([venueName, venueSeriesId]) => {
+            const exchange = this.localExchanges[venueName];
+            if (!exchange) {
+                logger_1.logger.debug(`Router.fetchSynthesizedSeries: no exchange instance for venue "${venueName}", skipping`);
+                return [];
+            }
+            try {
+                const events = await exchange.fetchEvents({ series: venueSeriesId });
+                return events.map((ev) => ({
+                    ...ev,
+                    sourceExchange: ev.sourceExchange ?? venueName,
+                }));
+            }
+            catch (error) {
+                logger_1.logger.warn(`Router.fetchSynthesizedSeries: fetchEvents failed for venue "${venueName}" ` +
+                    `series "${venueSeriesId}": ${error instanceof Error ? error.message : String(error)}`);
+                return [];
+            }
+        }));
+        const allEvents = eventsPerVenue.flat();
+        const synthesized = {
+            id: entry.id,
+            title: entry.title,
+            events: allEvents,
+            sourceExchange: 'Router',
+        };
+        // Apply limit/offset if the caller passed them (BaseExchange.fetchSeries strips
+        // them before calling fetchSeriesImpl, but guard defensively).
+        const limit = params.limit;
+        const offset = params.offset ?? 0;
+        if (limit !== undefined) {
+            return [{ ...synthesized, events: allEvents.slice(offset, offset + limit) }];
+        }
+        return [synthesized];
+    }
+    /**
+     * Fan out `fetchSeries(params)` to all venue instances whose
+     * `has.fetchSeries` is not `false`. Tag each result with its originating
+     * venue name.
+     */
+    async fanOutFetchSeries(params) {
+        const venueEntries = Object.entries(this.localExchanges);
+        if (venueEntries.length === 0)
+            return [];
+        const fetchResults = await Promise.all(venueEntries.map(async ([venueName, exchange]) => {
+            if (exchange.has.fetchSeries === false)
+                return [];
+            // When params.id is a venue-native id on this specific venue,
+            // pass it through directly so single-venue lookups still work.
+            let venueParams = params;
+            if (params.id !== undefined) {
+                const nativeId = (0, series_map_1.getVenueSeriesId)(params.id, venueName);
+                if (nativeId !== undefined) {
+                    venueParams = { ...params, id: nativeId };
+                }
+            }
+            try {
+                const series = await exchange.fetchSeries(venueParams);
+                return series.map((s) => ({
+                    ...s,
+                    sourceExchange: s.sourceExchange ?? venueName,
+                }));
+            }
+            catch (error) {
+                logger_1.logger.warn(`Router.fanOutFetchSeries: fetchSeries failed for venue "${venueName}": ` +
+                    `${error instanceof Error ? error.message : String(error)}`);
+                return [];
+            }
+        }));
+        return fetchResults.flat();
+    }
     // -----------------------------------------------------------------------
     // Unified orderbook (cross-exchange merge)
     // -----------------------------------------------------------------------

package/dist/router/index.d.ts

@@ -1,3 +1,4 @@
 export { Router } from './Router';
 export { PmxtApiClient } from './client';
 export * from './types';
+export * from './series-map';

package/dist/router/index.js

@@ -20,3 +20,4 @@ Object.defineProperty(exports, "Router", { enumerable: true, get: function () {
 var client_1 = require("./client");
 Object.defineProperty(exports, "PmxtApiClient", { enumerable: true, get: function () { return client_1.PmxtApiClient; } });
 __exportStar(require("./types"), exports);
+__exportStar(require("./series-map"), exports);

package/dist/router/series-map.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Curated mapping from normalized PMXT series ids to per-venue native series ids.
+ *
+ * The normalized ids use kebab-case following the pattern:
+ *   <sport-or-domain>-<category-or-format>
+ *
+ * Venue-native ids are the raw tickers/slugs each platform uses.
+ * It is intentional for some entries to have only partial venue coverage --
+ * the Router handles missing venue mappings gracefully by skipping that venue.
+ */
+export interface RouterSeriesEntry {
+    /** Normalized PMXT series id (kebab-case). */
+    id: string;
+    /** Human-readable title. */
+    title: string;
+    /** Map of venueName -> venue-native series id. */
+    venues: {
+        readonly [venueName: string]: string;
+    };
+}
+export declare const SERIES_MAP: readonly RouterSeriesEntry[];
+/**
+ * Resolve a normalized PMXT series id to the venue-native series id for a
+ * given venue. Returns `undefined` when either the normalized id is not in the
+ * map or that venue has no mapping for it.
+ */
+export declare function getVenueSeriesId(normalizedId: string, venue: string): string | undefined;
+/**
+ * Reverse-lookup: given a venue name and a venue-native series id, return the
+ * normalized PMXT series id. Returns `undefined` when not found.
+ */
+export declare function getNormalizedSeriesId(venue: string, venueSeriesId: string): string | undefined;

package/dist/router/series-map.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * Curated mapping from normalized PMXT series ids to per-venue native series ids.
+ *
+ * The normalized ids use kebab-case following the pattern:
+ *   <sport-or-domain>-<category-or-format>
+ *
+ * Venue-native ids are the raw tickers/slugs each platform uses.
+ * It is intentional for some entries to have only partial venue coverage --
+ * the Router handles missing venue mappings gracefully by skipping that venue.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERIES_MAP = void 0;
+exports.getVenueSeriesId = getVenueSeriesId;
+exports.getNormalizedSeriesId = getNormalizedSeriesId;
+exports.SERIES_MAP = [
+    {
+        id: 'tennis-atp-match',
+        title: 'ATP Match Winner',
+        venues: {
+            kalshi: 'KXATPSETWINNER',
+            polymarket: 'atp',
+        },
+    },
+    {
+        id: 'tennis-atp-challenger',
+        title: 'ATP Challenger Match Winner',
+        venues: {
+            kalshi: 'KXATPCHALLENGERMATCH',
+        },
+    },
+    {
+        id: 'tennis-wta-match',
+        title: 'WTA Match Winner',
+        venues: {
+            kalshi: 'KXWTASETWINNER',
+            polymarket: 'wta',
+        },
+    },
+    {
+        id: 'tennis-itf-match',
+        title: 'ITF Match Winner',
+        venues: {
+            kalshi: 'KXITFMATCH',
+        },
+    },
+    {
+        id: 'tennis-itf-women-match',
+        title: "ITF Women's Match Winner",
+        venues: {
+            kalshi: 'KXITFWMATCH',
+        },
+    },
+    {
+        id: 'nfl',
+        title: 'NFL Game Winner',
+        venues: {
+            kalshi: 'KXNFLGAME',
+            polymarket: 'nfl-game',
+        },
+    },
+    {
+        id: 'nba',
+        title: 'NBA Game Winner',
+        venues: {
+            kalshi: 'KXNBAGAME',
+            polymarket: 'nba',
+        },
+    },
+    {
+        id: 'ncaa-basketball',
+        title: 'NCAA Basketball Game Winner',
+        venues: {
+            kalshi: 'KXNCAABBGAME',
+        },
+    },
+    {
+        id: 'ufc',
+        title: 'UFC Fight Winner',
+        venues: {
+            polymarket: 'ufc',
+        },
+    },
+    {
+        id: 'soccer-fifa-world-cup',
+        title: 'FIFA World Cup Match Winner',
+        venues: {
+            polymarket: 'soccer-fifwc',
+        },
+    },
+    {
+        id: 'esports-cs2-map',
+        title: 'CS2 Map Winner',
+        venues: {
+            kalshi: 'KXCS2MAP',
+        },
+    },
+    {
+        id: 'esports-lol-map',
+        title: 'League of Legends Map Winner',
+        venues: {
+            kalshi: 'KXLOLMAP',
+        },
+    },
+    {
+        id: 'crypto-btc-15m',
+        title: 'Bitcoin Price (15-minute)',
+        venues: {
+            kalshi: 'KXBTC15M',
+        },
+    },
+    {
+        id: 'crypto-eth-15m',
+        title: 'Ethereum Price (15-minute)',
+        venues: {
+            kalshi: 'KXETH15M',
+        },
+    },
+    {
+        id: 'crypto-sol-15m',
+        title: 'Solana Price (15-minute)',
+        venues: {
+            kalshi: 'KXSOL15M',
+        },
+    },
+];
+// ---------------------------------------------------------------------------
+// Lookup helpers (O(n) over small constant array; acceptable for this table)
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a normalized PMXT series id to the venue-native series id for a
+ * given venue. Returns `undefined` when either the normalized id is not in the
+ * map or that venue has no mapping for it.
+ */
+function getVenueSeriesId(normalizedId, venue) {
+    const entry = exports.SERIES_MAP.find((e) => e.id === normalizedId);
+    return entry?.venues[venue];
+}
+/**
+ * Reverse-lookup: given a venue name and a venue-native series id, return the
+ * normalized PMXT series id. Returns `undefined` when not found.
+ */
+function getNormalizedSeriesId(venue, venueSeriesId) {
+    const entry = exports.SERIES_MAP.find((e) => e.venues[venue] === venueSeriesId);
+    return entry?.id;
+}

package/dist/server/app.js

@@ -384,13 +384,30 @@ function createApp(options = {}) {
     });
     // POST /api/:exchange/:method
     //
-    // The original RPC-shaped surface. Body: { args: any[], credentials? }.
+    // Supports two calling conventions:
+    //   - Envelope:   { args: [...], credentials? }  — original RPC shape, used by SDKs
+    //   - Flat body:  { slug: "wta", limit: 3, ... } — raw-curl / documentation examples
+    //
+    // When `args` is a valid array it is used directly (envelope path).
+    // When the body is a plain object without an `args` array, the body minus
+    // the reserved envelope keys (`args`, `credentials`) becomes args[0].
     // Accepts every method, including reads — so pre-existing clients
     // that POST reads keep working forever.
     app.post("/api/:exchange/:method", async (req, res, next) => {
         const methodName = req.params.method;
-        const args = Array.isArray(req.body.args) ? req.body.args : [];
-        const credentials = req.body.credentials;
+        const body = req.body;
+        const credentials = body.credentials;
+        let args;
+        if (Array.isArray(body.args)) {
+            args = body.args;
+        }
+        else if (body && typeof body === 'object' && !Array.isArray(body)) {
+            const { args: _ignored, credentials: _creds, ...rest } = body;
+            args = Object.keys(rest).length > 0 ? [rest] : [];
+        }
+        else {
+            args = [];
+        }
         await dispatchMethod(req, res, next, methodName, args, credentials);
     });
     // Error handler

package/dist/server/method-verbs.json

@@ -49,6 +49,16 @@
       }
     ]
   },
+  "fetchSeries": {
+    "verb": "get",
+    "args": [
+      {
+        "name": "params",
+        "kind": "object",
+        "optional": true
+      }
+    ]
+  },
   "fetchMarket": {
     "verb": "get",
     "args": [

package/dist/server/openapi.yaml

@@ -326,6 +326,15 @@ paths:
           schema:
             type: string
           description: Lookup by event slug
+        - in: query
+          name: series
+          required: false
+          schema:
+            type: string
+          description: >-
+            Filter events by their parent series. Accepts the venue-native series id / ticker / slug (e.g. Kalshi
+            `"KXATPMATCH"`, Polymarket `"wta"`). Passed through to the vendor where supported, otherwise applied to
+            `sourceMetadata` after fetch.
         - in: query
           name: filter
           required: false
@@ -369,6 +378,31 @@ paths:
       description: >-
         Fetch events with optional keyword search. Events group related markets together (e.g., "Who will be Fed Chair?"
         contains multiple candidate markets).
+  '/api/{exchange}/fetchSeries':
+    get:
+      summary: Fetch Series
+      operationId: fetchSeries
+      parameters:
+        - $ref: '#/components/parameters/ExchangeParam'
+      responses:
+        '200':
+          description: Fetch Series response
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/BaseResponse'
+                  - type: object
+                    properties:
+                      data:
+                        type: array
+                        items:
+                          $ref: '#/components/schemas/UnifiedSeries'
+      description: >-
+        Fetch the recurring series (fourth tier above Event -> Market -> Outcome) that this venue exposes. Returns an
+        empty array on venues without a series concept (Limitless, Smarkets, Probable, Metaculus, Baozi, Hyperliquid,
+        SuiBets, Polymarket US). - `params.id` -> a single matching series with its events populated where supported. -
+        no params -> the full list, typically without nested events for payload size.
   '/api/{exchange}/fetchMarket':
     get:
       summary: Fetch Market
@@ -548,6 +582,15 @@ paths:
           schema:
             type: string
           description: Lookup by event slug
+        - in: query
+          name: series
+          required: false
+          schema:
+            type: string
+          description: >-
+            Filter events by their parent series. Accepts the venue-native series id / ticker / slug (e.g. Kalshi
+            `"KXATPMATCH"`, Polymarket `"wta"`). Passed through to the vendor where supported, otherwise applied to
+            `sourceMetadata` after fetch.
         - in: query
           name: filter
           required: false
@@ -2780,6 +2823,63 @@ components:
         - markets
         - volume24h
         - url
+    UnifiedSeries:
+      type: object
+      description: >-
+        A recurring grouping of events on a venue — the fourth tier above Event -> Market -> Outcome. Examples: Kalshi
+        `KXATPMATCH` (every ATP tennis match), Polymarket `wta` (every WTA match), Opinion's daily `collection`. Series
+        only exists where the venue exposes a recurring-event concept; venues without one return an empty array from
+        `fetchSeries`.
+      properties:
+        id:
+          type: string
+          description: >-
+            Stable venue-native series identifier (e.g. "KXATPMATCH" on Kalshi, "atp" on Polymarket Gamma, numeric Gamma
+            id).
+        ticker:
+          type: string
+          description: 'Venue-native ticker, when distinct from `id`.'
+        slug:
+          type: string
+          description: Venue-native slug.
+        title:
+          type: string
+          description: 'Human-readable series title (e.g. "ATP Match Winner", "WTA").'
+        description:
+          oneOf:
+            - type: string
+            - {}
+          description: Long-form series description.
+        recurrence:
+          oneOf:
+            - type: string
+            - {}
+          description: 'Recurrence cadence the venue reports (''daily'', ''weekly'', ''annual'', ...).'
+        events:
+          type: array
+          items:
+            $ref: '#/components/schemas/UnifiedEvent'
+          description: Child events. Populated when fetched by id; the list form usually omits this to keep payloads small.
+        url:
+          oneOf:
+            - type: string
+            - {}
+          description: Canonical venue URL for the series.
+        image:
+          oneOf:
+            - type: string
+            - {}
+          description: Venue-hosted image.
+        sourceExchange:
+          type: string
+          description: The exchange this series originates from. Populated by the Router.
+        sourceMetadata:
+          type: object
+          additionalProperties: {}
+          description: Raw venue-specific fields not promoted to first-class columns.
+      required:
+        - id
+        - title
     PriceCandle:
       type: object
       properties:
@@ -3173,6 +3273,12 @@ components:
         slug:
           type: string
           description: Lookup by event slug
+        series:
+          type: string
+          description: >-
+            Filter events by their parent series. Accepts the venue-native series id / ticker / slug (e.g. Kalshi
+            `"KXATPMATCH"`, Polymarket `"wta"`). Passed through to the vendor where supported, otherwise applied to
+            `sourceMetadata` after fetch.
         filter:
           allOf:
             - $ref: '#/components/schemas/EventFilterCriteria'