pmxtjs 0.3.1 → 0.4.0

package/API_REFERENCE.md

@@ -123,7 +123,7 @@ const trades = await kalshi.fetchTrades('FED-25JAN', {
 ### `MarketOutcome`
 ```typescript
 {
-  id: string;              // ⚠️ Use this for fetchOHLCV/fetchOrderBook/fetchTrades
+  id: string;              // Use this for fetchOHLCV/fetchOrderBook/fetchTrades
                            // Polymarket: CLOB Token ID
                            // Kalshi: Market Ticker
   label: string;           // "Trump", "Yes", etc.
@@ -243,12 +243,241 @@ import pmxt, {
 
 ---
 
+## 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,4 +1,4 @@
-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;
@@ -11,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.
@@ -34,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/auth.d.ts

@@ -0,0 +1,23 @@
+import { ExchangeCredentials } from '../../BaseExchange';
+/**
+ * Manages Kalshi authentication using RSA-PSS signatures.
+ * Reference: https://docs.kalshi.com/getting_started/quick_start_authenticated_requests
+ */
+export declare class KalshiAuth {
+    private credentials;
+    constructor(credentials: ExchangeCredentials);
+    private validateCredentials;
+    /**
+     * Generates the required headers for an authenticated request.
+     *
+     * @param method The HTTP method (e.g., "GET", "POST").
+     * @param path The request path (e.g., "/trade-api/v2/portfolio/orders").
+     * @returns An object containing the authentication headers.
+     */
+    getHeaders(method: string, path: string): Record<string, string>;
+    /**
+     * Signs the request using RSA-PSS.
+     * The message to sign is: timestamp + method + path
+     */
+    private signRequest;
+}

package/dist/exchanges/kalshi/auth.js

@@ -0,0 +1,99 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KalshiAuth = void 0;
+const crypto = __importStar(require("crypto"));
+/**
+ * Manages Kalshi authentication using RSA-PSS signatures.
+ * Reference: https://docs.kalshi.com/getting_started/quick_start_authenticated_requests
+ */
+class KalshiAuth {
+    constructor(credentials) {
+        this.credentials = credentials;
+        this.validateCredentials();
+    }
+    validateCredentials() {
+        if (!this.credentials.apiKey) {
+            throw new Error('Kalshi requires an apiKey (Key ID) for authentication');
+        }
+        if (!this.credentials.privateKey) {
+            throw new Error('Kalshi requires a privateKey (RSA Private Key) for authentication');
+        }
+    }
+    /**
+     * Generates the required headers for an authenticated request.
+     *
+     * @param method The HTTP method (e.g., "GET", "POST").
+     * @param path The request path (e.g., "/trade-api/v2/portfolio/orders").
+     * @returns An object containing the authentication headers.
+     */
+    getHeaders(method, path) {
+        const timestamp = Date.now().toString();
+        const signature = this.signRequest(timestamp, method, path);
+        return {
+            'KALSHI-ACCESS-KEY': this.credentials.apiKey,
+            'KALSHI-ACCESS-TIMESTAMP': timestamp,
+            'KALSHI-ACCESS-SIGNATURE': signature,
+            'Content-Type': 'application/json'
+        };
+    }
+    /**
+     * Signs the request using RSA-PSS.
+     * The message to sign is: timestamp + method + path
+     */
+    signRequest(timestamp, method, path) {
+        const payload = `${timestamp}${method}${path}`;
+        try {
+            const signer = crypto.createSign('SHA256');
+            signer.update(payload);
+            // Allow input of private key in both raw string or PEM format
+            // If it's a raw key without headers, accessing it might be tricky with implicit types,
+            // but standard PEM is best. We assume the user provides a valid PEM.
+            const privateKey = this.credentials.privateKey;
+            // Kalshi uses RSA-PSS for signing
+            const signature = signer.sign({
+                key: privateKey,
+                padding: crypto.constants.RSA_PKCS1_PSS_PADDING,
+                saltLength: crypto.constants.RSA_PSS_SALTLEN_DIGEST
+            }, 'base64');
+            return signature;
+        }
+        catch (error) {
+            console.error('Error signing Kalshi request:', error);
+            throw new Error(`Failed to sign Kalshi request: ${error.message}`);
+        }
+    }
+}
+exports.KalshiAuth = KalshiAuth;

package/dist/exchanges/kalshi/fetchMarkets.d.ts

@@ -0,0 +1,3 @@
+import { MarketFilterParams } from '../../BaseExchange';
+import { UnifiedMarket } from '../../types';
+export declare function fetchMarkets(params?: MarketFilterParams): Promise<UnifiedMarket[]>;

package/dist/exchanges/kalshi/fetchMarkets.js

@@ -0,0 +1,84 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchMarkets = fetchMarkets;
+const axios_1 = __importDefault(require("axios"));
+const utils_1 = require("./utils");
+async function fetchActiveEvents(targetMarketCount) {
+    let allEvents = [];
+    let totalMarketCount = 0;
+    let cursor = null;
+    let page = 0;
+    // Note: Kalshi API uses cursor-based pagination which requires sequential fetching.
+    // We cannot parallelize requests for a single list because we need the cursor from page N to fetch page N+1.
+    // To optimize, we use the maximum allowed limit (200) and fetch until exhaustion.
+    const MAX_PAGES = 1000; // Safety cap against infinite loops
+    const BATCH_SIZE = 200; // Max limit per Kalshi API docs
+    do {
+        try {
+            // console.log(`Fetching Kalshi page ${page + 1}...`);
+            const queryParams = {
+                limit: BATCH_SIZE,
+                with_nested_markets: true,
+                status: 'open' // Filter to open markets to improve relevance and speed
+            };
+            if (cursor)
+                queryParams.cursor = cursor;
+            const response = await axios_1.default.get(utils_1.KALSHI_API_URL, { params: queryParams });
+            const events = response.data.events || [];
+            if (events.length === 0)
+                break;
+            allEvents = allEvents.concat(events);
+            // Count markets in this batch for early termination
+            if (targetMarketCount) {
+                for (const event of events) {
+                    totalMarketCount += (event.markets || []).length;
+                }
+                // Early termination: if we have enough markets, stop fetching
+                if (totalMarketCount >= targetMarketCount * 2) {
+                    break;
+                }
+            }
+            cursor = response.data.cursor;
+            page++;
+        }
+        catch (e) {
+            console.error(`Error fetching Kalshi page ${page}:`, e);
+            break;
+        }
+    } while (cursor && page < MAX_PAGES);
+    return allEvents;
+}
+async function fetchMarkets(params) {
+    const limit = params?.limit || 50;
+    try {
+        // Fetch active events with nested markets
+        // For small limits, we can optimize by fetching fewer pages
+        const allEvents = await fetchActiveEvents(limit);
+        // Extract ALL markets from all events
+        const allMarkets = [];
+        for (const event of allEvents) {
+            const markets = event.markets || [];
+            for (const market of markets) {
+                const unifiedMarket = (0, utils_1.mapMarketToUnified)(event, market);
+                if (unifiedMarket) {
+                    allMarkets.push(unifiedMarket);
+                }
+            }
+        }
+        // Sort by 24h volume
+        if (params?.sort === 'volume') {
+            allMarkets.sort((a, b) => b.volume24h - a.volume24h);
+        }
+        else if (params?.sort === 'liquidity') {
+            allMarkets.sort((a, b) => b.liquidity - a.liquidity);
+        }
+        return allMarkets.slice(0, limit);
+    }
+    catch (error) {
+        console.error("Error fetching Kalshi data:", error);
+        return [];
+    }
+}

package/dist/exchanges/kalshi/fetchOHLCV.d.ts

@@ -0,0 +1,3 @@
+import { HistoryFilterParams } from '../../BaseExchange';
+import { PriceCandle } from '../../types';
+export declare function fetchOHLCV(id: string, params: HistoryFilterParams): Promise<PriceCandle[]>;

package/dist/exchanges/kalshi/fetchOHLCV.js

@@ -0,0 +1,78 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchOHLCV = fetchOHLCV;
+const axios_1 = __importDefault(require("axios"));
+const utils_1 = require("./utils");
+async function fetchOHLCV(id, params) {
+    try {
+        // Kalshi API expects uppercase tickers
+        // Handle virtual "-NO" suffix by stripping it (fetching the underlying market history)
+        const cleanedId = id.replace(/-NO$/, '');
+        const normalizedId = cleanedId.toUpperCase();
+        const interval = (0, utils_1.mapIntervalToKalshi)(params.resolution);
+        // Heuristic for series_ticker
+        const parts = normalizedId.split('-');
+        if (parts.length < 2) {
+            throw new Error(`Invalid Kalshi Ticker format: "${id}". Expected format like "FED-25JAN29-B4.75".`);
+        }
+        const seriesTicker = parts.slice(0, -1).join('-');
+        const url = `https://api.elections.kalshi.com/trade-api/v2/series/${seriesTicker}/markets/${normalizedId}/candlesticks`;
+        const queryParams = { period_interval: interval };
+        const now = Math.floor(Date.now() / 1000);
+        let startTs = now - (24 * 60 * 60);
+        let endTs = now;
+        if (params.start) {
+            startTs = Math.floor(params.start.getTime() / 1000);
+        }
+        if (params.end) {
+            endTs = Math.floor(params.end.getTime() / 1000);
+            if (!params.start) {
+                startTs = endTs - (24 * 60 * 60);
+            }
+        }
+        queryParams.start_ts = startTs;
+        queryParams.end_ts = endTs;
+        const response = await axios_1.default.get(url, { params: queryParams });
+        const candles = response.data.candlesticks || [];
+        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);
+        }
+        return mappedCandles;
+    }
+    catch (error) {
+        if (axios_1.default.isAxiosError(error) && error.response) {
+            const apiError = error.response.data?.error || error.response.data?.message || "Unknown API Error";
+            throw new Error(`Kalshi History API Error (${error.response.status}): ${apiError}. Used Ticker: ${id}`);
+        }
+        console.error(`Unexpected error fetching Kalshi history for ${id}:`, error);
+        throw error;
+    }
+}

package/dist/exchanges/kalshi/fetchOrderBook.d.ts

@@ -0,0 +1,2 @@
+import { OrderBook } from '../../types';
+export declare function fetchOrderBook(id: string): Promise<OrderBook>;