pmxtjs 0.3.0 → 0.4.0

package/dist/exchanges/kalshi/utils.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KALSHI_API_URL = void 0;
+exports.mapMarketToUnified = mapMarketToUnified;
+exports.mapIntervalToKalshi = mapIntervalToKalshi;
+exports.KALSHI_API_URL = "https://api.elections.kalshi.com/trade-api/v2/events";
+function mapMarketToUnified(event, market) {
+    if (!market)
+        return null;
+    // Calculate price
+    let price = 0.5;
+    if (market.last_price) {
+        price = market.last_price / 100;
+    }
+    else if (market.yes_ask && market.yes_bid) {
+        price = (market.yes_ask + market.yes_bid) / 200;
+    }
+    else if (market.yes_ask) {
+        price = market.yes_ask / 100;
+    }
+    // Extract candidate name
+    let candidateName = null;
+    if (market.subtitle || market.yes_sub_title) {
+        candidateName = market.subtitle || market.yes_sub_title;
+    }
+    // Calculate 24h change
+    let priceChange = 0;
+    if (market.previous_price_dollars !== undefined && market.last_price_dollars !== undefined) {
+        priceChange = market.last_price_dollars - market.previous_price_dollars;
+    }
+    const outcomes = [
+        {
+            id: market.ticker, // The actual market ticker (primary tradeable)
+            label: candidateName || 'Yes',
+            price: price,
+            priceChange24h: priceChange
+        },
+        {
+            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
+        }
+    ];
+    return {
+        id: market.ticker,
+        title: event.title,
+        description: event.sub_title || market.subtitle || "",
+        outcomes: outcomes,
+        resolutionDate: new Date(market.expiration_time),
+        volume24h: Number(market.volume_24h || market.volume || 0),
+        volume: Number(market.volume || 0),
+        liquidity: Number(market.liquidity || 0), // Kalshi 'liquidity' might need specific mapping if available, otherwise 0 to avoid conflation
+        openInterest: Number(market.open_interest || 0),
+        url: `https://kalshi.com/events/${event.event_ticker}`,
+        category: event.category,
+        tags: event.tags || []
+    };
+}
+function mapIntervalToKalshi(interval) {
+    const mapping = {
+        '1m': 1,
+        '5m': 1,
+        '15m': 1,
+        '1h': 60,
+        '6h': 60,
+        '1d': 1440
+    };
+    return mapping[interval];
+}

package/dist/exchanges/polymarket/auth.d.ts

@@ -0,0 +1,32 @@
+import { ClobClient } from '@polymarket/clob-client';
+import type { ApiKeyCreds } from '@polymarket/clob-client';
+import { ExchangeCredentials } from '../../BaseExchange';
+/**
+ * Manages Polymarket authentication and CLOB client initialization.
+ * Handles both L1 (wallet-based) and L2 (API credentials) authentication.
+ */
+export declare class PolymarketAuth {
+    private credentials;
+    private signer?;
+    private clobClient?;
+    private apiCreds?;
+    constructor(credentials: ExchangeCredentials);
+    /**
+     * Get or create API credentials using L1 authentication.
+     * This uses the private key to derive/create API credentials.
+     */
+    getApiCredentials(): Promise<ApiKeyCreds>;
+    /**
+     * Get an authenticated CLOB client for L2 operations (trading).
+     * This client can place orders, cancel orders, query positions, etc.
+     */
+    getClobClient(): Promise<ClobClient>;
+    /**
+     * Get the signer's address.
+     */
+    getAddress(): string;
+    /**
+     * Reset cached credentials and client (useful for testing or credential rotation).
+     */
+    reset(): void;
+}

