@catalyst-team/poly-sdk 0.1.0

package/src/mcp/tools/trader.ts

@@ -0,0 +1,322 @@
+/**
+ * Trader Tools - MCP tools for trader/wallet analysis
+ */
+
+import type { PolymarketSDK } from '../../index.js';
+import type {
+  ToolDefinition,
+  GetTraderPositionsInput,
+  GetTraderPositionsOutput,
+  GetTraderTradesInput,
+  GetTraderTradesOutput,
+  GetTraderProfileInput,
+  GetTraderProfileOutput,
+  GetLeaderboardInput,
+  GetLeaderboardOutput,
+} from '../types.js';
+import { validateAddress, wrapError } from '../errors.js';
+
+export const traderToolDefinitions: ToolDefinition[] = [
+  {
+    name: 'get_trader_positions',
+    description: 'Get all positions held by a trader with PnL breakdown',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        address: {
+          type: 'string',
+          description: 'Trader wallet address (0x...)',
+        },
+      },
+      required: ['address'],
+    },
+  },
+  {
+    name: 'get_trader_trades',
+    description: 'Get recent trading activity for a trader',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        address: {
+          type: 'string',
+          description: 'Trader wallet address',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of trades to return',
+          default: 20,
+        },
+        side: {
+          type: 'string',
+          enum: ['BUY', 'SELL'],
+          description: 'Filter by trade side',
+        },
+      },
+      required: ['address'],
+    },
+  },
+  {
+    name: 'get_trader_profile',
+    description: 'Get comprehensive trader profile with performance metrics',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        address: {
+          type: 'string',
+          description: 'Trader wallet address',
+        },
+      },
+      required: ['address'],
+    },
+  },
+  {
+    name: 'get_leaderboard',
+    description: 'Get top traders by PnL',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: {
+          type: 'number',
+          description: 'Number of traders to return',
+          default: 10,
+        },
+        offset: {
+          type: 'number',
+          description: 'Pagination offset',
+          default: 0,
+        },
+      },
+    },
+  },
+];
+
+export async function handleGetTraderPositions(
+  sdk: PolymarketSDK,
+  input: GetTraderPositionsInput
+): Promise<GetTraderPositionsOutput> {
+  validateAddress(input.address);
+
+  try {
+    const positions = await sdk.wallets.getWalletPositions(input.address);
+
+    const totalUnrealizedPnl = positions.reduce((sum, p) => sum + (p.cashPnl || 0), 0);
+    const totalRealizedPnl = positions.reduce((sum, p) => sum + (p.realizedPnl || 0), 0);
+    const winningPositions = positions.filter((p) => (p.cashPnl || 0) > 0).length;
+    const losingPositions = positions.filter((p) => (p.cashPnl || 0) < 0).length;
+
+    return {
+      trader: {
+        address: input.address,
+        displayName: null, // Will be enriched if available
+      },
+      positions: positions.map((p) => ({
+        market: {
+          conditionId: p.conditionId,
+          title: p.title,
+          slug: p.slug,
+        },
+        holding: {
+          outcome: p.outcome,
+          size: p.size,
+          avgPrice: p.avgPrice,
+          curPrice: p.curPrice,
+        },
+        pnl: {
+          unrealized: p.cashPnl,
+          unrealizedPercent: p.percentPnl,
+          realized: p.realizedPnl,
+        },
+        status: {
+          redeemable: p.redeemable,
+          endDate: p.endDate,
+        },
+      })),
+      summary: {
+        totalPositions: positions.length,
+        totalUnrealizedPnl,
+        totalRealizedPnl,
+        winningPositions,
+        losingPositions,
+      },
+    };
+  } catch (err) {
+    throw wrapError(err);
+  }
+}
+
+export async function handleGetTraderTrades(
+  sdk: PolymarketSDK,
+  input: GetTraderTradesInput
+): Promise<GetTraderTradesOutput> {
+  validateAddress(input.address);
+
+  try {
+    const activityResult = await sdk.wallets.getWalletActivity(
+      input.address,
+      input.limit || 100
+    );
+
+    let trades = activityResult.activities.filter((a) => a.type === 'TRADE');
+
+    // Filter by side if specified
+    if (input.side) {
+      trades = trades.filter((a) => a.side === input.side);
+    }
+
+    // Apply limit
+    const limit = input.limit || 20;
+    trades = trades.slice(0, limit);
+
+    const buyTrades = trades.filter((t) => t.side === 'BUY');
+    const sellTrades = trades.filter((t) => t.side === 'SELL');
+
+    return {
+      trader: {
+        address: input.address,
+        displayName: null,
+      },
+      trades: trades.map((t) => ({
+        type: t.type,
+        side: t.side,
+        market: {
+          conditionId: t.conditionId,
+          title: t.title || '',
+          slug: t.slug,
+        },
+        outcome: t.outcome,
+        execution: {
+          size: t.size,
+          price: t.price,
+          usdcValue: t.usdcSize || t.size * t.price,
+        },
+        timestamp: new Date(t.timestamp).toISOString(),
+        txHash: t.transactionHash,
+      })),
+      summary: {
+        totalTrades: trades.length,
+        buyCount: buyTrades.length,
+        sellCount: sellTrades.length,
+        buyVolume: buyTrades.reduce((sum, t) => sum + (t.usdcSize || t.size * t.price), 0),
+        sellVolume: sellTrades.reduce((sum, t) => sum + (t.usdcSize || t.size * t.price), 0),
+      },
+    };
+  } catch (err) {
+    throw wrapError(err);
+  }
+}
+
+export async function handleGetTraderProfile(
+  sdk: PolymarketSDK,
+  input: GetTraderProfileInput
+): Promise<GetTraderProfileOutput> {
+  validateAddress(input.address);
+
+  try {
+    const profile = await sdk.wallets.getWalletProfile(input.address);
+
+    // Try to get leaderboard data for rank and official PnL
+    let rank: number | null = null;
+    let leaderboardPnl: number | null = null;
+    let leaderboardVolume: number | null = null;
+    let displayName: string | null = null;
+    let verified = false;
+    try {
+      const leaderboard = await sdk.wallets.getLeaderboard(0, 100);
+      const entry = leaderboard.entries.find(
+        (e) => e.address.toLowerCase() === input.address.toLowerCase()
+      );
+      if (entry) {
+        rank = entry.rank;
+        leaderboardPnl = entry.pnl;
+        leaderboardVolume = entry.volume;
+        displayName = entry.userName || null;
+        verified = entry.verifiedBadge || false;
+      }
+    } catch {
+      // Ignore leaderboard errors
+    }
+
+    const winningCount = profile.positionCount > 0
+      ? Math.round(profile.positionCount * (profile.avgPercentPnL > 0 ? 0.6 : 0.4))
+      : 0;
+    const winRate = profile.positionCount > 0
+      ? winningCount / profile.positionCount
+      : 0;
+
+    return {
+      trader: {
+        address: input.address,
+        displayName,
+        xUsername: null,
+        verified,
+        profileImage: null,
+      },
+      ranking: {
+        rank,
+        totalTraders: 10000, // Approximate
+      },
+      performance: {
+        // Official PnL from leaderboard (used for ranking)
+        officialPnl: leaderboardPnl,
+        // Volume from leaderboard
+        totalVolume: leaderboardVolume ?? (profile.totalPnL + profile.unrealizedPnL),
+        // Calculated PnL from profile positions
+        unrealizedPnl: profile.unrealizedPnL,
+        realizedPnl: profile.realizedPnL,
+      },
+      stats: {
+        positionCount: profile.positionCount,
+        winRate,
+        avgPercentPnl: profile.avgPercentPnL,
+        smartScore: profile.smartScore,
+      },
+      activity: {
+        lastTradeAt: profile.lastActiveAt.getTime() > 0
+          ? profile.lastActiveAt.toISOString()
+          : null,
+        isActive: Date.now() - profile.lastActiveAt.getTime() < 7 * 24 * 60 * 60 * 1000,
+      },
+      // Explain potential PnL differences
+      notes: leaderboardPnl !== null && Math.abs((leaderboardPnl || 0) - (profile.unrealizedPnL + profile.realizedPnL)) > 100
+        ? 'Note: officialPnl (from leaderboard) may differ from unrealizedPnl + realizedPnl (from positions) due to different calculation methods. Leaderboard PnL includes historical settled positions.'
+        : undefined,
+    };
+  } catch (err) {
+    throw wrapError(err);
+  }
+}
+
+export async function handleGetLeaderboard(
+  sdk: PolymarketSDK,
+  input: GetLeaderboardInput
+): Promise<GetLeaderboardOutput> {
+  const limit = input.limit || 10;
+  const offset = input.offset || 0;
+
+  try {
+    const page = Math.floor(offset / 50);
+    const leaderboard = await sdk.wallets.getLeaderboard(page, 50);
+
+    // Apply offset and limit within the page
+    const startIdx = offset % 50;
+    const entries = leaderboard.entries.slice(startIdx, startIdx + limit);
+
+    return {
+      traders: entries.map((e) => ({
+        rank: e.rank,
+        address: e.address,
+        displayName: e.userName || null,
+        pnl: e.pnl,
+        volume: e.volume,
+        verified: e.verifiedBadge || false,
+      })),
+      pagination: {
+        total: leaderboard.total,
+        offset,
+        limit,
+      },
+    };
+  } catch (err) {
+    throw wrapError(err);
+  }
+}