@catalyst-team/poly-sdk 0.3.0 → 0.4.3

package/dist/src/services/binance-service.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Binance Service
+ *
+ * Provides BTC/ETH/SOL K-line data from Binance public API.
+ * Used for:
+ * - Token vs underlying price correlation analysis
+ * - Price prediction for UP/DOWN markets
+ * - Backtesting strategies
+ *
+ * API Reference: https://binance-docs.github.io/apidocs/spot/en/#kline-candlestick-data
+ */
+import { RateLimiter } from '../core/rate-limiter.js';
+import type { UnifiedCache } from '../core/unified-cache.js';
+/**
+ * Binance K-Line (OHLCV) data
+ */
+export interface BinanceKLine {
+    /** Open time (Unix ms) */
+    timestamp: number;
+    /** Open price */
+    open: number;
+    /** High price */
+    high: number;
+    /** Low price */
+    low: number;
+    /** Close price */
+    close: number;
+    /** Base asset volume */
+    volume: number;
+    /** Close time (Unix ms) */
+    closeTime: number;
+    /** Quote asset volume */
+    quoteVolume: number;
+    /** Number of trades */
+    trades: number;
+}
+/**
+ * Supported Binance trading pairs
+ */
+export type BinanceSymbol = 'BTCUSDT' | 'ETHUSDT' | 'SOLUSDT';
+/**
+ * Supported K-line intervals
+ */
+export type BinanceInterval = '1m' | '5m' | '15m' | '30m' | '1h' | '4h' | '1d';
+/**
+ * Options for getKLines
+ */
+export interface BinanceKLineOptions {
+    /** Start time (Unix ms) */
+    startTime?: number;
+    /** End time (Unix ms) */
+    endTime?: number;
+    /** Number of candles (default 500, max 1000) */
+    limit?: number;
+}
+export declare class BinanceService {
+    private rateLimiter;
+    private cache;
+    constructor(rateLimiter: RateLimiter, cache: UnifiedCache);
+    /**
+     * Get K-lines (candlestick data) for a symbol
+     *
+     * @param symbol - Trading pair (BTCUSDT, ETHUSDT, SOLUSDT)
+     * @param interval - K-line interval
+     * @param options - Optional parameters
+     * @returns Array of K-line candles
+     *
+     * @example
+     * ```typescript
+     * const klines = await binanceService.getKLines('BTCUSDT', '1h', { limit: 100 });
+     * console.log(`Latest close: ${klines[klines.length - 1].close}`);
+     * ```
+     */
+    getKLines(symbol: BinanceSymbol, interval: BinanceInterval, options?: BinanceKLineOptions): Promise<BinanceKLine[]>;
+    /**
+     * Get current price for a symbol
+     *
+     * @param symbol - Trading pair (BTCUSDT, ETHUSDT, SOLUSDT)
+     * @returns Current price
+     *
+     * @example
+     * ```typescript
+     * const price = await binanceService.getPrice('BTCUSDT');
+     * console.log(`BTC price: $${price}`);
+     * ```
+     */
+    getPrice(symbol: BinanceSymbol): Promise<number>;
+    /**
+     * Get price at a specific timestamp (nearest candle close)
+     *
+     * Uses the 1-minute candle that contains the timestamp and returns
+     * the close price of that candle.
+     *
+     * @param symbol - Trading pair (BTCUSDT, ETHUSDT, SOLUSDT)
+     * @param timestamp - Unix timestamp in milliseconds
+     * @returns Price at the given timestamp
+     *
+     * @example
+     * ```typescript
+     * // Get BTC price 1 hour ago
+     * const oneHourAgo = Date.now() - 60 * 60 * 1000;
+     * const price = await binanceService.getPriceAt('BTCUSDT', oneHourAgo);
+     * ```
+     */
+    getPriceAt(symbol: BinanceSymbol, timestamp: number): Promise<number>;
+    /**
+     * Get multiple prices at once
+     *
+     * @param symbols - Array of trading pairs
+     * @returns Map of symbol to price
+     */
+    getPrices(symbols: BinanceSymbol[]): Promise<Map<BinanceSymbol, number>>;
+    /**
+     * Get price change over a time period
+     *
+     * @param symbol - Trading pair
+     * @param startTime - Start time (Unix ms)
+     * @param endTime - End time (Unix ms, defaults to now)
+     * @returns Price change percentage
+     */
+    getPriceChange(symbol: BinanceSymbol, startTime: number, endTime?: number): Promise<{
+        startPrice: number;
+        endPrice: number;
+        changePercent: number;
+    }>;
+    private validateSymbol;
+    private validateInterval;
+    private buildKLineCacheKey;
+    private buildKLinesUrl;
+    /**
+     * Parse Binance K-line array response
+     *
+     * Binance returns K-lines as arrays:
+     * [
+     *   [
+     *     1499040000000,      // Open time
+     *     "0.01634000",       // Open
+     *     "0.80000000",       // High
+     *     "0.01575800",       // Low
+     *     "0.01577100",       // Close
+     *     "148976.11427815",  // Volume
+     *     1499644799999,      // Close time
+     *     "2434.19055334",    // Quote asset volume
+     *     308,                // Number of trades
+     *     "1756.87402397",    // Taker buy base asset volume
+     *     "28.46694368",      // Taker buy quote asset volume
+     *     "17928899.62484339" // Ignore
+     *   ]
+     * ]
+     */
+    private parseKLines;
+    private handleApiError;
+}
+//# sourceMappingURL=binance-service.d.ts.map

