@catalyst-team/poly-sdk 0.1.0

package/examples/04-kline-aggregation.ts

@@ -0,0 +1,158 @@
+/**
+ * Example 4: K-Line Aggregation from Trade Data
+ *
+ * This example demonstrates:
+ * - Getting trade history for a market
+ * - Aggregating trades into K-Line (OHLCV) candles
+ * - Calculating dual-token K-Lines (YES + NO)
+ *
+ * Run: npx ts-node examples/04-kline-aggregation.ts
+ */
+
+import { PolymarketSDK, type Trade, type KLineInterval, getIntervalMs } from '../src/index.js';
+
+interface KLineCandle {
+  timestamp: number;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume: number;
+  tradeCount: number;
+  buyVolume: number;
+  sellVolume: number;
+}
+
+function aggregateToKLines(trades: Trade[], interval: KLineInterval): KLineCandle[] {
+  const intervalMs = getIntervalMs(interval);
+  const buckets = new Map<number, Trade[]>();
+
+  // Group trades into time buckets
+  for (const trade of trades) {
+    const bucketTime = Math.floor(trade.timestamp / intervalMs) * intervalMs;
+    const bucket = buckets.get(bucketTime) || [];
+    bucket.push(trade);
+    buckets.set(bucketTime, bucket);
+  }
+
+  // Convert buckets to candles
+  const candles: KLineCandle[] = [];
+  for (const [timestamp, bucketTrades] of buckets) {
+    if (bucketTrades.length === 0) continue;
+
+    // Sort by timestamp for correct open/close
+    bucketTrades.sort((a, b) => a.timestamp - b.timestamp);
+
+    const prices = bucketTrades.map((t) => t.price);
+    const buyTrades = bucketTrades.filter((t) => t.side === 'BUY');
+    const sellTrades = bucketTrades.filter((t) => t.side === 'SELL');
+
+    candles.push({
+      timestamp,
+      open: bucketTrades[0].price,
+      high: Math.max(...prices),
+      low: Math.min(...prices),
+      close: bucketTrades[bucketTrades.length - 1].price,
+      volume: bucketTrades.reduce((sum, t) => sum + t.size * t.price, 0),
+      tradeCount: bucketTrades.length,
+      buyVolume: buyTrades.reduce((sum, t) => sum + t.size * t.price, 0),
+      sellVolume: sellTrades.reduce((sum, t) => sum + t.size * t.price, 0),
+    });
+  }
+
+  return candles.sort((a, b) => a.timestamp - b.timestamp);
+}
+
+async function main() {
+  console.log('=== K-Line Aggregation from Trade Data ===\n');
+
+  const sdk = new PolymarketSDK();
+
+  // 1. Get a trending market
+  console.log('1. Fetching a trending market...');
+  const markets = await sdk.gammaApi.getTrendingMarkets(1);
+
+  if (markets.length === 0) {
+    console.log('No trending markets found');
+    return;
+  }
+
+  const market = markets[0];
+  console.log(`   Selected: ${market.question}`);
+  console.log(`   Condition ID: ${market.conditionId}\n`);
+
+  // 2. Get trade history
+  console.log('2. Fetching trade history...');
+  const trades = await sdk.dataApi.getTradesByMarket(market.conditionId, 500);
+  console.log(`   Found ${trades.length} trades\n`);
+
+  if (trades.length === 0) {
+    console.log('No trades found for this market');
+    return;
+  }
+
+  // 3. Get token info
+  console.log('3. Getting token info...');
+  const unifiedMarket = await sdk.getMarket(market.conditionId);
+  console.log(`   YES Token: ${unifiedMarket.tokens.yes.tokenId.slice(0, 16)}...`);
+  console.log(`   NO Token: ${unifiedMarket.tokens.no.tokenId.slice(0, 16)}...\n`);
+
+  // 4. Separate trades by token (YES vs NO)
+  const yesTrades = trades.filter((t) => t.outcomeIndex === 0 || t.outcome === 'Yes');
+  const noTrades = trades.filter((t) => t.outcomeIndex === 1 || t.outcome === 'No');
+  console.log(`4. Separated trades: YES=${yesTrades.length}, NO=${noTrades.length}\n`);
+
+  // 5. Aggregate into 1-hour candles
+  const interval: KLineInterval = '1h';
+  console.log(`5. Aggregating into ${interval} candles...\n`);
+
+  const yesCandles = aggregateToKLines(yesTrades, interval);
+  const noCandles = aggregateToKLines(noTrades, interval);
+
+  console.log(`   YES Token K-Lines (${yesCandles.length} candles):`);
+  for (const candle of yesCandles.slice(-5)) {
+    const date = new Date(candle.timestamp).toLocaleString();
+    console.log(
+      `   [${date}] O:${candle.open.toFixed(3)} H:${candle.high.toFixed(3)} L:${candle.low.toFixed(3)} C:${candle.close.toFixed(3)} V:$${candle.volume.toFixed(0)} (${candle.tradeCount} trades)`
+    );
+  }
+
+  console.log(`\n   NO Token K-Lines (${noCandles.length} candles):`);
+  for (const candle of noCandles.slice(-5)) {
+    const date = new Date(candle.timestamp).toLocaleString();
+    console.log(
+      `   [${date}] O:${candle.open.toFixed(3)} H:${candle.high.toFixed(3)} L:${candle.low.toFixed(3)} C:${candle.close.toFixed(3)} V:$${candle.volume.toFixed(0)} (${candle.tradeCount} trades)`
+    );
+  }
+
+  // 6. Calculate spread over time
+  console.log('\n6. Spread Analysis (YES_price + NO_price):\n');
+
+  // Find matching timestamps
+  const yesMap = new Map(yesCandles.map((c) => [c.timestamp, c]));
+  const noMap = new Map(noCandles.map((c) => [c.timestamp, c]));
+
+  const allTimestamps = [...new Set([...yesMap.keys(), ...noMap.keys()])].sort();
+  let lastYes = 0.5;
+  let lastNo = 0.5;
+
+  for (const ts of allTimestamps.slice(-5)) {
+    const date = new Date(ts).toLocaleString();
+    const yesCandle = yesMap.get(ts);
+    const noCandle = noMap.get(ts);
+
+    if (yesCandle) lastYes = yesCandle.close;
+    if (noCandle) lastNo = noCandle.close;
+
+    const spread = lastYes + lastNo;
+    const arbOpportunity = spread < 1 ? 'LONG ARB' : spread > 1 ? 'SHORT ARB' : '';
+
+    console.log(
+      `   [${date}] YES:${lastYes.toFixed(3)} + NO:${lastNo.toFixed(3)} = ${spread.toFixed(4)} ${arbOpportunity}`
+    );
+  }
+
+  console.log('\n=== Done ===');
+}
+
+main().catch(console.error);

