Trade History - Complete API Reference

Fetch, sync, and analyze trade history from Polymarket and Kalshi with detailed performance metrics.

Chat Commands

Fetch & Sync

/history fetch # Fetch all trades from APIs /history fetch poly # Fetch Polymarket only /history fetch --from 2024-01-01 # From specific date /history sync # Sync to local database

View History

/history list # Recent trades /history list --limit 50 # Last 50 trades /history list --platform poly # Polymarket only /history list --market <id> # Specific market

Statistics

/history stats # Overall statistics /history stats --period 30d # Last 30 days /history stats --platform kalshi # Platform-specific

P&L Analysis

/history daily-pnl # Daily P&L /history weekly-pnl # Weekly P&L /history monthly-pnl # Monthly P&L /history by-market # P&L by market category

Export

/history export # Export to CSV /history export --format json # Export as JSON /history export --from 2024-01-01 # Date range

Filtering

/history filter --side buy # Only buys /history filter --pnl positive # Only winners /history filter --pnl negative # Only losers /history filter --min-size 100 # Min $100 trades

TypeScript API Reference

Create History Service

import { createTradeHistoryService } from 'clodds/history';

const history = createTradeHistoryService({ polymarket: { apiKey: process.env.POLY_API_KEY, address: process.env.POLY_ADDRESS, }, kalshi: { apiKey: process.env.KALSHI_API_KEY, },

// Local storage dbPath: './trade-history.db', });

Fetch Trades from APIs

// Fetch all trades from exchange APIs const trades = await history.fetchTrades({ platforms: ['polymarket', 'kalshi'], from: '2024-01-01', });

console.log(Fetched ${trades.length} trades);

// Fetch from specific platform const polyTrades = await history.fetchTrades({ platforms: ['polymarket'], limit: 100, });

Sync to Database

// Sync fetched trades to local database await history.syncToDatabase();

console.log('Trades synced to database');

Get Trades

// Get trades from local storage const trades = await history.getTrades({ platform: 'polymarket', from: '2024-01-01', to: '2024-12-31', limit: 100, });

for (const trade of trades) { console.log(${trade.timestamp}: ${trade.side} ${trade.market}); console.log( Size: $${trade.size}); console.log( Price: ${trade.price}); console.log( P&L: $${trade.pnl?.toFixed(2) || 'open'}); }

Statistics

// Get comprehensive statistics const stats = await history.getStats({ period: '30d', platform: 'polymarket', });

console.log(=== Trading Statistics (30d) ===); console.log(Total trades: ${stats.totalTrades}); console.log(Winning trades: ${stats.winningTrades}); console.log(Losing trades: ${stats.losingTrades}); console.log(Win rate: ${(stats.winRate * 100).toFixed(1)}%); console.log(\nP&L:); console.log( Total: $${stats.totalPnl.toLocaleString()}); console.log( Gross profit: $${stats.grossProfit.toLocaleString()}); console.log( Gross loss: $${stats.grossLoss.toLocaleString()}); console.log( Profit factor: ${stats.profitFactor.toFixed(2)}); console.log(\nTrade sizes:); console.log( Average: $${stats.avgTradeSize.toFixed(2)}); console.log( Largest win: $${stats.largestWin.toFixed(2)}); console.log( Largest loss: $${stats.largestLoss.toFixed(2)}); console.log(\nRisk metrics:); console.log( Sharpe ratio: ${stats.sharpeRatio.toFixed(2)}); console.log( Max drawdown: ${(stats.maxDrawdown * 100).toFixed(1)}%);

Daily P&L

// Get daily P&L breakdown const dailyPnl = await history.getDailyPnL({ days: 30, platform: 'polymarket', });

console.log('=== Daily P&L ==='); for (const day of dailyPnl) { const sign = day.pnl >= 0 ? '+' : ''; const bar = day.pnl >= 0 ? '█'.repeat(Math.min(Math.floor(day.pnl / 10), 20)) : '▓'.repeat(Math.min(Math.floor(Math.abs(day.pnl) / 10), 20));

console.log(${day.date} | ${sign}$${day.pnl.toFixed(2).padStart(8)} | ${bar}); }

Performance by Market

// Get performance breakdown by market category const byMarket = await history.getPerformanceByMarket({ period: '30d', });

console.log('=== Performance by Market Category ==='); for (const [category, data] of Object.entries(byMarket)) { console.log(\n${category}:); console.log( Trades: ${data.trades}); console.log( Win rate: ${(data.winRate * 100).toFixed(1)}%); console.log( P&L: $${data.pnl.toLocaleString()}); console.log( Avg trade: $${data.avgTrade.toFixed(2)}); }

Export

// Export to CSV await history.exportCsv({ path: './trades.csv', from: '2024-01-01', to: '2024-12-31', columns: ['timestamp', 'platform', 'market', 'side', 'size', 'price', 'pnl'], });

// Export to JSON const json = await history.exportJson({ from: '2024-01-01', });

Database Schema

CREATE TABLE trades ( id TEXT PRIMARY KEY, platform TEXT NOT NULL, market_id TEXT NOT NULL, market_question TEXT, side TEXT NOT NULL, -- 'buy' or 'sell' outcome TEXT, -- 'YES' or 'NO' size REAL NOT NULL, price REAL NOT NULL, fee REAL DEFAULT 0, pnl REAL, timestamp INTEGER NOT NULL, created_at INTEGER DEFAULT (strftime('%s', 'now')) );

CREATE INDEX idx_trades_platform ON trades(platform); CREATE INDEX idx_trades_timestamp ON trades(timestamp); CREATE INDEX idx_trades_market ON trades(market_id);

Best Practices

• Sync regularly - Keep local database up to date

• Export backups - Periodically export to CSV

• Review weekly - Analyze performance patterns

• Track by category - Identify strong/weak areas

• Monitor drawdown - Set alerts for max drawdown