package/dist/src/services/binance-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binance-service.d.ts","sourceRoot":"","sources":["../../../src/services/binance-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,WAAW,EAAW,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAQ7D;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9D;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG,KAAK,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,2BAA2B;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAiCD,qBAAa,cAAc;IAEvB,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,KAAK;gBADL,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,YAAY;IAG7B;;;;;;;;;;;;;OAaG;IACG,SAAS,CACb,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,eAAe,EACzB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,YAAY,EAAE,CAAC;IA6B1B;;;;;;;;;;;OAWG;IACG,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAqBtD;;;;;;;;;;;;;;;;OAgBG;IACG,UAAU,CAAC,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAmB3E;;;;;OAKG;IACG,SAAS,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;IAW9E;;;;;;;OAOG;IACG,cAAc,CAClB,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IA0B3E,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,kBAAkB;IAoB1B,OAAO,CAAC,cAAc;IAuBtB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,WAAW;YAcL,cAAc;CAoC7B"}

package/dist/src/services/binance-service.js

@@ -0,0 +1,266 @@
+/**
+ * Binance Service
+ *
+ * Provides BTC/ETH/SOL K-line data from Binance public API.
+ * Used for:
+ * - Token vs underlying price correlation analysis
+ * - Price prediction for UP/DOWN markets
+ * - Backtesting strategies
+ *
+ * API Reference: https://binance-docs.github.io/apidocs/spot/en/#kline-candlestick-data
+ */
+import { ApiType } from '../core/rate-limiter.js';
+import { CACHE_TTL } from '../core/cache.js';
+import { PolymarketError, ErrorCode } from '../core/errors.js';
+// ============================================================================
+// Constants
+// ============================================================================
+const BINANCE_BASE_URL = 'https://api.binance.com';
+const BINANCE_KLINES_ENDPOINT = '/api/v3/klines';
+const BINANCE_PRICE_ENDPOINT = '/api/v3/ticker/price';
+const DEFAULT_LIMIT = 500;
+const MAX_LIMIT = 1000;
+// Valid symbols
+const VALID_SYMBOLS = new Set(['BTCUSDT', 'ETHUSDT', 'SOLUSDT']);
+// Valid intervals
+const VALID_INTERVALS = new Set([
+    '1m', '5m', '15m', '30m', '1h', '4h', '1d',
+]);
+// ============================================================================
+// BinanceService Implementation
+// ============================================================================
+export class BinanceService {
+    rateLimiter;
+    cache;
+    constructor(rateLimiter, cache) {
+        this.rateLimiter = rateLimiter;
+        this.cache = cache;
+    }
+    /**
+     * Get K-lines (candlestick data) for a symbol
+     *
+     * @param symbol - Trading pair (BTCUSDT, ETHUSDT, SOLUSDT)
+     * @param interval - K-line interval
+     * @param options - Optional parameters
+     * @returns Array of K-line candles
+     *
+     * @example
+     * ```typescript
+     * const klines = await binanceService.getKLines('BTCUSDT', '1h', { limit: 100 });
+     * console.log(`Latest close: ${klines[klines.length - 1].close}`);
+     * ```
+     */
+    async getKLines(symbol, interval, options) {
+        // Validate inputs
+        this.validateSymbol(symbol);
+        this.validateInterval(interval);
+        const limit = Math.min(options?.limit ?? DEFAULT_LIMIT, MAX_LIMIT);
+        // Build cache key
+        const cacheKey = this.buildKLineCacheKey(symbol, interval, options);
+        return this.cache.getOrSet(cacheKey, CACHE_TTL.BINANCE_KLINE, async () => {
+            return this.rateLimiter.execute(ApiType.BINANCE, async () => {
+                const url = this.buildKLinesUrl(symbol, interval, {
+                    ...options,
+                    limit,
+                });
+                const response = await fetch(url);
+                if (!response.ok) {
+                    await this.handleApiError(response);
+                }
+                const data = await response.json();
+                return this.parseKLines(data);
+            });
+        });
+    }
+    /**
+     * Get current price for a symbol
+     *
+     * @param symbol - Trading pair (BTCUSDT, ETHUSDT, SOLUSDT)
+     * @returns Current price
+     *
+     * @example
+     * ```typescript
+     * const price = await binanceService.getPrice('BTCUSDT');
+     * console.log(`BTC price: $${price}`);
+     * ```
+     */
+    async getPrice(symbol) {
+        this.validateSymbol(symbol);
+        const cacheKey = `binance:price:${symbol}`;
+        return this.cache.getOrSet(cacheKey, CACHE_TTL.BINANCE_PRICE, async () => {
+            return this.rateLimiter.execute(ApiType.BINANCE, async () => {
+                const url = `${BINANCE_BASE_URL}${BINANCE_PRICE_ENDPOINT}?symbol=${symbol}`;
+                const response = await fetch(url);
+                if (!response.ok) {
+                    await this.handleApiError(response);
+                }
+                const data = await response.json();
+                return parseFloat(data.price);
+            });
+        });
+    }
+    /**
+     * Get price at a specific timestamp (nearest candle close)
+     *
+     * Uses the 1-minute candle that contains the timestamp and returns
+     * the close price of that candle.
+     *
+     * @param symbol - Trading pair (BTCUSDT, ETHUSDT, SOLUSDT)
+     * @param timestamp - Unix timestamp in milliseconds
+     * @returns Price at the given timestamp
+     *
+     * @example
+     * ```typescript
+     * // Get BTC price 1 hour ago
+     * const oneHourAgo = Date.now() - 60 * 60 * 1000;
+     * const price = await binanceService.getPriceAt('BTCUSDT', oneHourAgo);
+     * ```
+     */
+    async getPriceAt(symbol, timestamp) {
+        this.validateSymbol(symbol);
+        // Fetch a single 1-minute candle at the specified time
+        const klines = await this.getKLines(symbol, '1m', {
+            startTime: timestamp,
+            limit: 1,
+        });
+        if (klines.length === 0) {
+            throw new PolymarketError(ErrorCode.INVALID_RESPONSE, `No price data available for ${symbol} at timestamp ${timestamp}`);
+        }
+        return klines[0].close;
+    }
+    /**
+     * Get multiple prices at once
+     *
+     * @param symbols - Array of trading pairs
+     * @returns Map of symbol to price
+     */
+    async getPrices(symbols) {
+        const prices = await Promise.all(symbols.map(async (symbol) => {
+            const price = await this.getPrice(symbol);
+            return [symbol, price];
+        }));
+        return new Map(prices);
+    }
+    /**
+     * Get price change over a time period
+     *
+     * @param symbol - Trading pair
+     * @param startTime - Start time (Unix ms)
+     * @param endTime - End time (Unix ms, defaults to now)
+     * @returns Price change percentage
+     */
+    async getPriceChange(symbol, startTime, endTime) {
+        const [startKlines, endKlines] = await Promise.all([
+            this.getKLines(symbol, '1m', { startTime, limit: 1 }),
+            endTime
+                ? this.getKLines(symbol, '1m', { startTime: endTime, limit: 1 })
+                : Promise.resolve([]),
+        ]);
+        const startPrice = startKlines[0]?.close;
+        if (!startPrice) {
+            throw new PolymarketError(ErrorCode.INVALID_RESPONSE, `No price data for ${symbol} at ${startTime}`);
+        }
+        const endPrice = endKlines[0]?.close ?? (await this.getPrice(symbol));
+        const changePercent = ((endPrice - startPrice) / startPrice) * 100;
+        return { startPrice, endPrice, changePercent };
+    }
+    // ============================================================================
+    // Private Methods
+    // ============================================================================
+    validateSymbol(symbol) {
+        if (!VALID_SYMBOLS.has(symbol)) {
+            throw new PolymarketError(ErrorCode.INVALID_CONFIG, `Invalid symbol: ${symbol}. Supported: ${[...VALID_SYMBOLS].join(', ')}`);
+        }
+    }
+    validateInterval(interval) {
+        if (!VALID_INTERVALS.has(interval)) {
+            throw new PolymarketError(ErrorCode.INVALID_CONFIG, `Invalid interval: ${interval}. Supported: ${[...VALID_INTERVALS].join(', ')}`);
+        }
+    }
+    buildKLineCacheKey(symbol, interval, options) {
+        const parts = ['binance', 'klines', symbol, interval];
+        if (options?.startTime) {
+            parts.push(`start:${options.startTime}`);
+        }
+        if (options?.endTime) {
+            parts.push(`end:${options.endTime}`);
+        }
+        if (options?.limit) {
+            parts.push(`limit:${options.limit}`);
+        }
+        return parts.join(':');
+    }
+    buildKLinesUrl(symbol, interval, options) {
+        const params = new URLSearchParams({
+            symbol,
+            interval,
+        });
+        if (options?.startTime) {
+            params.set('startTime', options.startTime.toString());
+        }
+        if (options?.endTime) {
+            params.set('endTime', options.endTime.toString());
+        }
+        if (options?.limit) {
+            params.set('limit', options.limit.toString());
+        }
+        return `${BINANCE_BASE_URL}${BINANCE_KLINES_ENDPOINT}?${params.toString()}`;
+    }
+    /**
+     * Parse Binance K-line array response
+     *
+     * Binance returns K-lines as arrays:
+     * [
+     *   [
+     *     1499040000000,      // Open time
+     *     "0.01634000",       // Open
+     *     "0.80000000",       // High
+     *     "0.01575800",       // Low
+     *     "0.01577100",       // Close
+     *     "148976.11427815",  // Volume
+     *     1499644799999,      // Close time
+     *     "2434.19055334",    // Quote asset volume
+     *     308,                // Number of trades
+     *     "1756.87402397",    // Taker buy base asset volume
+     *     "28.46694368",      // Taker buy quote asset volume
+     *     "17928899.62484339" // Ignore
+     *   ]
+     * ]
+     */
+    parseKLines(data) {
+        return data.map((kline) => ({
+            timestamp: kline[0],
+            open: parseFloat(kline[1]),
+            high: parseFloat(kline[2]),
+            low: parseFloat(kline[3]),
+            close: parseFloat(kline[4]),
+            volume: parseFloat(kline[5]),
+            closeTime: kline[6],
+            quoteVolume: parseFloat(kline[7]),
+            trades: kline[8],
+        }));
+    }
+    async handleApiError(response) {
+        let errorBody = null;
+        try {
+            errorBody = await response.json();
+        }
+        catch {
+            // Failed to parse error body
+        }
+        const message = errorBody?.msg || `Binance API error: HTTP ${response.status}`;
+        // Handle rate limiting
+        if (response.status === 429 || errorBody?.code === -1015) {
+            throw new PolymarketError(ErrorCode.RATE_LIMITED, message, true // retryable
+            );
+        }
+        // Handle invalid symbol/parameters
+        if (errorBody?.code === -1121 || errorBody?.code === -1100) {
+            throw new PolymarketError(ErrorCode.INVALID_CONFIG, message, false);
+        }
+        // Generic API error
+        throw new PolymarketError(ErrorCode.API_ERROR, message, response.status >= 500 // retryable for server errors
+        );
+    }
+}
+//# sourceMappingURL=binance-service.js.map

