pmxt-core 2.9.1 → 2.10.0

package/dist/BaseExchange.d.ts

@@ -149,16 +149,34 @@ export declare abstract class PredictionMarketExchange {
     constructor(credentials?: ExchangeCredentials);
     abstract get name(): string;
     /**
-     * Load and cache markets from the exchange.
-     * This method populates `this.markets` and `this.marketsBySlug`.
+     * Load and cache all markets from the exchange into `this.markets` and `this.marketsBySlug`.
+     * Subsequent calls return the cached result without hitting the API again.
      *
-     * @param reload - Force a reload of markets from the API even if already loaded
+     * This is the correct way to paginate or iterate over markets without drift.
+     * Because `fetchMarkets()` always hits the API, repeated calls with different `offset`
+     * values may return inconsistent results if the exchange reorders or adds markets between
+     * requests. Use `loadMarkets()` once to get a stable snapshot, then paginate over
+     * `Object.values(exchange.markets)` locally.
+     *
+     * @param reload - Force a fresh fetch from the API even if markets are already loaded
      * @returns Dictionary of markets indexed by marketId
+     *
+     * @example-ts Stable pagination
+     * await exchange.loadMarkets();
+     * const all = Object.values(exchange.markets);
+     * const page1 = all.slice(0, 100);
+     * const page2 = all.slice(100, 200);
+     *
+     * @example-python Stable pagination
+     * exchange.load_markets()
+     * all = list(exchange.markets.values())
+     * page1 = all[:100]
+     * page2 = all[100:200]
      */
     loadMarkets(reload?: boolean): Promise<Record<string, UnifiedMarket>>;
     /**
      * Fetch markets with optional filtering, search, or slug lookup.
-     * This is the primary method for retrieving markets.
+     * Always hits the exchange API — results reflect the live state at the time of the call.
      *
      * @param params - Optional parameters for filtering and search
      * @param params.query - Search keyword to filter markets
@@ -169,6 +187,10 @@ export declare abstract class PredictionMarketExchange {
      * @param params.searchIn - Where to search ('title' | 'description' | 'both')
      * @returns Array of unified markets
      *
+     * @note Calling this repeatedly with different `offset` values does not guarantee stable
+     * ordering — exchanges may reorder or add markets between requests. For stable iteration
+     * across pages, use `loadMarkets()` and paginate over `Object.values(exchange.markets)`.
+     *
      * @note Some exchanges (like Limitless) may only support status 'active' for search results.
      *
      * @example-ts Fetch markets

package/dist/BaseExchange.js

@@ -71,11 +71,29 @@ class PredictionMarketExchange {
         });
     }
     /**
-     * Load and cache markets from the exchange.
-     * This method populates `this.markets` and `this.marketsBySlug`.
+     * Load and cache all markets from the exchange into `this.markets` and `this.marketsBySlug`.
+     * Subsequent calls return the cached result without hitting the API again.
      *
-     * @param reload - Force a reload of markets from the API even if already loaded
+     * This is the correct way to paginate or iterate over markets without drift.
+     * Because `fetchMarkets()` always hits the API, repeated calls with different `offset`
+     * values may return inconsistent results if the exchange reorders or adds markets between
+     * requests. Use `loadMarkets()` once to get a stable snapshot, then paginate over
+     * `Object.values(exchange.markets)` locally.
+     *
+     * @param reload - Force a fresh fetch from the API even if markets are already loaded
      * @returns Dictionary of markets indexed by marketId
+     *
+     * @example-ts Stable pagination
+     * await exchange.loadMarkets();
+     * const all = Object.values(exchange.markets);
+     * const page1 = all.slice(0, 100);
+     * const page2 = all.slice(100, 200);
+     *
+     * @example-python Stable pagination
+     * exchange.load_markets()
+     * all = list(exchange.markets.values())
+     * page1 = all[:100]
+     * page2 = all[100:200]
      */
     async loadMarkets(reload = false) {
         if (this.loadedMarkets && !reload) {
@@ -98,7 +116,7 @@ class PredictionMarketExchange {
     }
     /**
      * Fetch markets with optional filtering, search, or slug lookup.
-     * This is the primary method for retrieving markets.
+     * Always hits the exchange API — results reflect the live state at the time of the call.
      *
      * @param params - Optional parameters for filtering and search
      * @param params.query - Search keyword to filter markets
@@ -109,6 +127,10 @@ class PredictionMarketExchange {
      * @param params.searchIn - Where to search ('title' | 'description' | 'both')
      * @returns Array of unified markets
      *
+     * @note Calling this repeatedly with different `offset` values does not guarantee stable
+     * ordering — exchanges may reorder or add markets between requests. For stable iteration
+     * across pages, use `loadMarkets()` and paginate over `Object.values(exchange.markets)`.
+     *
      * @note Some exchanges (like Limitless) may only support status 'active' for search results.
      *
      * @example-ts Fetch markets

package/dist/exchanges/kalshi/api.d.ts

@@ -1,6 +1,6 @@
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/kalshi/Kalshi.yaml
- * Generated at: 2026-02-18T16:13:58.523Z
+ * Generated at: 2026-02-19T11:56:56.608Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 export declare const kalshiApiSpec: {

package/dist/exchanges/kalshi/api.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.kalshiApiSpec = void 0;
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/kalshi/Kalshi.yaml
- * Generated at: 2026-02-18T16:13:58.523Z
+ * Generated at: 2026-02-19T11:56:56.608Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 exports.kalshiApiSpec = {

package/dist/exchanges/limitless/api.d.ts

@@ -1,6 +1,6 @@
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/limitless/Limitless.yaml
- * Generated at: 2026-02-18T16:13:58.561Z
+ * Generated at: 2026-02-19T11:56:56.657Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 export declare const limitlessApiSpec: {

package/dist/exchanges/limitless/api.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.limitlessApiSpec = void 0;
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/limitless/Limitless.yaml
- * Generated at: 2026-02-18T16:13:58.561Z
+ * Generated at: 2026-02-19T11:56:56.657Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 exports.limitlessApiSpec = {

package/dist/exchanges/myriad/api.d.ts

@@ -1,6 +1,6 @@
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/myriad/myriad.yaml
- * Generated at: 2026-02-18T16:13:58.572Z
+ * Generated at: 2026-02-19T11:56:56.675Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 export declare const myriadApiSpec: {

package/dist/exchanges/myriad/api.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.myriadApiSpec = void 0;
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/myriad/myriad.yaml
- * Generated at: 2026-02-18T16:13:58.572Z
+ * Generated at: 2026-02-19T11:56:56.675Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 exports.myriadApiSpec = {

package/dist/exchanges/polymarket/api-clob.d.ts

@@ -1,6 +1,6 @@
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/polymarket/PolymarketClobAPI.yaml
- * Generated at: 2026-02-18T16:13:58.529Z
+ * Generated at: 2026-02-19T11:56:56.616Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 export declare const polymarketClobSpec: {

package/dist/exchanges/polymarket/api-clob.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.polymarketClobSpec = void 0;
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/polymarket/PolymarketClobAPI.yaml
- * Generated at: 2026-02-18T16:13:58.529Z
+ * Generated at: 2026-02-19T11:56:56.616Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 exports.polymarketClobSpec = {

package/dist/exchanges/polymarket/api-data.d.ts

@@ -1,6 +1,6 @@
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/polymarket/Polymarket_Data_API.yaml
- * Generated at: 2026-02-18T16:13:58.541Z
+ * Generated at: 2026-02-19T11:56:56.634Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 export declare const polymarketDataSpec: {

package/dist/exchanges/polymarket/api-data.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.polymarketDataSpec = void 0;
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/polymarket/Polymarket_Data_API.yaml
- * Generated at: 2026-02-18T16:13:58.541Z
+ * Generated at: 2026-02-19T11:56:56.634Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 exports.polymarketDataSpec = {

package/dist/exchanges/polymarket/api-gamma.d.ts

@@ -1,6 +1,6 @@
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/polymarket/PolymarketGammaAPI.yaml
- * Generated at: 2026-02-18T16:13:58.539Z
+ * Generated at: 2026-02-19T11:56:56.631Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 export declare const polymarketGammaSpec: {

package/dist/exchanges/polymarket/api-gamma.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.polymarketGammaSpec = void 0;
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/polymarket/PolymarketGammaAPI.yaml
- * Generated at: 2026-02-18T16:13:58.539Z
+ * Generated at: 2026-02-19T11:56:56.631Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 exports.polymarketGammaSpec = {

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

@@ -46,9 +46,25 @@ export declare class PolymarketExchange extends PredictionMarketExchange {
      */
     private ensureAuth;
     /**
-     * Pre-warm the SDK's internal caches for a token by fetching tick size,
-     * fee rate, and neg-risk in parallel. Call this when you start watching
-     * a market so that subsequent createOrder calls hit only POST /order.
+     * Pre-warm the SDK's internal caches for a market outcome.
+     *
+     * Fetches tick size, fee rate, and neg-risk in parallel so that subsequent
+     * `createOrder` calls skip those lookups and hit only `POST /order`.
+     * Call this when you start watching a market.
+     *
+     * @param outcomeId - The CLOB Token ID for the outcome (use `outcome.outcomeId`)
+     *
+     * @example-ts Pre-warm before placing orders
+     * const markets = await exchange.fetchMarkets({ query: 'Trump' });
+     * const outcomeId = markets[0].outcomes[0].outcomeId;
+     * await exchange.preWarmMarket(outcomeId);
+     * // Subsequent createOrder calls are faster
+     *
+     * @example-python Pre-warm before placing orders
+     * markets = exchange.fetch_markets(query='Trump')
+     * outcome_id = markets[0].outcomes[0].outcome_id
+     * exchange.pre_warm_market(outcome_id)
+     * # Subsequent create_order calls are faster
      */
     preWarmMarket(outcomeId: string): Promise<void>;
     createOrder(params: CreateOrderParams): Promise<Order>;

package/dist/exchanges/polymarket/index.js

@@ -185,9 +185,25 @@ class PolymarketExchange extends BaseExchange_1.PredictionMarketExchange {
         return this.auth;
     }
     /**
-     * Pre-warm the SDK's internal caches for a token by fetching tick size,
-     * fee rate, and neg-risk in parallel. Call this when you start watching
-     * a market so that subsequent createOrder calls hit only POST /order.
+     * Pre-warm the SDK's internal caches for a market outcome.
+     *
+     * Fetches tick size, fee rate, and neg-risk in parallel so that subsequent
+     * `createOrder` calls skip those lookups and hit only `POST /order`.
+     * Call this when you start watching a market.
+     *
+     * @param outcomeId - The CLOB Token ID for the outcome (use `outcome.outcomeId`)
+     *
+     * @example-ts Pre-warm before placing orders
+     * const markets = await exchange.fetchMarkets({ query: 'Trump' });
+     * const outcomeId = markets[0].outcomes[0].outcomeId;
+     * await exchange.preWarmMarket(outcomeId);
+     * // Subsequent createOrder calls are faster
+     *
+     * @example-python Pre-warm before placing orders
+     * markets = exchange.fetch_markets(query='Trump')
+     * outcome_id = markets[0].outcomes[0].outcome_id
+     * exchange.pre_warm_market(outcome_id)
+     * # Subsequent create_order calls are faster
      */
     async preWarmMarket(outcomeId) {
         const auth = this.ensureAuth();

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

@@ -1,6 +1,6 @@
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/probable/probable.yaml
- * Generated at: 2026-02-18T16:13:58.565Z
+ * Generated at: 2026-02-19T11:56:56.667Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 export declare const probableApiSpec: {

package/dist/exchanges/probable/api.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.probableApiSpec = void 0;
 /**
  * Auto-generated from /home/runner/work/pmxt/pmxt/core/specs/probable/probable.yaml
- * Generated at: 2026-02-18T16:13:58.565Z
+ * Generated at: 2026-02-19T11:56:56.667Z
  * Do not edit manually -- run "npm run fetch:openapi" to regenerate.
  */
 exports.probableApiSpec = {

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

@@ -26,7 +26,43 @@ export declare class ProbableExchange extends PredictionMarketExchange {
     private ensureAuth;
     protected fetchMarketsImpl(params?: MarketFetchParams): Promise<UnifiedMarket[]>;
     protected fetchEventsImpl(params: EventFetchParams): Promise<UnifiedEvent[]>;
+    /**
+     * Fetch a single event by its numeric ID (Probable only).
+     *
+     * @param id - The numeric event ID
+     * @returns The UnifiedEvent, or null if not found
+     *
+     * @example-ts Get event by ID
+     * const event = await exchange.getEventById('42');
+     * if (event) {
+     *   console.log(event.title);
+     *   console.log(event.markets.length, 'markets');
+     * }
+     *
+     * @example-python Get event by ID
+     * event = exchange.get_event_by_id('42')
+     * if event:
+     *     print(event.title)
+     *     print(len(event.markets), 'markets')
+     */
     getEventById(id: string): Promise<UnifiedEvent | null>;
+    /**
+     * Fetch a single event by its URL slug (Probable only).
+     *
+     * @param slug - The event's URL slug (e.g. `"trump-2024-election"`)
+     * @returns The UnifiedEvent, or null if not found
+     *
+     * @example-ts Get event by slug
+     * const event = await exchange.getEventBySlug('trump-2024-election');
+     * if (event) {
+     *   console.log(event.title);
+     * }
+     *
+     * @example-python Get event by slug
+     * event = exchange.get_event_by_slug('trump-2024-election')
+     * if event:
+     *     print(event.title)
+     */
     getEventBySlug(slug: string): Promise<UnifiedEvent | null>;
     fetchOrderBook(id: string): Promise<OrderBook>;
     fetchOHLCV(id: string, params: OHLCVParams | HistoryFilterParams): Promise<PriceCandle[]>;

package/dist/exchanges/probable/index.js

@@ -82,9 +82,45 @@ class ProbableExchange extends BaseExchange_1.PredictionMarketExchange {
     async fetchEventsImpl(params) {
         return (0, fetchEvents_1.fetchEvents)(params, this.http, (tokenId) => this.callApi('getPublicApiV1Midpoint', { token_id: tokenId }), (queryParams) => this.callApi('getPublicApiV1PublicSearch', queryParams));
     }
+    /**
+     * Fetch a single event by its numeric ID (Probable only).
+     *
+     * @param id - The numeric event ID
+     * @returns The UnifiedEvent, or null if not found
+     *
+     * @example-ts Get event by ID
+     * const event = await exchange.getEventById('42');
+     * if (event) {
+     *   console.log(event.title);
+     *   console.log(event.markets.length, 'markets');
+     * }
+     *
+     * @example-python Get event by ID
+     * event = exchange.get_event_by_id('42')
+     * if event:
+     *     print(event.title)
+     *     print(len(event.markets), 'markets')
+     */
     async getEventById(id) {
         return (0, fetchEvents_1.fetchEventById)(id, this.http, (tokenId) => this.callApi('getPublicApiV1Midpoint', { token_id: tokenId }));
     }
+    /**
+     * Fetch a single event by its URL slug (Probable only).
+     *
+     * @param slug - The event's URL slug (e.g. `"trump-2024-election"`)
+     * @returns The UnifiedEvent, or null if not found
+     *
+     * @example-ts Get event by slug
+     * const event = await exchange.getEventBySlug('trump-2024-election');
+     * if (event) {
+     *   console.log(event.title);
+     * }
+     *
+     * @example-python Get event by slug
+     * event = exchange.get_event_by_slug('trump-2024-election')
+     * if event:
+     *     print(event.title)
+     */
     async getEventBySlug(slug) {
         return (0, fetchEvents_1.fetchEventBySlug)(slug, this.http, (tokenId) => this.callApi('getPublicApiV1Midpoint', { token_id: tokenId }));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmxt-core",
-  "version": "2.9.1",
+  "version": "2.10.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.9.1,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.9.1,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.10.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.10.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",