@catalyst-team/poly-sdk 0.2.0 → 0.3.0

package/dist/services/market-service.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Market Service
+ *
+ * Provides market data and analysis:
+ * - Market info and discovery
+ * - Orderbook data and analysis
+ * - K-Line aggregation from trade data
+ * - Spread analysis
+ * - Arbitrage detection
+ */
+import { DataApiClient } from '../clients/data-api.js';
+import { GammaApiClient, GammaMarket } from '../clients/gamma-api.js';
+import type { UnifiedCache } from '../core/unified-cache.js';
+import { RateLimiter } from '../core/rate-limiter.js';
+import type { UnifiedMarket, ProcessedOrderbook, ArbitrageOpportunity, KLineInterval, KLineCandle, DualKLineData, RealtimeSpreadAnalysis, Side, Orderbook } from '../core/types.js';
+export declare const POLYGON_MAINNET = 137;
+export type { Side, Orderbook } from '../core/types.js';
+export type PriceHistoryIntervalString = '1h' | '6h' | '1d' | '1w' | 'max';
+export interface PriceHistoryParams {
+    tokenId: string;
+    interval?: PriceHistoryIntervalString;
+    startTs?: number;
+    endTs?: number;
+    fidelity?: number;
+}
+export interface PricePoint {
+    timestamp: number;
+    price: number;
+}
+export interface MarketServiceConfig {
+    /** Private key for CLOB client auth (optional, for authenticated endpoints) */
+    privateKey?: string;
+    /** Chain ID (default: Polygon mainnet 137) */
+    chainId?: number;
+}
+/**
+ * CLOB Market type (from CLOB API)
+ *
+ * This represents the raw market data from the CLOB API.
+ * For merged market data with volume/liquidity, use UnifiedMarket from core/types.ts.
+ */
+export interface Market {
+    conditionId: string;
+    questionId?: string;
+    marketSlug: string;
+    question: string;
+    description?: string;
+    tokens: MarketToken[];
+    active: boolean;
+    closed: boolean;
+    acceptingOrders: boolean;
+    endDateIso?: string | null;
+    negRisk?: boolean;
+    minimumOrderSize?: number;
+    minimumTickSize?: number;
+}
+/**
+ * Token in a CLOB market
+ * Same structure as MarketToken in core/types.ts
+ */
+export interface MarketToken {
+    tokenId: string;
+    outcome: string;
+    price: number;
+    winner?: boolean;
+}
+export declare class MarketService {
+    private gammaApi;
+    private dataApi;
+    private rateLimiter;
+    private cache;
+    private config?;
+    private clobClient;
+    private initialized;
+    constructor(gammaApi: GammaApiClient | undefined, dataApi: DataApiClient | undefined, rateLimiter: RateLimiter, cache: UnifiedCache, config?: MarketServiceConfig | undefined);
+    private ensureInitialized;
+    /**
+     * Get market from CLOB by condition ID
+     */
+    getClobMarket(conditionId: string): Promise<Market>;
+    /**
+     * Get multiple markets from CLOB
+     */
+    getClobMarkets(nextCursor?: string): Promise<{
+        markets: Market[];
+        nextCursor: string;
+    }>;
+    /**
+     * Get orderbook for a single token
+     */
+    getTokenOrderbook(tokenId: string): Promise<Orderbook>;
+    /**
+     * Get orderbooks for multiple tokens
+     */
+    getTokenOrderbooks(params: Array<{
+        tokenId: string;
+        side: Side;
+    }>): Promise<Map<string, Orderbook>>;
+    /**
+     * Get processed orderbook with arbitrage analysis for a market
+     */
+    getProcessedOrderbook(conditionId: string): Promise<ProcessedOrderbook>;
+    /**
+     * Get price history for a token
+     */
+    getPricesHistory(params: PriceHistoryParams): Promise<PricePoint[]>;
+    /**
+     * Get midpoint price for a token
+     */
+    getMidpoint(tokenId: string): Promise<number>;
+    /**
+     * Get spread for a token
+     */
+    getSpread(tokenId: string): Promise<number>;
+    /**
+     * Get last trade price for a token
+     */
+    getLastTradePrice(tokenId: string): Promise<number>;
+    /**
+     * Get market by slug or condition ID
+     */
+    getMarket(identifier: string): Promise<UnifiedMarket>;
+    private getMarketBySlug;
+    private getMarketByConditionId;
+    /**
+     * Get K-Line candles for a market (single token)
+     */
+    getKLines(conditionId: string, interval: KLineInterval, options?: {
+        limit?: number;
+        tokenId?: string;
+        outcomeIndex?: number;
+    }): Promise<KLineCandle[]>;
+    /**
+     * Get dual K-Lines (YES + NO tokens)
+     */
+    getDualKLines(conditionId: string, interval: KLineInterval, options?: {
+        limit?: number;
+    }): Promise<DualKLineData>;
+    /**
+     * Aggregate trades into K-Line candles
+     */
+    private aggregateToKLines;
+    /**
+     * Analyze historical spread from trade close prices (for backtesting)
+     *
+     * This uses trade close prices, not orderbook bid/ask.
+     * Useful for:
+     * - Historical analysis / backtesting
+     * - Understanding past price movements
+     * - Identifying patterns when orderbook data unavailable
+     */
+    private analyzeHistoricalSpread;
+    /**
+     * Calculate real-time spread from orderbook (for live trading)
+     *
+     * This uses orderbook bid/ask prices for accurate arbitrage detection.
+     * Useful for:
+     * - Real-time arbitrage execution
+     * - Live trading decisions
+     * - Accurate profit calculations
+     */
+    private calculateRealtimeSpread;
+    /**
+     * Get real-time spread analysis only (without K-lines)
+     * Use this for quick arbitrage checks
+     */
+    getRealtimeSpread(conditionId: string): Promise<RealtimeSpreadAnalysis>;
+    /**
+     * Get processed orderbook with analytics (alias for getProcessedOrderbook)
+     */
+    getOrderbook(conditionId: string): Promise<ProcessedOrderbook>;
+    /**
+     * Detect arbitrage opportunity
+     *
+     * 使用有效价格（考虑镜像订单）计算套利机会
+     * 详细原理见: docs/01-polymarket-orderbook-arbitrage.md
+     */
+    detectArbitrage(conditionId: string, threshold?: number): Promise<ArbitrageOpportunity | null>;
+    /**
+     * Get trending markets
+     */
+    getTrendingMarkets(limit?: number): Promise<GammaMarket[]>;
+    /**
+     * Search markets
+     */
+    searchMarkets(params: {
+        active?: boolean;
+        closed?: boolean;
+        limit?: number;
+        offset?: number;
+        order?: string;
+    }): Promise<GammaMarket[]>;
+    /**
+     * Detect market signals (volume surge, depth imbalance, whale trades)
+     */
+    detectMarketSignals(conditionId: string): Promise<Array<{
+        type: 'volume_surge' | 'depth_imbalance' | 'whale_trade' | 'momentum';
+        severity: 'low' | 'medium' | 'high';
+        details: Record<string, unknown>;
+    }>>;
+    private normalizeClobMarket;
+    private processOrderbooks;
+    private mergeMarkets;
+    private fromGammaMarket;
+    private fromClobMarket;
+}
+export declare function getIntervalMs(interval: KLineInterval): number;
+//# sourceMappingURL=market-service.d.ts.map

package/dist/services/market-service.d.ts.map

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