package/examples/05-follow-wallet-strategy.ts

@@ -0,0 +1,156 @@
+/**
+ * Example 5: Follow Wallet Strategy
+ *
+ * This example demonstrates:
+ * - Tracking a smart money wallet's positions
+ * - Detecting sell activity (for exit signals)
+ * - Calculating sell ratio for position exit
+ *
+ * Run: npx ts-node examples/05-follow-wallet-strategy.ts
+ */
+
+import { PolymarketSDK, type Position, type Activity } from '../src/index.js';
+
+interface WalletPositionTracker {
+  address: string;
+  position: Position;
+  entryTimestamp: number;
+  peakValue: number;
+  cumulativeSellAmount: number;
+  sellRatio: number;
+}
+
+async function detectSellActivity(
+  sdk: PolymarketSDK,
+  address: string,
+  conditionId: string,
+  sinceTimestamp: number
+): Promise<{ totalSellAmount: number; sellTransactions: Activity[] }> {
+  const activities = await sdk.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
+  );
+
+  return { totalSellAmount, sellTransactions };
+}
+
+async function main() {
+  console.log('=== Follow Wallet Strategy ===\n');
+
+  const sdk = new PolymarketSDK();
+
+  // 1. Get top traders from leaderboard
+  console.log('1. Getting top traders from leaderboard...');
+  const leaderboard = await sdk.dataApi.getLeaderboard({ limit: 5 });
+  console.log(`   Found ${leaderboard.entries.length} top traders\n`);
+
+  if (leaderboard.entries.length === 0) {
+    console.log('No leaderboard entries found');
+    return;
+  }
+
+  // 2. Select a trader to follow
+  const traderToFollow = leaderboard.entries[0];
+  console.log(`2. Following trader: ${traderToFollow.address.slice(0, 10)}...`);
+  console.log(`   Rank: #${traderToFollow.rank}`);
+  console.log(`   PnL: $${traderToFollow.pnl.toLocaleString()}\n`);
+
+  // 3. Get their positions
+  console.log('3. Getting positions...');
+  const positions = await sdk.dataApi.getPositions(traderToFollow.address);
+  console.log(`   Found ${positions.length} positions\n`);
+
+  if (positions.length === 0) {
+    console.log('No positions found for this trader');
+    return;
+  }
+
+  // 4. Analyze each position for sell activity
+  console.log('4. Analyzing positions for sell activity...\n');
+
+  const trackers: WalletPositionTracker[] = [];
+  const oneWeekAgo = Date.now() - 7 * 24 * 60 * 60 * 1000;
+
+  for (const position of positions.slice(0, 5)) {
+    console.log(`   Checking: ${position.title.slice(0, 50)}...`);
+
+    try {
+      // Get sell activity since 1 week ago
+      const sellData = await detectSellActivity(
+        sdk,
+        traderToFollow.address,
+        position.conditionId,
+        oneWeekAgo
+      );
+
+      // Calculate peak value (current value + sells)
+      const currentValue = position.currentValue || position.size * (position.curPrice || position.avgPrice);
+      const peakValue = currentValue + sellData.totalSellAmount;
+
+      // Calculate sell ratio
+      const sellRatio = peakValue > 0 ? sellData.totalSellAmount / peakValue : 0;
+
+      trackers.push({
+        address: traderToFollow.address,
+        position,
+        entryTimestamp: oneWeekAgo, // Approximation
+        peakValue,
+        cumulativeSellAmount: sellData.totalSellAmount,
+        sellRatio,
+      });
+
+      console.log(`     Current Value: $${currentValue.toFixed(2)}`);
+      console.log(`     Cumulative Sells: $${sellData.totalSellAmount.toFixed(2)}`);
+      console.log(`     Estimated Peak: $${peakValue.toFixed(2)}`);
+      console.log(`     Sell Ratio: ${(sellRatio * 100).toFixed(1)}%`);
+
+      // Check if 30% threshold is reached
+      if (sellRatio >= 0.3) {
+        console.log(`     ** EXIT SIGNAL: Sell ratio >= 30% **`);
+      }
+      console.log('');
+
+    } catch (error) {
+      console.log(`     Error: ${(error as Error).message}\n`);
+    }
+  }
+
+  // 5. Summary
+  console.log('=== Follow Wallet Summary ===\n');
+  console.log(`Trader: ${traderToFollow.address.slice(0, 10)}...`);
+  console.log(`Positions analyzed: ${trackers.length}\n`);
+
+  const exitSignals = trackers.filter((t) => t.sellRatio >= 0.3);
+  if (exitSignals.length > 0) {
+    console.log(`EXIT SIGNALS (${exitSignals.length}):`);
+    for (const signal of exitSignals) {
+      console.log(`  - ${signal.position.title.slice(0, 40)}...`);
+      console.log(`    Sell Ratio: ${(signal.sellRatio * 100).toFixed(1)}%`);
+    }
+  } else {
+    console.log('No exit signals detected');
+  }
+
+  const holdingStrong = trackers.filter((t) => t.sellRatio < 0.1);
+  if (holdingStrong.length > 0) {
+    console.log(`\nSTRONG HOLDS (sell ratio < 10%):`);
+    for (const hold of holdingStrong) {
+      console.log(`  - ${hold.position.title.slice(0, 40)}...`);
+      console.log(`    Outcome: ${hold.position.outcome}`);
+      console.log(`    PnL: $${hold.position.cashPnl?.toFixed(2) || 'N/A'}`);
+    }
+  }
+
+  console.log('\n=== Done ===');
+}
+
+main().catch(console.error);

