pmxtjs 0.2.0 → 0.3.0

package/API_REFERENCE.md

@@ -7,13 +7,11 @@ This project implements a **Unified Interface** for interacting with multiple pr
 All components are available directly from the `pmxt` library.
 
 ```typescript
-import { 
-  PolymarketExchange, 
-  KalshiExchange
-} from './pmxt';
+import pmxt from 'pmxtjs';
 
-const polymarket = new PolymarketExchange();
-const kalshi = new KalshiExchange();
+// ccxt-style instantiation
+const polymarket = new pmxt.polymarket();
+const kalshi = new pmxt.kalshi();
 ```
 
 ## 1. Unified Interface (`PredictionMarketExchange`)
@@ -36,7 +34,7 @@ Search markets by title/description across the exchange(s).
 
 Methods available on specific exchange instances (`KalshiExchange`, `PolymarketExchange`) for detailed data.
 
-### `getMarketHistory(id, params)`
+### `fetchOHLCV(id, params)`
 Fetches OHLCV candlesticks.
 - **Input**: `id`, `resolution` (1m, 1h, 1d), `start`, `end`.
 - **Output**: `Promise<PriceCandle[]>`
@@ -44,18 +42,18 @@ Fetches OHLCV candlesticks.
   - **Kalshi**: Uses the Market Ticker (e.g., `FED-25DEC`). Returns **native OHLCV** (Open/High/Low/Close data is distinct).
   - **Polymarket**: Uses the **CLOB Token ID** found in `outcome.metadata.clobTokenId`. Returns **synthetic candles** (Open=High=Low=Close) derived from raw price points.
 
-### `getOrderBook(id)`
+### `fetchOrderBook(id)`
 Fetches live Bids/Asks.
 - **Input**: `id` (Ticker for Kalshi, Token ID for Polymarket).
 - **Output**: `Promise<OrderBook>` (Normalized: "No" bids becomes "Yes" asks).
 
-### `getTradeHistory(id, params)`
+### `fetchTrades(id, params)`
 Fetches the "Tape" (raw transaction history).
 - **Input**: `id`, `limit`.
 - **Output**: `Promise<Trade[]>`
 - **Note**: 
   - **Kalshi**: Publicly accessible for all tickers.
-  - **Polymarket**: Requires L2 Authentication (API Key). Without a key, this method will throw an unauthorized error. Use `getMarketHistory` for public historical data.
+  - **Polymarket**: Requires L2 Authentication (API Key). Without a key, this method will throw an unauthorized error. Use `fetchOHLCV` for public historical data.
 
 ---
 

package/dist/BaseExchange.d.ts

@@ -25,15 +25,15 @@ export declare abstract class PredictionMarketExchange {
      * Fetch historical price data for a specific market outcome.
      * @param id - The Outcome ID (MarketOutcome.id). This should be the ID of the specific tradeable asset.
      */
-    getMarketHistory(id: string, params: HistoryFilterParams): Promise<PriceCandle[]>;
+    fetchOHLCV(id: string, params: HistoryFilterParams): Promise<PriceCandle[]>;
     /**
      * Fetch the current order book (bids/asks) for a specific outcome.
      * Essential for calculating localized spread and depth.
      */
-    getOrderBook(id: string): Promise<OrderBook>;
+    fetchOrderBook(id: string): Promise<OrderBook>;
     /**
      * Fetch raw trade history.
      * Useful for generating synthetic OHLCV candles if the exchange doesn't provide them natively.
      */
-    getTradeHistory(id: string, params: HistoryFilterParams): Promise<Trade[]>;
+    fetchTrades(id: string, params: HistoryFilterParams): Promise<Trade[]>;
 }

package/dist/BaseExchange.js

