pmxtjs 0.3.1 → 0.4.1

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[]>;
+}

package/dist/exchanges/polymarket/index.js

@@ -0,0 +1,216 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolymarketExchange = void 0;
+const BaseExchange_1 = require("../../BaseExchange");
+const fetchMarkets_1 = require("./fetchMarkets");
+const searchMarkets_1 = require("./searchMarkets");
+const getMarketsBySlug_1 = require("./getMarketsBySlug");
+const fetchOHLCV_1 = require("./fetchOHLCV");
+const fetchOrderBook_1 = require("./fetchOrderBook");
+const fetchTrades_1 = require("./fetchTrades");
+const fetchPositions_1 = require("./fetchPositions");
+const auth_1 = require("./auth");
+const clob_client_1 = require("@polymarket/clob-client");
+class PolymarketExchange extends BaseExchange_1.PredictionMarketExchange {
+    constructor(credentials) {
+        super(credentials);
+        // Initialize auth if credentials are provided
+        if (credentials?.privateKey) {
+            this.auth = new auth_1.PolymarketAuth(credentials);
+        }
+    }
+    get name() {
+        return 'Polymarket';
+    }
+    async fetchMarkets(params) {
+        return (0, fetchMarkets_1.fetchMarkets)(params);
+    }
+    async searchMarkets(query, params) {
+        return (0, searchMarkets_1.searchMarkets)(query, params);
+    }
+    async getMarketsBySlug(slug) {
+        return (0, getMarketsBySlug_1.getMarketsBySlug)(slug);
+    }
+    async fetchOHLCV(id, params) {
+        return (0, fetchOHLCV_1.fetchOHLCV)(id, params);
+    }
+    async fetchOrderBook(id) {
+        return (0, fetchOrderBook_1.fetchOrderBook)(id);
+    }
+    async fetchTrades(id, params) {
+        return (0, fetchTrades_1.fetchTrades)(id, params);
+    }
+    // ----------------------------------------------------------------------------
+    // Trading Methods
+    // ----------------------------------------------------------------------------
+    /**
+     * Ensure authentication is initialized before trading operations.
+     */
+    ensureAuth() {
+        if (!this.auth) {
+            throw new Error('Trading operations require authentication. ' +
+                'Initialize PolymarketExchange with credentials: new PolymarketExchange({ privateKey: "0x..." })');
+        }
+        return this.auth;
+    }
+    async createOrder(params) {
+        const auth = this.ensureAuth();
+        const client = await auth.getClobClient();
+        // Map side to Polymarket enum
+        const side = params.side.toUpperCase() === 'BUY' ? clob_client_1.Side.BUY : clob_client_1.Side.SELL;
+        // For limit orders, price is required
+        if (params.type === 'limit' && !params.price) {
+            throw new Error('Price is required for limit orders');
+        }
+        // For market orders, use max slippage: 0.99 for BUY (willing to pay up to 99%), 0.01 for SELL (willing to accept down to 1%)
+        const price = params.price || (side === clob_client_1.Side.BUY ? 0.99 : 0.01);
+        try {
+            // We use createAndPostOrder which handles signing and posting
+            const response = await client.createAndPostOrder({
+                tokenID: params.outcomeId,
+                price: price,
+                side: side,
+                size: params.amount,
+                feeRateBps: 0,
+            }, {
+                tickSize: "0.01"
+            });
+            if (!response || !response.success) {
+                throw new Error(response?.errorMsg || 'Order placement failed');
+            }
+            return {
+                id: response.orderID,
+                marketId: params.marketId,
+                outcomeId: params.outcomeId,
+                side: params.side,
+                type: params.type,
+                price: price,
+                amount: params.amount,
+                status: 'open',
+                filled: 0,
+                remaining: params.amount,
+                timestamp: Date.now()
+            };
+        }
+        catch (error) {
+            console.error("Polymarket createOrder error:", error);
+            throw error;
+        }
+    }
+    async cancelOrder(orderId) {
+        const auth = this.ensureAuth();
+        const client = await auth.getClobClient();
+        try {
+            await client.cancelOrder({ orderID: orderId });
+            return {
+                id: orderId,
+                marketId: 'unknown',
+                outcomeId: 'unknown',
+                side: 'buy',
+                type: 'limit',
+                amount: 0,
+                status: 'cancelled',
+                filled: 0,
+                remaining: 0,
+                timestamp: Date.now()
+            };
+        }
+        catch (error) {
+            console.error("Polymarket cancelOrder error:", error);
+            throw error;
+        }
+    }
+    async fetchOrder(orderId) {
+        const auth = this.ensureAuth();
+        const client = await auth.getClobClient();
+        try {
+            const order = await client.getOrder(orderId);
+            return {
+                id: order.id,
+                marketId: order.market || 'unknown',
+                outcomeId: order.asset_id,
+                side: order.side.toLowerCase(),
+                type: order.order_type === 'GTC' ? 'limit' : 'market',
+                price: parseFloat(order.price),
+                amount: parseFloat(order.original_size),
+                status: order.status, // Needs precise mapping
+                filled: parseFloat(order.size_matched),
+                remaining: parseFloat(order.original_size) - parseFloat(order.size_matched),
+                timestamp: order.created_at * 1000
+            };
+        }
+        catch (error) {
+            console.error("Polymarket fetchOrder error:", error);
+            throw error;
+        }
+    }
+    async fetchOpenOrders(marketId) {
+        const auth = this.ensureAuth();
+        const client = await auth.getClobClient();
+        try {
+            const orders = await client.getOpenOrders({
+                market: marketId
+            });
+            return orders.map((o) => ({
+                id: o.id,
+                marketId: o.market || 'unknown',
+                outcomeId: o.asset_id,
+                side: o.side.toLowerCase(),
+                type: 'limit',
+                price: parseFloat(o.price),
+                amount: parseFloat(o.original_size),
+                status: 'open',
+                filled: parseFloat(o.size_matched),
+                remaining: parseFloat(o.size_left || (parseFloat(o.original_size) - parseFloat(o.size_matched))),
+                timestamp: o.created_at * 1000
+            }));
+        }
+        catch (error) {
+            console.error("Polymarket fetchOpenOrders error:", error);
+            return [];
+        }
+    }
+    async fetchPositions() {
+        const auth = this.ensureAuth();
+        const address = auth.getAddress();
+        return (0, fetchPositions_1.fetchPositions)(address);
+    }
+    async fetchBalance() {
+        const auth = this.ensureAuth();
+        const client = await auth.getClobClient();
+        try {
+            // 1. Fetch raw collateral balance (USDC)
+            // Polymarket relies strictly on USDC (Polygon) which has 6 decimals.
+            const USDC_DECIMALS = 6;
+            const balRes = await client.getBalanceAllowance({
+                asset_type: clob_client_1.AssetType.COLLATERAL
+            });
+            const rawBalance = parseFloat(balRes.balance);
+            const total = rawBalance / Math.pow(10, USDC_DECIMALS);
+            // 2. Fetch open orders to calculate locked funds
+            // We only care about BUY orders for USDC balance locking
+            const openOrders = await client.getOpenOrders({});
+            let locked = 0;
+            if (openOrders && Array.isArray(openOrders)) {
+                for (const order of openOrders) {
+                    if (order.side === clob_client_1.Side.BUY) {
+                        const remainingSize = parseFloat(order.original_size) - parseFloat(order.size_matched);
+                        const price = parseFloat(order.price);
+                        locked += remainingSize * price;
+                    }
+                }
+            }
+            return [{
+                    currency: 'USDC',
+                    total: total,
+                    available: total - locked, // Available for new trades
+                    locked: locked
+                }];
+        }
+        catch (error) {
+            console.error("Polymarket fetchBalance error:", error);
+            throw error;
+        }
+    }
+}
+exports.PolymarketExchange = PolymarketExchange;

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

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