package/examples/06-services-demo.ts

@@ -0,0 +1,124 @@
+/**
+ * Example 6: Services Demo
+ *
+ * This example demonstrates the new service layer:
+ * - WalletService for smart money analysis
+ * - MarketService for K-Line and market signals
+ *
+ * Run: npx tsx examples/06-services-demo.ts
+ */
+
+import { PolymarketSDK, type KLineInterval } from '../src/index.js';
+
+async function main() {
+  console.log('=== Services Demo ===\n');
+
+  const sdk = new PolymarketSDK();
+
+  // ===== WalletService Demo =====
+  console.log('--- WalletService Demo ---\n');
+
+  // 1. Get top traders
+  console.log('1. Getting top traders...');
+  const topTraders = await sdk.wallets.getTopTraders(5);
+  console.log(`   Found ${topTraders.length} top traders\n`);
+
+  for (const trader of topTraders.slice(0, 3)) {
+    console.log(`   Rank #${trader.rank}: ${trader.address.slice(0, 10)}...`);
+    console.log(`   PnL: $${trader.pnl.toLocaleString()}`);
+    console.log(`   Volume: $${trader.volume.toLocaleString()}\n`);
+  }
+
+  // 2. Get wallet profile
+  if (topTraders.length > 0) {
+    console.log('2. Getting wallet profile for top trader...');
+    const profile = await sdk.wallets.getWalletProfile(topTraders[0].address);
+    console.log(`   Address: ${profile.address.slice(0, 10)}...`);
+    console.log(`   Total PnL: $${profile.totalPnL.toFixed(2)}`);
+    console.log(`   Smart Score: ${profile.smartScore}/100`);
+    console.log(`   Position Count: ${profile.positionCount}`);
+    console.log(`   Last Active: ${profile.lastActiveAt.toLocaleString()}\n`);
+  }
+
+  // 3. Discover active wallets
+  console.log('3. Discovering active wallets from recent trades...');
+  const activeWallets = await sdk.wallets.discoverActiveWallets(5);
+  console.log(`   Found ${activeWallets.length} active wallets:\n`);
+  for (const wallet of activeWallets) {
+    console.log(`   - ${wallet.address.slice(0, 10)}...: ${wallet.tradeCount} trades`);
+  }
+
+  // ===== MarketService Demo =====
+  console.log('\n--- MarketService Demo ---\n');
+
+  // 4. Get trending market
+  console.log('4. Getting trending market...');
+  const trendingMarkets = await sdk.markets.getTrendingMarkets(1);
+  if (trendingMarkets.length === 0) {
+    console.log('No trending markets found');
+    return;
+  }
+
+  const market = trendingMarkets[0];
+  console.log(`   Market: ${market.question.slice(0, 60)}...`);
+  console.log(`   Condition ID: ${market.conditionId}\n`);
+
+  // 5. Get unified market data
+  console.log('5. Getting unified market data...');
+  const unifiedMarket = await sdk.markets.getMarket(market.conditionId);
+  console.log(`   Source: ${unifiedMarket.source}`);
+  console.log(`   YES Price: ${unifiedMarket.tokens.yes.price}`);
+  console.log(`   NO Price: ${unifiedMarket.tokens.no.price}`);
+  console.log(`   Volume 24hr: $${unifiedMarket.volume24hr?.toLocaleString() || 'N/A'}\n`);
+
+  // 6. Get K-Lines
+  console.log('6. Getting K-Line data...');
+  const interval: KLineInterval = '1h';
+  const klines = await sdk.markets.getKLines(market.conditionId, interval, { limit: 100 });
+  console.log(`   Generated ${klines.length} candles (${interval} interval)\n`);
+
+  if (klines.length > 0) {
+    console.log('   Last 3 candles:');
+    for (const candle of klines.slice(-3)) {
+      const date = new Date(candle.timestamp).toLocaleString();
+      console.log(`   [${date}] O:${candle.open.toFixed(3)} H:${candle.high.toFixed(3)} L:${candle.low.toFixed(3)} C:${candle.close.toFixed(3)} V:$${candle.volume.toFixed(0)}`);
+    }
+  }
+
+  // 7. Get Dual K-Lines
+  console.log('\n7. Getting dual K-Lines (YES + NO)...');
+  const dualKlines = await sdk.markets.getDualKLines(market.conditionId, interval, { limit: 100 });
+  console.log(`   YES Candles: ${dualKlines.yes.length}`);
+  console.log(`   NO Candles: ${dualKlines.no.length}`);
+
+  if (dualKlines.spreadAnalysis && dualKlines.spreadAnalysis.length > 0) {
+    console.log('\n   Spread Analysis (last 3):');
+    for (const point of dualKlines.spreadAnalysis.slice(-3)) {
+      const date = new Date(point.timestamp).toLocaleString();
+      console.log(`   [${date}] YES:${point.yesPrice.toFixed(3)} + NO:${point.noPrice.toFixed(3)} = ${point.spread.toFixed(4)} ${point.arbOpportunity}`);
+    }
+  }
+
+  // 8. Detect market signals
+  console.log('\n8. Detecting market signals...');
+  const signals = await sdk.markets.detectMarketSignals(market.conditionId);
+  console.log(`   Found ${signals.length} signals:\n`);
+  for (const signal of signals.slice(0, 5)) {
+    console.log(`   - Type: ${signal.type}, Severity: ${signal.severity}`);
+  }
+
+  // 9. Check for arbitrage
+  console.log('\n9. Checking for arbitrage...');
+  const arb = await sdk.markets.detectArbitrage(market.conditionId, 0.001);
+  if (arb) {
+    console.log(`   Arbitrage found!`);
+    console.log(`   Type: ${arb.type}, Profit: ${(arb.profit * 100).toFixed(3)}%`);
+    console.log(`   Action: ${arb.action}`);
+  } else {
+    console.log('   No arbitrage opportunity found');
+  }
+
+  console.log('\n=== Done ===');
+}
+
+main().catch(console.error);

