pmxt-core 0.0.1 → 1.0.0-b2

package/API_REFERENCE.md

@@ -0,0 +1,515 @@
+# Prediction Market API Reference
+
+A unified interface for interacting with multiple prediction market exchanges (Kalshi, Polymarket) identically.
+
+## Installation & Usage
+
+```bash
+npm install pmxtjs
+```
+
+### Basic Import (CommonJS)
+
+```typescript
+import pmxt from 'pmxtjs';
+
+// Both PascalCase and lowercase work
+const poly = new pmxt.Polymarket();
+const kalshi = new pmxt.Kalshi();
+
+// Or lowercase if you prefer
+const poly2 = new pmxt.polymarket();
+const kalshi2 = new pmxt.kalshi();
+```
+
+### Note for ESM Users
+
+**pmxt is currently CommonJS-only.** If you're using `"type": "module"` in your `package.json`, you have two options:
+
+**Option 1: Default import (recommended)**
+```typescript
+import pmxt from 'pmxtjs';
+const poly = new pmxt.polymarket();
+```
+
+**Option 2: Dynamic import**
+```typescript
+const pmxt = await import('pmxtjs');
+const poly = new pmxt.default.polymarket();
+```
+
+**Note**: Named exports like `import { polymarket } from 'pmxtjs'` will **not work** in ESM projects.
+
+---
+
+## Core Methods
+
+### `fetchMarkets(params?)`
+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 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 market ticker (auto-uppercased)
+const kalshiMarkets = await kalshi.getMarketsBySlug('KXFEDCHAIRNOM-29');
+```
+
+#### Universal Slug/Ticker Reference
+
+| Platform | Example Market URL | What to extract (Slug/Ticker) | Logic |
+|---|---|---|---|
+| **Kalshi** | `kalshi.com/markets/kxfedchairnom/.../kxfedchairnom-29` | `KXFEDCHAIRNOM-29` | The **last** path segment of the URL. |
+| **Polymarket** | `polymarket.com/event/who-will-trump-nominate-as-fed-chair` | `who-will-trump-nominate-as-fed-chair` | The slug immediately after `/event/`. |
+
+---
+
+## 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.
+
+```typescript
+const orderBook = await kalshi.fetchOrderBook('FED-25JAN');
+console.log('Best bid:', orderBook.bids[0].price);
+console.log('Best ask:', orderBook.asks[0].price);
+```
+
+### `fetchTrades(outcomeId, params)`
+Get trade history.
+
+**Note**: Polymarket requires API key. Use `fetchOHLCV` for public historical data.
+
+```typescript
+const trades = await kalshi.fetchTrades('FED-25JAN', {
+  resolution: '1h',
+  limit: 100
+});
+```
+
+---
+
+## Data Models
+
+### `UnifiedMarket`
+```typescript
+{
+  id: string;              // Market ID
+  title: string;
+  description: string;
+  outcomes: MarketOutcome[]; // All tradeable outcomes
+  
+  resolutionDate: Date;
+  volume24h: number;       // USD
+  volume?: number;         // Total volume (USD)
+  liquidity: number;       // USD
+  openInterest?: number;   // USD
+  
+  url: string;
+  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](https://github.com/qoery-com/pmxt/blob/main/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/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/bin/pmxt-ensure-server

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+
+/**
+ * PMXT Server Launcher
+ * 
+ * This script ensures the PMXT sidecar server is running.
+ * It's designed to be called by SDKs in any language (Python, Java, C#, Go, etc.)
+ * 
+ * Behavior:
+ * 1. Check if server is already running (via lock file)
+ * 2. If running, exit successfully
+ * 3. If not running, spawn the server and wait for health check
+ * 4. Exit with code 0 on success, 1 on failure
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn } = require('child_process');
+const http = require('http');
+
+const LOCK_FILE = path.join(os.homedir(), '.pmxt', 'server.lock');
+const DEFAULT_PORT = 3847;
+const HEALTH_CHECK_TIMEOUT = 10000; // 10 seconds
+const HEALTH_CHECK_INTERVAL = 100; // 100ms
+
+/**
+ * Check if the server is currently running
+ */
+function isServerRunning() {
+    try {
+        if (!fs.existsSync(LOCK_FILE)) {
+            return false;
+        }
+
+        const lockData = JSON.parse(fs.readFileSync(LOCK_FILE, 'utf-8'));
+        const { pid, port } = lockData;
+
+        // Check if process exists
+        try {
+            process.kill(pid, 0); // Signal 0 checks existence without killing
+            return { running: true, port };
+        } catch (err) {
+            // Process doesn't exist, remove stale lock file
+            fs.unlinkSync(LOCK_FILE);
+            return false;
+        }
+    } catch (err) {
+        return false;
+    }
+}
+
+/**
+ * Wait for server to respond to health check
+ */
+function waitForHealth(port, timeout = HEALTH_CHECK_TIMEOUT) {
+    return new Promise((resolve, reject) => {
+        const startTime = Date.now();
+
+        const checkHealth = () => {
+            const req = http.get(`http://localhost:${port}/health`, (res) => {
+                if (res.statusCode === 200) {
+                    resolve(true);
+                } else {
+                    scheduleNextCheck();
+                }
+            });
+
+            req.on('error', () => {
+                scheduleNextCheck();
+            });
+
+            req.setTimeout(1000);
+        };
+
+        const scheduleNextCheck = () => {
+            if (Date.now() - startTime > timeout) {
+                reject(new Error('Server health check timeout'));
+            } else {
+                setTimeout(checkHealth, HEALTH_CHECK_INTERVAL);
+            }
+        };
+
+        checkHealth();
+    });
+}
+
+/**
+ * Start the PMXT server
+ */
+async function startServer() {
+    // 1. Try to find the server binary/script
+    let serverCmd = 'pmxt-server';
+    let args = [];
+
+    // Local dev search: Check for ../dist/server/index.js relative to this script
+    const localDistServer = path.join(__dirname, '..', 'dist', 'server', 'index.js');
+    const localBinServer = path.join(__dirname, 'pmxt-server');
+
+    if (fs.existsSync(localDistServer)) {
+        serverCmd = 'node';
+        args = [localDistServer];
+    } else if (fs.existsSync(localBinServer)) {
+        serverCmd = localBinServer;
+    }
+
+    // Spawn server as detached process
+    const serverProcess = spawn(serverCmd, args, {
+        detached: true,
+        stdio: 'ignore',
+        env: process.env
+    });
+
+    // Detach from parent process
+    serverProcess.unref();
+
+    // Wait for server to be ready
+    await waitForHealth(DEFAULT_PORT);
+}
+
+/**
+ * Main entry point
+ */
+async function main() {
+    try {
+        // Check if server is already running
+        const serverStatus = isServerRunning();
+
+        if (serverStatus && serverStatus.running) {
+            // Server is running, verify it's healthy
+            try {
+                await waitForHealth(serverStatus.port, 2000);
+                process.exit(0);
+            } catch (err) {
+                // Server process exists but not responding, try to start fresh
+                console.error('Server process exists but not responding, starting fresh...');
+            }
+        }
+
+        // Start the server
+        await startServer();
+        process.exit(0);
+    } catch (err) {
+        console.error('Failed to ensure server is running:', err.message);
+        process.exit(1);
+    }
+}
+
+main();

package/package.json

@@ -1,11 +1,62 @@
 {
   "name": "pmxt-core",
-  "version": "0.0.1",
-  "description": "Core library for Prediction Markets Aggregator",
-  "main": "index.js",
+  "version": "1.0.0-b2",
+  "description": "pmxt is a unified prediction market data API. The ccxt for prediction markets.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pmxt-dev/pmxt.git"
+  },
+  "bin": {
+    "pmxt-server": "./dist/server/index.js",
+    "pmxt-ensure-server": "./bin/pmxt-ensure-server"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "API_REFERENCE.md"
+  ],
+  "directories": {
+    "example": "examples",
+    "test": "test"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean",
+    "build": "tsc",
+    "test": "jest -c jest.config.js",
+    "server": "tsx watch src/server/index.ts",
+    "server:prod": "node dist/server/index.js",
+    "generate:sdk:python": "npx @openapitools/openapi-generator-cli generate -i src/server/openapi.yaml -g python -o ../sdks/python/generated --package-name pmxt_internal --additional-properties=projectName=pmxt-internal,packageVersion=1.0.0b2,library=urllib3",
+    "generate:sdk:typescript": "npx @openapitools/openapi-generator-cli generate -i src/server/openapi.yaml -g typescript-fetch -o ../sdks/typescript/generated --additional-properties=npmName=pmxtjs,npmVersion=1.0.0-b2,supportsES6=true,typescriptThreePlus=true",
+    "generate:docs": "node ../scripts/generate-api-docs.js",
+    "generate:sdk:all": "npm run generate:sdk:python && npm run generate:sdk:typescript && npm run generate:docs"
   },
+  "keywords": [],
   "author": "",
-  "license": "ISC"
-}
+  "license": "MIT",
+  "type": "commonjs",
+  "dependencies": {
+    "@polymarket/clob-client": "^5.2.0",
+    "@types/express": "^5.0.6",
+    "axios": "^1.7.9",
+    "cors": "^2.8.5",
+    "dotenv": "^17.2.3",
+    "ethers": "^5.8.0",
+    "express": "^5.2.1",
+    "jest": "^30.2.0",
+    "tsx": "^4.21.0"
+  },
+  "devDependencies": {
+    "@openapitools/openapi-generator-cli": "^2.27.0",
+    "@types/cors": "^2.8.19",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.0.3",
+    "handlebars": "^4.7.8",
+    "identity-obj-proxy": "^3.0.0",
+    "js-yaml": "^3.14.2",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.9.3"
+  }
+}

package/.env

@@ -1,5 +0,0 @@
-# Polymarket
-POLYMARKET_PRIVATE_KEY=0x331917d429ce4dbbf046c6a29b76b1818b975e6479df4feb396c5881509d6577
-
-# Kalshi
-KALSHI_API_KEY=0x/NA

package/index.js

@@ -1 +0,0 @@
-console.log("pmxt-core placeholder");