pmxt-core 2.46.14 → 2.48.0

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,43 @@ 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:
+        - in: path
+          name: exchange
+          schema:
+            type: string
+            enum:
+              - polymarket
+              - kalshi
+              - kalshi-demo
+              - opinion
+              - polymarket_us
+              - router
+          required: true
+          description: The prediction market exchange to target.
+      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 +594,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
@@ -2654,6 +2709,13 @@ components:
         contractAddress:
           type: string
           description: 'On-chain contract / condition identifier where applicable (Polymarket conditionId, etc.).'
+        sourceMetadata:
+          type: object
+          additionalProperties: {}
+          description: >-
+            Raw venue-specific metadata not captured by first-class fields (e.g. Kalshi series_ticker / series_title
+            from the parent event, Polymarket series). Passed through verbatim so downstream consumers can recover
+            anything the unified shape omits. Each venue populates what it has.
         sourceExchange:
           type: string
           description: 'The exchange/venue this market originates from (e.g. ''polymarket'', ''kalshi''). Populated by the Router.'
@@ -2755,6 +2817,13 @@ components:
             Optional list of tags. More granular than category — e.g. ["Sports", "FIFA World Cup", "2026 FIFA World
             Cup"] or ["Politics", "Geopolitics", "Middle East"]. Tags vary by venue: Polymarket markets carry several,
             Kalshi typically one.
+        sourceMetadata:
+          type: object
+          additionalProperties: {}
+          description: >-
+            Raw venue-specific metadata not captured by first-class fields (e.g. Kalshi series_ticker / series_title,
+            Polymarket series). Passed through verbatim so downstream consumers can recover anything the unified shape
+            omits. Each venue populates what it has.
         sourceExchange:
           type: string
           description: 'The exchange/venue this event originates from (e.g. ''polymarket'', ''kalshi''). Populated by the Router.'
@@ -2766,6 +2835,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:
@@ -3159,6 +3285,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'

package/dist/types.d.ts

@@ -37,6 +37,8 @@ export interface UnifiedEvent {
     category?: string;
     /** Optional list of tags. More granular than category — e.g. ["Sports", "FIFA World Cup", "2026 FIFA World Cup"] or ["Politics", "Geopolitics", "Middle East"]. Tags vary by venue: Polymarket markets carry several, Kalshi typically one. */
     tags?: string[];
+    /** Raw venue-specific metadata not captured by first-class fields (e.g. Kalshi series_ticker / series_title, Polymarket series). Passed through verbatim so downstream consumers can recover anything the unified shape omits. Each venue populates what it has. */
+    sourceMetadata?: Record<string, unknown>;
     /** The exchange/venue this event originates from (e.g. 'polymarket', 'kalshi'). Populated by the Router. */
     sourceExchange?: string;
 }
@@ -75,6 +77,8 @@ export interface UnifiedMarket {
     status?: string;
     /** On-chain contract / condition identifier where applicable (Polymarket conditionId, etc.). */
     contractAddress?: string;
+    /** Raw venue-specific metadata not captured by first-class fields (e.g. Kalshi series_ticker / series_title from the parent event, Polymarket series). Passed through verbatim so downstream consumers can recover anything the unified shape omits. Each venue populates what it has. */
+    sourceMetadata?: Record<string, unknown>;
     /** The exchange/venue this market originates from (e.g. 'polymarket', 'kalshi'). Populated by the Router. */
     sourceExchange?: string;
     /** Convenience accessor for the YES outcome on a binary market. */
@@ -86,6 +90,37 @@ export interface UnifiedMarket {
     /** Convenience accessor for the DOWN outcome on a binary market. */
     down?: MarketOutcome;
 }
+/**
+ * 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`.
+ */
+export interface UnifiedSeries {
+    /** Stable venue-native series identifier (e.g. "KXATPMATCH" on Kalshi, "atp" on Polymarket Gamma, numeric Gamma id). */
+    id: string;
+    /** Venue-native ticker, when distinct from `id`. */
+    ticker?: string;
+    /** Venue-native slug. */
+    slug?: string;
+    /** Human-readable series title (e.g. "ATP Match Winner", "WTA"). */
+    title: string;
+    /** Long-form series description. */
+    description?: string | null;
+    /** Recurrence cadence the venue reports ('daily', 'weekly', 'annual', ...). */
+    recurrence?: string | null;
+    /** Child events. Populated when fetched by id; the list form usually omits this to keep payloads small. */
+    events?: UnifiedEvent[];
+    /** Canonical venue URL for the series. */
+    url?: string | null;
+    /** Venue-hosted image. */
+    image?: string | null;
+    /** The exchange this series originates from. Populated by the Router. */
+    sourceExchange?: string;
+    /** Raw venue-specific fields not promoted to first-class columns. */
+    sourceMetadata?: Record<string, unknown>;
+}
 /**
  * Candle interval for OHLCV data.
  *

package/dist/utils/metadata.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Build a `sourceMetadata` object from a raw venue payload, capturing only the
+ * venue-specific data that the unified shape would otherwise drop.
+ *
+ * Keys listed in `promotedKeys` are omitted because they are already
+ * represented by first-class Unified / DB columns (price, volume, status, ...),
+ * so keeping them here would duplicate data. Everything else on the raw payload
+ * is preserved verbatim. `extra` adds non-promoted fields that live on a
+ * different raw object (e.g. a parent event's series identifiers attached to a
+ * market); `undefined` extras are skipped so we never store empty keys.
+ *
+ * Returns a new object — the inputs are never mutated.
+ */
+export declare function buildSourceMetadata(raw: Record<string, unknown> | null | undefined, promotedKeys: readonly string[], extra?: Record<string, unknown>): Record<string, unknown>;

package/dist/utils/metadata.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSourceMetadata = buildSourceMetadata;
+/**
+ * Build a `sourceMetadata` object from a raw venue payload, capturing only the
+ * venue-specific data that the unified shape would otherwise drop.
+ *
+ * Keys listed in `promotedKeys` are omitted because they are already
+ * represented by first-class Unified / DB columns (price, volume, status, ...),
+ * so keeping them here would duplicate data. Everything else on the raw payload
+ * is preserved verbatim. `extra` adds non-promoted fields that live on a
+ * different raw object (e.g. a parent event's series identifiers attached to a
+ * market); `undefined` extras are skipped so we never store empty keys.
+ *
+ * Returns a new object — the inputs are never mutated.
+ */
+function buildSourceMetadata(raw, promotedKeys, extra) {
+    const promoted = new Set(promotedKeys);
+    const out = {};
+    if (raw && typeof raw === 'object') {
+        for (const [key, value] of Object.entries(raw)) {
+            if (!promoted.has(key))
+                out[key] = value;
+        }
+    }
+    if (extra) {
+        for (const [key, value] of Object.entries(extra)) {
+            if (value !== undefined)
+                out[key] = value;
+        }
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmxt-core",
-  "version": "2.46.14",
+  "version": "2.48.0",
   "description": "pmxt is a unified prediction market data API. The ccxt for prediction markets.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -29,8 +29,8 @@
     "test": "jest -c jest.config.js",
     "server": "tsx watch src/server/index.ts",
     "server:prod": "node dist/server/index.js",
-    "generate:sdk:python": "npx @openapitools/openapi-generator-cli generate -i src/server/openapi.yaml -g python -o ../sdks/python/generated --package-name pmxt_internal --additional-properties=projectName=pmxt-internal,packageVersion=2.46.14,library=urllib3",
-    "generate:sdk:typescript": "npx @openapitools/openapi-generator-cli generate -i src/server/openapi.yaml -g typescript-fetch -o ../sdks/typescript/generated --additional-properties=npmName=pmxtjs,npmVersion=2.46.14,supportsES6=true,typescriptThreePlus=true && node ../sdks/typescript/scripts/fix-generated.js",
+    "generate:sdk:python": "npx @openapitools/openapi-generator-cli generate -i src/server/openapi.yaml -g python -o ../sdks/python/generated --package-name pmxt_internal --additional-properties=projectName=pmxt-internal,packageVersion=2.48.0,library=urllib3",
+    "generate:sdk:typescript": "npx @openapitools/openapi-generator-cli generate -i src/server/openapi.yaml -g typescript-fetch -o ../sdks/typescript/generated --additional-properties=npmName=pmxtjs,npmVersion=2.48.0,supportsES6=true,typescriptThreePlus=true && node ../sdks/typescript/scripts/fix-generated.js",
     "fetch:openapi": "node scripts/fetch-openapi-specs.js",
     "extract:jsdoc": "node ../scripts/extract-jsdoc.js",
     "generate:docs": "npm run extract:jsdoc && node ../scripts/generate-api-docs.js",