package/dist/exchanges/polymarket/searchMarkets.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchMarkets = searchMarkets;
+const fetchMarkets_1 = require("./fetchMarkets");
+async function searchMarkets(query, params) {
+    // Polymarket Gamma API doesn't support native search
+    // Fetch all active markets and filter client-side
+    const searchLimit = 100000; // Fetch all markets for comprehensive search
+    try {
+        // Fetch markets with a higher limit
+        const markets = await (0, fetchMarkets_1.fetchMarkets)({
+            ...params,
+            limit: searchLimit
+        });
+        // Client-side text filtering
+        const lowerQuery = query.toLowerCase();
+        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'
+        });
+        // Apply limit to filtered results
+        const limit = params?.limit || 20;
+        return filtered.slice(0, limit);
+    }
+    catch (error) {
+        console.error("Error searching Polymarket data:", error);
+        return [];
+    }
+}

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

@@ -0,0 +1,7 @@
+import { UnifiedMarket, CandleInterval } from '../../types';
+export declare const GAMMA_API_URL = "https://gamma-api.polymarket.com/events";
+export declare const CLOB_API_URL = "https://clob.polymarket.com";
+export declare function mapMarketToUnified(event: any, market: any, options?: {
+    useQuestionAsCandidateFallback?: boolean;
+}): UnifiedMarket | null;
+export declare function mapIntervalToFidelity(interval: CandleInterval): number;

