@catalyst-team/poly-sdk 0.2.1 → 0.4.0

package/dist/services/market-service.js

@@ -1,25 +1,268 @@
 /**
  * Market Service
  *
- * Provides enhanced market analysis features:
+ * Provides market data and analysis:
+ * - Market info and discovery
+ * - Orderbook data and analysis
  * - K-Line aggregation from trade data
- * - Dual token K-Lines (YES + NO)
  * - Spread analysis
- * - Market signal detection
+ * - Arbitrage detection
  */
+import { ClobClient, Side as ClobSide, PriceHistoryInterval, } from '@polymarket/clob-client';
+import { Wallet } from 'ethers';
+import { CACHE_TTL } from '../core/unified-cache.js';
+import { ApiType } from '../core/rate-limiter.js';
 import { PolymarketError, ErrorCode } from '../core/errors.js';
+// CLOB Host
+const CLOB_HOST = 'https://clob.polymarket.com';
+// Chain IDs
+export const POLYGON_MAINNET = 137;
+// Mapping from underlying asset to Binance symbol
+const UNDERLYING_TO_SYMBOL = {
+    BTC: 'BTCUSDT',
+    ETH: 'ETHUSDT',
+    SOL: 'SOLUSDT',
+};
+// Map from KLineInterval to BinanceInterval (Binance doesn't support 30s or 12h)
+const KLINE_TO_BINANCE_INTERVAL = {
+    '1m': '1m',
+    '5m': '5m',
+    '15m': '15m',
+    '30m': '30m',
+    '1h': '1h',
+    '4h': '4h',
+    '1d': '1d',
+};
+// ============================================================================
+// MarketService Implementation
+// ============================================================================
 export class MarketService {
     gammaApi;
-    clobApi;
     dataApi;
+    rateLimiter;
     cache;
-    constructor(gammaApi, clobApi, dataApi, cache) {
+    config;
+    binanceService;
+    clobClient = null;
+    initialized = false;
+    constructor(gammaApi, dataApi, rateLimiter, cache, config, binanceService) {
         this.gammaApi = gammaApi;
-        this.clobApi = clobApi;
         this.dataApi = dataApi;
+        this.rateLimiter = rateLimiter;
         this.cache = cache;
+        this.config = config;
+        this.binanceService = binanceService;
+    }
+    // ============================================================================
+    // Initialization
+    // ============================================================================
+    async ensureInitialized() {
+        if (!this.initialized || !this.clobClient) {
+            const chainId = (this.config?.chainId || POLYGON_MAINNET);
+            if (this.config?.privateKey) {
+                // Authenticated client
+                const wallet = new Wallet(this.config.privateKey);
+                this.clobClient = new ClobClient(CLOB_HOST, chainId, wallet);
+            }
+            else {
+                // Read-only client (no auth needed for market data)
+                this.clobClient = new ClobClient(CLOB_HOST, chainId);
+            }
+            this.initialized = true;
+        }
+        return this.clobClient;
+    }
+    // ============================================================================
+    // CLOB Market Data Methods
+    // ============================================================================
+    /**
+     * Get market from CLOB by condition ID
+     */
+    async getClobMarket(conditionId) {
+        const cacheKey = `clob:market:${conditionId}`;
+        return this.cache.getOrSet(cacheKey, CACHE_TTL.MARKET_INFO, async () => {
+            const client = await this.ensureInitialized();
+            return this.rateLimiter.execute(ApiType.CLOB_API, async () => {
+                try {
+                    const market = await client.getMarket(conditionId);
+                    if (!market || !market.tokens) {
+                        return null;
+                    }
+                    return this.normalizeClobMarket(market);
+                }
+                catch (error) {
+                    // Handle 404 "market not found" gracefully
+                    if (error && typeof error === 'object' && 'status' in error && error.status === 404) {
+                        return null;
+                    }
+                    throw error;
+                }
+            });
+        });
+    }
+    /**
+     * Get multiple markets from CLOB
+     */
+    async getClobMarkets(nextCursor) {
+        const client = await this.ensureInitialized();
+        return this.rateLimiter.execute(ApiType.CLOB_API, async () => {
+            const result = await client.getMarkets(nextCursor);
+            return {
+                markets: result.data.map(m => this.normalizeClobMarket(m)),
+                nextCursor: result.next_cursor,
+            };
+        });
+    }
+    /**
+     * Get orderbook for a single token
+     */
+    async getTokenOrderbook(tokenId) {
+        const client = await this.ensureInitialized();
+        return this.rateLimiter.execute(ApiType.CLOB_API, async () => {
+            const book = await client.getOrderBook(tokenId);
+            const bids = (book.bids || [])
+                .map((l) => ({
+                price: parseFloat(l.price),
+                size: parseFloat(l.size),
+            }))
+                .sort((a, b) => b.price - a.price);
+            const asks = (book.asks || [])
+                .map((l) => ({
+                price: parseFloat(l.price),
+                size: parseFloat(l.size),
+            }))
+                .sort((a, b) => a.price - b.price);
+            return {
+                tokenId: book.asset_id,
+                assetId: book.asset_id, // Backward compatibility
+                bids,
+                asks,
+                timestamp: parseInt(book.timestamp || '0', 10) || Date.now(),
+                market: book.market,
+                hash: book.hash,
+            };
+        });
+    }
+    /**
+     * Get orderbooks for multiple tokens
+     */
+    async getTokenOrderbooks(params) {
+        const client = await this.ensureInitialized();
+        return this.rateLimiter.execute(ApiType.CLOB_API, async () => {
+            const bookParams = params.map(p => ({
+                token_id: p.tokenId,
+                side: p.side === 'BUY' ? ClobSide.BUY : ClobSide.SELL,
+            }));
+            const books = await client.getOrderBooks(bookParams);
+            const result = new Map();
+            for (const book of books) {
+                const bids = (book.bids || [])
+                    .map((l) => ({
+                    price: parseFloat(l.price),
+                    size: parseFloat(l.size),
+                }))
+                    .sort((a, b) => b.price - a.price);
+                const asks = (book.asks || [])
+                    .map((l) => ({
+                    price: parseFloat(l.price),
+                    size: parseFloat(l.size),
+                }))
+                    .sort((a, b) => a.price - b.price);
+                result.set(book.asset_id, {
+                    tokenId: book.asset_id,
+                    assetId: book.asset_id, // Backward compatibility
+                    bids,
+                    asks,
+                    timestamp: parseInt(book.timestamp || '0', 10) || Date.now(),
+                    market: book.market,
+                    hash: book.hash,
+                });
+            }
+            return result;
+        });
+    }
+    /**
+     * Get processed orderbook with arbitrage analysis for a market
+     */
+    async getProcessedOrderbook(conditionId) {
+        const market = await this.getClobMarket(conditionId);
+        if (!market) {
+            throw new PolymarketError(ErrorCode.MARKET_NOT_FOUND, `Market not found: ${conditionId}`);
+        }
+        // Use index-based access instead of name-based (supports Yes/No, Up/Down, Team1/Team2, etc.)
+        const yesToken = market.tokens[0]; // primary outcome
+        const noToken = market.tokens[1]; // secondary outcome
+        if (!yesToken || !noToken) {
+            throw new PolymarketError(ErrorCode.INVALID_RESPONSE, 'Missing tokens in market');
+        }
+        const [yesBook, noBook] = await Promise.all([
+            this.getTokenOrderbook(yesToken.tokenId),
+            this.getTokenOrderbook(noToken.tokenId),
+        ]);
+        return this.processOrderbooks(yesBook, noBook, yesToken.tokenId, noToken.tokenId);
+    }
+    /**
+     * Get price history for a token
+     */
+    async getPricesHistory(params) {
+        const client = await this.ensureInitialized();
+        return this.rateLimiter.execute(ApiType.CLOB_API, async () => {
+            const intervalMap = {
+                '1h': PriceHistoryInterval.ONE_HOUR,
+                '6h': PriceHistoryInterval.SIX_HOURS,
+                '1d': PriceHistoryInterval.ONE_DAY,
+                '1w': PriceHistoryInterval.ONE_WEEK,
+                'max': PriceHistoryInterval.MAX,
+            };
+            const history = await client.getPricesHistory({
+                market: params.tokenId,
+                interval: params.interval ? intervalMap[params.interval] : undefined,
+                startTs: params.startTs,
+                endTs: params.endTs,
+                fidelity: params.fidelity,
+            });
+            const historyArray = Array.isArray(history)
+                ? history
+                : history?.history || [];
+            return historyArray.map((pt) => ({
+                timestamp: pt.t,
+                price: pt.p,
+            }));
+        });
     }
-    // ===== Unified Market Access =====
+    /**
+     * Get midpoint price for a token
+     */
+    async getMidpoint(tokenId) {
+        const client = await this.ensureInitialized();
+        return this.rateLimiter.execute(ApiType.CLOB_API, async () => {
+            const midpoint = await client.getMidpoint(tokenId);
+            return Number(midpoint);
+        });
+    }
+    /**
+     * Get spread for a token
+     */
+    async getSpread(tokenId) {
+        const client = await this.ensureInitialized();
+        return this.rateLimiter.execute(ApiType.CLOB_API, async () => {
+            const spread = await client.getSpread(tokenId);
+            return Number(spread);
+        });
+    }
+    /**
+     * Get last trade price for a token
+     */
+    async getLastTradePrice(tokenId) {
+        const client = await this.ensureInitialized();
+        return this.rateLimiter.execute(ApiType.CLOB_API, async () => {
+            const price = await client.getLastTradePrice(tokenId);
+            return Number(price);
+        });
+    }
+    // ============================================================================
+    // Unified Market Access
+    // ============================================================================
     /**
      * Get market by slug or condition ID
      */
@@ -33,13 +276,19 @@ export class MarketService {
         }
     }
     async getMarketBySlug(slug) {
+        if (!this.gammaApi) {
+            throw new PolymarketError(ErrorCode.INVALID_CONFIG, 'GammaApiClient is required for slug-based lookups');
+        }
         const gammaMarket = await this.gammaApi.getMarketBySlug(slug);
         if (!gammaMarket) {
             throw new PolymarketError(ErrorCode.MARKET_NOT_FOUND, `Market not found: ${slug}`);
         }
         try {
-            const clobMarket = await this.clobApi.getMarket(gammaMarket.conditionId);
-            return this.mergeMarkets(gammaMarket, clobMarket);
+            const clobMarket = await this.getClobMarket(gammaMarket.conditionId);
+            if (clobMarket) {
+                return this.mergeMarkets(gammaMarket, clobMarket);
+            }
+            return this.fromGammaMarket(gammaMarket);
         }
         catch {
             return this.fromGammaMarket(gammaMarket);
@@ -51,17 +300,19 @@ export class MarketService {
         let gammaMarket = null;
         // Try CLOB first (authoritative for trading data)
         try {
-            clobMarket = await this.clobApi.getMarket(conditionId);
+            clobMarket = await this.getClobMarket(conditionId);
         }
         catch {
             // CLOB failed, continue to try Gamma
         }
-        // Always try Gamma for accurate slug and metadata
-        try {
-            gammaMarket = await this.gammaApi.getMarketByConditionId(conditionId);
-        }
-        catch {
-            // Gamma failed
+        // Always try Gamma for accurate slug and metadata (if available)
+        if (this.gammaApi) {
+            try {
+                gammaMarket = await this.gammaApi.getMarketByConditionId(conditionId);
+            }
+            catch {
+                // Gamma failed
+            }
         }
         // Merge if both available (preferred)
         if (gammaMarket && clobMarket) {
@@ -74,7 +325,7 @@ export class MarketService {
         // CLOB only - slug might be stale, add warning
         if (clobMarket) {
             const market = this.fromClobMarket(clobMarket);
-            // Check if CLOB slug looks stale (doesn't match question keywords)
+            // Check if slug looks stale (doesn't match question keywords)
             const questionWords = clobMarket.question.toLowerCase().split(/\s+/).slice(0, 3);
             const slugWords = clobMarket.marketSlug.toLowerCase().split('-');
             const hasMatchingWord = questionWords.some(qw => slugWords.some(sw => sw.includes(qw) || qw.includes(sw)));
@@ -89,9 +340,36 @@ export class MarketService {
     // ===== K-Line Aggregation =====
     /**
      * Get K-Line candles for a market (single token)
+     *
+     * @param conditionId - Market condition ID
+     * @param interval - K-line interval (1s, 5s, 15s, 30s, 1m, 5m, 15m, 30m, 1h, 4h, 12h, 1d)
+     * @param options - Query options
+     * @param options.limit - Maximum number of trades to fetch for aggregation (default: 1000)
+     * @param options.tokenId - Filter by specific token ID
+     * @param options.outcomeIndex - Filter by outcome index (0 = primary, 1 = secondary)
+     * @param options.startTimestamp - Start timestamp (Unix ms) - filter trades after this time
+     * @param options.endTimestamp - End timestamp (Unix ms) - filter trades before this time
+     *
+     * @example
+     * ```typescript
+     * // Get 5s candles for the last 15 minutes
+     * const now = Date.now();
+     * const candles = await sdk.markets.getKLines(conditionId, '5s', {
+     *   startTimestamp: now - 15 * 60 * 1000,
+     *   endTimestamp: now,
+     * });
+     * ```
      */
     async getKLines(conditionId, interval, options) {
-        const trades = await this.dataApi.getTradesByMarket(conditionId, options?.limit || 1000);
+        if (!this.dataApi) {
+            throw new PolymarketError(ErrorCode.INVALID_CONFIG, 'DataApiClient is required for K-Line data');
+        }
+        const trades = await this.dataApi.getTrades({
+            market: conditionId,
+            limit: options?.limit || 1000,
+            startTimestamp: options?.startTimestamp,
+            endTimestamp: options?.endTimestamp,
+        });
         // Filter by token/outcome if specified
         let filteredTrades = trades;
         if (options?.tokenId) {
@@ -104,20 +382,47 @@ export class MarketService {
     }
     /**
      * Get dual K-Lines (YES + NO tokens)
+     *
+     * @param conditionId - Market condition ID
+     * @param interval - K-line interval (1s, 5s, 15s, 30s, 1m, 5m, 15m, 30m, 1h, 4h, 12h, 1d)
+     * @param options - Query options
+     * @param options.limit - Maximum number of trades to fetch for aggregation (default: 1000)
+     * @param options.startTimestamp - Start timestamp (Unix ms) - filter trades after this time
+     * @param options.endTimestamp - End timestamp (Unix ms) - filter trades before this time
+     *
+     * @example
+     * ```typescript
+     * // Get 15s dual K-lines for a 15-minute market
+     * const now = Date.now();
+     * const data = await sdk.markets.getDualKLines(conditionId, '15s', {
+     *   startTimestamp: now - 15 * 60 * 1000,
+     *   endTimestamp: now,
+     * });
+     * console.log(`Up candles: ${data.yes.length}, Down candles: ${data.no.length}`);
+     * ```
      */
     async getDualKLines(conditionId, interval, options) {
+        if (!this.dataApi) {
+            throw new PolymarketError(ErrorCode.INVALID_CONFIG, 'DataApiClient is required for K-Line data');
+        }
         const market = await this.getMarket(conditionId);
-        const trades = await this.dataApi.getTradesByMarket(conditionId, options?.limit || 1000);
-        // Separate trades by outcome
-        const yesTrades = trades.filter((t) => t.outcomeIndex === 0 || t.outcome === 'Yes');
-        const noTrades = trades.filter((t) => t.outcomeIndex === 1 || t.outcome === 'No');
+        const trades = await this.dataApi.getTrades({
+            market: conditionId,
+            limit: options?.limit || 1000,
+            startTimestamp: options?.startTimestamp,
+            endTimestamp: options?.endTimestamp,
+        });
+        // Separate trades by outcome using index (more reliable than name matching)
+        // outcomeIndex 0 = primary (Yes/Up/Team1), outcomeIndex 1 = secondary (No/Down/Team2)
+        const yesTrades = trades.filter((t) => t.outcomeIndex === 0);
+        const noTrades = trades.filter((t) => t.outcomeIndex === 1);
         const yesCandles = this.aggregateToKLines(yesTrades, interval);
         const noCandles = this.aggregateToKLines(noTrades, interval);
         // Get current orderbook for real-time spread analysis
         let currentOrderbook;
         let realtimeSpread;
         try {
-            currentOrderbook = await this.clobApi.getProcessedOrderbook(conditionId);
+            currentOrderbook = await this.getProcessedOrderbook(conditionId);
             realtimeSpread = this.calculateRealtimeSpread(currentOrderbook);
         }
         catch {
@@ -136,6 +441,184 @@ export class MarketService {
             currentOrderbook,
         };
     }
+    // ===== Token vs Underlying Correlation =====
+    /**
+     * Get aligned K-line data for token and underlying asset
+     *
+     * This method fetches K-line data from both Polymarket (token prices)
+     * and Binance (underlying asset prices), aligns them by timestamp,
+     * and optionally calculates Pearson correlation coefficients.
+     *
+     * @param conditionId - Market condition ID
+     * @param underlying - Underlying asset (BTC, ETH, SOL)
+     * @param interval - K-line interval (must be supported by both Poly and Binance)
+     * @param options - Optional parameters
+     * @returns Aligned data with optional correlation coefficients
+     *
+     * @example
+     * ```typescript
+     * const data = await marketService.getTokenUnderlyingData(
+     *   '0x123...',
+     *   'BTC',
+     *   '1h',
+     *   { limit: 100, calculateCorrelation: true }
+     * );
+     *
+     * // Access aligned data
+     * for (const point of data.data) {
+     *   console.log(`${point.timestamp}: Up=${point.upPrice}, BTC=${point.underlyingPrice}`);
+     * }
+     *
+     * // Check correlation
+     * if (data.correlation) {
+     *   console.log(`Correlation: ${data.correlation.upVsUnderlying}`);
+     * }
+     * ```
+     */
+    async getTokenUnderlyingData(conditionId, underlying, interval, options) {
+        // Validate BinanceService is available
+        if (!this.binanceService) {
+            throw new PolymarketError(ErrorCode.INVALID_CONFIG, 'BinanceService is required for token-underlying correlation analysis');
+        }
+        // Validate interval is supported by Binance
+        const binanceInterval = KLINE_TO_BINANCE_INTERVAL[interval];
+        if (!binanceInterval) {
+            throw new PolymarketError(ErrorCode.INVALID_CONFIG, `Interval ${interval} is not supported for correlation analysis. ` +
+                `Supported intervals: ${Object.keys(KLINE_TO_BINANCE_INTERVAL).join(', ')}`);
+        }
+        const limit = options?.limit || 500;
+        // Fetch data in parallel
+        const [dualKLines, binanceKLines] = await Promise.all([
+            this.getDualKLines(conditionId, interval, { limit }),
+            this.binanceService.getKLines(UNDERLYING_TO_SYMBOL[underlying], binanceInterval, { limit }),
+        ]);
+        // Create maps for quick lookup
+        const upMap = new Map(dualKLines.yes.map(c => [c.timestamp, c.close]));
+        const downMap = new Map(dualKLines.no.map(c => [c.timestamp, c.close]));
+        const binanceMap = new Map(binanceKLines.map(c => [c.timestamp, c.close]));
+        // Get all unique timestamps and sort them
+        const allTimestamps = new Set([
+            ...upMap.keys(),
+            ...downMap.keys(),
+            ...binanceMap.keys(),
+        ]);
+        const sortedTimestamps = [...allTimestamps].sort((a, b) => a - b);
+        // Find the first Binance price for calculating percentage change
+        const firstBinancePrice = binanceKLines.length > 0 ? binanceKLines[0].close : 0;
+        // Align data points
+        const alignedData = [];
+        let lastUpPrice;
+        let lastDownPrice;
+        let lastBinancePrice;
+        for (const timestamp of sortedTimestamps) {
+            // Get prices, falling back to previous values if not available
+            const upPrice = upMap.get(timestamp) ?? this.findNearestPrice(timestamp, upMap, sortedTimestamps);
+            const downPrice = downMap.get(timestamp) ?? this.findNearestPrice(timestamp, downMap, sortedTimestamps);
+            const binancePrice = binanceMap.get(timestamp) ?? this.findNearestPrice(timestamp, binanceMap, sortedTimestamps);
+            // Update last known prices
+            if (upPrice !== undefined)
+                lastUpPrice = upPrice;
+            if (downPrice !== undefined)
+                lastDownPrice = downPrice;
+            if (binancePrice !== undefined)
+                lastBinancePrice = binancePrice;
+            // Skip if we don't have underlying price
+            if (lastBinancePrice === undefined)
+                continue;
+            const priceSum = (lastUpPrice !== undefined && lastDownPrice !== undefined)
+                ? lastUpPrice + lastDownPrice
+                : undefined;
+            const underlyingChange = firstBinancePrice > 0
+                ? ((lastBinancePrice - firstBinancePrice) / firstBinancePrice) * 100
+                : 0;
+            alignedData.push({
+                timestamp,
+                upPrice: lastUpPrice,
+                downPrice: lastDownPrice,
+                priceSum,
+                underlyingPrice: lastBinancePrice,
+                underlyingChange,
+            });
+        }
+        // Calculate correlation if requested
+        let correlation;
+        if (options?.calculateCorrelation && alignedData.length >= 2) {
+            correlation = this.calculatePearsonCorrelation(alignedData);
+        }
+        return {
+            conditionId,
+            underlying,
+            interval,
+            data: alignedData,
+            correlation,
+        };
+    }
+    /**
+     * Find the nearest available price for a timestamp
+     */
+    findNearestPrice(targetTimestamp, priceMap, sortedTimestamps) {
+        if (priceMap.size === 0)
+            return undefined;
+        // Find the nearest timestamp that has a price
+        let nearestTimestamp;
+        let minDiff = Infinity;
+        for (const ts of sortedTimestamps) {
+            if (priceMap.has(ts)) {
+                const diff = Math.abs(ts - targetTimestamp);
+                if (diff < minDiff) {
+                    minDiff = diff;
+                    nearestTimestamp = ts;
+                }
+            }
+        }
+        return nearestTimestamp !== undefined ? priceMap.get(nearestTimestamp) : undefined;
+    }
+    /**
+     * Calculate Pearson correlation coefficients
+     */
+    calculatePearsonCorrelation(data) {
+        // Filter data points that have all required prices
+        const upData = data.filter(d => d.upPrice !== undefined && d.underlyingPrice !== undefined);
+        const downData = data.filter(d => d.downPrice !== undefined && d.underlyingPrice !== undefined);
+        const upVsUnderlying = this.pearson(upData.map(d => d.upPrice), upData.map(d => d.underlyingPrice));
+        const downVsUnderlying = this.pearson(downData.map(d => d.downPrice), downData.map(d => d.underlyingPrice));
+        return {
+            upVsUnderlying,
+            downVsUnderlying,
+        };
+    }
+    /**
+     * Calculate Pearson correlation coefficient between two arrays
+     * Returns a value between -1 and 1
+     */
+    pearson(x, y) {
+        const n = Math.min(x.length, y.length);
+        if (n < 2)
+            return 0;
+        // Calculate means
+        let sumX = 0, sumY = 0;
+        for (let i = 0; i < n; i++) {
+            sumX += x[i];
+            sumY += y[i];
+        }
+        const meanX = sumX / n;
+        const meanY = sumY / n;
+        // Calculate correlation
+        let numerator = 0;
+        let sumSqX = 0;
+        let sumSqY = 0;
+        for (let i = 0; i < n; i++) {
+            const dx = x[i] - meanX;
+            const dy = y[i] - meanY;
+            numerator += dx * dy;
+            sumSqX += dx * dx;
+            sumSqY += dy * dy;
+        }
+        const denominator = Math.sqrt(sumSqX * sumSqY);
+        if (denominator === 0)
+            return 0;
+        return numerator / denominator;
+    }
     /**
      * Aggregate trades into K-Line candles
      */
@@ -262,15 +745,15 @@ export class MarketService {
      * Use this for quick arbitrage checks
      */
     async getRealtimeSpread(conditionId) {
-        const orderbook = await this.clobApi.getProcessedOrderbook(conditionId);
+        const orderbook = await this.getProcessedOrderbook(conditionId);
         return this.calculateRealtimeSpread(orderbook);
     }
     // ===== Orderbook Analysis =====
     /**
-     * Get processed orderbook with analytics
+     * Get processed orderbook with analytics (alias for getProcessedOrderbook)
      */
     async getOrderbook(conditionId) {
-        return this.clobApi.getProcessedOrderbook(conditionId);
+        return this.getProcessedOrderbook(conditionId);
     }
     /**
      * Detect arbitrage opportunity
@@ -306,20 +789,171 @@ export class MarketService {
      * Get trending markets
      */
     async getTrendingMarkets(limit = 20) {
+        if (!this.gammaApi) {
+            throw new PolymarketError(ErrorCode.INVALID_CONFIG, 'GammaApiClient is required for trending markets');
+        }
         return this.gammaApi.getTrendingMarkets(limit);
     }
     /**
      * Search markets
      */
     async searchMarkets(params) {
+        if (!this.gammaApi) {
+            throw new PolymarketError(ErrorCode.INVALID_CONFIG, 'GammaApiClient is required for market search');
+        }
         return this.gammaApi.getMarkets(params);
     }
+    /**
+     * Scan for short-term crypto markets (Up/Down markets ending soon)
+     *
+     * ## Market Types
+     * Polymarket has short-term crypto markets in two durations:
+     * - **5-minute markets**: slug pattern `{coin}-updown-5m-{timestamp}`
+     * - **15-minute markets**: slug pattern `{coin}-updown-15m-{timestamp}`
+     *
+     * ## Slug Pattern
+     * The timestamp in the slug is the START time of the time window:
+     * - 15-minute markets: `{coin}-updown-15m-{Math.floor(startTime / 900) * 900}`
+     * - 5-minute markets: `{coin}-updown-5m-{Math.floor(startTime / 300) * 300}`
+     *
+     * Example: `btc-updown-15m-1767456000` starts at 1767456000 (16:00:00 UTC)
+     * and ends 15 minutes later at 1767456900 (16:15:00 UTC)
+     *
+     * ## Supported Coins
+     * - BTC (Bitcoin)
+     * - ETH (Ethereum)
+     * - SOL (Solana)
+     * - XRP (Ripple)
+     *
+     * ## Market Lifecycle Rules
+     * 1. Markets are created ahead of time (before they become tradeable)
+     * 2. New markets may not have prices yet (show 0.5/0.5)
+     * 3. When one market ends, the next one is already open for trading
+     * 4. A market ending doesn't mean no price - it means resolution is pending
+     *
+     * ## Outcomes
+     * All crypto short-term markets have:
+     * - outcomes: ["Up", "Down"]
+     * - Resolution based on price movement during the time window
+     *
+     * @param options - Scan options
+     * @param options.minMinutesUntilEnd - Minimum minutes until market ends (default: 5)
+     * @param options.maxMinutesUntilEnd - Maximum minutes until market ends (default: 60)
+     * @param options.limit - Maximum number of markets to return (default: 20)
+     * @param options.sortBy - Sort field: 'endDate' | 'volume' | 'liquidity' (default: 'endDate')
+     * @param options.duration - Filter by duration: '5m' | '15m' | 'all' (default: 'all')
+     * @param options.coin - Filter by coin: 'BTC' | 'ETH' | 'SOL' | 'XRP' | 'all' (default: 'all')
+     * @returns Array of crypto short-term markets
+     *
+     * @example
+     * ```typescript
+     * // Find all 15-minute markets ending in 5-30 minutes
+     * const markets = await sdk.markets.scanCryptoShortTermMarkets({
+     *   minMinutesUntilEnd: 5,
+     *   maxMinutesUntilEnd: 30,
+     *   duration: '15m',
+     * });
+     *
+     * // Find BTC 5-minute markets only
+     * const btcMarkets = await sdk.markets.scanCryptoShortTermMarkets({
+     *   coin: 'BTC',
+     *   duration: '5m',
+     * });
+     * ```
+     */
+    async scanCryptoShortTermMarkets(options) {
+        if (!this.gammaApi) {
+            throw new PolymarketError(ErrorCode.INVALID_CONFIG, 'GammaApiClient is required for market scanning');
+        }
+        const { minMinutesUntilEnd = 5, maxMinutesUntilEnd = 60, limit = 20, sortBy = 'endDate', duration = 'all', coin = 'all', } = options ?? {};
+        // Duration to interval seconds mapping
+        const durationIntervals = {
+            '5m': 300, // 5 minutes in seconds
+            '15m': 900, // 15 minutes in seconds
+        };
+        // Supported coins
+        const allCoins = ['btc', 'eth', 'sol', 'xrp'];
+        const targetCoins = coin === 'all' ? allCoins : [coin.toLowerCase()];
+        // Target durations
+        const targetDurations = duration === 'all' ? ['5m', '15m'] : [duration];
+        // Calculate time slots to fetch
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        const minEndSeconds = nowSeconds + minMinutesUntilEnd * 60;
+        const maxEndSeconds = nowSeconds + maxMinutesUntilEnd * 60;
+        // Generate slugs for all combinations
+        const slugsToFetch = [];
+        for (const dur of targetDurations) {
+            const intervalSeconds = durationIntervals[dur];
+            const durationStr = dur.replace('m', 'm'); // 5m or 15m
+            // Calculate the current slot and extend to cover the time range
+            // The slug timestamp is the START time, endTime = startTime + interval
+            // So if we want markets ending after minEndSeconds:
+            //   startTime + interval >= minEndSeconds => startTime >= minEndSeconds - interval
+            // And ending before maxEndSeconds:
+            //   startTime + interval <= maxEndSeconds => startTime <= maxEndSeconds - interval
+            const minSlotStart = Math.floor((minEndSeconds - intervalSeconds) / intervalSeconds) * intervalSeconds;
+            const maxSlotStart = Math.ceil(maxEndSeconds / intervalSeconds) * intervalSeconds;
+            // Generate slots from minSlotStart to maxSlotStart
+            for (let slotStart = minSlotStart; slotStart <= maxSlotStart; slotStart += intervalSeconds) {
+                for (const coinName of targetCoins) {
+                    slugsToFetch.push(`${coinName}-updown-${durationStr}-${slotStart}`);
+                }
+            }
+        }
+        // Fetch markets in parallel batches
+        const BATCH_SIZE = 10;
+        const allMarkets = [];
+        for (let i = 0; i < slugsToFetch.length; i += BATCH_SIZE) {
+            const batch = slugsToFetch.slice(i, i + BATCH_SIZE);
+            const results = await Promise.all(batch.map(async (slug) => {
+                try {
+                    const markets = await this.gammaApi.getMarkets({ slug, limit: 1 });
+                    return markets.length > 0 ? markets[0] : null;
+                }
+                catch {
+                    return null;
+                }
+            }));
+            for (const market of results) {
+                if (market && market.active && !market.closed) {
+                    allMarkets.push(market);
+                }
+            }
+        }
+        // Filter by end time range
+        const nowMs = Date.now();
+        const minEndTime = nowMs + minMinutesUntilEnd * 60 * 1000;
+        const maxEndTime = nowMs + maxMinutesUntilEnd * 60 * 1000;
+        const filteredMarkets = allMarkets.filter((market) => {
+            const endTime = market.endDate ? new Date(market.endDate).getTime() : 0;
+            return endTime >= minEndTime && endTime <= maxEndTime;
+        });
+        // Sort by preference
+        if (sortBy === 'volume') {
+            filteredMarkets.sort((a, b) => (b.volume24hr ?? 0) - (a.volume24hr ?? 0));
+        }
+        else if (sortBy === 'liquidity') {
+            filteredMarkets.sort((a, b) => (b.liquidity ?? 0) - (a.liquidity ?? 0));
+        }
+        else {
+            // Sort by endDate (soonest first)
+            filteredMarkets.sort((a, b) => {
+                const aEnd = a.endDate ? new Date(a.endDate).getTime() : Infinity;
+                const bEnd = b.endDate ? new Date(b.endDate).getTime() : Infinity;
+                return aEnd - bEnd;
+            });
+        }
+        return filteredMarkets.slice(0, limit);
+    }
     // ===== Market Signal Detection =====
     /**
      * Detect market signals (volume surge, depth imbalance, whale trades)
      */
     async detectMarketSignals(conditionId) {
         const signals = [];
+        if (!this.dataApi) {
+            throw new PolymarketError(ErrorCode.INVALID_CONFIG, 'DataApiClient is required for signal detection');
+        }
         const market = await this.getMarket(conditionId);
         const orderbook = await this.getOrderbook(conditionId);
         const trades = await this.dataApi.getTradesByMarket(conditionId, 100);
@@ -368,18 +1002,101 @@ export class MarketService {
         return signals;
     }
     // ===== Helper Methods =====
+    normalizeClobMarket(m) {
+        return {
+            conditionId: m.condition_id,
+            questionId: m.question_id,
+            marketSlug: m.market_slug,
+            question: m.question,
+            description: m.description,
+            tokens: m.tokens.map(t => ({
+                tokenId: t.token_id,
+                outcome: t.outcome,
+                price: t.price,
+                winner: t.winner,
+            })),
+            active: m.active,
+            closed: m.closed,
+            acceptingOrders: m.accepting_orders,
+            endDateIso: m.end_date_iso,
+            negRisk: m.neg_risk,
+            minimumOrderSize: m.minimum_order_size,
+            minimumTickSize: m.minimum_tick_size,
+        };
+    }
+    processOrderbooks(yesBook, noBook, yesTokenId, noTokenId) {
+        const yesBestBid = yesBook.bids[0]?.price || 0;
+        const yesBestAsk = yesBook.asks[0]?.price || 1;
+        const noBestBid = noBook.bids[0]?.price || 0;
+        const noBestAsk = noBook.asks[0]?.price || 1;
+        const yesBidDepth = yesBook.bids.reduce((sum, l) => sum + l.price * l.size, 0);
+        const yesAskDepth = yesBook.asks.reduce((sum, l) => sum + l.price * l.size, 0);
+        const noBidDepth = noBook.bids.reduce((sum, l) => sum + l.price * l.size, 0);
+        const noAskDepth = noBook.asks.reduce((sum, l) => sum + l.price * l.size, 0);
+        const askSum = yesBestAsk + noBestAsk;
+        const bidSum = yesBestBid + noBestBid;
+        // Effective prices (accounting for mirroring)
+        const effectivePrices = {
+            effectiveBuyYes: Math.min(yesBestAsk, 1 - noBestBid),
+            effectiveBuyNo: Math.min(noBestAsk, 1 - yesBestBid),
+            effectiveSellYes: Math.max(yesBestBid, 1 - noBestAsk),
+            effectiveSellNo: Math.max(noBestBid, 1 - yesBestAsk),
+        };
+        const effectiveLongCost = effectivePrices.effectiveBuyYes + effectivePrices.effectiveBuyNo;
+        const effectiveShortRevenue = effectivePrices.effectiveSellYes + effectivePrices.effectiveSellNo;
+        const longArbProfit = 1 - effectiveLongCost;
+        const shortArbProfit = effectiveShortRevenue - 1;
+        const yesSpread = yesBestAsk - yesBestBid;
+        return {
+            yes: {
+                bid: yesBestBid,
+                ask: yesBestAsk,
+                bidSize: yesBook.bids[0]?.size || 0,
+                askSize: yesBook.asks[0]?.size || 0,
+                bidDepth: yesBidDepth,
+                askDepth: yesAskDepth,
+                spread: yesSpread,
+                tokenId: yesTokenId,
+            },
+            no: {
+                bid: noBestBid,
+                ask: noBestAsk,
+                bidSize: noBook.bids[0]?.size || 0,
+                askSize: noBook.asks[0]?.size || 0,
+                bidDepth: noBidDepth,
+                askDepth: noAskDepth,
+                spread: noBestAsk - noBestBid,
+                tokenId: noTokenId,
+            },
+            summary: {
+                askSum,
+                bidSum,
+                effectivePrices,
+                effectiveLongCost,
+                effectiveShortRevenue,
+                longArbProfit,
+                shortArbProfit,
+                totalBidDepth: yesBidDepth + noBidDepth,
+                totalAskDepth: yesAskDepth + noAskDepth,
+                imbalanceRatio: (yesBidDepth + noBidDepth) / (yesAskDepth + noAskDepth + 0.001),
+                yesSpread,
+            },
+        };
+    }
     mergeMarkets(gamma, clob) {
-        const yesToken = clob.tokens.find((t) => t.outcome === 'Yes');
-        const noToken = clob.tokens.find((t) => t.outcome === 'No');
+        // Build tokens array from CLOB data, falling back to Gamma prices
+        const tokens = clob.tokens.map((t, index) => ({
+            tokenId: t.tokenId,
+            outcome: t.outcome,
+            price: t.price || gamma.outcomePrices[index] || 0.5,
+            winner: t.winner,
+        }));
         return {
             conditionId: clob.conditionId,
             slug: gamma.slug,
             question: clob.question,
             description: clob.description || gamma.description,
-            tokens: {
-                yes: { tokenId: yesToken?.tokenId || '', price: yesToken?.price || gamma.outcomePrices[0] || 0.5 },
-                no: { tokenId: noToken?.tokenId || '', price: noToken?.price || gamma.outcomePrices[1] || 0.5 },
-            },
+            tokens,
             volume: gamma.volume,
             volume24hr: gamma.volume24hr,
             liquidity: gamma.liquidity,
@@ -394,15 +1111,19 @@ export class MarketService {
         };
     }
     fromGammaMarket(gamma) {
+        // Create tokens from Gamma outcomes - use actual outcome names from gamma data
+        // This supports Yes/No, Up/Down, Team1/Team2, Heads/Tails, etc.
+        const outcomes = gamma.outcomes || ['Yes', 'No'];
+        const tokens = [
+            { tokenId: '', outcome: outcomes[0], price: gamma.outcomePrices[0] || 0.5 },
+            { tokenId: '', outcome: outcomes[1], price: gamma.outcomePrices[1] || 0.5 },
+        ];
         return {
             conditionId: gamma.conditionId,
             slug: gamma.slug,
             question: gamma.question,
             description: gamma.description,
-            tokens: {
-                yes: { tokenId: '', price: gamma.outcomePrices[0] || 0.5 },
-                no: { tokenId: '', price: gamma.outcomePrices[1] || 0.5 },
-            },
+            tokens,
             volume: gamma.volume,
             volume24hr: gamma.volume24hr,
             liquidity: gamma.liquidity,
@@ -417,17 +1138,19 @@ export class MarketService {
         };
     }
     fromClobMarket(clob) {
-        const yesToken = clob.tokens.find((t) => t.outcome === 'Yes');
-        const noToken = clob.tokens.find((t) => t.outcome === 'No');
+        // Convert CLOB tokens to UnifiedMarketToken format
+        const tokens = clob.tokens.map(t => ({
+            tokenId: t.tokenId,
+            outcome: t.outcome,
+            price: t.price,
+            winner: t.winner,
+        }));
         return {
             conditionId: clob.conditionId,
             slug: clob.marketSlug,
             question: clob.question,
             description: clob.description,
-            tokens: {
-                yes: { tokenId: yesToken?.tokenId || '', price: yesToken?.price || 0.5 },
-                no: { tokenId: noToken?.tokenId || '', price: noToken?.price || 0.5 },
-            },
+            tokens,
             volume: 0,
             volume24hr: undefined,
             liquidity: 0,
@@ -443,11 +1166,17 @@ export class MarketService {
 // ===== Utility Functions =====
 export function getIntervalMs(interval) {
     const map = {
+        // Second-level intervals (for 15-minute crypto markets)
+        '1s': 1 * 1000,
+        '5s': 5 * 1000,
+        '15s': 15 * 1000,
         '30s': 30 * 1000,
+        // Minute-level intervals
         '1m': 60 * 1000,
         '5m': 5 * 60 * 1000,
         '15m': 15 * 60 * 1000,
         '30m': 30 * 60 * 1000,
+        // Hour-level intervals
         '1h': 60 * 60 * 1000,
         '4h': 4 * 60 * 60 * 1000,
         '12h': 12 * 60 * 60 * 1000,