pmxtjs 0.3.0 → 0.4.0

package/API_REFERENCE.md

@@ -1,86 +1,483 @@
 # Prediction Market API Reference
 
-This project implements a **Unified Interface** for interacting with multiple prediction market exchanges (Kalshi, Polymarket) identically.
+A unified interface for interacting with multiple prediction market exchanges (Kalshi, Polymarket) identically.
 
-## Usage
+## Installation & Usage
 
-All components are available directly from the `pmxt` library.
+```bash
+npm install pmxtjs
+```
 
 ```typescript
 import pmxt from 'pmxtjs';
 
-// ccxt-style instantiation
 const polymarket = new pmxt.polymarket();
 const kalshi = new pmxt.kalshi();
 ```
 
-## 1. Unified Interface (`PredictionMarketExchange`)
+---
 
-All exchanges implement this core interface for discovery.
+## Core Methods
 
 ### `fetchMarkets(params?)`
-Retrieves active markets normalized into a standard format.
-- **Input**: `limit`, `sort` ('volume' | 'liquidity' | 'newest')
-- **Output**: `Promise<UnifiedMarket[]>`
+Get active markets from an exchange.
+
+```typescript
+const markets = await polymarket.fetchMarkets({ 
+  limit: 20, 
+  offset: 0,
+  sort: 'volume' // 'volume' | 'liquidity' | 'newest'
+});
+```
 
 ### `searchMarkets(query, params?)`
-Search markets by title/description across the exchange(s).
-- **Input**: `query` (string), `limit`
-- **Output**: `Promise<UnifiedMarket[]>`
+Search markets by keyword. By default, searches only in titles.
+
+```typescript
+const results = await kalshi.searchMarkets('Fed rates', { 
+  limit: 10,
+  searchIn: 'title' // 'title' (default) | 'description' | 'both'
+});
+```
+
+### `getMarketsBySlug(slug)`
+Fetch markets by URL slug/ticker.
+
+```typescript
+// Polymarket: use URL slug
+const polyMarkets = await polymarket.getMarketsBySlug('who-will-trump-nominate-as-fed-chair');
+
+// Kalshi: use event ticker (auto-uppercased)
+const kalshiMarkets = await kalshi.getMarketsBySlug('FED-25JAN');
+```
 
 ---
 
-## 2. Deep-Dive Interface (Exchange Only)
+## Deep-Dive Methods
+
+### `fetchOHLCV(outcomeId, params)`
+Get historical price candles.
+
+**CRITICAL**: Use `outcome.id`, not `market.id`.
+- **Polymarket**: `outcome.id` is the CLOB Token ID
+- **Kalshi**: `outcome.id` is the Market Ticker
+
+```typescript
+const markets = await polymarket.searchMarkets('Trump');
+const outcomeId = markets[0].outcomes[0].id; // Get the outcome ID
+
+const candles = await polymarket.fetchOHLCV(outcomeId, {
+  resolution: '1h', // '1m' | '5m' | '15m' | '1h' | '6h' | '1d'
+  start: new Date('2024-01-01'),
+  end: new Date('2024-01-31'),
+  limit: 100
+});
+```
+
+### `fetchOrderBook(outcomeId)`
+Get current bids/asks.
 
-Methods available on specific exchange instances (`KalshiExchange`, `PolymarketExchange`) for detailed data.
+```typescript
+const orderBook = await kalshi.fetchOrderBook('FED-25JAN');
+console.log('Best bid:', orderBook.bids[0].price);
+console.log('Best ask:', orderBook.asks[0].price);
+```
 
-### `fetchOHLCV(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.
+### `fetchTrades(outcomeId, params)`
+Get trade history.
 
-### `fetchOrderBook(id)`
-Fetches live Bids/Asks.
-- **Input**: `id` (Ticker for Kalshi, Token ID for Polymarket).
-- **Output**: `Promise<OrderBook>` (Normalized: "No" bids becomes "Yes" asks).
+**Note**: Polymarket requires API key. Use `fetchOHLCV` for public historical data.
 
-### `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 `fetchOHLCV` for public historical data.
+```typescript
+const trades = await kalshi.fetchTrades('FED-25JAN', {
+  resolution: '1h',
+  limit: 100
+});
+```
 
 ---
 
