feat: unified event discovery across all exchanges

- Removed mandatory query/eventId/slug requirement for fetchEvents() in BaseExchange
- Implemented discovery path for Polymarket via Gamma /events endpoint
- Implemented discovery path for Kalshi with client-side sorting (volume, liquidity, newest)
- Implemented discovery path for Limitless via group market filtering
- Updated unit tests to align with unrestricted parameter requirements
- Bumped version to 2.17.0

Author: realfishsam

changelog.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.17.0] - 2026-02-24
+
+### Improved
+
+- **Unified Discovery: Unrestricted Event Fetching**: Removed the mandatory requirement for a query, event identification, or slug in `fetchEvents`. Users can now call `fetchEvents()` without parameters to retrieve the "front page" of an exchange (typically top events by volume).
+- **Polymarket: High-Performance Discovery**: Redirects no-query `fetchEvents` calls to the specific Gamma `/events` list endpoint, providing a cleaner and faster experience than the fuzzy search path.
+- **Kalshi: Client-Side Event Ranking**: Implemented robust client-side sorting for Kalshi events. Since the Kalshi API lacks server-side sorting for the event list, `fetchEvents` now aggregates volume, liquidity, and recency from nested markets to provide consistent `sort` support (`volume`, `liquidity`, `newest`).
+- **Limitless: Semantic Event Mapping**: Mapped Limitless "Group Markets" to the unified `fetchEvents` interface. Discovery calls now automatically filter for group markets, aligning Limitless with event-centric discovery patterns.
+- **Developer Experience**: Synchronized `fetchEvents` behavior with `fetchMarkets` across all exchanges (Baozi, Myriad, Probable, Kalshi, Polymarket, Limitless).
+
+### Fixed
+
+- **Unit Tests**: Updated core validation suite to reflect the relaxed requirements for event fetching.
+
 ## [2.16.1] - 2026-02-24
 
 ### Fixed

core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmxt-core",
-  "version": "2.0.2",
+  "version": "2.17.0",
   "description": "pmxt is a unified prediction market data API. The ccxt for prediction markets.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -80,4 +80,4 @@
       "optional": true
     }
   }
-}
+}

core/src/BaseExchange.ts

