@catalyst-team/poly-sdk 0.2.0 → 0.3.0

package/examples/01-basic-usage.ts

@@ -1,68 +0,0 @@
-/**
- * Example 1: Basic SDK Usage
- *
- * This example demonstrates:
- * - Getting trending markets from Gamma API
- * - Getting market details from unified API (Gamma + CLOB)
- * - Getting orderbook data
- *
- * Run: npx ts-node examples/01-basic-usage.ts
- */
-
-import { PolymarketSDK } from '../src/index.js';
-
-async function main() {
-  console.log('=== Polymarket SDK Basic Usage ===\n');
-
-  const sdk = new PolymarketSDK();
-
-  // 1. Get trending markets
-  console.log('1. Fetching trending markets...');
-  const trendingMarkets = await sdk.gammaApi.getTrendingMarkets(5);
-  console.log(`   Found ${trendingMarkets.length} trending markets:\n`);
-
-  for (const market of trendingMarkets) {
-    console.log(`   - ${market.question}`);
-    console.log(`     Slug: ${market.slug}`);
-    console.log(`     Volume: $${market.volume.toLocaleString()}`);
-    console.log(`     24h Volume: $${market.volume24hr?.toLocaleString() || 'N/A'}`);
-    console.log(`     Prices: Yes=${market.outcomePrices[0]?.toFixed(2)}, No=${market.outcomePrices[1]?.toFixed(2)}`);
-    console.log('');
-  }
-
-  // 2. Get unified market details (Gamma + CLOB merged)
-  if (trendingMarkets.length > 0) {
-    const firstMarket = trendingMarkets[0];
-    console.log(`2. Getting unified market details for: ${firstMarket.slug}`);
-    const unifiedMarket = await sdk.getMarket(firstMarket.slug);
-    console.log(`   Question: ${unifiedMarket.question}`);
-    console.log(`   Condition ID: ${unifiedMarket.conditionId}`);
-    console.log(`   YES Token ID: ${unifiedMarket.tokens.yes.tokenId}`);
-    console.log(`   NO Token ID: ${unifiedMarket.tokens.no.tokenId}`);
-    console.log(`   YES Price: ${unifiedMarket.tokens.yes.price.toFixed(4)}`);
-    console.log(`   NO Price: ${unifiedMarket.tokens.no.price.toFixed(4)}`);
-    console.log(`   Source: ${unifiedMarket.source}`);
-    console.log('');
-
-    // 3. Get orderbook
-    console.log('3. Getting orderbook...');
-    const orderbook = await sdk.getOrderbook(unifiedMarket.conditionId);
-    console.log(`   YES Best Bid: ${orderbook.yes.bid.toFixed(4)} (size: ${orderbook.yes.bidSize.toFixed(2)})`);
-    console.log(`   YES Best Ask: ${orderbook.yes.ask.toFixed(4)} (size: ${orderbook.yes.askSize.toFixed(2)})`);
-    console.log(`   YES Spread: ${(orderbook.yes.spread * 100).toFixed(2)}%`);
-    console.log('');
-    console.log(`   NO Best Bid: ${orderbook.no.bid.toFixed(4)} (size: ${orderbook.no.bidSize.toFixed(2)})`);
-    console.log(`   NO Best Ask: ${orderbook.no.ask.toFixed(4)} (size: ${orderbook.no.askSize.toFixed(2)})`);
-    console.log(`   NO Spread: ${(orderbook.no.spread * 100).toFixed(2)}%`);
-    console.log('');
-    console.log(`   Ask Sum (YES+NO): ${orderbook.summary.askSum.toFixed(4)}`);
-    console.log(`   Bid Sum (YES+NO): ${orderbook.summary.bidSum.toFixed(4)}`);
-    console.log(`   Long Arb Profit: ${(orderbook.summary.longArbProfit * 100).toFixed(3)}%`);
-    console.log(`   Short Arb Profit: ${(orderbook.summary.shortArbProfit * 100).toFixed(3)}%`);
-    console.log(`   Imbalance Ratio: ${orderbook.summary.imbalanceRatio.toFixed(2)}`);
-  }
-
-  console.log('\n=== Done ===');
-}
-
-main().catch(console.error);

package/examples/02-smart-money.ts

