@catalyst-team/poly-sdk 0.3.0 → 0.4.3

package/dist/src/services/smart-money-service.d.ts

@@ -0,0 +1,769 @@
+/**
+ * SmartMoneyService
+ *
+ * 聪明钱监控和自动跟单服务
+ *
+ * 核心功能：
+ * 1. 监听指定地址的交易 - subscribeSmartMoneyTrades()
+ * 2. 自动跟单 - startAutoCopyTrading()
+ * 3. 聪明钱信息获取 - getSmartMoneyList(), getSmartMoneyInfo()
+ *
+ * ============================================================================
+ * 设计决策
+ * ============================================================================
+ *
+ * ## 监控方式
+ * 使用 Activity WebSocket，延迟 < 100ms，实测验证有效。
+ *
+ * ## 下单方式
+ * | 方式 | 使用场景 | 特点 |
+ * |------|---------|------|
+ * | FOK | 小额跟单 | 全部成交或取消 |
+ * | FAK | 大额跟单 | 部分成交也接受 |
+ *
+ * ## 重要限制
+ * ⚠️ Activity WebSocket 不会广播用户自己的交易！
+ * 验证跟单结果请使用 TradingService.getTrades()
+ */
+import type { WalletService, TimePeriod } from './wallet-service.js';
+import type { RealtimeServiceV2 } from './realtime-service-v2.js';
+import type { TradingService, OrderResult } from './trading-service.js';
+import type { DataApiClient } from '../clients/data-api.js';
+/**
+ * Market category for classification
+ */
+export type MarketCategory = 'crypto' | 'politics' | 'sports' | 'entertainment' | 'economics' | 'science' | 'other';
+/**
+ * Keywords for market categorization by category
+ */
+export declare const CATEGORY_KEYWORDS: Record<MarketCategory, RegExp>;
+/**
+ * Categorize a market based on its title
+ *
+ * @param title - Market title to categorize
+ * @returns The market category
+ *
+ * @example
+ * ```typescript
+ * import { categorizeMarket } from '@catalyst-team/poly-sdk';
+ *
+ * categorizeMarket('Will BTC hit $100k?'); // 'crypto'
+ * categorizeMarket('Trump wins 2024?');    // 'politics'
+ * categorizeMarket('Lakers win NBA?');     // 'sports'
+ * categorizeMarket('Random event?');       // 'other'
+ * ```
+ */
+export declare function categorizeMarket(title: string): MarketCategory;
+/**
+ * Smart Money wallet information
+ */
+export interface SmartMoneyWallet {
+    address: string;
+    name?: string;
+    pnl: number;
+    volume: number;
+    score: number;
+    rank?: number;
+}
+/**
+ * Smart Money trade from Activity WebSocket
+ */
+export interface SmartMoneyTrade {
+    traderAddress: string;
+    traderName?: string;
+    conditionId?: string;
+    marketSlug?: string;
+    side: 'BUY' | 'SELL';
+    size: number;
+    price: number;
+    tokenId?: string;
+    outcome?: string;
+    txHash?: string;
+    timestamp: number;
+    isSmartMoney: boolean;
+    smartMoneyInfo?: SmartMoneyWallet;
+}
+/**
+ * Auto copy trading options
+ */
+export interface AutoCopyTradingOptions {
+    /** Specific wallet addresses to follow */
+    targetAddresses?: string[];
+    /** Follow top N from leaderboard */
+    topN?: number;
+    /** Scale factor for size (0.1 = 10%) */
+    sizeScale?: number;
+    /** Maximum USDC per trade */
+    maxSizePerTrade?: number;
+    /** Maximum slippage (e.g., 0.03 = 3%) */
+    maxSlippage?: number;
+    /** Order type: FOK or FAK */
+    orderType?: 'FOK' | 'FAK';
+    /** Delay before executing (ms) */
+    delay?: number;
+    /** Minimum trade value to copy (USDC) */
+    minTradeSize?: number;
+    /** Only copy BUY or SELL trades */
+    sideFilter?: 'BUY' | 'SELL';
+    /** Dry run mode */
+    dryRun?: boolean;
+    /** Callbacks */
+    onTrade?: (trade: SmartMoneyTrade, result: OrderResult) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Auto copy trading statistics
+ */
+export interface AutoCopyTradingStats {
+    startTime: number;
+    tradesDetected: number;
+    tradesExecuted: number;
+    tradesSkipped: number;
+    tradesFailed: number;
+    totalUsdcSpent: number;
+}
+/**
+ * Auto copy trading subscription
+ */
+export interface AutoCopyTradingSubscription {
+    id: string;
+    targetAddresses: string[];
+    startTime: number;
+    isActive: boolean;
+    stats: AutoCopyTradingStats;
+    stop: () => void;
+    getStats: () => AutoCopyTradingStats;
+}
+/**
+ * Service configuration
+ */
+export interface SmartMoneyServiceConfig {
+    /** Minimum PnL to be considered Smart Money (default: $1000) */
+    minPnl?: number;
+    /** Cache TTL (default: 300000 = 5 min) */
+    cacheTtl?: number;
+}
+/**
+ * Leaderboard query options
+ */
+export interface LeaderboardOptions {
+    /** Time period: 'day' | 'week' | 'month' | 'all' */
+    period?: TimePeriod;
+    /** Maximum entries (default: 50, max: 500) */
+    limit?: number;
+    /** Sort by: 'pnl' | 'volume' */
+    sortBy?: 'pnl' | 'volume';
+    /** Pagination offset (default: 0, max: 10000) */
+    offset?: number;
+}
+/**
+ * Smart Money Leaderboard entry (extended from PeriodLeaderboardEntry)
+ */
+export interface SmartMoneyLeaderboardEntry {
+    address: string;
+    rank: number;
+    pnl: number;
+    volume: number;
+    tradeCount: number;
+    userName?: string;
+    profileImage?: string;
+    xUsername?: string;
+    verifiedBadge?: boolean;
+    totalPnl: number;
+    realizedPnl: number;
+    unrealizedPnl: number;
+    buyCount: number;
+    sellCount: number;
+    buyVolume: number;
+    sellVolume: number;
+    makerVolume: number;
+    takerVolume: number;
+}
+/**
+ * Leaderboard result with proper semantics
+ *
+ * Note: Polymarket API doesn't return total count.
+ */
+export interface SmartMoneyLeaderboardResult {
+    /** Leaderboard entries returned by the API */
+    entries: SmartMoneyLeaderboardEntry[];
+    /** Whether there may be more entries (entries.length === request.limit) */
+    hasMore: boolean;
+    /** Echo of request parameters for pagination convenience */
+    request: {
+        offset: number;
+        limit: number;
+    };
+}
+/**
+ * Period ranking info
+ */
+export interface PeriodRanking {
+    rank: number;
+    pnl: number;
+    volume: number;
+}
+/**
+ * Wallet report - comprehensive wallet analysis
+ */
+export interface WalletReport {
+    address: string;
+    generatedAt: Date;
+    overview: {
+        totalPnL: number;
+        realizedPnL: number;
+        unrealizedPnL: number;
+        positionCount: number;
+        tradeCount: number;
+        smartScore: number;
+        lastActiveAt: Date;
+    };
+    rankings: {
+        daily: PeriodRanking | null;
+        weekly: PeriodRanking | null;
+        monthly: PeriodRanking | null;
+        allTime: PeriodRanking | null;
+    };
+    performance: {
+        winRate: number;
+        winCount: number;
+        lossCount: number;
+        avgPositionSize: number;
+        avgWinAmount: number;
+        avgLossAmount: number;
+        uniqueMarkets: number;
+    };
+    categoryBreakdown: Array<{
+        category: string;
+        positionCount: number;
+        totalPnl: number;
+    }>;
+    topPositions: Array<{
+        market: string;
+        slug?: string;
+        outcome: string;
+        size: number;
+        avgPrice: number;
+        currentPrice?: number;
+        pnl: number;
+        percentPnl?: number;
+    }>;
+    recentTrades: Array<{
+        timestamp: number;
+        side: 'BUY' | 'SELL';
+        size: number;
+        price: number;
+        usdcSize?: number;
+        title?: string;
+        slug?: string;
+        outcome?: string;
+        conditionId?: string;
+    }>;
+    activitySummary: {
+        totalBuys: number;
+        totalSells: number;
+        buyVolume: number;
+        sellVolume: number;
+        activeMarketsCount: number;
+    };
+}
+/**
+ * Wallet comparison result
+ */
+export interface WalletComparison {
+    period: TimePeriod;
+    generatedAt: Date;
+    wallets: Array<{
+        address: string;
+        userName?: string;
+        rank: number | null;
+        pnl: number;
+        volume: number;
+        positionCount: number;
+        winRate: number;
+    }>;
+}
+/**
+ * Category color scheme for charts
+ */
+export declare const CATEGORY_COLORS: Record<MarketCategory, string>;
+/**
+ * Category labels for display
+ */
+export declare const CATEGORY_LABELS: Record<MarketCategory, string>;
+/**
+ * Daily summary statistics
+ */
+export interface DailySummary {
+    totalTrades: number;
+    buyCount: number;
+    sellCount: number;
+    buyVolume: number;
+    sellVolume: number;
+    realizedPnL: number;
+    positionsClosed: number;
+    positionsOpened: number;
+}
+/**
+ * Category statistics for breakdown
+ */
+export interface CategoryStats {
+    category: MarketCategory;
+    tradeCount: number;
+    volume: number;
+    pnl: number;
+    percentage: number;
+}
+/**
+ * Trade record for significant trades
+ */
+export interface TradeRecord {
+    market: string;
+    conditionId?: string;
+    outcome: string;
+    side: 'BUY' | 'SELL';
+    price: number;
+    size: number;
+    usdcValue: number;
+    timestamp: Date;
+}
+/**
+ * Position summary
+ */
+export interface PositionSummary {
+    market: string;
+    conditionId?: string;
+    outcome: string;
+    size: number;
+    avgPrice: number;
+}
+/**
+ * Closed market summary
+ */
+export interface ClosedMarketSummary {
+    market: string;
+    conditionId: string;
+    outcome: string;
+    realizedPnL: number;
+    closePrice: number;
+}
+/**
+ * Daily wallet report
+ */
+export interface DailyWalletReport {
+    address: string;
+    reportDate: string;
+    generatedAt: Date;
+    summary: DailySummary;
+    categoryBreakdown: CategoryStats[];
+    significantTrades: TradeRecord[];
+    newPositions: PositionSummary[];
+    closedMarkets: ClosedMarketSummary[];
+}
+/**
+ * Data range for lifecycle report
+ */
+export interface DataRange {
+    firstActivityAt: Date;
+    lastActivityAt: Date;
+    totalDays: number;
+}
+/**
+ * Performance metrics
+ */
+export interface PerformanceMetrics {
+    totalPnL: number;
+    realizedPnL: number;
+    unrealizedPnL: number;
+    totalVolume: number;
+    winRate: number;
+    profitFactor: number;
+    avgWin: number;
+    avgLoss: number;
+    maxWin: number;
+    maxLoss: number;
+    totalMarketsTraded: number;
+    winningMarkets: number;
+    losingMarkets: number;
+}
+/**
+ * Market statistics for top/worst markets
+ */
+export interface MarketStats {
+    market: string;
+    conditionId: string;
+    category: MarketCategory;
+    pnl: number;
+    volume: number;
+    tradeCount: number;
+    outcome: 'win' | 'lose' | 'open';
+    avgPrice: number;
+    closePrice?: number;
+}
+/**
+ * Trading patterns analysis
+ */
+export interface TradingPatterns {
+    avgTradesPerDay: number;
+    avgTradesPerWeek: number;
+    preferredSide: 'YES' | 'NO' | 'balanced';
+    avgPositionSize: number;
+    avgHoldingDays: number;
+    topCategories: MarketCategory[];
+    positionConcentration: number;
+}
+/**
+ * Current positions summary
+ */
+export interface CurrentPositionsSummary {
+    count: number;
+    totalValue: number;
+    unrealizedPnL: number;
+    categories: CategoryStats[];
+}
+/**
+ * Wallet lifecycle report
+ */
+export interface WalletLifecycleReport {
+    address: string;
+    generatedAt: Date;
+    dataRange: DataRange;
+    performance: PerformanceMetrics;
+    categoryDistribution: CategoryStats[];
+    topMarkets: MarketStats[];
+    worstMarkets: MarketStats[];
+    patterns: TradingPatterns;
+    currentPositions: CurrentPositionsSummary;
+}
+/**
+ * Pie chart slice
+ */
+export interface PieSlice {
+    name: string;
+    value: number;
+    percentage: number;
+    color: string;
+}
+/**
+ * Pie chart data
+ */
+export interface PieChartData {
+    name: string;
+    data: PieSlice[];
+    total: number;
+}
+/**
+ * Bar chart item
+ */
+export interface BarItem {
+    label: string;
+    value: number;
+    color: string;
+}
+/**
+ * Bar chart data
+ */
+export interface BarChartData {
+    name: string;
+    data: BarItem[];
+}
+/**
+ * Monthly PnL item
+ */
+export interface MonthlyPnLItem extends BarItem {
+    month: string;
+    pnl: number;
+    tradeCount: number;
+    cumulativePnL: number;
+}
+/**
+ * Monthly PnL chart data
+ */
+export interface MonthlyPnLData extends BarChartData {
+    data: MonthlyPnLItem[];
+}
+/**
+ * Chart metadata
+ */
+export interface ChartMetadata {
+    address: string;
+    generatedAt: Date;
+    dataRange: {
+        from: Date;
+        to: Date;
+    };
+}
+/**
+ * Wallet chart data
+ */
+export interface WalletChartData {
+    tradeDistribution: PieChartData;
+    positionDistribution: PieChartData;
+    profitDistribution: PieChartData;
+    monthlyPnL?: MonthlyPnLData;
+    metadata: ChartMetadata;
+}
+/**
+ * Report generation progress callback
+ */
+export type ReportProgressCallback = (progress: number, message: string) => void;
+/**
+ * Lifecycle report options
+ */
+export interface LifecycleReportOptions {
+    onProgress?: ReportProgressCallback;
+}
+/**
+ * Text report output
+ */
+export interface TextReport {
+    address: string;
+    generatedAt: Date;
+    markdown: string;
+    metrics: {
+        totalPnL: number;
+        winRate: number;
+        profitFactor: number;
+        totalMarketsTraded: number;
+        totalDays: number;
+    };
+}
+export declare class SmartMoneyService {
+    private walletService;
+    private realtimeService;
+    private tradingService;
+    private dataApi;
+    private config;
+    private smartMoneyCache;
+    private smartMoneySet;
+    private cacheTimestamp;
+    private activeSubscription;
+    private tradeHandlers;
+    constructor(walletService: WalletService, realtimeService: RealtimeServiceV2, tradingService: TradingService, config?: SmartMoneyServiceConfig, dataApi?: DataApiClient);
+    /**
+     * Set DataApiClient for report generation
+     * This allows setting the client after construction
+     */
+    setDataApiClient(dataApi: DataApiClient): void;
+    /**
+     * Get list of Smart Money wallets from leaderboard
+     */
+    getSmartMoneyList(limit?: number): Promise<SmartMoneyWallet[]>;
+    /**
+     * Check if an address is Smart Money
+     */
+    isSmartMoney(address: string): Promise<boolean>;
+    /**
+     * Get Smart Money info for an address
+     */
+    getSmartMoneyInfo(address: string): Promise<SmartMoneyWallet | null>;
+    /**
+     * Subscribe to trades from specific addresses
+     *
+     * @example
+     * ```typescript
+     * const sub = smartMoneyService.subscribeSmartMoneyTrades(
+     *   (trade) => {
+     *     console.log(`${trade.traderName} ${trade.side} ${trade.size} @ ${trade.price}`);
+     *   },
+     *   { filterAddresses: ['0x1234...', '0x5678...'] }
+     * );
+     *
+     * // Stop listening
+     * sub.unsubscribe();
+     * ```
+     */
+    subscribeSmartMoneyTrades(onTrade: (trade: SmartMoneyTrade) => void, options?: {
+        filterAddresses?: string[];
+        minSize?: number;
+        smartMoneyOnly?: boolean;
+    }): {
+        id: string;
+        unsubscribe: () => void;
+    };
+    private handleActivityTrade;
+    /**
+     * Start auto copy trading - 自动跟单
+     *
+     * @example
+     * ```typescript
+     * const sub = await smartMoneyService.startAutoCopyTrading({
+     *   targetAddresses: ['0x1234...'],
+     *   // 或者跟踪排行榜前N名
+     *   topN: 10,
+     *
+     *   sizeScale: 0.1,        // 10%
+     *   maxSizePerTrade: 50,   // $50
+     *   maxSlippage: 0.03,     // 3%
+     *   orderType: 'FOK',
+     *
+     *   dryRun: true,          // 测试模式
+     *
+     *   onTrade: (trade, result) => console.log(result),
+     * });
+     *
+     * // 停止
+     * sub.stop();
+     * ```
+     */
+    startAutoCopyTrading(options: AutoCopyTradingOptions): Promise<AutoCopyTradingSubscription>;
+    /**
+     * Get leaderboard by time period
+     *
+     * @example
+     * ```typescript
+     * // Get weekly top 100 by PnL
+     * const leaderboard = await sdk.smartMoney.getLeaderboard({
+     *   period: 'week',
+     *   limit: 100,
+     *   sortBy: 'pnl'
+     * });
+     * ```
+     */
+    getLeaderboard(options?: LeaderboardOptions): Promise<SmartMoneyLeaderboardResult>;
+    /**
+     * Generate comprehensive wallet report
+     *
+     * @example
+     * ```typescript
+     * const report = await sdk.smartMoney.getWalletReport('0x...');
+     * console.log(report.overview.totalPnL);
+     * console.log(report.rankings.weekly?.rank);
+     * ```
+     */
+    getWalletReport(address: string): Promise<WalletReport>;
+    /**
+     * Analyze position categories based on title keywords
+     */
+    private analyzeCategories;
+    /**
+     * Compare multiple wallets
+     *
+     * @example
+     * ```typescript
+     * const comparison = await sdk.smartMoney.compareWallets(
+     *   ['0x111...', '0x222...', '0x333...'],
+     *   { period: 'week' }
+     * );
+     * ```
+     */
+    compareWallets(addresses: string[], options?: {
+        period?: TimePeriod;
+    }): Promise<WalletComparison>;
+    /**
+     * Get daily wallet report
+     *
+     * @param address - Wallet address
+     * @param date - Date for the report (default: today)
+     *
+     * @example
+     * ```typescript
+     * const report = await sdk.smartMoney.getDailyReport('0x...', new Date('2026-01-08'));
+     * console.log(report.summary.realizedPnL);
+     * ```
+     */
+    getDailyReport(address: string, date?: Date): Promise<DailyWalletReport>;
+    /**
+     * Get wallet lifecycle report
+     *
+     * @param address - Wallet address
+     * @param options - Report options with progress callback
+     *
+     * @example
+     * ```typescript
+     * const report = await sdk.smartMoney.getLifecycleReport('0x...', {
+     *   onProgress: (p, msg) => console.log(`${p * 100}%: ${msg}`)
+     * });
+     * console.log(report.performance.winRate);
+     * ```
+     */
+    getLifecycleReport(address: string, options?: LifecycleReportOptions): Promise<WalletLifecycleReport>;
+    /**
+     * Get wallet chart data
+     *
+     * @param address - Wallet address
+     *
+     * @example
+     * ```typescript
+     * const chartData = await sdk.smartMoney.getWalletChartData('0x...');
+     * // Use chartData.tradeDistribution with recharts
+     * ```
+     */
+    getWalletChartData(address: string): Promise<WalletChartData>;
+    /**
+     * Generate a text analysis report for a wallet
+     *
+     * @param address - Wallet address
+     * @param options - Report options with progress callback
+     *
+     * @example
+     * ```typescript
+     * const textReport = await sdk.smartMoney.generateTextReport('0x...');
+     * console.log(textReport.markdown);
+     * ```
+     */
+    generateTextReport(address: string, options?: LifecycleReportOptions): Promise<TextReport>;
+    /**
+     * Build markdown text report from data
+     */
+    private buildTextReport;
+    /**
+     * Analyze trading style from patterns
+     */
+    private analyzeTradingStyle;
+    /**
+     * Assess risk profile
+     */
+    private assessRisk;
+    /**
+     * Generate copy trading recommendation
+     */
+    private generateRecommendation;
+    /**
+     * Categorize market based on title keywords
+     */
+    private categorizeMarket;
+    /**
+     * Fetch all closed positions with pagination
+     */
+    private fetchAllClosedPositions;
+    /**
+     * Calculate performance metrics from closed positions
+     */
+    private calculatePerformanceMetricsFromClosed;
+    /**
+     * Calculate category distribution from closed positions
+     */
+    private calculateCategoryDistributionFromClosed;
+    /**
+     * Calculate category distribution from current positions
+     */
+    private calculateCategoryDistributionFromPositions;
+    /**
+     * Calculate category breakdown from activity trades
+     */
+    private calculateCategoryBreakdownFromActivities;
+    /**
+     * Get top markets by PnL
+     */
+    private getTopMarkets;
+    /**
+     * Get worst markets by PnL
+     */
+    private getWorstMarkets;
+    /**
+     * Analyze trading patterns
+     */
+    private analyzeTradingPatterns;
+    /**
+     * Build pie chart data
+     */
+    private buildPieChart;
+    /**
+     * Format date as YYYY-MM-DD
+     */
+    private formatDate;
+    private isCacheValid;
+    disconnect(): void;
+}
+//# sourceMappingURL=smart-money-service.d.ts.map