pmxtjs 0.1.1 → 0.2.0

package/API_REFERENCE.md

@@ -0,0 +1,88 @@
+# Prediction Market API Reference
+
+This project implements a **Unified Interface** for interacting with multiple prediction market exchanges (Kalshi, Polymarket) identically.
+
+## Usage
+
+All components are available directly from the `pmxt` library.
+
+```typescript
+import { 
+  PolymarketExchange, 
+  KalshiExchange
+} from './pmxt';
+
+const polymarket = new PolymarketExchange();
+const kalshi = new KalshiExchange();
+```
+
+## 1. Unified Interface (`PredictionMarketExchange`)
+
+All exchanges implement this core interface for discovery.
+
+### `fetchMarkets(params?)`
+Retrieves active markets normalized into a standard format.
+- **Input**: `limit`, `sort` ('volume' | 'liquidity' | 'newest')
+- **Output**: `Promise<UnifiedMarket[]>`
+
+### `searchMarkets(query, params?)`
+Search markets by title/description across the exchange(s).
+- **Input**: `query` (string), `limit`
+- **Output**: `Promise<UnifiedMarket[]>`
+
+---
+
+## 2. Deep-Dive Interface (Exchange Only)
+
+Methods available on specific exchange instances (`KalshiExchange`, `PolymarketExchange`) for detailed data.
+
+### `getMarketHistory(id, params)`
+Fetches OHLCV candlesticks.
+- **Input**: `id`, `resolution` (1m, 1h, 1d), `start`, `end`.
+- **Output**: `Promise<PriceCandle[]>`
+- **Important**:
+  - **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)`
+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)`
+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.
+
+---
+
+## 3. Data Models
+
+### `UnifiedMarket` (The Standard Atom)
+```typescript
+{
+  id: string;          // Exchange-specific ID
+  title: string;       // "Who will win the election?"
+  description: string; // Detailed context/rules of the market
+  outcomes: [
+    { 
+      id: string, 
+      label: "Trump", 
+      price: 0.52,
+      priceChange24h: 0.05, // Optional: Change in price over last 24h
+      metadata: { ... }      // Exchange-specific keys (clobTokenId)
+    }
+  ];
+  resolutionDate: Date;
+  volume24h: number;
+  liquidity: number;
+  url: string;
+  image?: string;       // Optional: Thumbnail URL
+  category?: string;    // Optional: Primary category (e.g., "Politics")
+  tags?: string[];      // Optional: Searchable tags
+}
+```
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qoery.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/BaseExchange.d.ts

@@ -0,0 +1,39 @@
+import { UnifiedMarket, PriceCandle, CandleInterval, OrderBook, Trade } from './types';
+export interface MarketFilterParams {
+    limit?: number;
+    offset?: number;
+    sort?: 'volume' | 'liquidity' | 'newest';
+}
+export interface HistoryFilterParams {
+    resolution: CandleInterval;
+    start?: Date;
+    end?: Date;
+    limit?: number;
+}
+export declare abstract class PredictionMarketExchange {
+    abstract get name(): string;
+    /**
+     * Fetch all relevant markets from the source.
+     */
+    abstract fetchMarkets(params?: MarketFilterParams): Promise<UnifiedMarket[]>;
+    /**
+     * Search for markets matching a keyword query.
+     * Searches across title and description fields.
+     */
+    abstract searchMarkets(query: string, params?: MarketFilterParams): Promise<UnifiedMarket[]>;
+    /**
+     * 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[]>;
+    /**
+     * Fetch the current order book (bids/asks) for a specific outcome.
+     * Essential for calculating localized spread and depth.
+     */
+    getOrderBook(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[]>;
+}

package/dist/BaseExchange.js

@@ -6,8 +6,8 @@ exports.PredictionMarketExchange = void 0;
 // ----------------------------------------------------------------------------
 class PredictionMarketExchange {
     /**
-     * Fetch historical price data for a specific market or outcome.
-     * @param id - The market ID or specific outcome ID/Token ID depending on the exchange
+     * 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.");

package/dist/exchanges/Kalshi.d.ts

@@ -0,0 +1,20 @@
+import { PredictionMarketExchange, MarketFilterParams, HistoryFilterParams } from '../BaseExchange';
+import { UnifiedMarket, PriceCandle, OrderBook, Trade } from '../types';
+export declare class KalshiExchange extends PredictionMarketExchange {
+    get name(): string;
+    private baseUrl;
+    fetchMarkets(params?: MarketFilterParams): Promise<UnifiedMarket[]>;
+    private fetchActiveEvents;
+    private mapMarketToUnified;
+    searchMarkets(query: string, params?: MarketFilterParams): Promise<UnifiedMarket[]>;
+    /**
+     * Fetch specific markets by their event ticker.
+     * Useful for looking up a specific event from a URL.
+     * @param eventTicker - The event ticker (e.g. "FED-25JAN" or "PRES-2024")
+     */
+    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[]>;
+}

package/dist/exchanges/Kalshi.js

@@ -31,7 +31,6 @@ class KalshiExchange extends BaseExchange_1.PredictionMarketExchange {
                     }
                 }
             }
