pmxt-core 1.3.3 → 1.4.0

package/API_REFERENCE.md

@@ -129,6 +129,29 @@ const trades = await kalshi.fetchTrades('FED-25JAN', {
 
 ---
 
+## Helper Methods
+
+### `getExecutionPrice(orderBook, side, amount)`
+Calculate the volume-weighted average price for a given amount. Returns `0` if there is insufficient liquidity to fully fill the amount.
+
+```typescript
+const orderBook = await polymarket.fetchOrderBook(outcomeId);
+const price = await polymarket.getExecutionPrice(orderBook, 'buy', 100);
+console.log(`Average price for 100 shares: ${price}`);
+```
+
+### `getExecutionPriceDetailed(orderBook, side, amount)`
+Calculate detailed execution price information, including partial fills.
+
+```typescript
+const detailed = await polymarket.getExecutionPriceDetailed(orderBook, 'buy', 100);
+console.log(`Average Price: ${detailed.price}`);
+console.log(`Filled Amount: ${detailed.filledAmount}`);
+console.log(`Fully Filled: ${detailed.fullyFilled}`);
+```
+
+---
+
 ## Data Models
 
 ### `UnifiedMarket`
@@ -196,6 +219,12 @@ interface Trade {
   amount: number;
   side: 'buy' | 'sell' | 'unknown';
 }
+
+interface ExecutionPriceResult {
+  price: number;           // Average execution price
+  filledAmount: number;    // Amount filled (shares)
+  fullyFilled: boolean;    // If the requested amount was met
+}
 ```
 
 ---

package/dist/BaseExchange.d.ts

@@ -1,4 +1,5 @@
 import { UnifiedMarket, UnifiedEvent, PriceCandle, CandleInterval, OrderBook, Trade, Order, Position, Balance, CreateOrderParams } from './types';
+import { ExecutionPriceResult } from './utils/math';
 export interface MarketFilterParams {
     limit?: number;
     offset?: number;
@@ -32,6 +33,11 @@ export declare abstract class PredictionMarketExchange {
      * By default, searches only in market titles. Use params.searchIn to search descriptions or both.
      */
     abstract searchMarkets(query: string, params?: MarketFilterParams): Promise<UnifiedMarket[]>;
+    /**
+     * Fetch markets by URL slug (Polymarket) or ticker (Kalshi).
+     * @param slug - Market slug or ticker
+     */
+    abstract getMarketsBySlug(slug: string): Promise<UnifiedMarket[]>;
     /**
      * Search for events matching a keyword query.
      * Returns grouped events, each containing related markets.
@@ -78,6 +84,8 @@ export declare abstract class PredictionMarketExchange {
      * Fetch account balances.
      */
     fetchBalance(): Promise<Balance[]>;
+    getExecutionPrice(orderBook: OrderBook, side: 'buy' | 'sell', amount: number): number;
+    getExecutionPriceDetailed(orderBook: OrderBook, side: 'buy' | 'sell', amount: number): ExecutionPriceResult;
     /**
      * Watch orderbook updates in real-time via WebSocket.
      * Returns a promise that resolves with the latest orderbook state.

package/dist/BaseExchange.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PredictionMarketExchange = void 0;
+const math_1 = require("./utils/math");
 // ----------------------------------------------------------------------------
 // Base Exchange Class
 // ----------------------------------------------------------------------------
@@ -77,6 +78,12 @@ class PredictionMarketExchange {
     async fetchBalance() {
         throw new Error("Method fetchBalance not implemented.");
     }
+    getExecutionPrice(orderBook, side, amount) {
+        return (0, math_1.getExecutionPrice)(orderBook, side, amount);
+    }
+    getExecutionPriceDetailed(orderBook, side, amount) {
+        return (0, math_1.getExecutionPriceDetailed)(orderBook, side, amount);
+    }
     // ----------------------------------------------------------------------------
     // WebSocket Streaming Methods
     // ----------------------------------------------------------------------------

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './BaseExchange';
 export * from './types';
+export * from './utils/math';
 export * from './exchanges/polymarket';
 export * from './exchanges/kalshi';
 export * from './server/app';

package/dist/index.js

@@ -17,6 +17,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.kalshi = exports.polymarket = void 0;
 __exportStar(require("./BaseExchange"), exports);
 __exportStar(require("./types"), exports);
+__exportStar(require("./utils/math"), exports);
 __exportStar(require("./exchanges/polymarket"), exports);
 __exportStar(require("./exchanges/kalshi"), exports);
 __exportStar(require("./server/app"), exports);

package/dist/utils/math.d.ts

@@ -0,0 +1,8 @@
+import { OrderBook } from '../types';
+export declare function getExecutionPrice(orderBook: OrderBook, side: 'buy' | 'sell', amount: number): number;
+export interface ExecutionPriceResult {
+    price: number;
+    filledAmount: number;
+    fullyFilled: boolean;
+}
+export declare function getExecutionPriceDetailed(orderBook: OrderBook, side: 'buy' | 'sell', amount: number): ExecutionPriceResult;

package/dist/utils/math.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getExecutionPrice = getExecutionPrice;
+exports.getExecutionPriceDetailed = getExecutionPriceDetailed;
+function getExecutionPrice(orderBook, side, amount) {
+    const result = getExecutionPriceDetailed(orderBook, side, amount);
+    return result.fullyFilled ? result.price : 0;
+}
+function getExecutionPriceDetailed(orderBook, side, amount) {
+    if (amount <= 0) {
+        throw new Error('Amount must be greater than 0');
+    }
+    // Defensive copy to avoid mutating the original object if we were to sort in place (though toSorted/spread is safer)
+    // We filter out any zero-size levels just in case
+    let levels = (side === 'buy' ? orderBook.asks : orderBook.bids).filter(l => l.size > 0);
+    // Sort levels to ensure we get the best price
+    // Asks: Lowest Price First (Ascending)
+    // Bids: Highest Price First (Descending)
+    levels.sort((a, b) => side === 'buy' ? a.price - b.price : b.price - a.price);
+    if (levels.length === 0) {
+        return {
+            price: 0,
+            filledAmount: 0,
+            fullyFilled: false,
+        };
+    }
+    let remainingAmount = amount;
+    let totalCost = 0;
+    let filledAmount = 0;
+    // Use a small epsilon to handle floating point arithmetic errors
+    const EPSILON = 0.00000001;
+    for (const level of levels) {
+        if (remainingAmount <= EPSILON) {
+            break;
+        }
+        const fillSize = Math.min(remainingAmount, level.size);
+        totalCost += fillSize * level.price;
+        filledAmount += fillSize;
+        remainingAmount -= fillSize;
+    }
+    const fullyFilled = remainingAmount <= EPSILON;
+    const executionPrice = filledAmount > EPSILON ? totalCost / filledAmount : 0;
+    return {
+        price: executionPrice,
+        filledAmount,
+        fullyFilled,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmxt-core",
-  "version": "1.3.3",
+  "version": "1.4.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=1.3.3,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=1.3.3,supportsES6=true,typescriptThreePlus=true",
+    "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=1.4.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=1.4.0,supportsES6=true,typescriptThreePlus=true",
     "generate:docs": "node ../scripts/generate-api-docs.js",
     "generate:sdk:all": "npm run generate:sdk:python && npm run generate:sdk:typescript && npm run generate:docs"
   },