package/dist/exchanges/polymarket/auth.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolymarketAuth = void 0;
+const clob_client_1 = require("@polymarket/clob-client");
+const ethers_1 = require("ethers");
+const POLYMARKET_HOST = 'https://clob.polymarket.com';
+const POLYGON_CHAIN_ID = 137;
+/**
+ * Manages Polymarket authentication and CLOB client initialization.
+ * Handles both L1 (wallet-based) and L2 (API credentials) authentication.
+ */
+class PolymarketAuth {
+    constructor(credentials) {
+        this.credentials = credentials;
+        if (!credentials.privateKey) {
+            throw new Error('Polymarket requires a privateKey for authentication');
+        }
+        // Initialize the signer
+        this.signer = new ethers_1.Wallet(credentials.privateKey);
+    }
+    /**
+     * Get or create API credentials using L1 authentication.
+     * This uses the private key to derive/create API credentials.
+     */
+    async getApiCredentials() {
+        // Return cached credentials if available
+        if (this.apiCreds) {
+            return this.apiCreds;
+        }
+        // If credentials were provided, use them
+        if (this.credentials.apiKey && this.credentials.apiSecret && this.credentials.passphrase) {
+            this.apiCreds = {
+                key: this.credentials.apiKey,
+                secret: this.credentials.apiSecret,
+                passphrase: this.credentials.passphrase,
+            };
+            return this.apiCreds;
+        }
+        // Otherwise, derive/create them using L1 auth
+        const l1Client = new clob_client_1.ClobClient(POLYMARKET_HOST, POLYGON_CHAIN_ID, this.signer);
+        // Robust derivation strategy:
+        // 1. Try to DERIVE existing credentials first (most common case).
+        // 2. If that fails (e.g. 404 or 400), try to CREATE new ones.
+        let creds;
+        try {
+            // console.log('Trying to derive existing API key...');
+            creds = await l1Client.deriveApiKey();
+        }
+        catch (deriveError) {
+            // console.log('Derivation failed, trying to create new API key...');
+            try {
+                creds = await l1Client.createApiKey();
+            }
+            catch (createError) {
+                console.error('Failed to both derive and create API key:', createError?.message || createError);
+                throw new Error('Authentication failed: Could not create or derive API key.');
+            }
+        }
+        if (!creds) {
+            throw new Error('Authentication failed: Credentials are empty.');
+        }
+        this.apiCreds = creds;
+        return creds;
+    }
+    /**
+     * Get an authenticated CLOB client for L2 operations (trading).
+     * This client can place orders, cancel orders, query positions, etc.
+     */
+    async getClobClient() {
+        // Return cached client if available
+        if (this.clobClient) {
+            return this.clobClient;
+        }
+        // Get API credentials (L1 auth)
+        const apiCreds = await this.getApiCredentials();
+        // Determine signature type (default to EOA = 0)
+        const signatureType = this.credentials.signatureType ?? 0;
+        // Determine funder address (defaults to signer's address)
+        const funderAddress = this.credentials.funderAddress ?? this.signer.address;
+        // Create L2-authenticated client
+        this.clobClient = new clob_client_1.ClobClient(POLYMARKET_HOST, POLYGON_CHAIN_ID, this.signer, apiCreds, signatureType, funderAddress);
+        return this.clobClient;
+    }
+    /**
+     * Get the signer's address.
+     */
+    getAddress() {
+        return this.signer.address;
+    }
+    /**
+     * Reset cached credentials and client (useful for testing or credential rotation).
+     */
+    reset() {
+        this.apiCreds = undefined;
+        this.clobClient = undefined;
+    }
+}
+exports.PolymarketAuth = PolymarketAuth;

package/dist/exchanges/polymarket/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/polymarket/fetchMarkets.js