@@ -9,22 +9,22 @@ class PredictionMarketExchange {
      * Fetch historical price data for a specific market outcome.
      * @param id - The Outcome ID (MarketOutcome.id). This should be the ID of the specific tradeable asset.
      */
-    async getMarketHistory(id, params) {
-        throw new Error("Method getMarketHistory not implemented.");
+    async fetchOHLCV(id, params) {
+        throw new Error("Method fetchOHLCV not implemented.");
     }
     /**
      * Fetch the current order book (bids/asks) for a specific outcome.
      * Essential for calculating localized spread and depth.
      */
-    async getOrderBook(id) {
-        throw new Error("Method getOrderBook not implemented.");
+    async fetchOrderBook(id) {
+        throw new Error("Method fetchOrderBook not implemented.");
     }
     /**
      * Fetch raw trade history.
      * Useful for generating synthetic OHLCV candles if the exchange doesn't provide them natively.
      */
-    async getTradeHistory(id, params) {
-        throw new Error("Method getTradeHistory not implemented.");
+    async fetchTrades(id, params) {
+        throw new Error("Method fetchTrades not implemented.");
     }
 }
 exports.PredictionMarketExchange = PredictionMarketExchange;

package/dist/exchanges/Kalshi.d.ts

@@ -14,7 +14,7 @@ export declare class KalshiExchange extends PredictionMarketExchange {
      */
     getMarketsBySlug(eventTicker: string): Promise<UnifiedMarket[]>;
     private mapIntervalToKalshi;
-    getMarketHistory(id: string, params: HistoryFilterParams): Promise<PriceCandle[]>;
-    getOrderBook(id: string): Promise<OrderBook>;
-    getTradeHistory(id: string, params: HistoryFilterParams): Promise<Trade[]>;
+    fetchOHLCV(id: string, params: HistoryFilterParams): Promise<PriceCandle[]>;
+    fetchOrderBook(id: string): Promise<OrderBook>;
+    fetchTrades(id: string, params: HistoryFilterParams): Promise<Trade[]>;
 }

package/dist/exchanges/Kalshi.js

@@ -149,8 +149,8 @@ class KalshiExchange extends BaseExchange_1.PredictionMarketExchange {
         try {
             const markets = await this.fetchMarkets({ ...params, limit: fetchLimit });
             const lowerQuery = query.toLowerCase();
-            const filtered = markets.filter(market => market.title.toLowerCase().includes(lowerQuery) ||
-                market.description.toLowerCase().includes(lowerQuery));
+            const filtered = markets.filter(market => (market.title || '').toLowerCase().includes(lowerQuery) ||
+                (market.description || '').toLowerCase().includes(lowerQuery));
             const limit = params?.limit || 20;
             return filtered.slice(0, limit);
         }
@@ -208,7 +208,7 @@ class KalshiExchange extends BaseExchange_1.PredictionMarketExchange {
         };
         return mapping[interval];
     }
-    async getMarketHistory(id, params) {
+    async fetchOHLCV(id, params) {
         try {
             // Kalshi API expects uppercase tickers
             // Handle virtual "-NO" suffix by stripping it (fetching the underlying market history)
@@ -239,14 +239,31 @@ class KalshiExchange extends BaseExchange_1.PredictionMarketExchange {
             queryParams.end_ts = endTs;
             const response = await axios_1.default.get(url, { params: queryParams });
             const candles = response.data.candlesticks || [];
-            const mappedCandles = candles.map((c) => ({
-                timestamp: c.end_period_ts * 1000,
-                open: (c.price.open || 0) / 100,
-                high: (c.price.high || 0) / 100,
-                low: (c.price.low || 0) / 100,
-                close: (c.price.close || 0) / 100,
-                volume: c.volume
-            }));
+            const mappedCandles = candles.map((c) => {
+                // Priority:
+                // 1. Transaction price (close)
+                // 2. Mid price (average of yes_ask and yes_bid close)
+                // 3. Fallback to 0 if everything is missing
+                const p = c.price || {};
+                const ask = c.yes_ask || {};
+                const bid = c.yes_bid || {};
+                const getVal = (field) => {
+                    if (p[field] !== null && p[field] !== undefined)
+                        return p[field];
+                    if (ask[field] !== null && bid[field] !== null && ask[field] !== undefined && bid[field] !== undefined) {
+                        return (ask[field] + bid[field]) / 2;
+                    }
+                    return p.previous || 0;
+                };
+                return {
+                    timestamp: c.end_period_ts * 1000,
+                    open: getVal('open') / 100,
+                    high: getVal('high') / 100,
+                    low: getVal('low') / 100,
+                    close: getVal('close') / 100,
+                    volume: c.volume || 0
+                };
+            });
             if (params.limit && mappedCandles.length > params.limit) {
                 return mappedCandles.slice(-params.limit);
             }
@@ -261,7 +278,7 @@ class KalshiExchange extends BaseExchange_1.PredictionMarketExchange {
             throw error;
         }
     }
-    async getOrderBook(id) {
+    async fetchOrderBook(id) {
         try {
             const ticker = id.replace(/-NO$/, '');
             const url = `https://api.elections.kalshi.com/trade-api/v2/markets/${ticker}/orderbook`;
@@ -286,7 +303,7 @@ class KalshiExchange extends BaseExchange_1.PredictionMarketExchange {
             return { bids: [], asks: [] };
         }
     }
-    async getTradeHistory(id, params) {
+    async fetchTrades(id, params) {
         try {
             const ticker = id.replace(/-NO$/, '');
             const url = `https://api.elections.kalshi.com/trade-api/v2/markets/trades`;

package/dist/exchanges/Polymarket.d.ts

@@ -20,19 +20,19 @@ export declare class PolymarketExchange extends PredictionMarketExchange {
      * Fetch historical price data (OHLCV candles) for a specific token.
      * @param id - The CLOB token ID (e.g., outcome token ID)
      */
-    getMarketHistory(id: string, params: HistoryFilterParams): Promise<PriceCandle[]>;
+    fetchOHLCV(id: string, params: HistoryFilterParams): Promise<PriceCandle[]>;
     /**
      * Fetch the current order book for a specific token.
      * @param id - The CLOB token ID
      */
-    getOrderBook(id: string): Promise<OrderBook>;
+    fetchOrderBook(id: string): Promise<OrderBook>;
     /**
      * Fetch raw trade history for a specific token.
      * @param id - The CLOB token ID
      *
      * NOTE: Polymarket's /trades endpoint currently requires L2 Authentication (API Key).
      * This method will return an empty array if an API key is not provided in headers.
-     * Use getMarketHistory for public historical price data instead.
+     * Use fetchOHLCV for public historical price data instead.
      */
-    getTradeHistory(id: string, params: HistoryFilterParams): Promise<Trade[]>;
+    fetchTrades(id: string, params: HistoryFilterParams): Promise<Trade[]>;
 }

package/dist/exchanges/Polymarket.js

@@ -64,6 +64,7 @@ class PolymarketExchange extends BaseExchange_1.PredictionMarketExchange {
                         outcomePrices = typeof market.outcomePrices === 'string' ? JSON.parse(market.outcomePrices) : (market.outcomePrices || []);
                     }
                     catch (e) {
+                        console.warn(`Error parsing outcomes for market ${market.id}:`, e);
                     }
                     // Extract CLOB token IDs for granular operations
                     let clobTokenIds = [];
@@ -158,8 +159,8 @@ class PolymarketExchange extends BaseExchange_1.PredictionMarketExchange {
             });
             // Client-side text filtering
             const lowerQuery = query.toLowerCase();
-            const filtered = markets.filter(market => market.title.toLowerCase().includes(lowerQuery) ||
-                market.description.toLowerCase().includes(lowerQuery));
+            const filtered = markets.filter(market => (market.title || '').toLowerCase().includes(lowerQuery) ||
+                (market.description || '').toLowerCase().includes(lowerQuery));
             // Apply limit to filtered results
             const limit = params?.limit || 20;
             return filtered.slice(0, limit);
@@ -201,7 +202,9 @@ class PolymarketExchange extends BaseExchange_1.PredictionMarketExchange {
                         outcomePrices = typeof market.outcomePrices === 'string' ? JSON.parse(market.outcomePrices) : (market.outcomePrices || []);
                         clobTokenIds = typeof market.clobTokenIds === 'string' ? JSON.parse(market.clobTokenIds) : (market.clobTokenIds || []);
                     }
-                    catch (e) { /* ignore */ }
+                    catch (e) {
+                        console.warn(`Error parsing outcomes for market ${market.id}:`, e);
+                    }
                     let candidateName = market.groupItemTitle;
                     if (!candidateName && market.question)
                         candidateName = market.question;
@@ -271,7 +274,7 @@ class PolymarketExchange extends BaseExchange_1.PredictionMarketExchange {
      * Fetch historical price data (OHLCV candles) for a specific token.
      * @param id - The CLOB token ID (e.g., outcome token ID)
      */
-    async getMarketHistory(id, params) {
+    async fetchOHLCV(id, params) {
         // ID Validation: Polymarket CLOB requires a Token ID (long numeric string) not a Market ID
         if (id.length < 10 && /^\d+$/.test(id)) {
             throw new Error(`Invalid ID for Polymarket history: "${id}". You provided a Market ID, but Polymarket's CLOB API requires a Token ID. Ensure you are using 'outcome.id'.`);
@@ -336,7 +339,7 @@ class PolymarketExchange extends BaseExchange_1.PredictionMarketExchange {
      * Fetch the current order book for a specific token.
      * @param id - The CLOB token ID
      */
-    async getOrderBook(id) {
+    async fetchOrderBook(id) {
         try {
             const response = await axios_1.default.get(`${this.clobUrl}/book`, {
                 params: { token_id: id }
@@ -368,9 +371,9 @@ class PolymarketExchange extends BaseExchange_1.PredictionMarketExchange {
      *
      * NOTE: Polymarket's /trades endpoint currently requires L2 Authentication (API Key).
      * This method will return an empty array if an API key is not provided in headers.
-     * Use getMarketHistory for public historical price data instead.
+     * Use fetchOHLCV for public historical price data instead.
      */
-    async getTradeHistory(id, params) {
+    async fetchTrades(id, params) {
         // ID Validation
         if (id.length < 10 && /^\d+$/.test(id)) {
             throw new Error(`Invalid ID for Polymarket trades: "${id}". You provided a Market ID, but Polymarket's CLOB API requires a Token ID.`);

package/dist/index.d.ts

@@ -2,3 +2,12 @@ export * from './BaseExchange';
 export * from './types';
 export * from './exchanges/Polymarket';
 export * from './exchanges/Kalshi';
+import { PolymarketExchange } from './exchanges/Polymarket';
+import { KalshiExchange } from './exchanges/Kalshi';
+declare const pmxt: {
+    polymarket: typeof PolymarketExchange;
+    kalshi: typeof KalshiExchange;
+    Polymarket: typeof PolymarketExchange;
+    Kalshi: typeof KalshiExchange;
+};
+export default pmxt;

package/dist/index.js

@@ -18,3 +18,12 @@ __exportStar(require("./BaseExchange"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./exchanges/Polymarket"), exports);
 __exportStar(require("./exchanges/Kalshi"), exports);
+const Polymarket_1 = require("./exchanges/Polymarket");
+const Kalshi_1 = require("./exchanges/Kalshi");
+const pmxt = {
+    polymarket: Polymarket_1.PolymarketExchange,
+    kalshi: Kalshi_1.KalshiExchange,
+    Polymarket: Polymarket_1.PolymarketExchange,
+    Kalshi: Kalshi_1.KalshiExchange
+};
+exports.default = pmxt;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmxtjs",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "pmxt is a unified prediction market data API. The ccxt for prediction markets.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,7 +26,9 @@
     "tsx": "^4.21.0"
   },
   "devDependencies": {
+    "@types/jest": "^30.0.0",
     "@types/node": "^25.0.3",
+    "ts-jest": "^29.4.6",
     "typescript": "^5.9.3"
   }
-}
+}

package/readme.md

@@ -57,13 +57,13 @@ Different prediction market platforms have different APIs, data formats, and con
 Search for markets across Polymarket and Kalshi using the same API:
 
 ```typescript
-import { PolymarketExchange, KalshiExchange } from 'pmxtjs';
+import pmxt from 'pmxtjs';
 
 const query = process.argv[2] || 'Who will Trump nominate as Fed Chair?';
 console.log(`Searching for "${query}"...\n`);
 
 // Polymarket
-const polymarket = new PolymarketExchange();
+const polymarket = new pmxt.polymarket();
 const polyResults = await polymarket.searchMarkets(query, { sort: 'volume' });
 
 console.log(`--- Polymarket Found ${polyResults.length} ---`);
@@ -73,7 +73,7 @@ polyResults.slice(0, 10).forEach(m => {
 });
 
 // Kalshi
-const kalshi = new KalshiExchange();
+const kalshi = new pmxt.kalshi();
 const kalshiResults = await kalshi.searchMarkets(query);
 
 console.log(`\n--- Kalshi Found ${kalshiResults.length} ---`);