package/dist/src/services/binance-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binance-service.js","sourceRoot":"","sources":["../../../src/services/binance-service.ts"],"names":[],"mappings":"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"}

package/dist/src/services/dip-arb-service.d.ts

@@ -0,0 +1,245 @@
+/**
+ * DipArbService - Dip Arbitrage Service
+ *
+ * 暴跌套利服务 - 针对 Polymarket 15分钟/5分钟 UP/DOWN 市场
+ *
+ * 策略原理：
+ * 1. 每个市场有一个 "price to beat"（开盘时的 Chainlink 价格）
+ * 2. 结算规则：
+ *    - UP 赢：结束时价格 >= price to beat
+ *    - DOWN 赢：结束时价格 < price to beat
+ *
+ * 3. 套利流程：
+ *    - Leg1：检测暴跌 → 买入暴跌侧
+ *    - Leg2：等待对冲条件 → 买入另一侧
+ *    - 利润：总成本 < $1 时获得无风险利润
+ *
+ * 使用示例：
+ * ```typescript
+ * const sdk = await PolymarketSDK.create({ privateKey: '...' });
+ *
+ * // 自动找到并启动
+ * await sdk.dipArb.findAndStart({ coin: 'BTC' });
+ *
+ * // 监听信号
+ * sdk.dipArb.on('signal', (signal) => {
+ *   console.log(`Signal: ${signal.type} ${signal.side}`);
+ * });
+ * ```
+ */
+import { EventEmitter } from 'events';
+import { RealtimeServiceV2 } from './realtime-service-v2.js';
+import { TradingService } from './trading-service.js';
+import { MarketService } from './market-service.js';
+import { type DipArbServiceConfig, type DipArbConfigInternal, type DipArbMarketConfig, type DipArbRoundState, type DipArbStats, type DipArbLeg1Signal, type DipArbLeg2Signal, type DipArbExecutionResult, type DipArbScanOptions, type DipArbFindAndStartOptions, type DipArbAutoRotateConfig, type DipArbSettleResult, type DipArbPendingRedemption } from './dip-arb-types.js';
+export declare class DipArbService extends EventEmitter {
+    private realtimeService;
+    private tradingService;
+    private marketService;
+    private ctf;
+    private config;
+    private autoRotateConfig;
+    private market;
+    private currentRound;
+    private isRunning;
+    private isExecuting;
+    private lastExecutionTime;
+    private stats;
+    private marketSubscription;
+    private chainlinkSubscription;
+    private rotateCheckInterval;
+    private nextMarket;
+    private pendingRedemptions;
+    private redeemCheckInterval;
+    private upAsks;
+    private downAsks;
+    private priceHistory;
+    private readonly MAX_HISTORY_LENGTH;
+    private currentUnderlyingPrice;
+    private leg1SignalEmitted;
+    private lastOrderbookLogTime;
+    private readonly ORDERBOOK_LOG_INTERVAL_MS;
+    private orderbookBuffer;
+    private readonly ORDERBOOK_BUFFER_SIZE;
+    constructor(realtimeService: RealtimeServiceV2, tradingService: TradingService | null, marketService: MarketService, privateKey?: string, chainId?: number);
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<DipArbServiceConfig>): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): DipArbConfigInternal;
+    /**
+     * Scan for upcoming UP/DOWN markets
+     *
+     * Uses MarketService.scanCryptoShortTermMarkets()
+     */
+    scanUpcomingMarkets(options?: DipArbScanOptions): Promise<DipArbMarketConfig[]>;
+    /**
+     * Find the best market and start monitoring
+     */
+    findAndStart(options?: DipArbFindAndStartOptions): Promise<DipArbMarketConfig | null>;
+    /**
+     * Start monitoring a market
+     */
+    start(market: DipArbMarketConfig): Promise<void>;
+    /**
+     * ✅ FIX: Scan and merge existing UP/DOWN pairs at startup
+     *
+     * When the service starts or rotates to a new market, check if there are
+     * existing UP + DOWN token pairs from previous sessions and merge them.
+     */
+    private scanAndMergeExistingPairs;
+    /**
+     * Stop monitoring
+     */
+    stop(): Promise<void>;
+    /**
+     * Check if service is running
+     */
+    isActive(): boolean;
+    /**
+     * Get current market
+     */
+    getMarket(): DipArbMarketConfig | null;
+    /**
+     * Get statistics
+     */
+    getStats(): DipArbStats;
+    /**
+     * Get current round state
+     */
+    getCurrentRound(): DipArbRoundState | null;
+    /**
+     * Get current price to beat
+     */
+    getPriceToBeat(): number | null;
+    /**
+     * Execute Leg1 trade
+     */
+    executeLeg1(signal: DipArbLeg1Signal): Promise<DipArbExecutionResult>;
+    /**
+     * Execute Leg2 trade
+     */
+    executeLeg2(signal: DipArbLeg2Signal): Promise<DipArbExecutionResult>;
+    /**
+     * Merge UP + DOWN tokens to USDC.e
+     *
+     * Uses mergeByTokenIds with Polymarket token IDs for correct CLOB market handling.
+     * This locks in profit immediately after Leg2 completes.
+     */
+    merge(): Promise<DipArbExecutionResult>;
+    private handleOrderbookUpdate;
+    /**
+     * Record current prices to history buffer for sliding window detection
+     */
+    private recordPriceHistory;
+    /**
+     * Get price from N milliseconds ago for sliding window detection
+     *
+     * @param side - 'UP' or 'DOWN'
+     * @param msAgo - Milliseconds ago (e.g., 3000 for 3 seconds)
+     * @returns Price from that time, or null if not available
+     */
+    private getPriceFromHistory;
+    private handleChainlinkPriceUpdate;
+    private checkAndStartNewRound;
+    /**
+     * Emergency exit Leg1 position when Leg2 times out
+     * Sells the Leg1 tokens at market price to avoid unhedged exposure
+     */
+    private emergencyExitLeg1;
+    private detectSignal;
+    private detectLeg1Signal;
+    private createLeg1Signal;
+    private detectLeg2Signal;
+    private validateSignalProfitability;
+    private handleSignal;
+    /**
+     * Configure and enable auto-rotate
+     *
+     * Auto-rotate 会自动：
+     * 1. 监控当前市场到期时间
+     * 2. 在市场结束前预加载下一个市场
+     * 3. 市场结束时自动结算（redeem 或 sell）
+     * 4. 无缝切换到下一个 15m 市场
+     *
+     * @example
+     * ```typescript
+     * sdk.dipArb.enableAutoRotate({
+     *   underlyings: ['BTC', 'ETH'],
+     *   duration: '15m',
+     *   autoSettle: true,
+     *   settleStrategy: 'redeem',
+     * });
+     * ```
+     */
+    enableAutoRotate(config?: Partial<DipArbAutoRotateConfig>): void;
+    /**
+     * ✅ FIX: Scan for existing redeemable positions and add them to the queue
+     *
+     * This is called when auto-rotate is enabled to recover any positions
+     * from previous sessions that can be redeemed.
+     */
+    private scanAndQueueRedeemablePositions;
+    /**
+     * Disable auto-rotate
+     */
+    disableAutoRotate(): void;
+    /**
+     * Get auto-rotate configuration
+     */
+    getAutoRotateConfig(): Required<DipArbAutoRotateConfig>;
+    /**
+     * Manually settle current position
+     *
+     * 结算策略：
+     * - 'redeem': 等待市场结算后 redeem（需要等待结算完成）
+     * - 'sell': 直接卖出 token（更快但可能有滑点）
+     */
+    settle(strategy?: 'redeem' | 'sell'): Promise<DipArbSettleResult>;
+    /**
+     * Manually rotate to next market
+     */
+    rotateToNextMarket(): Promise<DipArbMarketConfig | null>;
+    private startRotateCheck;
+    private stopRotateCheck;
+    private startRedeemCheck;
+    private stopRedeemCheck;
+    /**
+     * Add a position to pending redemption queue
+     */
+    private addPendingRedemption;
+    /**
+     * Process all pending redemptions
+     * Called periodically by redeemCheckInterval
+     */
+    private processPendingRedemptions;
+    /**
+     * Get pending redemptions (for debugging/monitoring)
+     */
+    getPendingRedemptions(): DipArbPendingRedemption[];
+    private checkRotation;
+    private findNextMarket;
+    private settleByRedeem;
+    private settleBySell;
+    /**
+     * Update orderbook buffer for smart logging
+     * Keeps last 5 seconds of orderbook data
+     */
+    private updateOrderbookBuffer;
+    /**
+     * Log orderbook summary at intervals (every 10 seconds)
+     * Reduces log noise from ~10 logs/sec to 1 log/10sec
+     */
+    private maybeLogOrderbookSummary;
+    /**
+     * Log orderbook buffer around a signal/trade
+     * Called when signal is detected to capture market context
+     */
+    private logOrderbookContext;
+    private log;
+}
+export * from './dip-arb-types.js';
+//# sourceMappingURL=dip-arb-service.d.ts.map