@@ -0,0 +1,75 @@
+"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 fetchMarkets(params) {
+    const limit = params?.limit || 200; // Higher default for better coverage
+    const offset = params?.offset || 0;
+    // Map generic sort params to Polymarket Gamma API params
+    let queryParams = {
+        active: 'true',
+        closed: 'false',
+        limit: limit,
+        offset: offset,
+    };
+    // Gamma API uses 'order' and 'ascending' for sorting
+    if (params?.sort === 'volume') {
+        queryParams.order = 'volume';
+        queryParams.ascending = 'false';
+    }
+    else if (params?.sort === 'newest') {
+        queryParams.order = 'startDate';
+        queryParams.ascending = 'false';
+    }
+    else if (params?.sort === 'liquidity') {
+        // queryParams.order = 'liquidity';
+    }
+    else {
+        // Default: do not send order param to avoid 422
+    }
+    try {
+        // Fetch active events from Gamma
+        const response = await axios_1.default.get(utils_1.GAMMA_API_URL, {
+            params: queryParams
+        });
+        const events = response.data;
+        const unifiedMarkets = [];
+        for (const event of events) {
+            // Each event is a container (e.g. "US Election"). 
+            // It contains specific "markets" (e.g. "Winner", "Pop Vote").
+            if (!event.markets)
+                continue;
+            for (const market of event.markets) {
+                const unifiedMarket = (0, utils_1.mapMarketToUnified)(event, market);
+                if (unifiedMarket) {
+                    unifiedMarkets.push(unifiedMarket);
+                }
+            }
+        }
+        // Client-side Sort capability to ensure contract fulfillment
+        // Often API filters are "good effort" or apply to the 'event' but not the 'market'
+        if (params?.sort === 'volume') {
+            unifiedMarkets.sort((a, b) => b.volume24h - a.volume24h);
+        }
+        else if (params?.sort === 'newest') {
+            // unifiedMarkets.sort((a, b) => b.resolutionDate.getTime() - a.resolutionDate.getTime()); // Not quite 'newest'
+        }
+        else if (params?.sort === 'liquidity') {
+            unifiedMarkets.sort((a, b) => b.liquidity - a.liquidity);
+        }
+        else {
+            // Default volume sort
+            unifiedMarkets.sort((a, b) => b.volume24h - a.volume24h);
+        }
+        // Respect limit strictly after flattening 
+        return unifiedMarkets.slice(0, limit);
+    }
+    catch (error) {
+        console.error("Error fetching Polymarket data:", error);
+        return [];
+    }
+}

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

@@ -0,0 +1,7 @@
+import { HistoryFilterParams } from '../../BaseExchange';
+import { PriceCandle } from '../../types';
+/**
+ * Fetch historical price data (OHLCV candles) for a specific token.
+ * @param id - The CLOB token ID (e.g., outcome token ID)
+ */
+export declare function fetchOHLCV(id: string, params: HistoryFilterParams): Promise<PriceCandle[]>;

package/dist/exchanges/polymarket/fetchOHLCV.js

