@catalyst-team/poly-sdk 0.2.0 → 0.3.0

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

@@ -0,0 +1,275 @@
+/**
+ * Wallet Service
+ *
+ * Provides smart money analysis features:
+ * - Wallet profile analysis
+ * - Position tracking
+ * - Activity monitoring
+ * - Sell detection for follow wallet strategy
+ * - Time-based leaderboard and wallet stats
+ */
+import { DataApiClient, Position, Activity, LeaderboardEntry, LeaderboardPage, LeaderboardTimePeriod, LeaderboardOrderBy, LeaderboardCategory } from '../clients/data-api.js';
+import { SubgraphClient } from '../clients/subgraph.js';
+import type { UnifiedCache } from '../core/unified-cache.js';
+/** Time period (lowercase for SDK, maps to API's uppercase) */
+export type TimePeriod = 'day' | 'week' | 'month' | 'all';
+/** Sort criteria for period leaderboard (official API supports PNL and VOL) */
+export type LeaderboardSortBy = 'volume' | 'pnl';
+export type { LeaderboardTimePeriod, LeaderboardOrderBy, LeaderboardCategory };
+/**
+ * Parsed trade from OrderFilledEvent
+ */
+export interface ParsedTrade {
+    timestamp: number;
+    user: string;
+    role: 'maker' | 'taker';
+    side: 'BUY' | 'SELL';
+    tokenId: string;
+    tokenAmount: number;
+    usdcAmount: number;
+    price: number;
+}
+/**
+ * Position tracking for PnL calculation
+ */
+export interface TokenPosition {
+    tokenId: string;
+    amount: number;
+    avgCost: number;
+    totalCost: number;
+    realizedPnl: number;
+}
+/**
+ * User stats with PnL
+ */
+export interface UserPeriodStats {
+    address: string;
+    volume: number;
+    tradeCount: number;
+    buyCount: number;
+    sellCount: number;
+    buyVolume: number;
+    sellVolume: number;
+    realizedPnl: number;
+    unrealizedPnl: number;
+    positions: Map<string, TokenPosition>;
+}
+export interface PeriodLeaderboardEntry {
+    address: string;
+    rank: number;
+    volume: number;
+    pnl: number;
+    totalPnl: number;
+    realizedPnl: number;
+    unrealizedPnl: number;
+    tradeCount: number;
+    buyCount: number;
+    sellCount: number;
+    buyVolume: number;
+    sellVolume: number;
+    makerVolume: number;
+    takerVolume: number;
+    userName?: string;
+    profileImage?: string;
+}
+export interface WalletPeriodStats {
+    address: string;
+    period: TimePeriod;
+    startTime: number;
+    endTime: number;
+    volume: number;
+    tradeCount: number;
+    makerVolume: number;
+    takerVolume: number;
+    makerCount: number;
+    takerCount: number;
+    splitCount: number;
+    mergeCount: number;
+    redemptionCount: number;
+    redemptionPayout: number;
+}
+export interface WalletProfile {
+    address: string;
+    totalPnL: number;
+    realizedPnL: number;
+    unrealizedPnL: number;
+    avgPercentPnL: number;
+    positionCount: number;
+    tradeCount: number;
+    smartScore: number;
+    lastActiveAt: Date;
+}
+export interface WalletActivitySummary {
+    address: string;
+    activities: Activity[];
+    summary: {
+        totalBuys: number;
+        totalSells: number;
+        buyVolume: number;
+        sellVolume: number;
+        activeMarkets: string[];
+    };
+}
+export interface SellActivityResult {
+    totalSellAmount: number;
+    sellTransactions: Activity[];
+    sellRatio: number;
+    shouldExit: boolean;
+}
+export declare class WalletService {
+    private dataApi;
+    private subgraph;
+    private cache;
+    constructor(dataApi: DataApiClient, subgraph: SubgraphClient, cache: UnifiedCache);
+    /**
+     * Get start timestamp for a time period
+     */
+    private getPeriodStartTime;
+    /**
+     * Get comprehensive wallet profile with PnL analysis
+     */
+    getWalletProfile(address: string): Promise<WalletProfile>;
+    /**
+     * Get positions for a wallet
+     */
+    getWalletPositions(address: string): Promise<Position[]>;
+    /**
+     * Get positions for a specific market
+     */
+    getPositionsForMarket(address: string, conditionId: string): Promise<Position[]>;
+    /**
+     * Get wallet activity with summary
+     */
+    getWalletActivity(address: string, limit?: number): Promise<WalletActivitySummary>;
+    /**
+     * Get leaderboard
+     */
+    getLeaderboard(page?: number, pageSize?: number): Promise<LeaderboardPage>;
+    /**
+     * Get top traders from leaderboard
+     */
+    getTopTraders(limit?: number): Promise<LeaderboardEntry[]>;
+    /**
+     * Get leaderboard by time period using official Polymarket API
+     *
+     * Uses the official Data API which supports time period filtering.
+     * This is the recommended method as it uses server-side calculations.
+     *
+     * @param period - Time period: 'day', 'week', 'month', or 'all'
+     * @param limit - Maximum entries to return (default: 50, max: 50)
+     * @param sortBy - Sort criteria: 'volume' or 'pnl' (default: 'pnl')
+     * @param category - Market category filter (default: 'OVERALL')
+     *
+     * @example
+     * ```typescript
+     * // Get top traders of the week by PnL
+     * const weeklyByPnl = await walletService.getLeaderboardByPeriod('week', 20, 'pnl');
+     *
+     * // Get top traders by volume
+     * const weeklyByVolume = await walletService.getLeaderboardByPeriod('week', 20, 'volume');
+     *
+     * // Get politics category leaderboard
+     * const politics = await walletService.getLeaderboardByPeriod('week', 20, 'pnl', 'POLITICS');
+     * ```
+     */
+    getLeaderboardByPeriod(period: TimePeriod, limit?: number, sortBy?: LeaderboardSortBy, category?: LeaderboardCategory): Promise<PeriodLeaderboardEntry[]>;
+    /**
+     * Get a specific user's PnL and ranking for a time period
+     *
+     * Uses the official Data API's user filter to get a single user's stats.
+     *
+     * @param address - User's wallet address
+     * @param period - Time period: 'day', 'week', 'month', or 'all'
+     * @param category - Market category filter (default: 'OVERALL')
+     *
+     * @example
+     * ```typescript
+     * // Get user's weekly PnL
+     * const stats = await walletService.getUserPeriodPnl(address, 'week');
+     * console.log(`Rank: #${stats.rank}, PnL: $${stats.pnl}`);
+     *
+     * // Get user's monthly PnL in politics category
+     * const politicsStats = await walletService.getUserPeriodPnl(address, 'month', 'POLITICS');
+     * ```
+     */
+    getUserPeriodPnl(address: string, period: TimePeriod, category?: LeaderboardCategory): Promise<PeriodLeaderboardEntry | null>;
+    /**
+     * Get wallet stats for a specific time period
+     *
+     * Combines data from Orderbook Subgraph (trades) and Activity Subgraph (splits/merges/redemptions)
+     *
+     * @param address - Wallet address
+     * @param period - Time period: 'day', 'week', 'month', or 'all'
+     *
+     * @example
+     * ```typescript
+     * // Get wallet's monthly stats
+     * const stats = await walletService.getWalletStatsByPeriod(address, 'month');
+     * console.log(`Monthly volume: $${stats.volume}`);
+     * ```
+     */
+    getWalletStatsByPeriod(address: string, period: TimePeriod): Promise<WalletPeriodStats>;
+    /**
+     * Fetch all order filled events in a time period with pagination
+     */
+    private fetchAllFillsInPeriod;
+    /**
+     * Parse OrderFilledEvent into user trades
+     *
+     * OrderFilledEvent 结构:
+     * - makerAssetId = "0" (USDC): Maker 卖 USDC = BUY outcome token
+     * - makerAssetId = 长数字: Maker 卖 outcome token = SELL
+     */
+    private parseOrderFilledEvent;
+    /**
+     * Update position with a trade and calculate realized PnL
+     *
+     * 买入: 增加持仓，更新平均成本
+     * 卖出: 减少持仓，计算已实现盈亏 = 卖出收入 - 成本基础
+     */
+    private updatePositionWithTrade;
+    /**
+     * Calculate unrealized PnL for a position
+     *
+     * 未实现盈亏 = 当前市值 - 总成本
+     * 假设当前价格约等于最后交易价格 (简化处理)
+     */
+    private calculateUnrealizedPnl;
+    /**
+     * Aggregate user statistics with PnL calculation from order filled events
+     *
+     * 核心计算流程:
+     * 1. 解析 OrderFilledEvent 为标准化的 ParsedTrade
+     * 2. 按时间顺序处理每笔交易
+     * 3. 追踪每个用户每个 token 的持仓和平均成本
+     * 4. 卖出时计算已实现盈亏
+     * 5. 期末计算未实现盈亏
+     */
+    private aggregateUserStatsWithPnl;
+    /**
+     * Discover active wallets from recent trades
+     */
+    discoverActiveWallets(limit?: number): Promise<Array<{
+        address: string;
+        tradeCount: number;
+    }>>;
+    /**
+     * Detect sell activity for a wallet in a specific market
+     */
+    detectSellActivity(address: string, conditionId: string, sinceTimestamp: number, peakValue?: number): Promise<SellActivityResult>;
+    /**
+     * Track sell ratio for multiple wallets (aggregated)
+     */
+    trackGroupSellRatio(addresses: string[], conditionId: string, peakTotalValue: number, sinceTimestamp: number): Promise<{
+        cumulativeSellAmount: number;
+        sellRatio: number;
+        shouldExit: boolean;
+        walletSells: Array<{
+            address: string;
+            sellAmount: number;
+        }>;
+    }>;
+    private calculateSmartScore;
+    private calculateVariance;
+}
+//# sourceMappingURL=wallet-service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wallet-service.d.ts","sourceRoot":"","sources":["../../src/services/wallet-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,gBAAgB,EAChB,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,cAAc,EAAoB,MAAM,wBAAwB,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAK7D,+DAA+D;AAC/D,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;AAE1D,+EAA+E;AAC/E,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,KAAK,CAAC;AAGjD,YAAY,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,CAAC;AAe/E;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IACxB,IAAI,EAAE,KAAK,GAAG,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IAEb,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IAEZ,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IAEtB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IAEnB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IAEpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,UAAU,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAEhB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IAEnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,QAAQ,EAAE,CAAC;IACvB,OAAO,EAAE;QACP,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,aAAa,EAAE,MAAM,EAAE,CAAC;KACzB,CAAC;CACH;AAED,MAAM,WAAW,kBAAkB;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,QAAQ,EAAE,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,qBAAa,aAAa;IAEtB,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,KAAK;gBAFL,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE,YAAY;IAK7B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAgB1B;;OAEG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA8B/D;;OAEG;IACG,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAI9D;;OAEG;IACG,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAKtF;;OAEG;IACG,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,SAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAqBrF;;OAEG;IACG,cAAc,CAAC,IAAI,SAAI,EAAE,QAAQ,SAAK,GAAG,OAAO,CAAC,eAAe,CAAC;IAIvE;;OAEG;IACG,aAAa,CAAC,KAAK,SAAK,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAO5D;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,sBAAsB,CAC1B,MAAM,EAAE,UAAU,EAClB,KAAK,SAAK,EACV,MAAM,GAAE,iBAAyB,EACjC,QAAQ,GAAE,mBAA+B,GACxC,OAAO,CAAC,sBAAsB,EAAE,CAAC;IAkDpC;;;;;;;;;;;;;;;;;;OAkBG;IACG,gBAAgB,CACpB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,UAAU,EAClB,QAAQ,GAAE,mBAA+B,GACxC,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC;IA6CzC;;;;;;;;;;;;;;OAcG;IACG,sBAAsB,CAC1B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC,iBAAiB,CAAC;IA+D7B;;OAEG;YACW,qBAAqB;IA6BnC;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;IAmE7B;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB;IAmC/B;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;IAM9B;;;;;;;;;OASG;IACH,OAAO,CAAC,yBAAyB;IA6FjC;;OAEG;IACG,qBAAqB,CAAC,KAAK,SAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAoBjG;;OAEG;IACG,kBAAkB,CACtB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,kBAAkB,CAAC;IAoB9B;;OAEG;IACG,mBAAmB,CACvB,SAAS,EAAE,MAAM,EAAE,EACnB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC;QACT,oBAAoB,EAAE,MAAM,CAAC;QAC7B,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,OAAO,CAAC;QACpB,WAAW,EAAE,KAAK,CAAC;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAC7D,CAAC;IAsBF,OAAO,CAAC,mBAAmB;IA2B3B,OAAO,CAAC,iBAAiB;CAK1B"}