feat(dx): typed SDK params, passthrough converters, outcome ID consistency

Typed SDK params replace `any` with real types (MarketFilterParams, etc.)
giving consumers IDE autocomplete. Passthrough converters use spread (TS)
and _auto_convert (Python) so new fields flow through automatically.
All outcome-accepting methods renamed id->outcomeId with MarketOutcome
object acceptance. Python backwards compat via _compat_id deprecation shim.
Fixes Limitless fetchTrades missing resolveSlug bug.

Author: realfishsam

changelog.md

@@ -2,6 +2,67 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.39.0] - 2026-05-08
+
+### DX: SDK type safety, passthrough converters, and outcome ID consistency
+
+A developer experience overhaul across core, TypeScript SDK, and Python SDK.
+
+**Typed SDK params** -- Generated SDK methods now have real parameter types
+instead of `any`. `fetchMarkets(params?: MarketFilterParams)` replaces
+`fetchMarkets(params?: any)`, giving consumers full IDE autocomplete and
+compile-time validation. Affected params: `MarketFilterParams`,
+`EventFetchParams`, `MyTradesParams`, `OrderHistoryParams`, `OHLCVParams`,
+`TradesParams`.
+
+**Passthrough converters** -- SDK converter functions (`convertMarket`,
+`convertEvent`, etc.) no longer enumerate fields explicitly. TypeScript
+uses spread (`{ ...raw }`) and Python uses a new `_auto_convert()` helper
+that iterates dataclass fields. New fields added to `types.ts` now flow
+through to both SDKs automatically instead of being silently dropped.
+
+**Outcome ID consistency** -- All methods that accept an outcome identifier
+now use `outcomeId` (TS) / `outcome_id` (Python) instead of the ambiguous
+`id`. Renamed in: `fetchOHLCV`, `fetchOrderBook`, `fetchTrades`,
+`watchOrderBook`, `watchOrderBooks`, `unwatchOrderBook`, `watchTrades`.
+
+**MarketOutcome acceptance** -- All outcome-accepting methods now accept
+`string | MarketOutcome` (TS) / `Union[str, MarketOutcome]` (Python), so
+you can pass `market.yes` directly instead of `market.yes.outcomeId`. The
+SDK generators auto-apply this to future methods.
+
+**Limitless bug fix** -- `fetchTrades` was missing `resolveSlug()`, so
+numeric outcome IDs that worked in `fetchOrderBook` failed silently.
+Added `resolveSlug` to `fetchTrades`, `watchOrderBook`, and `watchTrades`.
+
+### Migration
+
+No breaking changes. Python callers using the old `id=` keyword argument
+will see a `DeprecationWarning` but the call still works:
+
+```python
+# Old (deprecated, still works)
+ex.fetch_order_book(id="token123")
+
+# New (preferred)
+ex.fetch_order_book(outcome_id="token123")
+ex.fetch_order_book(market.yes)  # MarketOutcome object
+```
+
+TypeScript is fully backwards compatible -- parameter names are positional
+in JS/TS so the rename has no runtime impact.
+
+### Files
+
+- `core/src/BaseExchange.ts` -- param renames
+- `core/src/exchanges/*/index.ts` -- param renames (15 exchange files)
+- `core/src/exchanges/limitless/index.ts` -- resolveSlug bug fix
+- `sdks/typescript/pmxt/client.ts` -- passthrough converters, new imports
+- `sdks/typescript/pmxt/models.ts` -- added param types, fixed missing fields
+- `sdks/typescript/scripts/generate-client-methods.js` -- typed params, MarketOutcome widening
+- `sdks/python/pmxt/client.py` -- _auto_convert helper, compat shim, MarketOutcome widening
+- `sdks/python/scripts/generate-client-methods.js` -- typed params, compat shim generation
+
 ## [2.38.0] - 2026-05-08
 
 ### Feat: Hyperliquid prediction market (HIP-4 Outcome Markets)

core/src/BaseExchange.ts