@@ -0,0 +1,73 @@
+"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");
+/**
+ * Fetch historical price data (OHLCV candles) for a specific token.
+ * @param id - The CLOB token ID (e.g., outcome token ID)
+ */
+async function fetchOHLCV(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. Ensure you are using 'outcome.id'.`);
+    }
+    try {
+        const fidelity = (0, utils_1.mapIntervalToFidelity)(params.resolution);
+        const nowTs = Math.floor(Date.now() / 1000);
+        // 1. Smart Lookback Calculation
+        // If start/end not provided, calculate window based on limit * resolution
+        let startTs = params.start ? Math.floor(params.start.getTime() / 1000) : 0;
+        let endTs = params.end ? Math.floor(params.end.getTime() / 1000) : nowTs;
+        if (!params.start) {
+            // Default limit is usually 20 in the example, but safety margin is good.
+            // If limit is not set, we default to 100 candles.
+            const count = params.limit || 100;
+            // fidelity is in minutes. 
+            const durationSeconds = count * fidelity * 60;
+            startTs = endTs - durationSeconds;
+        }
+        const queryParams = {
+            market: id,
+            fidelity: fidelity,
+            startTs: startTs,
+            endTs: endTs
+        };
+        const response = await axios_1.default.get(`${utils_1.CLOB_API_URL}/prices-history`, {
+            params: queryParams
+        });
+        const history = response.data.history || [];
+        // 2. Align Timestamps (Snap to Grid)
+        // Polymarket returns random tick timestamps (e.g. 1:00:21).
+        // We want to normalize this to the start of the bucket (1:00:00).
+        const resolutionMs = fidelity * 60 * 1000;
+        const candles = history.map((item) => {
+            const rawMs = item.t * 1000;
+            const snappedMs = Math.floor(rawMs / resolutionMs) * resolutionMs;
+            return {
+                timestamp: snappedMs, // Aligned timestamp
+                open: item.p,
+                high: item.p,
+                low: item.p,
+                close: item.p,
+                volume: undefined
+            };
+        });
+        // Apply limit if specified
+        if (params.limit && candles.length > params.limit) {
+            return candles.slice(-params.limit);
+        }
+        return candles;
+    }
+    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(`Polymarket History API Error (${error.response.status}): ${apiError}. Used ID: ${id}`);
+        }
+        console.error(`Unexpected error fetching Polymarket history for ${id}:`, error);
+        throw error;
+    }
+}

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

@@ -0,0 +1,6 @@
+import { OrderBook } from '../../types';
+/**
+ * Fetch the current order book for a specific token.
+ * @param id - The CLOB token ID
+ */
+export declare function fetchOrderBook(id: string): Promise<OrderBook>;

package/dist/exchanges/polymarket/fetchOrderBook.js

@@ -0,0 +1,38 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchOrderBook = fetchOrderBook;
+const axios_1 = __importDefault(require("axios"));
+const utils_1 = require("./utils");
+/**
+ * Fetch the current order book for a specific token.
+ * @param id - The CLOB token ID
+ */
+async function fetchOrderBook(id) {
+    try {
+        const response = await axios_1.default.get(`${utils_1.CLOB_API_URL}/book`, {
+            params: { token_id: id }
+        });
+        const data = response.data;
+        // Response format: { bids: [{price: "0.52", size: "100"}], asks: [...] }
+        const bids = (data.bids || []).map((level) => ({
+            price: parseFloat(level.price),
+            size: parseFloat(level.size)
+        })).sort((a, b) => b.price - a.price); // Sort Bids Descending (Best/Highest first)
+        const asks = (data.asks || []).map((level) => ({
+            price: parseFloat(level.price),
+            size: parseFloat(level.size)
+        })).sort((a, b) => a.price - b.price); // Sort Asks Ascending (Best/Lowest first)
+        return {
+            bids,
+            asks,
+            timestamp: data.timestamp ? new Date(data.timestamp).getTime() : Date.now()
+        };
+    }
+    catch (error) {
+        console.error(`Error fetching Polymarket orderbook for ${id}:`, error);
+        return { bids: [], asks: [] };
+    }
+}

package/dist/exchanges/polymarket/fetchPositions.d.ts

@@ -0,0 +1,2 @@
+import { Position } from '../../types';
+export declare function fetchPositions(userAddress: string): Promise<Position[]>;

package/dist/exchanges/polymarket/fetchPositions.js

@@ -0,0 +1,27 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchPositions = fetchPositions;
+const axios_1 = __importDefault(require("axios"));
+const DATA_API_URL = 'https://data-api.polymarket.com';
+async function fetchPositions(userAddress) {
+    const response = await axios_1.default.get(`${DATA_API_URL}/positions`, {
+        params: {
+            user: userAddress,
+            limit: 100
+        }
+    });
+    const data = Array.isArray(response.data) ? response.data : [];
+    return data.map((p) => ({
+        marketId: p.conditionId,
+        outcomeId: p.asset,
+        outcomeLabel: p.outcome || 'Unknown',
+        size: parseFloat(p.size),
+        entryPrice: parseFloat(p.avgPrice),
+        currentPrice: parseFloat(p.curPrice || '0'),
+        unrealizedPnL: parseFloat(p.cashPnl || '0'),
+        realizedPnL: parseFloat(p.realizedPnl || '0')
+    }));
+}

package/dist/exchanges/polymarket/fetchTrades.d.ts

@@ -0,0 +1,11 @@
+import { HistoryFilterParams } from '../../BaseExchange';
+import { Trade } from '../../types';
+/**
+ * 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 fetchOHLCV for public historical price data instead.
+ */
+export declare function fetchTrades(id: string, params: HistoryFilterParams): Promise<Trade[]>;

package/dist/exchanges/polymarket/fetchTrades.js

@@ -0,0 +1,59 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchTrades = fetchTrades;
+const axios_1 = __importDefault(require("axios"));
+const utils_1 = require("./utils");
+/**
+ * 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 fetchOHLCV for public historical price data instead.
+ */
+async function fetchTrades(id, params) {
+    // ID Validation
+    if (id.length < 10 && /^\d+$/.test(id)) {
+        throw new Error(`Invalid ID for Polymarket trades: "${id}". You provided a Market ID, but Polymarket's CLOB API requires a Token ID.`);
+    }
+    try {
+        const queryParams = {
+            market: id
+        };
+        // Add time filters if provided
+        if (params.start) {
+            queryParams.after = Math.floor(params.start.getTime() / 1000);
+        }
+        if (params.end) {
+            queryParams.before = Math.floor(params.end.getTime() / 1000);
+        }
+        const response = await axios_1.default.get(`${utils_1.CLOB_API_URL}/trades`, {
+            params: queryParams
+        });
+        // Response is an array of trade objects
+        const trades = response.data || [];
+        const mappedTrades = trades.map((trade) => ({
+            id: trade.id || `${trade.timestamp}-${trade.price}`,
+            timestamp: trade.timestamp * 1000, // Convert to milliseconds
+            price: parseFloat(trade.price),
+            amount: parseFloat(trade.size || trade.amount || 0),
+            side: trade.side === 'BUY' ? 'buy' : trade.side === 'SELL' ? 'sell' : 'unknown'
+        }));
+        // Apply limit if specified
+        if (params.limit && mappedTrades.length > params.limit) {
+            return mappedTrades.slice(-params.limit); // Return most recent N trades
+        }
+        return mappedTrades;
+    }
+    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(`Polymarket Trades API Error (${error.response.status}): ${apiError}. Used ID: ${id}`);
+        }
+        console.error(`Unexpected error fetching Polymarket trades for ${id}:`, error);
+        throw error;
+    }
+}