-## 3. Data Models
+## Data Models
 
-### `UnifiedMarket` (The Standard Atom)
+### `UnifiedMarket`
 ```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)
-    }
-  ];
+  id: string;              // Market ID
+  title: string;
+  description: string;
+  outcomes: MarketOutcome[]; // All tradeable outcomes
+  
   resolutionDate: Date;
-  volume24h: number;
-  liquidity: number;
+  volume24h: number;       // USD
+  volume?: number;         // Total volume (USD)
+  liquidity: number;       // USD
+  openInterest?: number;   // USD
+  
   url: string;
-  image?: string;       // Optional: Thumbnail URL
-  category?: string;    // Optional: Primary category (e.g., "Politics")
-  tags?: string[];      // Optional: Searchable tags
+  image?: string;
+  category?: string;
+  tags?: string[];
+}
+```
+
+### `MarketOutcome`
+```typescript
+{
+  id: string;              // Use this for fetchOHLCV/fetchOrderBook/fetchTrades
+                           // Polymarket: CLOB Token ID
+                           // Kalshi: Market Ticker
+  label: string;           // "Trump", "Yes", etc.
+  price: number;           // 0.0 to 1.0 (probability)
+  priceChange24h?: number;
+  metadata?: {
+    clobTokenId?: string;  // Polymarket only
+  }
+}
+```
+
+### Other Types
+```typescript
+interface PriceCandle {
+  timestamp: number;       // Unix ms
+  open: number;            // 0.0 to 1.0
+  high: number;
+  low: number;
+  close: number;
+  volume?: number;
+}
+
+interface OrderBook {
+  bids: OrderLevel[];      // Sorted high to low
+  asks: OrderLevel[];      // Sorted low to high
+  timestamp?: number;
+}
+
+interface OrderLevel {
+  price: number;           // 0.0 to 1.0
+  size: number;            // Contracts
+}
+
+interface Trade {
+  id: string;
+  timestamp: number;       // Unix ms
+  price: number;           // 0.0 to 1.0
+  amount: number;
+  side: 'buy' | 'sell' | 'unknown';
+}
+```
+
+---
+
+## Complete Workflow Example
+
+```typescript
+// 1. Search for markets
+const markets = await polymarket.searchMarkets('Fed Chair');
+const market = markets[0];
+
+// 2. Get outcome details
+const outcome = market.outcomes[0];
+console.log(`${outcome.label}: ${(outcome.price * 100).toFixed(1)}%`);
+
+// 3. Fetch historical data (use outcome.id!)
+const candles = await polymarket.fetchOHLCV(outcome.id, {
+  resolution: '1d',
+  limit: 30
+});
+
+// 4. Get current order book
+const orderBook = await polymarket.fetchOrderBook(outcome.id);
+const spread = orderBook.asks[0].price - orderBook.bids[0].price;
+console.log(`Spread: ${(spread * 100).toFixed(2)}%`);
+```
+
+---
+
+## Exchange Differences
+
+| Feature | Polymarket | Kalshi |
+|---------|-----------|--------|
+| **Sorting** | Server-side | Client-side (slower for large sets) |
+| **Market ID** | UUID | Event Ticker (e.g., "PRES-2024") |
+| **Outcome ID** | CLOB Token ID | Market Ticker (e.g., "FED-25JAN") |
+| **OHLCV Quality** | Synthetic (O=H=L=C) | Native (distinct values) |
+| **Auth Required** | Only for `fetchTrades()` | No (all public) |
+| **Slug Format** | lowercase-with-hyphens | UPPERCASE (auto-normalized) |
+
+---
+
+## Error Handling
+
+```typescript
+try {
+  const markets = await kalshi.getMarketsBySlug('INVALID-TICKER');
+} catch (error) {
+  // Kalshi: "Event not found: INVALID-TICKER"
+  // Polymarket: Returns empty array []
+  console.error(error.message);
+}
+```
+
+**Common Errors**:
+- `404`: Market/event doesn't exist
+- `401`: Missing API key (Polymarket `fetchTrades`)
+- `429`: Rate limited
+- `500`: Exchange API issue
+
+---
+
+## Type Exports
+
+```typescript
+import pmxt, { 
+  UnifiedMarket,
+  MarketOutcome,
+  PriceCandle,
+  OrderBook,
+  Trade,
+  CandleInterval,
+  MarketFilterParams,
+  HistoryFilterParams
+} from 'pmxtjs';
+```
+
+---
+
+## Authentication & Trading
+
+Both Polymarket and Kalshi support authenticated trading operations. You must provide credentials when initializing the exchange.
+
+### Polymarket Authentication
+
+Requires your **Polygon Private Key**. See [Setup Guide](docs/SETUP_POLYMARKET.md) for details.
+
+```typescript
+import pmxt from 'pmxtjs';
+
+const polymarket = new pmxt.Polymarket({
+  privateKey: process.env.POLYMARKET_PRIVATE_KEY
+});
+```
+
+### Kalshi Authentication
+
+Requires **API Key** and **Private Key**.
+
+```typescript
+import pmxt from 'pmxtjs';
+
+const kalshi = new pmxt.Kalshi({
+  apiKey: process.env.KALSHI_API_KEY,
+  privateKey: process.env.KALSHI_PRIVATE_KEY
+});
+```
+
+---
+
+## Account Methods
+
+### `fetchBalance()`
+Get your account balance.
+
+```typescript
+const balances = await polymarket.fetchBalance();
+console.log(balances);
+// [{ currency: 'USDC', total: 1000, available: 950, locked: 50 }]
+```
+
+**Returns**: `Balance[]`
+```typescript
+interface Balance {
+  currency: string;   // e.g., 'USDC'
+  total: number;      // Total balance
+  available: number;  // Available for trading
+  locked: number;     // Locked in open orders
+}
+```
+
+### `fetchPositions()`
+Get your current positions across all markets.
+
+```typescript
+const positions = await kalshi.fetchPositions();
+positions.forEach(pos => {
+  console.log(`${pos.outcomeLabel}: ${pos.size} @ $${pos.entryPrice}`);
+  console.log(`Unrealized P&L: $${pos.unrealizedPnL}`);
+});
+```
+
+**Returns**: `Position[]`
+```typescript
+interface Position {
+  marketId: string;
+  outcomeId: string;
+  outcomeLabel: string;
+  size: number;           // Positive for long, negative for short
+  entryPrice: number;
+  currentPrice: number;
+  unrealizedPnL: number;
+  realizedPnL?: number;
+}
+```
+
+---
+
+## Trading Methods
+
+### `createOrder(params)`
+Place a new order (market or limit).
+
+**Limit Order Example**:
+```typescript
+const order = await polymarket.createOrder({
+  marketId: '663583',
+  outcomeId: '10991849228756847439673778874175365458450913336396982752046655649803657501964',
+  side: 'buy',
+  type: 'limit',
+  amount: 10,        // Number of contracts
+  price: 0.55        // Required for limit orders (0.0-1.0)
+});
+
+console.log(`Order ${order.id}: ${order.status}`);
+```
+
+**Market Order Example**:
+```typescript
+const order = await kalshi.createOrder({
+  marketId: 'FED-25JAN',
+  outcomeId: 'FED-25JAN-YES',
+  side: 'sell',
+  type: 'market',
+  amount: 5          // Price not needed for market orders
+});
+```
+
+**Parameters**: `CreateOrderParams`
+```typescript
+interface CreateOrderParams {
+  marketId: string;
+  outcomeId: string;      // Use outcome.id from market data
+  side: 'buy' | 'sell';
+  type: 'market' | 'limit';
+  amount: number;         // Number of contracts/shares
+  price?: number;         // Required for limit orders (0.0-1.0)
+}
+```
+
+**Returns**: `Order`
+```typescript
+interface Order {
+  id: string;
+  marketId: string;
+  outcomeId: string;
+  side: 'buy' | 'sell';
+  type: 'market' | 'limit';
+  price?: number;
+  amount: number;
+  status: 'pending' | 'open' | 'filled' | 'cancelled' | 'rejected';
+  filled: number;         // Amount filled so far
+  remaining: number;      // Amount remaining
+  timestamp: number;
+  fee?: number;
+}
+```
+
+### `cancelOrder(orderId)`
+Cancel an open order.
+
+```typescript
+const cancelledOrder = await polymarket.cancelOrder('order-123');
+console.log(cancelledOrder.status); // 'cancelled'
+```
+
+**Returns**: `Order` (with updated status)
+
+### `fetchOrder(orderId)`
+Get details of a specific order.
+
+```typescript
+const order = await kalshi.fetchOrder('order-456');
+console.log(`Filled: ${order.filled}/${order.amount}`);
+```
+
+**Returns**: `Order`
+
+### `fetchOpenOrders(marketId?)`
+Get all open orders, optionally filtered by market.
+
+```typescript
+// All open orders
+const allOrders = await polymarket.fetchOpenOrders();
+
+// Open orders for specific market
+const marketOrders = await kalshi.fetchOpenOrders('FED-25JAN');
+
+allOrders.forEach(order => {
+  console.log(`${order.side} ${order.amount} @ ${order.price}`);
+});
+```
+
+**Returns**: `Order[]`
+
+---
+
+## Complete Trading Workflow
+
+```typescript
+import pmxt from 'pmxtjs';
+
+const exchange = new pmxt.Polymarket({
+  privateKey: process.env.POLYMARKET_PRIVATE_KEY
+});
+
+// 1. Check balance
+const [balance] = await exchange.fetchBalance();
+console.log(`Available: $${balance.available}`);
+
+// 2. Search for a market
+const markets = await exchange.searchMarkets('Trump');
+const market = markets[0];
+const outcome = market.outcomes[0];
+
+// 3. Place a limit order
+const order = await exchange.createOrder({
+  marketId: market.id,
+  outcomeId: outcome.id,
+  side: 'buy',
+  type: 'limit',
+  amount: 10,
+  price: 0.50
+});
+
+console.log(`Order placed: ${order.id}`);
+
+// 4. Check order status
+const updatedOrder = await exchange.fetchOrder(order.id);
+console.log(`Status: ${updatedOrder.status}`);
+console.log(`Filled: ${updatedOrder.filled}/${updatedOrder.amount}`);
+
+// 5. Cancel if needed
+if (updatedOrder.status === 'open') {
+  await exchange.cancelOrder(order.id);
+  console.log('Order cancelled');
 }
+
+// 6. Check positions
+const positions = await exchange.fetchPositions();
+positions.forEach(pos => {
+  console.log(`${pos.outcomeLabel}: ${pos.unrealizedPnL > 0 ? '+' : ''}$${pos.unrealizedPnL.toFixed(2)}`);
+});
 ```
 
