pmxtjs 0.1.1 → 0.1.2

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/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 or outcome.
+     * @param id - The market ID or specific outcome ID/Token ID depending on the exchange
+     */
+    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/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) {

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;
@@ -202,9 +200,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;

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.1.2",
   "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",
@@ -22,5 +23,9 @@
   "dependencies": {
     "axios": "^1.7.9",
     "tsx": "^4.21.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "@types/node": "^25.0.3"
   }
 }

package/readme.md

@@ -0,0 +1,62 @@
+# pmxt
+
+**The ccxt for prediction markets.** A unified API for accessing prediction market data across multiple exchanges.
+
+## 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] || 'Fed';
+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