@@ -1,95 +0,0 @@
-/**
- * Example 2: Smart Money Analysis
- *
- * This example demonstrates:
- * - Getting wallet positions
- * - Getting wallet activity (trades)
- * - Getting leaderboard data
- * - Discovering active wallets from recent trades
- *
- * Run: npx ts-node examples/02-smart-money.ts
- */
-
-import { PolymarketSDK } from '../src/index.js';
-
-async function main() {
-  console.log('=== Smart Money Analysis ===\n');
-
-  const sdk = new PolymarketSDK();
-
-  // 1. Get leaderboard
-  console.log('1. Fetching leaderboard (top 10)...');
-  const leaderboard = await sdk.dataApi.getLeaderboard({ limit: 10 });
-  console.log(`   Total entries: ${leaderboard.total}`);
-  console.log('   Top 10 traders:\n');
-
-  for (const entry of leaderboard.entries.slice(0, 10)) {
-    console.log(`   #${entry.rank} ${entry.address.slice(0, 8)}...${entry.address.slice(-6)}`);
-    console.log(`       PnL: $${entry.pnl.toLocaleString()}`);
-    console.log(`       Volume: $${entry.volume.toLocaleString()}`);
-    console.log(`       Positions: ${entry.positions}, Trades: ${entry.trades}`);
-  }
-
-  // 2. Get wallet positions for top trader
-  if (leaderboard.entries.length > 0) {
-    const topTrader = leaderboard.entries[0].address;
-    console.log(`\n2. Getting positions for top trader: ${topTrader.slice(0, 8)}...`);
-
-    const positions = await sdk.dataApi.getPositions(topTrader);
-    console.log(`   Found ${positions.length} positions:\n`);
-
-    for (const pos of positions.slice(0, 5)) {
-      console.log(`   - ${pos.title || 'Unknown Market'}`);
-      console.log(`     Outcome: ${pos.outcome}`);
-      console.log(`     Size: ${pos.size.toFixed(2)}`);
-      console.log(`     Avg Price: ${pos.avgPrice.toFixed(4)}`);
-      console.log(`     Current Price: ${pos.curPrice?.toFixed(4) || 'N/A'}`);
-      console.log(`     PnL: $${pos.cashPnl?.toFixed(2) || 'N/A'} (${pos.percentPnl?.toFixed(1) || 'N/A'}%)`);
-      console.log('');
-    }
-
-    // 3. Get recent activity for top trader
-    console.log(`3. Getting recent activity for top trader...`);
-    const activity = await sdk.dataApi.getActivity(topTrader, { limit: 10 });
-    console.log(`   Found ${activity.length} recent activities:\n`);
-
-    for (const act of activity.slice(0, 5)) {
-      const date = new Date(act.timestamp).toLocaleString();
-      console.log(`   - [${date}] ${act.type} ${act.side}`);
-      console.log(`     Size: ${act.size.toFixed(2)} @ ${act.price.toFixed(4)}`);
-      console.log(`     Value: $${(act.usdcSize || 0).toFixed(2)}`);
-      console.log(`     Outcome: ${act.outcome}`);
-      console.log('');
-    }
-  }
-
-  // 4. Discover active wallets from recent trades
-  console.log('4. Discovering active wallets from recent trades...');
-  const recentTrades = await sdk.dataApi.getTrades({ limit: 100 });
-  console.log(`   Fetched ${recentTrades.length} recent trades`);
-
-  // Count trades per wallet
-  const walletCounts = new Map<string, number>();
-  for (const trade of recentTrades) {
-    if (trade.proxyWallet) {
-      walletCounts.set(
-        trade.proxyWallet,
-        (walletCounts.get(trade.proxyWallet) || 0) + 1
-      );
-    }
-  }
-
-  // Sort by count
-  const sortedWallets = [...walletCounts.entries()]
-    .sort((a, b) => b[1] - a[1])
-    .slice(0, 5);
-
-  console.log('   Most active wallets in recent trades:\n');
-  for (const [wallet, count] of sortedWallets) {
-    console.log(`   - ${wallet.slice(0, 8)}...${wallet.slice(-6)}: ${count} trades`);
-  }
-
-  console.log('\n=== Done ===');
-}
-
-main().catch(console.error);

package/examples/03-market-analysis.ts