package/dist/exchanges/polymarket/utils.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLOB_API_URL = exports.GAMMA_API_URL = void 0;
+exports.mapMarketToUnified = mapMarketToUnified;
+exports.mapIntervalToFidelity = mapIntervalToFidelity;
+exports.GAMMA_API_URL = 'https://gamma-api.polymarket.com/events';
+exports.CLOB_API_URL = 'https://clob.polymarket.com';
+function mapMarketToUnified(event, market, options = {}) {
+    if (!market)
+        return null;
+    const outcomes = [];
+    // Polymarket Gamma often returns 'outcomes' and 'outcomePrices' as stringified JSON keys.
+    let outcomeLabels = [];
+    let outcomePrices = [];
+    try {
+        outcomeLabels = typeof market.outcomes === 'string' ? JSON.parse(market.outcomes) : (market.outcomes || []);
+        outcomePrices = typeof market.outcomePrices === 'string' ? JSON.parse(market.outcomePrices) : (market.outcomePrices || []);
+    }
+    catch (e) {
+        console.warn(`Error parsing outcomes for market ${market.id}:`, e);
+    }
+    // Extract CLOB token IDs for granular operations
+    let clobTokenIds = [];
+    try {
+        clobTokenIds = typeof market.clobTokenIds === 'string' ? JSON.parse(market.clobTokenIds) : (market.clobTokenIds || []);
+    }
+    catch (e) {
+        // console.warn(`Error parsing clobTokenIds for market ${market.id}`, e);
+    }
+    // Extract candidate/option name from market question for better outcome labels
+    let candidateName = null;
+    if (market.groupItemTitle) {
+        candidateName = market.groupItemTitle;
+    }
+    else if (market.question && options.useQuestionAsCandidateFallback) {
+        // Fallback or sometimes question is the candidate name in nested structures
+        // Only used if explicitly requested (e.g. for getMarketsBySlug)
+        candidateName = market.question;
+    }
+    if (outcomeLabels.length > 0) {
+        outcomeLabels.forEach((label, index) => {
+            const rawPrice = outcomePrices[index] || "0";
+            // For Yes/No markets with specific candidates, use the candidate name
+            let outcomeLabel = label;
+            if (candidateName && label.toLowerCase() === 'yes') {
+                outcomeLabel = candidateName;
+            }
+            else if (candidateName && label.toLowerCase() === 'no') {
+                outcomeLabel = `Not ${candidateName}`;
+            }
+            // 24h Price Change
+            // Polymarket API provides 'oneDayPriceChange' on the market object
+            let priceChange = 0;
+            if (index === 0 || label.toLowerCase() === 'yes' || (candidateName && label === candidateName)) {
+                priceChange = Number(market.oneDayPriceChange || 0);
+            }
+            outcomes.push({
+                id: clobTokenIds[index] || String(index), // Use CLOB Token ID as the primary ID
+                label: outcomeLabel,
+                price: parseFloat(rawPrice) || 0,
+                priceChange24h: priceChange,
+                metadata: {
+                    // clobTokenId is now the main ID, but keeping it in metadata for backward compat if needed
+                    clobTokenId: clobTokenIds[index]
+                }
+            });
+        });
+    }
+    return {
+        id: market.id,
+        title: market.question ? `${event.title} - ${market.question}` : event.title,
+        description: market.description || event.description,
+        outcomes: outcomes,
+        resolutionDate: market.endDate ? new Date(market.endDate) : (market.end_date_iso ? new Date(market.end_date_iso) : new Date()),
+        volume24h: Number(market.volume24hr || market.volume_24h || 0),
+        volume: Number(market.volume || 0),
+        liquidity: Number(market.liquidity || market.rewards?.liquidity || 0),
+        openInterest: Number(market.openInterest || market.open_interest || 0),
+        url: `https://polymarket.com/event/${event.slug}`,
+        image: event.image || market.image || `https://polymarket.com/api/og?slug=${event.slug}`,
+        category: event.category || event.tags?.[0]?.label,
+        tags: event.tags?.map((t) => t.label) || []
+    };
+}
+function mapIntervalToFidelity(interval) {
+    const mapping = {
+        '1m': 1,
+        '5m': 5,
+        '15m': 15,
+        '1h': 60,
+        '6h': 360,
+        '1d': 1440
+    };
+    return mapping[interval];
+}