-            console.log(`Extracted ${allMarkets.length} markets from ${allEvents.length} events.`);
             // Sort by 24h volume
             if (params?.sort === 'volume') {
                 allMarkets.sort((a, b) => b.volume24h - a.volume24h);
@@ -77,25 +76,18 @@ class KalshiExchange extends BaseExchange_1.PredictionMarketExchange {
                         totalMarketCount += (event.markets || []).length;
                     }
                     // Early termination: if we have enough markets, stop fetching
-                    // Add a buffer (2x) to ensure we have enough after filtering/sorting
                     if (totalMarketCount >= targetMarketCount * 2) {
-                        console.log(`Early termination: collected ${totalMarketCount} markets (target: ${targetMarketCount})`);
                         break;
                     }
                 }
                 cursor = response.data.cursor;
                 page++;
-                // Log progress every few pages to avoid spam
-                if (page % 5 === 0) {
-                    console.log(`Fetched ${page} pages (${allEvents.length} events) from Kalshi...`);
-                }
             }
             catch (e) {
                 console.error(`Error fetching Kalshi page ${page}:`, e);
                 break;
             }
         } while (cursor && page < MAX_PAGES);
-        console.log(`Finished fetching Kalshi: ${allEvents.length} total events across ${page} pages.`);
         return allEvents;
     }
     mapMarketToUnified(event, market) {
@@ -124,13 +116,13 @@ class KalshiExchange extends BaseExchange_1.PredictionMarketExchange {
         }
         const outcomes = [
             {
-                id: 'yes',
+                id: market.ticker, // The actual market ticker (primary tradeable)
                 label: candidateName || 'Yes',
                 price: price,
                 priceChange24h: priceChange
             },
             {
-                id: 'no',
+                id: `${market.ticker}-NO`, // Virtual ID for the No outcome
                 label: candidateName ? `Not ${candidateName}` : 'No',
                 price: 1 - price,
                 priceChange24h: -priceChange // Inverse change for No? simplified assumption
@@ -219,7 +211,9 @@ class KalshiExchange extends BaseExchange_1.PredictionMarketExchange {
     async getMarketHistory(id, params) {
         try {
             // Kalshi API expects uppercase tickers
-            const normalizedId = id.toUpperCase();
+            // Handle virtual "-NO" suffix by stripping it (fetching the underlying market history)
+            const cleanedId = id.replace(/-NO$/, '');
+            const normalizedId = cleanedId.toUpperCase();
             const interval = this.mapIntervalToKalshi(params.resolution);
             // Heuristic for series_ticker
             const parts = normalizedId.split('-');
@@ -269,7 +263,8 @@ class KalshiExchange extends BaseExchange_1.PredictionMarketExchange {
     }
     async getOrderBook(id) {
         try {
-            const url = `https://api.elections.kalshi.com/trade-api/v2/markets/${id}/orderbook`;
+            const ticker = id.replace(/-NO$/, '');
+            const url = `https://api.elections.kalshi.com/trade-api/v2/markets/${ticker}/orderbook`;
             const response = await axios_1.default.get(url);
             const data = response.data.orderbook;
             // Structure: { yes: [[price, qty], ...], no: [[price, qty], ...] }
@@ -293,10 +288,11 @@ class KalshiExchange extends BaseExchange_1.PredictionMarketExchange {
     }
     async getTradeHistory(id, params) {
         try {
+            const ticker = id.replace(/-NO$/, '');
             const url = `https://api.elections.kalshi.com/trade-api/v2/markets/trades`;
             const response = await axios_1.default.get(url, {
                 params: {
-                    ticker: id,
+                    ticker: ticker,
                     limit: params.limit || 100
                 }
             });

package/dist/exchanges/Polymarket.d.ts

@@ -0,0 +1,38 @@
+import { PredictionMarketExchange, MarketFilterParams, HistoryFilterParams } from '../BaseExchange';
+import { UnifiedMarket, PriceCandle, OrderBook, Trade } from '../types';
+export declare class PolymarketExchange extends PredictionMarketExchange {
+    get name(): string;
+    private readonly baseUrl;
+    private readonly clobUrl;
+    fetchMarkets(params?: MarketFilterParams): Promise<UnifiedMarket[]>;
+    searchMarkets(query: string, params?: MarketFilterParams): Promise<UnifiedMarket[]>;
+    /**
+     * Fetch specific markets by their URL slug.
+     * Useful for looking up a specific event from a URL.
+     * @param slug - The event slug (e.g. "will-fed-cut-rates-in-march")
+     */
+    getMarketsBySlug(slug: string): Promise<UnifiedMarket[]>;
+    /**
+     * Map our generic CandleInterval to Polymarket's fidelity (in minutes)
+     */
+    private mapIntervalToFidelity;
+    /**
+     * 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[]>;
+    /**
+     * Fetch the current order book for a specific token.
+     * @param id - The CLOB token ID
+     */
+    getOrderBook(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.
+     */
+    getTradeHistory(id: string, params: HistoryFilterParams): Promise<Trade[]>;
+}

package/dist/exchanges/Polymarket.js

@@ -64,7 +64,6 @@ class PolymarketExchange extends BaseExchange_1.PredictionMarketExchange {
                         outcomePrices = typeof market.outcomePrices === 'string' ? JSON.parse(market.outcomePrices) : (market.outcomePrices || []);
                     }
                     catch (e) {
-                        console.warn(`Failed to parse outcomes for market ${market.id}`, e);
                     }
                     // Extract CLOB token IDs for granular operations
                     let clobTokenIds = [];
@@ -72,7 +71,6 @@ class PolymarketExchange extends BaseExchange_1.PredictionMarketExchange {
                         clobTokenIds = typeof market.clobTokenIds === 'string' ? JSON.parse(market.clobTokenIds) : (market.clobTokenIds || []);
                     }
                     catch (e) {
-                        console.warn(`Failed to parse clobTokenIds for market ${market.id}`, e);
                     }
                     // Extract candidate/option name from market question for better outcome labels
                     let candidateName = null;
@@ -97,11 +95,12 @@ class PolymarketExchange extends BaseExchange_1.PredictionMarketExchange {
                                 priceChange = Number(market.oneDayPriceChange || 0);
                             }
                             outcomes.push({
-                                id: String(index),
+                                id: clobTokenIds[index] || String(index), // Use CLOB Token ID as the primary ID
                                 label: outcomeLabel,
                                 price: parseFloat(rawPrice) || 0,
                                 priceChange24h: priceChange,
                                 metadata: {
+                                    // clobTokenId is now the main ID, but keeping it in metadata for backward compat if needed
                                     clobTokenId: clobTokenIds[index]
                                 }
                             });
@@ -202,9 +201,7 @@ 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) {
-                        console.warn(`Parse error for market ${market.id}`, e);
-                    }
+                    catch (e) { /* ignore */ }
                     let candidateName = market.groupItemTitle;
                     if (!candidateName && market.question)
                         candidateName = market.question;
@@ -222,7 +219,7 @@ class PolymarketExchange extends BaseExchange_1.PredictionMarketExchange {
                                 priceChange = Number(market.oneDayPriceChange || 0);
                             }
                             outcomes.push({
-                                id: String(index),
+                                id: clobTokenIds[index] || String(index),
                                 label: outcomeLabel,
                                 price: parseFloat(outcomePrices[index] || "0") || 0,
                                 priceChange24h: priceChange,
@@ -277,7 +274,7 @@ class PolymarketExchange extends BaseExchange_1.PredictionMarketExchange {
     async getMarketHistory(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. Use outcome.metadata.clobTokenId instead.`);
+            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'.`);
         }
         try {
             const fidelity = this.mapIntervalToFidelity(params.resolution);

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './BaseExchange';
+export * from './types';
+export * from './exchanges/Polymarket';
+export * from './exchanges/Kalshi';

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+export interface MarketOutcome {
+    id: string;
+    label: string;
+    price: number;
+    priceChange24h?: number;
+    metadata?: Record<string, any>;
+}
+export interface UnifiedMarket {
+    id: string;
+    title: string;
+    description: string;
+    outcomes: MarketOutcome[];
+    resolutionDate: Date;
+    volume24h: number;
+    volume?: number;
+    liquidity: number;
+    openInterest?: number;
+    url: string;
+    image?: string;
+    category?: string;
+    tags?: string[];
+}
+export type CandleInterval = '1m' | '5m' | '15m' | '1h' | '6h' | '1d';
+export interface PriceCandle {
+    timestamp: number;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume?: number;
+}
+export interface OrderLevel {
+    price: number;
+    size: number;
+}
+export interface OrderBook {
+    bids: OrderLevel[];
+    asks: OrderLevel[];
+    timestamp?: number;
+}
+export interface Trade {
+    id: string;
+    timestamp: number;
+    price: number;
+    amount: number;
+    side: 'buy' | 'sell' | 'unknown';
+}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "pmxtjs",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "pmxt is a unified prediction market data API. The ccxt for prediction markets.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "API_REFERENCE.md"
   ],
   "directories": {
     "example": "examples",
@@ -17,10 +18,15 @@
   },
   "keywords": [],
   "author": "",
-  "license": "ISC",
+  "license": "MIT",
   "type": "commonjs",
   "dependencies": {
     "axios": "^1.7.9",
+    "jest": "^30.2.0",
     "tsx": "^4.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "typescript": "^5.9.3"
   }
-}
+}

package/readme.md

@@ -0,0 +1,111 @@
+# pmxt [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?text=The%20ccxt%20for%20prediction%20markets.&url=https://github.com/qoery-com/pmxt&hashtags=predictionmarkets,trading)
+
+**The ccxt for prediction markets.** A unified API for accessing prediction market data across multiple exchanges.
+
+<img width="3840" height="2160" alt="plot" src="https://github.com/user-attachments/assets/ed77d244-c95f-4fe0-a7a7-89af713c053f" />
+
+<div align="center">
+<table>
+<tr>
+<td rowspan="3">
+<a href="https://www.producthunt.com/products/qoery-python-sdk?embed=true&amp;utm_source=badge-featured&amp;utm_medium=badge&amp;utm_campaign=badge-qoery-python-sdk" target="_blank" rel="noopener noreferrer"><img alt="Qoery Python SDK - 50% cheaper crypto data. Now in Python. | Product Hunt" width="250" height="54" src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1056631&amp;theme=light&amp;t=1767263265752"></a>
+</td>
+<td>
+<img src="https://img.shields.io/github/watchers/qoery-com/pmxt?style=social" alt="GitHub watchers">
+</td>
+<td>
+<a href="https://www.npmjs.com/package/pmxtjs"><img src="https://img.shields.io/npm/dt/pmxtjs" alt="Downloads"></a>
+</td>
+</tr>
+<tr>
+<td>
+<img src="https://img.shields.io/github/forks/qoery-com/pmxt?style=social" alt="GitHub forks">
+</td>
+<td>
+<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License"></a>
+</td>
+</tr>
+<tr>
+<td>
+<a href="https://github.com/qoery-com/pmxt/stargazers"><img src="https://img.shields.io/github/stars/qoery-com/pmxt?refresh=1" alt="GitHub stars"></a>
+</td>
+<td>
+<!-- Space for future badge -->
+</td>
+</tr>
+</table>
+</div>
+
+<p align="center">
+<img src="https://polymarket.com/favicon.ico" alt="Polymarket" width="40" height="40">
+&nbsp;&nbsp;&nbsp;&nbsp;
+<img src="https://kalshi.com/favicon.ico" alt="Kalshi" width="40" height="40">
+&nbsp;&nbsp;&nbsp;&nbsp;
+<img src="https://manifold.markets/logo.svg" alt="Manifold Markets" width="40" height="40">
+&nbsp;&nbsp;&nbsp;&nbsp;
+<img src="https://metaculus.com/favicon.ico" alt="Metaculus" width="40" height="40">
+&nbsp;&nbsp;&nbsp;&nbsp;
+<img src="https://predictit.org/favicon.ico" alt="PredictIt" width="40" height="40">
+</p>
+
+## Why pmxt?
+
+Different prediction market platforms have different APIs, data formats, and conventions. pmxt provides a single, consistent interface to work with all of them.
+
+## Quick Example
+
+Search for markets across Polymarket and Kalshi using the same API:
+
+```typescript
+import { PolymarketExchange, KalshiExchange } 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 polyResults = await polymarket.searchMarkets(query, { sort: 'volume' });
+
+console.log(`--- Polymarket Found ${polyResults.length} ---`);
+polyResults.slice(0, 10).forEach(m => {
+    const label = m.outcomes[0]?.label || 'Unknown';
+    console.log(`[${m.id}] ${m.title} - ${label} (Vol24h: $${m.volume24h.toLocaleString()})`);
+});
+
+// Kalshi
+const kalshi = new KalshiExchange();
+const kalshiResults = await kalshi.searchMarkets(query);
+
+console.log(`\n--- Kalshi Found ${kalshiResults.length} ---`);
+kalshiResults.slice(0, 10).forEach(m => {
+    const label = m.outcomes[0]?.label || 'Unknown';
+    console.log(`[${m.id}] ${m.title} - ${label} (Vol24h: $${m.volume24h.toLocaleString()})`);
+});
+```
+
+## Installation
+
+```bash
+npm install pmxtjs
+```
+
+## Supported Exchanges
+
+- Polymarket
+- Kalshi
+
+## Documentation
+
+See the [API Reference](pmxt/API_REFERENCE.md) for detailed documentation and more examples.
+
+## Examples
+
+Check out the [examples](pmxt/examples/) directory for more use cases:
+- Market search
+- Order book data
+- Historical prices
+- Event price tracking
+- Recent trades
+
+
+[![Stargazers repo roster for @qoery-com/pmxt](https://reporoster.com/stars/qoery-com/pmxt)](https://github.com/qoery-com/pmxt/stargazers)