package/dist/exchanges/polymarket/getMarketsBySlug.d.ts

@@ -0,0 +1,7 @@
+import { UnifiedMarket } from '../../types';
+/**
+ * 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")
+ */
+export declare function getMarketsBySlug(slug: string): Promise<UnifiedMarket[]>;

package/dist/exchanges/polymarket/getMarketsBySlug.js

@@ -0,0 +1,39 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMarketsBySlug = getMarketsBySlug;
+const axios_1 = __importDefault(require("axios"));
+const utils_1 = require("./utils");
+/**
+ * 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")
+ */
+async function getMarketsBySlug(slug) {
+    try {
+        const response = await axios_1.default.get(utils_1.GAMMA_API_URL, {
+            params: { slug: slug }
+        });
+        const events = response.data;
+        if (!events || events.length === 0)
+            return [];
+        const unifiedMarkets = [];
+        for (const event of events) {
+            if (!event.markets)
+                continue;
+            for (const market of event.markets) {
+                const unifiedMarket = (0, utils_1.mapMarketToUnified)(event, market, { useQuestionAsCandidateFallback: true });
+                if (unifiedMarket) {
+                    unifiedMarkets.push(unifiedMarket);
+                }
+            }
+        }
+        return unifiedMarkets;
+    }
+    catch (error) {
+        console.error(`Error fetching Polymarket slug ${slug}:`, error);
+        return [];
+    }
+}

package/dist/exchanges/polymarket/index.d.ts

@@ -0,0 +1,23 @@
+import { PredictionMarketExchange, MarketFilterParams, HistoryFilterParams, ExchangeCredentials } from '../../BaseExchange';
+import { UnifiedMarket, PriceCandle, OrderBook, Trade, Order, Position, Balance, CreateOrderParams } from '../../types';
+export declare class PolymarketExchange extends PredictionMarketExchange {
+    private auth?;
+    constructor(credentials?: ExchangeCredentials);
+    get name(): string;
+    fetchMarkets(params?: MarketFilterParams): Promise<UnifiedMarket[]>;
+    searchMarkets(query: string, params?: MarketFilterParams): Promise<UnifiedMarket[]>;
+    getMarketsBySlug(slug: string): Promise<UnifiedMarket[]>;
+    fetchOHLCV(id: string, params: HistoryFilterParams): Promise<PriceCandle[]>;
+    fetchOrderBook(id: string): Promise<OrderBook>;
+    fetchTrades(id: string, params: HistoryFilterParams): Promise<Trade[]>;
+    /**
+     * Ensure authentication is initialized before trading operations.
+     */
+    private ensureAuth;
+    createOrder(params: CreateOrderParams): Promise<Order>;
+    cancelOrder(orderId: string): Promise<Order>;
+    fetchOrder(orderId: string): Promise<Order>;
+    fetchOpenOrders(marketId?: string): Promise<Order[]>;
+    fetchPositions(): Promise<Position[]>;
+    fetchBalance(): Promise<Balance[]>;
+}