@@ -813,43 +813,43 @@ export abstract class PredictionMarketExchange {
     /**
      * Fetch historical OHLCV (candlestick) price data for a specific market outcome.
      *
-     * @param id - The Outcome ID (outcomeId). Use outcome.outcomeId, NOT market.marketId
+     * @param outcomeId - The Outcome ID (outcomeId). Use outcome.outcomeId, NOT market.marketId
      * @param params - OHLCV parameters including resolution (required)
      * @returns Array of price candles
      *
      * @notes **CRITICAL**: Use `outcome.outcomeId` (TS) / `outcome.outcome_id` (Python), not the market ID.
      * @notes Polymarket: outcomeId is the CLOB Token ID. Kalshi: outcomeId is the Market Ticker.
      * @notes Common resolutions: '1m' | '5m' | '15m' | '1h' | '6h' | '1d'. Arbitrary intervals (e.g. '30s', '120s', '3h') accepted by venues that support them.
      */
-    async fetchOHLCV(id: string, params: OHLCVParams): Promise<PriceCandle[]> {
+    async fetchOHLCV(outcomeId: string, params: OHLCVParams): Promise<PriceCandle[]> {
         throw new Error("Method fetchOHLCV not implemented.");
     }
 
     /**
      * Fetch the current order book (bids/asks) for a specific outcome.
      * Essential for calculating spread, depth, and execution prices.
      *
-     * @param id - The Outcome ID (outcomeId) or market slug
+     * @param outcomeId - The Outcome ID (outcomeId) or market slug
      * @param side - Optional 'yes' or 'no' to explicitly indicate the
      *   outcome side. Required for exchanges where the API returns a
      *   single orderbook per market (e.g. Limitless) and the caller
      *   passes a slug instead of a token ID.
      * @returns Current order book with bids and asks
      */
-    async fetchOrderBook(id: string, side?: 'yes' | 'no'): Promise<OrderBook> {
+    async fetchOrderBook(outcomeId: string, side?: 'yes' | 'no'): Promise<OrderBook> {
         throw new Error("Method fetchOrderBook not implemented.");
     }
 
     /**
      * Fetch raw trade history for a specific outcome.
      *
-     * @param id - The Outcome ID (outcomeId)
+     * @param outcomeId - The Outcome ID (outcomeId)
      * @param params - Trade filter parameters
      * @returns Array of recent trades
      *
      * @notes Polymarket requires an API key for trade history. Use fetchOHLCV for public historical data.
      */
-    async fetchTrades(id: string, params: TradesParams | HistoryFilterParams): Promise<Trade[]> {
+    async fetchTrades(outcomeId: string, params: TradesParams | HistoryFilterParams): Promise<Trade[]> {
         // Deprecation warning for resolution parameter
         if ('resolution' in params && params.resolution !== undefined) {
             console.warn(
@@ -1246,11 +1246,11 @@ export abstract class PredictionMarketExchange {
      * Watch order book updates in real-time via WebSocket.
      * Returns a promise that resolves with the next order book update. Call repeatedly in a loop to stream updates (CCXT Pro pattern).
      *
-     * @param id - The Outcome ID to watch
+     * @param outcomeId - The Outcome ID to watch
      * @param limit - Optional limit for orderbook depth
      * @returns Promise that resolves with the current orderbook state
      */
-    async watchOrderBook(id: string, limit?: number): Promise<OrderBook> {
+    async watchOrderBook(outcomeId: string, limit?: number): Promise<OrderBook> {
         throw new Error(`watchOrderBook() is not supported by ${this.name}`);
     }
 
@@ -1260,33 +1260,33 @@ export abstract class PredictionMarketExchange {
      * Exchanges with native batch support (e.g. Kalshi) send a single subscribe message
      * for all tickers; others fall back to individual watchOrderBook calls.
      *
-     * @param ids - Array of Outcome IDs to watch
+     * @param outcomeIds - Array of Outcome IDs to watch
      * @param limit - Optional limit for orderbook depth
      * @returns Promise that resolves with order books keyed by ID
      */
-    async watchOrderBooks(ids: string[], limit?: number): Promise<Record<string, OrderBook>> {
+    async watchOrderBooks(outcomeIds: string[], limit?: number): Promise<Record<string, OrderBook>> {
         // Default implementation: subscribe to each ID individually.
         // Exchanges with native batch support (e.g. Kalshi) override this
         // to send a single subscribe message for all tickers.
         const entries = await Promise.all(
-            ids.map(async (id): Promise<[string, OrderBook]> => {
-                const book = await this.watchOrderBook(id, limit);
-                return [id, book];
+            outcomeIds.map(async (oid): Promise<[string, OrderBook]> => {
+                const book = await this.watchOrderBook(oid, limit);
+                return [oid, book];
             }),
         );
         const result: Record<string, OrderBook> = {};
-        for (const [id, book] of entries) {
-            result[id] = book;
+        for (const [oid, book] of entries) {
+            result[oid] = book;
         }
         return result;
     }
 
     /**
      * Unsubscribe from a previously watched order book stream.
      *
-     * @param id - The Outcome ID to stop watching
+     * @param outcomeId - The Outcome ID to stop watching
      */
-    async unwatchOrderBook(id: string): Promise<void> {
+    async unwatchOrderBook(outcomeId: string): Promise<void> {
         throw new Error(`unwatchOrderBook() is not supported by ${this.name}`);
     }
 
@@ -1298,13 +1298,13 @@ export abstract class PredictionMarketExchange {
      * Watch trade executions in real-time via WebSocket.
      * Returns a promise that resolves with the next trade(s). Call repeatedly in a loop to stream updates (CCXT Pro pattern).
      *
-     * @param id - The Outcome ID to watch
+     * @param outcomeId - The Outcome ID to watch
      * @param address - Public wallet address
      * @param since - Optional timestamp to filter trades from
      * @param limit - Optional limit for number of trades
      * @returns Promise that resolves with recent trades
      */
-    async watchTrades(id: string, address?: string, since?: number, limit?: number): Promise<Trade[]> {
+    async watchTrades(outcomeId: string, address?: string, since?: number, limit?: number): Promise<Trade[]> {
         throw new Error(`watchTrades() is not supported by ${this.name}`);
     }
 

core/src/exchanges/baozi/index.ts

@@ -123,9 +123,9 @@ export class BaoziExchange extends PredictionMarketExchange {
         return [];
     }
 
-    async fetchOrderBook(id: string): Promise<OrderBook> {
-        const rawMarket = await this.fetcher.fetchRawOrderBook(id);
-        return this.normalizer.normalizeOrderBook(rawMarket, id);
+    async fetchOrderBook(outcomeId: string): Promise<OrderBook> {
+        const rawMarket = await this.fetcher.fetchRawOrderBook(outcomeId);
+        return this.normalizer.normalizeOrderBook(rawMarket, outcomeId);
     }
 
     async fetchTrades(): Promise<Trade[]> {
@@ -403,11 +403,11 @@ export class BaoziExchange extends PredictionMarketExchange {
     // WebSocket
     // -----------------------------------------------------------------------
 
-    async watchOrderBook(id: string): Promise<OrderBook> {
+    async watchOrderBook(outcomeId: string): Promise<OrderBook> {
         if (!this.ws) {
             this.ws = new BaoziWebSocket();
         }
-        return this.ws.watchOrderBook(this.connection, id);
+        return this.ws.watchOrderBook(this.connection, outcomeId);
     }
 
     async watchTrades(): Promise<Trade[]> {

core/src/exchanges/kalshi/index.ts

@@ -186,21 +186,21 @@ export class KalshiExchange extends PredictionMarketExchange {
   }
 
   async fetchOHLCV(
-    id: string,
+    outcomeId: string,
     params: OHLCVParams,
   ): Promise<PriceCandle[]> {
-    const rawCandles = await this.fetcher.fetchRawOHLCV(id, params);
+    const rawCandles = await this.fetcher.fetchRawOHLCV(outcomeId, params);
     return this.normalizer.normalizeOHLCV(rawCandles, params);
   }
 
-  async fetchOrderBook(id: string): Promise<OrderBook> {
-    validateIdFormat(id, "OrderBook");
-    const raw = await this.fetcher.fetchRawOrderBook(id);
-    return this.normalizer.normalizeOrderBook(raw, id);
+  async fetchOrderBook(outcomeId: string): Promise<OrderBook> {
+    validateIdFormat(outcomeId, "OrderBook");
+    const raw = await this.fetcher.fetchRawOrderBook(outcomeId);
+    return this.normalizer.normalizeOrderBook(raw, outcomeId);
   }
 
   async fetchTrades(
-    id: string,
+    outcomeId: string,
     params: TradesParams | HistoryFilterParams,
   ): Promise<Trade[]> {
     if ("resolution" in params && params.resolution !== undefined) {
@@ -209,7 +209,7 @@ export class KalshiExchange extends PredictionMarketExchange {
         "It will be removed in v3.0.0. Please remove it from your code.",
       );
     }
-    const rawTrades = await this.fetcher.fetchRawTrades(id, params);
+    const rawTrades = await this.fetcher.fetchRawTrades(outcomeId, params);
     return rawTrades.map((raw, i) => this.normalizer.normalizeTrade(raw, i));
   }
 
@@ -341,7 +341,7 @@ export class KalshiExchange extends PredictionMarketExchange {
 
   private ws?: KalshiWebSocket;
 
-  async watchOrderBook(id: string, limit?: number): Promise<OrderBook> {
+  async watchOrderBook(outcomeId: string, limit?: number): Promise<OrderBook> {
     const auth = this.ensureAuth();
     if (!this.ws) {
       const wsConfigWithUrl: KalshiWebSocketConfig = {
@@ -350,11 +350,11 @@ export class KalshiExchange extends PredictionMarketExchange {
       };
       this.ws = new KalshiWebSocket(auth, wsConfigWithUrl);
     }
-    const marketTicker = id.replace(/-NO$/, "");
+    const marketTicker = outcomeId.replace(/-NO$/, "");
     return this.ws.watchOrderBook(marketTicker);
   }
 
-  async watchOrderBooks(ids: string[], limit?: number): Promise<Record<string, OrderBook>> {
+  async watchOrderBooks(outcomeIds: string[], limit?: number): Promise<Record<string, OrderBook>> {
     const auth = this.ensureAuth();
     if (!this.ws) {
       const wsConfigWithUrl: KalshiWebSocketConfig = {
@@ -363,12 +363,12 @@ export class KalshiExchange extends PredictionMarketExchange {
       };
       this.ws = new KalshiWebSocket(auth, wsConfigWithUrl);
     }
-    const marketTickers = ids.map((id) => id.replace(/-NO$/, ""));
+    const marketTickers = outcomeIds.map((oid) => oid.replace(/-NO$/, ""));
     return this.ws.watchOrderBooks(marketTickers);
   }
 
   async watchTrades(
-    id: string,
+    outcomeId: string,
     address?: string,
     since?: number,
     limit?: number,
@@ -381,7 +381,7 @@ export class KalshiExchange extends PredictionMarketExchange {
       };
       this.ws = new KalshiWebSocket(auth, wsConfigWithUrl);
     }
-    const marketTicker = id.replace(/-NO$/, "");
+    const marketTicker = outcomeId.replace(/-NO$/, "");
     return this.ws.watchTrades(marketTicker);
   }
 

core/src/exchanges/limitless/index.ts

@@ -194,21 +194,21 @@ export class LimitlessExchange extends PredictionMarketExchange {
             .filter((e): e is UnifiedEvent => e !== null);
     }
 
-    async fetchOHLCV(id: string, params: OHLCVParams): Promise<PriceCandle[]> {
-        const slug = await this.resolveSlug(id);
+    async fetchOHLCV(outcomeId: string, params: OHLCVParams): Promise<PriceCandle[]> {
+        const slug = await this.resolveSlug(outcomeId);
         const rawPrices = await this.fetcher.fetchRawOHLCV!(slug, params);
         return this.normalizer.normalizeOHLCV!(rawPrices as any, params);
     }
 
-    async fetchOrderBook(id: string, side?: 'yes' | 'no'): Promise<OrderBook> {
-        const slug = await this.resolveSlug(id);
+    async fetchOrderBook(outcomeId: string, side?: 'yes' | 'no'): Promise<OrderBook> {
+        const slug = await this.resolveSlug(outcomeId);
         const rawOrderBook = await this.fetcher.fetchRawOrderBook!(slug);
-        const orderBook = this.normalizer.normalizeOrderBook!(rawOrderBook as any, id);
+        const orderBook = this.normalizer.normalizeOrderBook!(rawOrderBook as any, outcomeId);
 
         // The Limitless API always returns the Yes-side order book regardless
         // of which token is queried. If the caller asked for the No token,
         // flip: noBid = 1 - yesAsk, noAsk = 1 - yesBid.
-        const isNoToken = side === 'no' || (!side && await this.isNoOutcome(id, slug));
+        const isNoToken = side === 'no' || (!side && await this.isNoOutcome(outcomeId, slug));
         if (isNoToken) {
             return {
                 bids: orderBook.asks.map((level) => ({ price: 1 - level.price, size: level.size }))
@@ -238,14 +238,15 @@ export class LimitlessExchange extends PredictionMarketExchange {
         return false;
     }
 
-    async fetchTrades(id: string, params: TradesParams | HistoryFilterParams): Promise<Trade[]> {
+    async fetchTrades(outcomeId: string, params: TradesParams | HistoryFilterParams): Promise<Trade[]> {
         if ('resolution' in params && params.resolution !== undefined) {
             console.warn(
                 '[pmxt] Warning: The "resolution" parameter is deprecated for fetchTrades() and will be ignored. ' +
                 'It will be removed in v3.0.0. Please remove it from your code.'
             );
         }
-        const rawTrades = await this.fetcher.fetchRawTrades!(id, params);
+        const slug = await this.resolveSlug(outcomeId);
+        const rawTrades = await this.fetcher.fetchRawTrades!(slug, params);
         return rawTrades.map((raw, i) => this.normalizer.normalizeTrade!(raw, i));
     }
 
@@ -435,14 +436,16 @@ export class LimitlessExchange extends PredictionMarketExchange {
     // WebSocket
     // ------------------------------------------------------------------------
 
-    async watchOrderBook(id: string, limit?: number): Promise<OrderBook> {
+    async watchOrderBook(outcomeId: string, limit?: number): Promise<OrderBook> {
+        const slug = await this.resolveSlug(outcomeId);
         const ws = this.ensureWs();
-        return ws.watchOrderBook(id);
+        return ws.watchOrderBook(slug);
     }
 
-    async watchTrades(id: string, address?: string, since?: number, limit?: number): Promise<Trade[]> {
+    async watchTrades(outcomeId: string, address?: string, since?: number, limit?: number): Promise<Trade[]> {
+        const slug = await this.resolveSlug(outcomeId);
         const ws = this.ensureWs();
-        return ws.watchTrades(id, address);
+        return ws.watchTrades(slug, address);
     }
 
     /**