@@ -1,108 +0,0 @@
-/**
- * Example 3: Market Analysis & Arbitrage Detection
- *
- * This example demonstrates:
- * - Getting multiple markets' orderbooks
- * - Detecting arbitrage opportunities
- * - Analyzing market depth and imbalance
- *
- * Run: npx ts-node examples/03-market-analysis.ts
- */
-
-import { PolymarketSDK } from '../src/index.js';
-
-async function main() {
-  console.log('=== Market Analysis & Arbitrage Detection ===\n');
-
-  const sdk = new PolymarketSDK();
-
-  // 1. Get trending markets for analysis
-  console.log('1. Fetching trending markets...');
-  const markets = await sdk.gammaApi.getTrendingMarkets(10);
-  console.log(`   Found ${markets.length} trending markets\n`);
-
-  // 2. Analyze each market for arbitrage
-  console.log('2. Analyzing markets for arbitrage opportunities...\n');
-
-  const arbitrageOpportunities = [];
-
-  for (const market of markets) {
-    try {
-      console.log(`   Checking: ${market.question.slice(0, 60)}...`);
-
-      // Get unified market for token IDs
-      const unifiedMarket = await sdk.getMarket(market.conditionId);
-
-      if (!unifiedMarket.tokens.yes.tokenId || !unifiedMarket.tokens.no.tokenId) {
-        console.log('     Skipping (missing token IDs)\n');
-        continue;
-      }
-
-      // Get orderbook
-      const orderbook = await sdk.getOrderbook(market.conditionId);
-
-      // Check for arbitrage
-      const arb = await sdk.detectArbitrage(market.conditionId, 0.001); // 0.1% threshold
-
-      if (arb) {
-        console.log(`     ** ARBITRAGE FOUND **`);
-        console.log(`     Type: ${arb.type}`);
-        console.log(`     Profit: ${(arb.profit * 100).toFixed(3)}%`);
-        console.log(`     Action: ${arb.action}`);
-        arbitrageOpportunities.push({
-          market: market.question,
-          slug: market.slug,
-          ...arb,
-        });
-      } else {
-        console.log(`     No arbitrage (ask sum: ${orderbook.summary.askSum.toFixed(4)}, bid sum: ${orderbook.summary.bidSum.toFixed(4)})`);
-      }
-      console.log('');
-
-    } catch (error) {
-      console.log(`     Error: ${(error as Error).message}\n`);
-    }
-  }
-
-  // 3. Summary
-  console.log('=== Summary ===\n');
-
-  if (arbitrageOpportunities.length > 0) {
-    console.log(`Found ${arbitrageOpportunities.length} arbitrage opportunities:\n`);
-    for (const opp of arbitrageOpportunities) {
-      console.log(`- ${opp.market.slice(0, 60)}...`);
-      console.log(`  Slug: ${opp.slug}`);
-      console.log(`  Type: ${opp.type}, Profit: ${(opp.profit * 100).toFixed(3)}%`);
-      console.log('');
-    }
-  } else {
-    console.log('No arbitrage opportunities found (this is normal in efficient markets)');
-  }
-
-  // 4. Analyze market depth
-  console.log('\n=== Market Depth Analysis ===\n');
-
-  for (const market of markets.slice(0, 3)) {
-    try {
-      const orderbook = await sdk.getOrderbook(market.conditionId);
-
-      console.log(`Market: ${market.question.slice(0, 50)}...`);
-      console.log(`  Total Bid Depth: $${orderbook.summary.totalBidDepth.toFixed(2)}`);
-      console.log(`  Total Ask Depth: $${orderbook.summary.totalAskDepth.toFixed(2)}`);
-      console.log(`  Imbalance Ratio: ${orderbook.summary.imbalanceRatio.toFixed(2)}`);
-
-      if (orderbook.summary.imbalanceRatio > 1.5) {
-        console.log(`  ** HIGH BUY PRESSURE (ratio > 1.5) **`);
-      } else if (orderbook.summary.imbalanceRatio < 0.67) {
-        console.log(`  ** HIGH SELL PRESSURE (ratio < 0.67) **`);
-      }
-      console.log('');
-    } catch {
-      // Skip errors
-    }
-  }
-
-  console.log('=== Done ===');
-}
-
-main().catch(console.error);

package/examples/04-kline-aggregation.ts

@@ -1,158 +0,0 @@
-/**
- * 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

@@ -1,156 +0,0 @@
-/**
- * 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);