package/examples/07-realtime-websocket.ts

@@ -0,0 +1,117 @@
+/**
+ * Example 7: Real-time WebSocket
+ *
+ * This example demonstrates real-time price updates:
+ * - WebSocketManager for low-level access
+ * - RealtimeService for subscription management
+ *
+ * Run: npx tsx examples/07-realtime-websocket.ts
+ */
+
+import { PolymarketSDK } from '../src/index.js';
+import { WebSocketManager } from '../src/clients/websocket-manager.js';
+import { RealtimeService } from '../src/services/realtime-service.js';
+
+async function main() {
+  console.log('=== Real-time WebSocket Demo ===\n');
+
+  const sdk = new PolymarketSDK();
+
+  // 1. Get a trending market to subscribe to
+  console.log('1. Getting trending market...');
+  const trendingMarkets = await sdk.markets.getTrendingMarkets(1);
+  if (trendingMarkets.length === 0) {
+    console.log('No trending markets found');
+    return;
+  }
+
+  const market = trendingMarkets[0];
+  console.log(`   Market: ${market.question.slice(0, 60)}...`);
+  console.log(`   Condition ID: ${market.conditionId}\n`);
+
+  // 2. Get market details for token IDs
+  console.log('2. Getting market details...');
+  const unifiedMarket = await sdk.markets.getMarket(market.conditionId);
+  const yesTokenId = unifiedMarket.tokens.yes.tokenId;
+  const noTokenId = unifiedMarket.tokens.no.tokenId;
+  console.log(`   YES Token: ${yesTokenId.slice(0, 20)}...`);
+  console.log(`   NO Token: ${noTokenId.slice(0, 20)}...`);
+  console.log(`   Current YES Price: ${unifiedMarket.tokens.yes.price}`);
+  console.log(`   Current NO Price: ${unifiedMarket.tokens.no.price}\n`);
+
+  if (!yesTokenId || !noTokenId) {
+    console.log('No token IDs available for this market');
+    return;
+  }
+
+  // 3. Create RealtimeService and subscribe
+  console.log('3. Subscribing to real-time updates...');
+  const wsManager = new WebSocketManager({ enableLogging: true });
+  const realtime = new RealtimeService(wsManager);
+
+  let updateCount = 0;
+  const maxUpdates = 10;
+
+  const subscription = await realtime.subscribeMarket(yesTokenId, noTokenId, {
+    onPriceUpdate: (update) => {
+      updateCount++;
+      const side = update.assetId === yesTokenId ? 'YES' : 'NO';
+      console.log(`   [${new Date().toLocaleTimeString()}] ${side} Price: ${update.price.toFixed(4)} (mid: ${update.midpoint.toFixed(4)}, spread: ${update.spread.toFixed(4)})`);
+    },
+    onBookUpdate: (update) => {
+      const side = update.assetId === yesTokenId ? 'YES' : 'NO';
+      const bestBid = update.bids[0];
+      const bestAsk = update.asks[0];
+      console.log(`   [${new Date().toLocaleTimeString()}] ${side} Book: Bid ${bestBid?.price.toFixed(4)} (${bestBid?.size.toFixed(0)}) | Ask ${bestAsk?.price.toFixed(4)} (${bestAsk?.size.toFixed(0)})`);
+    },
+    onLastTrade: (trade) => {
+      const side = trade.assetId === yesTokenId ? 'YES' : 'NO';
+      console.log(`   [${new Date().toLocaleTimeString()}] ${side} Trade: ${trade.side} ${trade.size} @ ${trade.price.toFixed(4)}`);
+    },
+    onPairUpdate: (update) => {
+      const spread = update.spread;
+      const arbSignal = spread < 0.99 ? '🔴 ARB!' : spread > 1.01 ? '🔴 ARB!' : '✅';
+      console.log(`   [${new Date().toLocaleTimeString()}] PAIR: YES ${update.yes.price.toFixed(4)} + NO ${update.no.price.toFixed(4)} = ${spread.toFixed(4)} ${arbSignal}`);
+    },
+    onError: (error) => {
+      console.error(`   Error: ${error.message}`);
+    },
+  });
+
+  console.log(`   Subscription ID: ${subscription.id}`);
+  console.log(`   Subscribed to: ${subscription.assetIds.length} assets`);
+  console.log(`\n   Waiting for updates (max ${maxUpdates})...\n`);
+
+  // 4. Wait for some updates
+  await new Promise<void>((resolve) => {
+    const interval = setInterval(() => {
+      if (updateCount >= maxUpdates) {
+        clearInterval(interval);
+        resolve();
+      }
+    }, 500);
+
+    // Timeout after 30 seconds
+    setTimeout(() => {
+      clearInterval(interval);
+      resolve();
+    }, 30000);
+  });
+
+  // 5. Check cached prices
+  console.log('\n4. Cached prices:');
+  const prices = realtime.getAllPrices();
+  for (const [assetId, price] of prices) {
+    const side = assetId === yesTokenId ? 'YES' : 'NO';
+    console.log(`   ${side}: ${price.price.toFixed(4)}`);
+  }
+
+  // 6. Cleanup
+  console.log('\n5. Cleaning up...');
+  await subscription.unsubscribe();
+  console.log('   Unsubscribed');
+
+  console.log('\n=== Done ===');
+}
+
+main().catch(console.error);