@catalyst-team/poly-sdk 0.1.0

package/src/services/wallet-service.ts

@@ -0,0 +1,259 @@
+/**
+ * Wallet Service
+ *
+ * Provides smart money analysis features:
+ * - Wallet profile analysis
+ * - Position tracking
+ * - Activity monitoring
+ * - Sell detection for follow wallet strategy
+ */
+
+import { DataApiClient, Position, Activity, LeaderboardEntry, LeaderboardPage } from '../clients/data-api.js';
+import type { UnifiedCache } from '../core/unified-cache.js';
+import { CACHE_TTL } from '../core/unified-cache.js';
+
+export interface WalletProfile {
+  address: string;
+  totalPnL: number;
+  realizedPnL: number;
+  unrealizedPnL: number;
+  avgPercentPnL: number;
+  positionCount: number;
+  tradeCount: number;
+  smartScore: number; // 0-100
+  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 class WalletService {
+  constructor(
+    private dataApi: DataApiClient,
+    private cache: UnifiedCache
+  ) {}
+
+  // ===== Wallet Analysis =====
+
+  /**
+   * Get comprehensive wallet profile with PnL analysis
+   */
+  async getWalletProfile(address: string): Promise<WalletProfile> {
+    const [positions, activities] = await Promise.all([
+      this.dataApi.getPositions(address),
+      this.dataApi.getActivity(address, { limit: 100 }),
+    ]);
+
+    const totalPnL = positions.reduce((sum, p) => sum + (p.cashPnl || 0), 0);
+    const realizedPnL = positions.reduce((sum, p) => sum + (p.realizedPnl || 0), 0);
+    const unrealizedPnL = totalPnL - realizedPnL;
+
+    const avgPercentPnL =
+      positions.length > 0
+        ? positions.reduce((sum, p) => sum + (p.percentPnl || 0), 0) / positions.length
+        : 0;
+
+    const lastActivity = activities[0];
+
+    return {
+      address,
+      totalPnL,
+      realizedPnL,
+      unrealizedPnL,
+      avgPercentPnL,
+      positionCount: positions.length,
+      tradeCount: activities.filter((a) => a.type === 'TRADE').length,
+      smartScore: this.calculateSmartScore(positions, activities),
+      lastActiveAt: lastActivity ? new Date(lastActivity.timestamp) : new Date(0),
+    };
+  }
+
+  /**
+   * Get positions for a wallet
+   */
+  async getWalletPositions(address: string): Promise<Position[]> {
+    return this.dataApi.getPositions(address);
+  }
+
+  /**
+   * Get positions for a specific market
+   */
+  async getPositionsForMarket(address: string, conditionId: string): Promise<Position[]> {
+    const positions = await this.dataApi.getPositions(address);
+    return positions.filter((p) => p.conditionId === conditionId);
+  }
+
+  /**
+   * Get wallet activity with summary
+   */
+  async getWalletActivity(address: string, limit = 100): Promise<WalletActivitySummary> {
+    const activities = await this.dataApi.getActivity(address, { limit });
+
+    const buys = activities.filter((a) => a.side === 'BUY');
+    const sells = activities.filter((a) => a.side === 'SELL');
+
+    return {
+      address,
+      activities,
+      summary: {
+        totalBuys: buys.length,
+        totalSells: sells.length,
+        buyVolume: buys.reduce((sum, a) => sum + (a.usdcSize || 0), 0),
+        sellVolume: sells.reduce((sum, a) => sum + (a.usdcSize || 0), 0),
+        activeMarkets: [...new Set(activities.map((a) => a.conditionId))],
+      },
+    };
+  }
+
+  // ===== Wallet Discovery =====
+
+  /**
+   * Get leaderboard
+   */
+  async getLeaderboard(page = 0, pageSize = 50): Promise<LeaderboardPage> {
+    return this.dataApi.getLeaderboard({ limit: pageSize, offset: page * pageSize });
+  }
+
+  /**
+   * Get top traders from leaderboard
+   */
+  async getTopTraders(limit = 10): Promise<LeaderboardEntry[]> {
+    const leaderboard = await this.dataApi.getLeaderboard({ limit });
+    return leaderboard.entries;
+  }
+
+  /**
+   * Discover active wallets from recent trades
+   */
+  async discoverActiveWallets(limit = 100): Promise<Array<{ address: string; tradeCount: number }>> {
+    const trades = await this.dataApi.getTrades({ limit: 1000 });
+
+    // Count trades per wallet
+    const walletCounts = new Map<string, number>();
+    for (const trade of trades) {
+      if (trade.proxyWallet) {
+        walletCounts.set(trade.proxyWallet, (walletCounts.get(trade.proxyWallet) || 0) + 1);
+      }
+    }
+
+    // Sort by trade count
+    return [...walletCounts.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, limit)
+      .map(([address, tradeCount]) => ({ address, tradeCount }));
+  }
+
+  // ===== Sell Detection (Follow Wallet Strategy) =====
+
+  /**
+   * Detect sell activity for a wallet in a specific market
+   */
+  async detectSellActivity(
+    address: string,
+    conditionId: string,
+    sinceTimestamp: number,
+    peakValue?: number
+  ): Promise<SellActivityResult> {
+    const activities = await this.dataApi.getActivity(address, { limit: 200, type: 'TRADE' });
+
+    const sellTransactions = activities.filter(
+      (a) => a.conditionId === conditionId && a.side === 'SELL' && a.timestamp >= sinceTimestamp
+    );
+
+    const totalSellAmount = sellTransactions.reduce((sum, a) => sum + (a.usdcSize || a.size * a.price), 0);
+
+    // Calculate sell ratio if peak value is provided
+    const sellRatio = peakValue && peakValue > 0 ? totalSellAmount / peakValue : 0;
+
+    return {
+      totalSellAmount,
+      sellTransactions,
+      sellRatio,
+      shouldExit: sellRatio >= 0.3, // 30% threshold for exit signal
+    };
+  }
+
+  /**
+   * Track sell ratio for multiple wallets (aggregated)
+   */
+  async trackGroupSellRatio(
+    addresses: string[],
+    conditionId: string,
+    peakTotalValue: number,
+    sinceTimestamp: number
+  ): Promise<{
+    cumulativeSellAmount: number;
+    sellRatio: number;
+    shouldExit: boolean;
+    walletSells: Array<{ address: string; sellAmount: number }>;
+  }> {
+    const walletSells: Array<{ address: string; sellAmount: number }> = [];
+    let cumulativeSellAmount = 0;
+
+    for (const address of addresses) {
+      const sellData = await this.detectSellActivity(address, conditionId, sinceTimestamp);
+      walletSells.push({ address, sellAmount: sellData.totalSellAmount });
+      cumulativeSellAmount += sellData.totalSellAmount;
+    }
+
+    const sellRatio = peakTotalValue > 0 ? cumulativeSellAmount / peakTotalValue : 0;
+
+    return {
+      cumulativeSellAmount,
+      sellRatio,
+      shouldExit: sellRatio >= 0.3,
+      walletSells,
+    };
+  }
+
+  // ===== Smart Score Calculation =====
+
+  private calculateSmartScore(positions: Position[], activities: Activity[]): number {
+    // Weights: PnL 40%, Win Rate 30%, Consistency 20%, Activity 10%
+
+    // PnL Score (0-40)
+    const avgPnL =
+      positions.length > 0
+        ? positions.reduce((sum, p) => sum + (p.percentPnl || 0), 0) / positions.length
+        : 0;
+    const pnlScore = Math.min(40, Math.max(0, ((avgPnL + 50) / 100) * 40));
+
+    // Win Rate Score (0-30)
+    const winningPositions = positions.filter((p) => (p.cashPnl || 0) > 0).length;
+    const winRate = positions.length > 0 ? winningPositions / positions.length : 0;
+    const winRateScore = winRate * 30;
+
+    // Consistency Score (0-20)
+    const pnlValues = positions.map((p) => p.percentPnl || 0);
+    const variance = this.calculateVariance(pnlValues);
+    const consistencyScore = Math.max(0, 20 - variance / 10);
+
+    // Activity Score (0-10)
+    const recentTrades = activities.filter((a) => a.timestamp > Date.now() - 7 * 24 * 60 * 60 * 1000).length;
+    const activityScore = Math.min(10, (recentTrades / 5) * 10);
+
+    return Math.round(pnlScore + winRateScore + consistencyScore + activityScore);
+  }
+
+  private calculateVariance(values: number[]): number {
+    if (values.length === 0) return 0;
+    const mean = values.reduce((a, b) => a + b, 0) / values.length;
+    return values.reduce((sum, v) => sum + Math.pow(v - mean, 2), 0) / values.length;
+  }
+}

package/src/utils/price-utils.ts

@@ -0,0 +1,307 @@
+/**
+ * Price Utilities for Polymarket Trading
+ *
+ * Provides helpers for:
+ * - Price validation and rounding to tick size
+ * - Size validation
+ * - Order amount calculation
+ */
+
+// Tick size types (as defined by Polymarket)
+export type TickSize = '0.1' | '0.01' | '0.001' | '0.0001';
+
+// Rounding configuration for each tick size
+export const ROUNDING_CONFIG: Record<
+  TickSize,
+  { price: number; size: number; amount: number }
+> = {
+  '0.1': { price: 1, size: 2, amount: 2 },
+  '0.01': { price: 2, size: 2, amount: 4 },
+  '0.001': { price: 3, size: 2, amount: 5 },
+  '0.0001': { price: 4, size: 2, amount: 6 },
+};
+
+/**
+ * Round a price to the appropriate tick size
+ *
+ * @param price - The price to round (0 to 1)
+ * @param tickSize - The tick size for the market
+ * @param direction - 'floor' for sells, 'ceil' for buys, 'round' for midpoint
+ * @returns Rounded price
+ *
+ * @example
+ * roundPrice(0.523, '0.01', 'floor') // 0.52
+ * roundPrice(0.523, '0.01', 'ceil') // 0.53
+ */
+export function roundPrice(
+  price: number,
+  tickSize: TickSize,
+  direction: 'floor' | 'ceil' | 'round' = 'round'
+): number {
+  const decimals = ROUNDING_CONFIG[tickSize].price;
+  const multiplier = Math.pow(10, decimals);
+
+  let rounded: number;
+  switch (direction) {
+    case 'floor':
+      rounded = Math.floor(price * multiplier) / multiplier;
+      break;
+    case 'ceil':
+      rounded = Math.ceil(price * multiplier) / multiplier;
+      break;
+    default:
+      rounded = Math.round(price * multiplier) / multiplier;
+  }
+
+  // Clamp to valid price range
+  return Math.max(0.001, Math.min(0.999, rounded));
+}
+
+/**
+ * Round a size to valid decimals (always 2 decimal places)
+ */
+export function roundSize(size: number): number {
+  return Math.round(size * 100) / 100;
+}
+
+/**
+ * Validate a price is within valid range and tick size
+ *
+ * @param price - The price to validate
+ * @param tickSize - The tick size for the market
+ * @returns Validation result with error message if invalid
+ */
+export function validatePrice(
+  price: number,
+  tickSize: TickSize
+): { valid: boolean; error?: string } {
+  // Check range
+  if (price < 0.001 || price > 0.999) {
+    return { valid: false, error: 'Price must be between 0.001 and 0.999' };
+  }
+
+  // Check tick size alignment
+  const decimals = ROUNDING_CONFIG[tickSize].price;
+  const multiplier = Math.pow(10, decimals);
+  const rounded = Math.round(price * multiplier) / multiplier;
+
+  if (Math.abs(price - rounded) > 1e-10) {
+    return {
+      valid: false,
+      error: `Price ${price} does not align with tick size ${tickSize}. Use ${rounded} instead.`,
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Validate minimum size requirements
+ *
+ * @param size - The size to validate
+ * @param minOrderSize - Minimum order size from market config (usually 0.1)
+ */
+export function validateSize(
+  size: number,
+  minOrderSize = 0.1
+): { valid: boolean; error?: string } {
+  if (size < minOrderSize) {
+    return {
+      valid: false,
+      error: `Size ${size} is below minimum order size ${minOrderSize}`,
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Calculate the amount needed for a buy order (in USDC)
+ *
+ * @param price - Price per share
+ * @param size - Number of shares to buy
+ * @returns Amount in USDC
+ */
+export function calculateBuyAmount(price: number, size: number): number {
+  return price * size;
+}
+
+/**
+ * Calculate the payout for a sell order (in USDC)
+ *
+ * @param price - Price per share
+ * @param size - Number of shares to sell
+ * @returns Amount in USDC
+ */
+export function calculateSellPayout(price: number, size: number): number {
+  return price * size;
+}
+
+/**
+ * Calculate number of shares that can be bought with a given amount
+ *
+ * @param amount - USDC amount to spend
+ * @param price - Price per share
+ * @returns Number of shares
+ */
+export function calculateSharesForAmount(
+  amount: number,
+  price: number
+): number {
+  return roundSize(amount / price);
+}
+
+/**
+ * Calculate the spread between bid and ask
+ *
+ * @param bid - Highest bid price
+ * @param ask - Lowest ask price
+ * @returns Spread as a decimal (0 to 1)
+ */
+export function calculateSpread(bid: number, ask: number): number {
+  return ask - bid;
+}
+
+/**
+ * Calculate the midpoint price between bid and ask
+ *
+ * @param bid - Highest bid price
+ * @param ask - Lowest ask price
+ * @returns Midpoint price
+ */
+export function calculateMidpoint(bid: number, ask: number): number {
+  return (bid + ask) / 2;
+}
+
+/**
+ * 计算有效价格（考虑 Polymarket 订单簿的镜像特性）
+ *
+ * Polymarket 的关键特性：买 YES @ P = 卖 NO @ (1-P)
+ * 因此同一订单会在两个订单簿中出现
+ *
+ * 有效价格是考虑镜像后的最优价格
+ *
+ * @param yesAsk - YES token 的最低卖价
+ * @param yesBid - YES token 的最高买价
+ * @param noAsk - NO token 的最低卖价
+ * @param noBid - NO token 的最高买价
+ */
+export function getEffectivePrices(
+  yesAsk: number,
+  yesBid: number,
+  noAsk: number,
+  noBid: number
+): {
+  effectiveBuyYes: number;
+  effectiveBuyNo: number;
+  effectiveSellYes: number;
+  effectiveSellNo: number;
+} {
+  return {
+    // 买 YES: 直接买 YES.ask 或 通过卖 NO (成本 = 1 - NO.bid)
+    effectiveBuyYes: Math.min(yesAsk, 1 - noBid),
+
+    // 买 NO: 直接买 NO.ask 或 通过卖 YES (成本 = 1 - YES.bid)
+    effectiveBuyNo: Math.min(noAsk, 1 - yesBid),
+
+    // 卖 YES: 直接卖 YES.bid 或 通过买 NO (收入 = 1 - NO.ask)
+    effectiveSellYes: Math.max(yesBid, 1 - noAsk),
+
+    // 卖 NO: 直接卖 NO.bid 或 通过买 YES (收入 = 1 - YES.ask)
+    effectiveSellNo: Math.max(noBid, 1 - yesAsk),
+  };
+}
+
+/**
+ * Check if there's an arbitrage opportunity
+ *
+ * 使用有效价格计算套利机会（正确考虑镜像订单）
+ *
+ * Long arb: Buy YES + Buy NO < 1 (使用有效买入价格)
+ * Short arb: Sell YES + Sell NO > 1 (使用有效卖出价格)
+ *
+ * 详细文档见: docs/01-polymarket-orderbook-arbitrage.md
+ *
+ * @param yesAsk - Lowest ask for YES token
+ * @param noAsk - Lowest ask for NO token
+ * @param yesBid - Highest bid for YES token
+ * @param noBid - Highest bid for NO token
+ * @returns Arbitrage info or null
+ */
+export function checkArbitrage(
+  yesAsk: number,
+  noAsk: number,
+  yesBid: number,
+  noBid: number
+): { type: 'long' | 'short'; profit: number; description: string } | null {
+  // 计算有效价格
+  const effective = getEffectivePrices(yesAsk, yesBid, noAsk, noBid);
+
+  // Long arbitrage: Buy complete set (YES + NO) cheaper than $1
+  const effectiveLongCost = effective.effectiveBuyYes + effective.effectiveBuyNo;
+  const longProfit = 1 - effectiveLongCost;
+
+  if (longProfit > 0) {
+    return {
+      type: 'long',
+      profit: longProfit,
+      description: `Buy YES @ ${effective.effectiveBuyYes.toFixed(4)} + NO @ ${effective.effectiveBuyNo.toFixed(4)}, Merge for $1`,
+    };
+  }
+
+  // Short arbitrage: Sell complete set (YES + NO) for more than $1
+  const effectiveShortRevenue = effective.effectiveSellYes + effective.effectiveSellNo;
+  const shortProfit = effectiveShortRevenue - 1;
+
+  if (shortProfit > 0) {
+    return {
+      type: 'short',
+      profit: shortProfit,
+      description: `Split $1, Sell YES @ ${effective.effectiveSellYes.toFixed(4)} + NO @ ${effective.effectiveSellNo.toFixed(4)}`,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Format price for display
+ */
+export function formatPrice(price: number, tickSize?: TickSize): string {
+  const decimals = tickSize ? ROUNDING_CONFIG[tickSize].price : 4;
+  return price.toFixed(decimals);
+}
+
+/**
+ * Format amount in USDC
+ */
+export function formatUSDC(amount: number): string {
+  return `$${amount.toFixed(2)}`;
+}
+
+/**
+ * Calculate PnL for a position
+ *
+ * @param entryPrice - Average entry price
+ * @param currentPrice - Current market price
+ * @param size - Position size
+ * @param side - 'long' for YES, 'short' for NO
+ */
+export function calculatePnL(
+  entryPrice: number,
+  currentPrice: number,
+  size: number,
+  side: 'long' | 'short' = 'long'
+): { pnl: number; pnlPercent: number } {
+  const pnl =
+    side === 'long'
+      ? (currentPrice - entryPrice) * size
+      : (entryPrice - currentPrice) * size;
+
+  const pnlPercent =
+    side === 'long'
+      ? ((currentPrice - entryPrice) / entryPrice) * 100
+      : ((entryPrice - currentPrice) / entryPrice) * 100;
+
+  return { pnl, pnlPercent };
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"]
+}

package/vitest.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    // Default: run only unit tests
+    include: ['src/**/*.test.ts'],
+    exclude: ['src/__tests__/integration/**'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      include: ['src/**/*.ts'],
+      exclude: ['src/**/*.test.ts', 'src/__tests__/**'],
+    },
+    // Longer timeout for integration tests
+    testTimeout: 30000,
+  },
+});

package/vitest.integration.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    // Run only integration tests
+    include: ['src/__tests__/integration/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      include: ['src/**/*.ts'],
+      exclude: ['src/**/*.test.ts', 'src/__tests__/**'],
+    },
+    // Longer timeout for integration tests (real API calls)
+    testTimeout: 60000,
+  },
+});