+---
+
+## Quick Reference
+
+- **Prices**: Always 0.0-1.0 (multiply by 100 for %)
+- **Timestamps**: Unix milliseconds
+- **Volumes**: USD
+- **IDs**: Use `outcome.id` for deep-dive methods, not `market.id`
+- **Authentication**: Required for all trading and account methods
+
+For more examples, see [`examples/`](examples/).
+

package/dist/BaseExchange.d.ts

@@ -1,8 +1,9 @@
-import { UnifiedMarket, PriceCandle, CandleInterval, OrderBook, Trade } from './types';
+import { UnifiedMarket, PriceCandle, CandleInterval, OrderBook, Trade, Order, Position, Balance, CreateOrderParams } from './types';
 export interface MarketFilterParams {
     limit?: number;
     offset?: number;
     sort?: 'volume' | 'liquidity' | 'newest';
+    searchIn?: 'title' | 'description' | 'both';
 }
 export interface HistoryFilterParams {
     resolution: CandleInterval;
@@ -10,7 +11,17 @@ export interface HistoryFilterParams {
     end?: Date;
     limit?: number;
 }
+export interface ExchangeCredentials {
+    apiKey?: string;
+    apiSecret?: string;
+    passphrase?: string;
+    privateKey?: string;
+    signatureType?: number;
+    funderAddress?: string;
+}
 export declare abstract class PredictionMarketExchange {
+    protected credentials?: ExchangeCredentials;
+    constructor(credentials?: ExchangeCredentials);
     abstract get name(): string;
     /**
      * Fetch all relevant markets from the source.
@@ -18,7 +29,7 @@ export declare abstract class PredictionMarketExchange {
     abstract fetchMarkets(params?: MarketFilterParams): Promise<UnifiedMarket[]>;
     /**
      * Search for markets matching a keyword query.
-     * Searches across title and description fields.
+     * By default, searches only in market titles. Use params.searchIn to search descriptions or both.
      */
     abstract searchMarkets(query: string, params?: MarketFilterParams): Promise<UnifiedMarket[]>;
     /**
@@ -33,7 +44,31 @@ export declare abstract class PredictionMarketExchange {
     fetchOrderBook(id: string): Promise<OrderBook>;
     /**
      * Fetch raw trade history.
-     * Useful for generating synthetic OHLCV candles if the exchange doesn't provide them natively.
      */
     fetchTrades(id: string, params: HistoryFilterParams): Promise<Trade[]>;
+    /**
+     * Place a new order.
+     */
+    createOrder(params: CreateOrderParams): Promise<Order>;
+    /**
+     * Cancel an existing order.
+     */
+    cancelOrder(orderId: string): Promise<Order>;
+    /**
+     * Fetch a specific order by ID.
+     */
+    fetchOrder(orderId: string): Promise<Order>;
+    /**
+     * Fetch all open orders.
+     * @param marketId - Optional filter by market.
+     */
+    fetchOpenOrders(marketId?: string): Promise<Order[]>;
+    /**
+     * Fetch current user positions.
+     */
+    fetchPositions(): Promise<Position[]>;
+    /**
+     * Fetch account balances.
+     */
+    fetchBalance(): Promise<Balance[]>;
 }

package/dist/BaseExchange.js

@@ -5,6 +5,9 @@ exports.PredictionMarketExchange = void 0;
 // Base Exchange Class
 // ----------------------------------------------------------------------------
 class PredictionMarketExchange {
+    constructor(credentials) {
+        this.credentials = credentials;
+    }
     /**
      * 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.
@@ -21,10 +24,49 @@ class PredictionMarketExchange {
     }
     /**
      * Fetch raw trade history.
-     * Useful for generating synthetic OHLCV candles if the exchange doesn't provide them natively.
      */
     async fetchTrades(id, params) {
         throw new Error("Method fetchTrades not implemented.");
     }
+    // ----------------------------------------------------------------------------
+    // Trading Methods
+    // ----------------------------------------------------------------------------
+    /**
+     * Place a new order.
+     */
+    async createOrder(params) {
+        throw new Error("Method createOrder not implemented.");
+    }
+    /**
+     * Cancel an existing order.
+     */
+    async cancelOrder(orderId) {
+        throw new Error("Method cancelOrder not implemented.");
+    }
+    /**
+     * Fetch a specific order by ID.
+     */
+    async fetchOrder(orderId) {
+        throw new Error("Method fetchOrder not implemented.");
+    }
+    /**
+     * Fetch all open orders.
+     * @param marketId - Optional filter by market.
+     */
+    async fetchOpenOrders(marketId) {
+        throw new Error("Method fetchOpenOrders not implemented.");
+    }
+    /**
+     * Fetch current user positions.
+     */
+    async fetchPositions() {
+        throw new Error("Method fetchPositions not implemented.");
+    }
+    /**
+     * Fetch account balances.
+     */
+    async fetchBalance() {
+        throw new Error("Method fetchBalance not implemented.");
+    }
 }
 exports.PredictionMarketExchange = PredictionMarketExchange;

package/dist/exchanges/Kalshi.js

@@ -149,8 +149,16 @@ 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 searchIn = params?.searchIn || 'title'; // Default to title-only search
+            const filtered = markets.filter(market => {
+                const titleMatch = (market.title || '').toLowerCase().includes(lowerQuery);
+                const descMatch = (market.description || '').toLowerCase().includes(lowerQuery);
+                if (searchIn === 'title')
+                    return titleMatch;
+                if (searchIn === 'description')
+                    return descMatch;
+                return titleMatch || descMatch; // 'both'
+            });
             const limit = params?.limit || 20;
             return filtered.slice(0, limit);
         }