@@ -475,7 +475,7 @@ export abstract class PredictionMarketExchange {
      * Events group related markets together (e.g., "Who will be Fed Chair?" contains multiple candidate markets).
      *
      * @param params - Optional parameters for search and filtering
-     * @param params.query - Search keyword to filter events (required)
+     * @param params.query - Search keyword to filter events. If omitted, returns top events by volume.
      * @param params.limit - Maximum number of results
      * @param params.offset - Pagination offset
      * @param params.searchIn - Where to search ('title' | 'description' | 'both')
@@ -494,10 +494,7 @@ export abstract class PredictionMarketExchange {
      * print(fed_event.title, len(fed_event.markets), 'markets')
      */
     async fetchEvents(params?: EventFetchParams): Promise<UnifiedEvent[]> {
-        if (!params?.query && !params?.eventId && !params?.slug) {
-            throw new Error("fetchEvents() requires a query, eventId, or slug parameter");
-        }
-        return this.fetchEventsImpl(params!);
+        return this.fetchEventsImpl(params ?? {});
     }
 
     /**

core/src/exchanges/kalshi/fetchEvents.ts

@@ -45,6 +45,61 @@ async function fetchEventByTicker(
   return [unifiedEvent];
 }
 
+function rawEventToUnified(event: any): UnifiedEvent {
+  const markets: UnifiedMarket[] = [];
+  if (event.markets) {
+    for (const market of event.markets) {
+      const unifiedMarket = mapMarketToUnified(event, market);
+      if (unifiedMarket) {
+        markets.push(unifiedMarket);
+      }
+    }
+  }
+  return {
+    id: event.event_ticker,
+    title: event.title,
+    description: event.mututals_description || "",
+    slug: event.event_ticker,
+    markets: markets,
+    url: `https://kalshi.com/events/${event.event_ticker}`,
+    image: event.image_url,
+    category: event.category,
+    tags: event.tags || [],
+  };
+}
+
+async function fetchAllWithStatus(
+  callApi: CallApi,
+  apiStatus: string,
+): Promise<any[]> {
+  let allEvents: any[] = [];
+  let cursor = null;
+  let page = 0;
+
+  const MAX_PAGES = 1000;
+  const BATCH_SIZE = 200;
+
+  do {
+    const queryParams: any = {
+      limit: BATCH_SIZE,
+      with_nested_markets: true,
+      status: apiStatus,
+    };
+    if (cursor) queryParams.cursor = cursor;
+
+    const data = await callApi("GetEvents", queryParams);
+    const events = data.events || [];
+
+    if (events.length === 0) break;
+
+    allEvents = allEvents.concat(events);
+    cursor = data.cursor;
+    page++;
+  } while (cursor && page < MAX_PAGES);
+
+  return allEvents;
+}
+
 export async function fetchEvents(
   params: EventFetchParams,
   callApi: CallApi,
@@ -64,89 +119,74 @@ export async function fetchEvents(
     const limit = params?.limit || 10000;
     const query = (params?.query || "").toLowerCase();
 
-    const fetchAllWithStatus = async (apiStatus: string) => {
-      let allEvents: any[] = [];
-      let cursor = null;
-      let page = 0;
-
-      const MAX_PAGES = 1000; // Safety cap against infinite loops
-      const BATCH_SIZE = 200; // Max limit per Kalshi API docs
-
-      do {
-        const queryParams: any = {
-          limit: BATCH_SIZE,
-          with_nested_markets: true,
-          status: apiStatus,
-        };
-        if (cursor) queryParams.cursor = cursor;
-
-        const data = await callApi("GetEvents", queryParams);
-        const events = data.events || [];
-
-        if (events.length === 0) break;
-
-        allEvents = allEvents.concat(events);
-        cursor = data.cursor;
-        page++;
-
-        // If we have no search query and have fetched enough events, we can stop early
-        if (!query && allEvents.length >= limit * 1.5) {
-          break;
-        }
-      } while (cursor && page < MAX_PAGES);
-
-      return allEvents;
-    };
-
-    let events = [];
+    let events: any[] = [];
     if (status === "all") {
       const [openEvents, closedEvents, settledEvents] = await Promise.all([
-        fetchAllWithStatus("open"),
-        fetchAllWithStatus("closed"),
-        fetchAllWithStatus("settled"),
+        fetchAllWithStatus(callApi, "open"),
+        fetchAllWithStatus(callApi, "closed"),
+        fetchAllWithStatus(callApi, "settled"),
       ]);
       events = [...openEvents, ...closedEvents, ...settledEvents];
     } else if (status === "closed" || status === "inactive") {
       const [closedEvents, settledEvents] = await Promise.all([
-        fetchAllWithStatus("closed"),
-        fetchAllWithStatus("settled"),
+        fetchAllWithStatus(callApi, "closed"),
+        fetchAllWithStatus(callApi, "settled"),
       ]);
       events = [...closedEvents, ...settledEvents];
     } else {
-      events = await fetchAllWithStatus("open");
+      events = await fetchAllWithStatus(callApi, "open");
     }
 
-    const filtered = events.filter((event: any) => {
-      return (event.title || "").toLowerCase().includes(query);
-    });
-
-    const unifiedEvents: UnifiedEvent[] = filtered.map((event: any) => {
-      const markets: UnifiedMarket[] = [];
-      if (event.markets) {
-        for (const market of event.markets) {
-          const unifiedMarket = mapMarketToUnified(event, market);
-          if (unifiedMarket) {
-            markets.push(unifiedMarket);
-          }
-        }
-      }
+    // Apply keyword filter if a query was provided
+    const filtered = query
+      ? events.filter((event: any) =>
+        (event.title || "").toLowerCase().includes(query),
+      )
+      : events;
 
-      const unifiedEvent: UnifiedEvent = {
-        id: event.event_ticker,
-        title: event.title,
-        description: event.mututals_description || "",
-        slug: event.event_ticker,
-        markets: markets,
-        url: `https://kalshi.com/events/${event.event_ticker}`,
-        image: event.image_url,
-        category: event.category,
-        tags: event.tags || [],
-      };
-      return unifiedEvent;
-    });
+    // Client-side sort — Kalshi's /events endpoint has no sort param.
+    // We aggregate stats from nested markets and sort the full set before slicing.
+    const sort = params?.sort || "volume";
+    const sorted = sortRawEvents(filtered, sort);
 
+    const unifiedEvents: UnifiedEvent[] = sorted.map(rawEventToUnified);
     return unifiedEvents.slice(0, limit);
   } catch (error: any) {
     throw kalshiErrorMapper.mapError(error);
   }
 }
+
+function eventVolume(event: any): number {
+  return (event.markets || []).reduce(
+    (sum: number, m: any) => sum + Number(m.volume || 0),
+    0,
+  );
+}
+
+function eventLiquidity(event: any): number {
+  return (event.markets || []).reduce(
+    (sum: number, m: any) => sum + Number(m.open_interest || m.liquidity || 0),
+    0,
+  );
+}
+
+function eventNewest(event: any): number {
+  // Use the earliest close_time across markets as a proxy for "newness"
+  const times = (event.markets || [])
+    .map((m: any) => (m.close_time ? new Date(m.close_time).getTime() : 0))
+    .filter((t: number) => t > 0);
+  return times.length > 0 ? Math.min(...times) : 0;
+}
+
+function sortRawEvents(events: any[], sort: string): any[] {
+  const copy = [...events];
+  if (sort === "newest") {
+    copy.sort((a, b) => eventNewest(b) - eventNewest(a));
+  } else if (sort === "liquidity") {
+    copy.sort((a, b) => eventLiquidity(b) - eventLiquidity(a));
+  } else {
+    // Default: volume
+    copy.sort((a, b) => eventVolume(b) - eventVolume(a));
+  }
+  return copy;
+}