@gaberoo/kalshitools 1.0.3 → 1.1.0

package/dist/lib/analytics.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Portfolio analytics calculation utilities
+ */
+import type { Fill, Position } from './kalshi/types.js';
+/**
+ * Calculate win rate from a set of fills
+ * Matches buys and sells for the same ticker to determine wins/losses
+ */
+export declare function calculateWinRate(fills: Fill[]): number;
+/**
+ * Calculate average P&L for winning and losing trades
+ */
+export declare function calculateAveragePnL(fills: Fill[]): {
+    avgLoss: number;
+    avgWin: number;
+};
+/**
+ * Calculate portfolio concentration by ticker
+ * Returns map of ticker to percentage of portfolio value
+ */
+export declare function calculatePortfolioConcentration(positions: Position[], portfolioValue: number): Map<string, number>;
+/**
+ * Calculate exposure ratio (total market exposure / portfolio value)
+ */
+export declare function calculateExposureRatio(positions: Position[], portfolioValue: number): number;
+/**
+ * Group fills by time period (day, week, or month)
+ */
+export declare function groupFillsByPeriod(fills: Fill[], period: 'day' | 'month' | 'week'): Map<string, Fill[]>;
+/**
+ * Estimate total P&L from fills by matching buys and sells
+ * Note: This is an estimate based on fills alone, actual P&L should come from positions
+ */
+export declare function estimatePnLFromFills(fills: Fill[]): number;
+/**
+ * Calculate total fees paid from fills
+ * Fees are calculated based on whether the fill was a maker or taker
+ */
+export declare function calculateTotalFees(fills: Fill[]): number;
+/**
+ * Group fills by ticker and calculate statistics
+ */
+export declare function groupFillsByTicker(fills: Fill[]): Map<string, {
+    buyVolume: number;
+    count: number;
+    estimatedPnL: number;
+    sellVolume: number;
+    volume: number;
+}>;
+/**
+ * Calculate maker vs taker statistics
+ */
+export declare function calculateMakerTakerStats(fills: Fill[]): {
+    maker: {
+        avgFeePct: number;
+        fills: number;
+        volume: number;
+    };
+    taker: {
+        avgFeePct: number;
+        fills: number;
+        volume: number;
+    };
+};

package/dist/lib/analytics.js

@@ -0,0 +1,236 @@
+/**
+ * Portfolio analytics calculation utilities
+ */
+/**
+ * Calculate win rate from a set of fills
+ * Matches buys and sells for the same ticker to determine wins/losses
+ */
+export function calculateWinRate(fills) {
+    if (fills.length === 0)
+        return 0;
+    // Group fills by ticker
+    const fillsByTicker = new Map();
+    for (const fill of fills) {
+        const existing = fillsByTicker.get(fill.ticker) || [];
+        existing.push(fill);
+        fillsByTicker.set(fill.ticker, existing);
+    }
+    let winningTrades = 0;
+    let losingTrades = 0;
+    // For each ticker, match buys and sells to calculate P&L
+    for (const [, tickerFills] of fillsByTicker) {
+        const sorted = tickerFills.sort((a, b) => new Date(a.created_time).getTime() - new Date(b.created_time).getTime());
+        let position = 0;
+        let totalCost = 0;
+        for (const fill of sorted) {
+            const quantity = fill.action === 'buy' ? fill.count : -fill.count;
+            const cost = fill.action === 'buy' ? fill.count * fill.price : -fill.count * fill.price;
+            if (fill.action === 'sell' && position > 0) {
+                // Closing a position - calculate P&L
+                const avgEntryPrice = totalCost / position;
+                const sellPrice = fill.price;
+                const pnl = (sellPrice - avgEntryPrice) * fill.count;
+                if (pnl > 0)
+                    winningTrades++;
+                else if (pnl < 0)
+                    losingTrades++;
+            }
+            position += quantity;
+            totalCost += cost;
+        }
+    }
+    const totalTrades = winningTrades + losingTrades;
+    return totalTrades > 0 ? winningTrades / totalTrades : 0;
+}
+/**
+ * Calculate average P&L for winning and losing trades
+ */
+export function calculateAveragePnL(fills) {
+    if (fills.length === 0)
+        return { avgLoss: 0, avgWin: 0 };
+    // Group fills by ticker
+    const fillsByTicker = new Map();
+    for (const fill of fills) {
+        const existing = fillsByTicker.get(fill.ticker) || [];
+        existing.push(fill);
+        fillsByTicker.set(fill.ticker, existing);
+    }
+    const wins = [];
+    const losses = [];
+    // For each ticker, match buys and sells to calculate P&L
+    for (const [, tickerFills] of fillsByTicker) {
+        const sorted = tickerFills.sort((a, b) => new Date(a.created_time).getTime() - new Date(b.created_time).getTime());
+        let position = 0;
+        let totalCost = 0;
+        for (const fill of sorted) {
+            const quantity = fill.action === 'buy' ? fill.count : -fill.count;
+            const cost = fill.action === 'buy' ? fill.count * fill.price : -fill.count * fill.price;
+            if (fill.action === 'sell' && position > 0) {
+                // Closing a position - calculate P&L
+                const avgEntryPrice = totalCost / position;
+                const sellPrice = fill.price;
+                const pnl = (sellPrice - avgEntryPrice) * fill.count;
+                if (pnl > 0)
+                    wins.push(pnl);
+                else if (pnl < 0)
+                    losses.push(pnl);
+            }
+            position += quantity;
+            totalCost += cost;
+        }
+    }
+    const avgWin = wins.length > 0 ? wins.reduce((sum, w) => sum + w, 0) / wins.length : 0;
+    const avgLoss = losses.length > 0 ? losses.reduce((sum, l) => sum + l, 0) / losses.length : 0;
+    return { avgLoss, avgWin };
+}
+/**
+ * Calculate portfolio concentration by ticker
+ * Returns map of ticker to percentage of portfolio value
+ */
+export function calculatePortfolioConcentration(positions, portfolioValue) {
+    const concentration = new Map();
+    if (portfolioValue <= 0)
+        return concentration;
+    for (const position of positions) {
+        const percentage = (position.market_exposure / portfolioValue) * 100;
+        concentration.set(position.ticker, percentage);
+    }
+    return concentration;
+}
+/**
+ * Calculate exposure ratio (total market exposure / portfolio value)
+ */
+export function calculateExposureRatio(positions, portfolioValue) {
+    if (portfolioValue <= 0)
+        return 0;
+    const totalExposure = positions.reduce((sum, pos) => sum + pos.market_exposure, 0);
+    return totalExposure / portfolioValue;
+}
+/**
+ * Group fills by time period (day, week, or month)
+ */
+export function groupFillsByPeriod(fills, period) {
+    const grouped = new Map();
+    for (const fill of fills) {
+        const date = new Date(fill.created_time);
+        let key;
+        if (period === 'day') {
+            key = date.toISOString().split('T')[0]; // YYYY-MM-DD
+        }
+        else if (period === 'week') {
+            // Get ISO week number
+            const onejan = new Date(date.getFullYear(), 0, 1);
+            const weekNumber = Math.ceil((((date.getTime() - onejan.getTime()) / 86_400_000) + onejan.getDay() + 1) / 7);
+            key = `${date.getFullYear()}-W${weekNumber.toString().padStart(2, '0')}`;
+        }
+        else {
+            // month
+            key = `${date.getFullYear()}-${(date.getMonth() + 1).toString().padStart(2, '0')}`;
+        }
+        const existing = grouped.get(key) || [];
+        existing.push(fill);
+        grouped.set(key, existing);
+    }
+    return grouped;
+}
+/**
+ * Estimate total P&L from fills by matching buys and sells
+ * Note: This is an estimate based on fills alone, actual P&L should come from positions
+ */
+export function estimatePnLFromFills(fills) {
+    // Group fills by ticker
+    const fillsByTicker = new Map();
+    for (const fill of fills) {
+        const existing = fillsByTicker.get(fill.ticker) || [];
+        existing.push(fill);
+        fillsByTicker.set(fill.ticker, existing);
+    }
+    let totalPnL = 0;
+    // For each ticker, match buys and sells to calculate P&L
+    for (const [, tickerFills] of fillsByTicker) {
+        const sorted = tickerFills.sort((a, b) => new Date(a.created_time).getTime() - new Date(b.created_time).getTime());
+        let position = 0;
+        let totalCost = 0;
+        for (const fill of sorted) {
+            const quantity = fill.action === 'buy' ? fill.count : -fill.count;
+            const cost = fill.action === 'buy' ? fill.count * fill.price : -fill.count * fill.price;
+            if (fill.action === 'sell' && position > 0) {
+                // Closing a position - calculate P&L
+                const avgEntryPrice = totalCost / position;
+                const sellPrice = fill.price;
+                const pnl = (sellPrice - avgEntryPrice) * fill.count;
+                totalPnL += pnl;
+            }
+            position += quantity;
+            totalCost += cost;
+        }
+    }
+    return totalPnL;
+}
+/**
+ * Calculate total fees paid from fills
+ * Fees are calculated based on whether the fill was a maker or taker
+ */
+export function calculateTotalFees(fills) {
+    // Kalshi fee structure (approximate):
+    // Maker: 0.5% (0.005)
+    // Taker: 1.5% (0.015)
+    const MAKER_FEE = 0.005;
+    const TAKER_FEE = 0.015;
+    let totalFees = 0;
+    for (const fill of fills) {
+        const notionalValue = fill.count * fill.price;
+        const feeRate = fill.is_taker ? TAKER_FEE : MAKER_FEE;
+        totalFees += notionalValue * feeRate;
+    }
+    return totalFees;
+}
+/**
+ * Group fills by ticker and calculate statistics
+ */
+export function groupFillsByTicker(fills) {
+    const grouped = new Map();
+    const fillsByTicker = new Map();
+    for (const fill of fills) {
+        const existing = fillsByTicker.get(fill.ticker) || [];
+        existing.push(fill);
+        fillsByTicker.set(fill.ticker, existing);
+    }
+    for (const [ticker, tickerFills] of fillsByTicker) {
+        const volume = tickerFills.reduce((sum, f) => sum + f.count * f.price, 0);
+        const buyVolume = tickerFills.filter(f => f.action === 'buy').reduce((sum, f) => sum + f.count * f.price, 0);
+        const sellVolume = tickerFills.filter(f => f.action === 'sell').reduce((sum, f) => sum + f.count * f.price, 0);
+        const estimatedPnL = estimatePnLFromFills(tickerFills);
+        grouped.set(ticker, {
+            buyVolume,
+            count: tickerFills.length,
+            estimatedPnL,
+            sellVolume,
+            volume,
+        });
+    }
+    return grouped;
+}
+/**
+ * Calculate maker vs taker statistics
+ */
+export function calculateMakerTakerStats(fills) {
+    const MAKER_FEE = 0.005;
+    const TAKER_FEE = 0.015;
+    const makerFills = fills.filter(f => !f.is_taker);
+    const takerFills = fills.filter(f => f.is_taker);
+    const makerVolume = makerFills.reduce((sum, f) => sum + f.count * f.price, 0);
+    const takerVolume = takerFills.reduce((sum, f) => sum + f.count * f.price, 0);
+    return {
+        maker: {
+            avgFeePct: MAKER_FEE,
+            fills: makerFills.length,
+            volume: makerVolume,
+        },
+        taker: {
+            avgFeePct: TAKER_FEE,
+            fills: takerFills.length,
+            volume: takerVolume,
+        },
+    };
+}

package/dist/lib/risk.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Risk management calculation utilities
+ */
+import type { Market, Position } from './kalshi/types.js';
+export type RiskLevel = 'HIGH' | 'LOW' | 'MEDIUM';
+/**
+ * Calculate risk score for a single position (0-100)
+ * Higher score = higher risk
+ */
+export declare function calculatePositionRiskScore(position: Position, portfolioValue: number, threshold: number): number;
+/**
+ * Detect correlated positions by grouping them by event or series
+ * Returns map of event/series ticker to positions and total exposure
+ */
+export declare function detectCorrelatedPositions(positions: Position[], markets: Market[]): Map<string, {
+    exposure: number;
+    markets: string[];
+}>;
+/**
+ * Suggest maximum safe position size based on portfolio value and risk tolerance
+ */
+export declare function suggestMaxPositionSize(balance: number, portfolioValue: number, maxPct: number): number;
+/**
+ * Group positions by event, series, or ticker
+ */
+export declare function groupPositionsBy(positions: Position[], markets: Market[], groupBy: 'event' | 'series' | 'ticker'): Map<string, {
+    positions: Position[];
+    totalExposure: number;
+}>;
+/**
+ * Calculate overall portfolio risk score (0-100) and categorize risk level
+ */
+export declare function calculatePortfolioRiskScore(positions: Position[], portfolioValue: number): {
+    level: RiskLevel;
+    score: number;
+};
+/**
+ * Identify positions that exceed a risk threshold
+ */
+export declare function identifyHighRiskPositions(positions: Position[], portfolioValue: number, threshold: number): Position[];
+/**
+ * Calculate concentration by grouping
+ * Returns sorted array of concentrations
+ */
+export declare function calculateConcentrationByGroup(positions: Position[], markets: Market[], portfolioValue: number, groupBy: 'event' | 'series' | 'ticker', threshold: number): Array<{
+    alert: boolean;
+    exposure: number;
+    markets?: string[];
+    name: string;
+    pct_of_portfolio: number;
+}>;

package/dist/lib/risk.js

@@ -0,0 +1,153 @@
+/**
+ * Risk management calculation utilities
+ */
+/**
+ * Calculate risk score for a single position (0-100)
+ * Higher score = higher risk
+ */
+export function calculatePositionRiskScore(position, portfolioValue, threshold) {
+    if (portfolioValue <= 0)
+        return 0;
+    const concentrationPct = (position.market_exposure / portfolioValue) * 100;
+    // Risk increases exponentially as concentration approaches/exceeds threshold
+    let score = (concentrationPct / threshold) * 50;
+    // Additional risk if position is unrealized loss
+    if (position.realized_pnl < 0) {
+        const lossRatio = Math.abs(position.realized_pnl) / position.total_cost;
+        score += lossRatio * 25;
+    }
+    return Math.min(100, Math.max(0, score));
+}
+/**
+ * Detect correlated positions by grouping them by event or series
+ * Returns map of event/series ticker to positions and total exposure
+ */
+export function detectCorrelatedPositions(positions, markets) {
+    const correlations = new Map();
+    // Create a map of ticker to market for quick lookup
+    const marketMap = new Map(markets.map(m => [m.ticker, m]));
+    // Group positions by event ticker
+    for (const position of positions) {
+        const market = marketMap.get(position.ticker);
+        if (!market)
+            continue;
+        const eventTicker = market.event_ticker;
+        const existing = correlations.get(eventTicker) || { exposure: 0, markets: [] };
+        existing.markets.push(position.ticker);
+        existing.exposure += position.market_exposure;
+        correlations.set(eventTicker, existing);
+    }
+    // Filter to only events with multiple positions
+    const filtered = new Map();
+    for (const [eventTicker, data] of correlations) {
+        if (data.markets.length > 1) {
+            filtered.set(eventTicker, data);
+        }
+    }
+    return filtered;
+}
+/**
+ * Suggest maximum safe position size based on portfolio value and risk tolerance
+ */
+export function suggestMaxPositionSize(balance, portfolioValue, maxPct) {
+    if (portfolioValue <= 0)
+        return balance;
+    return (portfolioValue * maxPct) / 100;
+}
+/**
+ * Group positions by event, series, or ticker
+ */
+export function groupPositionsBy(positions, markets, groupBy) {
+    const grouped = new Map();
+    // Create a map of ticker to market for quick lookup
+    const marketMap = new Map(markets.map(m => [m.ticker, m]));
+    for (const position of positions) {
+        let key;
+        if (groupBy === 'ticker') {
+            key = position.ticker;
+        }
+        else {
+            const market = marketMap.get(position.ticker);
+            if (!market)
+                continue;
+            key = groupBy === 'event' ? market.event_ticker : market.event_ticker;
+            // series - extract from event ticker (format: SERIES-SPECIFIC or just use event_ticker)
+            // For now, use event_ticker as series identifier
+        }
+        const existing = grouped.get(key) || { positions: [], totalExposure: 0 };
+        existing.positions.push(position);
+        existing.totalExposure += position.market_exposure;
+        grouped.set(key, existing);
+    }
+    return grouped;
+}
+/**
+ * Calculate overall portfolio risk score (0-100) and categorize risk level
+ */
+export function calculatePortfolioRiskScore(positions, portfolioValue) {
+    if (positions.length === 0 || portfolioValue <= 0) {
+        return { level: 'LOW', score: 0 };
+    }
+    // Calculate exposure ratio
+    const totalExposure = positions.reduce((sum, pos) => sum + pos.market_exposure, 0);
+    const exposureRatio = totalExposure / portfolioValue;
+    // Calculate concentration (largest position as % of portfolio)
+    const largestExposure = Math.max(...positions.map(pos => pos.market_exposure));
+    const largestConcentration = (largestExposure / portfolioValue) * 100;
+    // Calculate unrealized loss ratio
+    const totalUnrealizedLoss = positions
+        .filter(pos => pos.realized_pnl < 0)
+        .reduce((sum, pos) => sum + Math.abs(pos.realized_pnl), 0);
+    const lossRatio = totalExposure > 0 ? totalUnrealizedLoss / totalExposure : 0;
+    // Weighted risk score
+    let score = 0;
+    // Exposure contributes up to 40 points (0.5 exposure = 20 points, 1.0 = 40 points)
+    score += Math.min(40, exposureRatio * 40);
+    // Concentration contributes up to 30 points (20% = 15 points, 40% = 30 points)
+    score += Math.min(30, (largestConcentration / 40) * 30);
+    // Loss ratio contributes up to 30 points
+    score += Math.min(30, lossRatio * 100 * 0.3);
+    // Categorize risk level
+    let level;
+    if (score < 30)
+        level = 'LOW';
+    else if (score < 60)
+        level = 'MEDIUM';
+    else
+        level = 'HIGH';
+    return { level, score: Math.round(score) };
+}
+/**
+ * Identify positions that exceed a risk threshold
+ */
+export function identifyHighRiskPositions(positions, portfolioValue, threshold) {
+    if (portfolioValue <= 0)
+        return [];
+    return positions.filter(pos => {
+        const concentrationPct = (pos.market_exposure / portfolioValue) * 100;
+        return concentrationPct > threshold;
+    });
+}
+/**
+ * Calculate concentration by grouping
+ * Returns sorted array of concentrations
+ */
+// eslint-disable-next-line max-params
+export function calculateConcentrationByGroup(positions, markets, portfolioValue, groupBy, threshold) {
+    if (portfolioValue <= 0)
+        return [];
+    const grouped = groupPositionsBy(positions, markets, groupBy);
+    const concentrations = [];
+    for (const [name, data] of grouped) {
+        const pctOfPortfolio = (data.totalExposure / portfolioValue) * 100;
+        concentrations.push({
+            alert: pctOfPortfolio > threshold,
+            exposure: data.totalExposure,
+            markets: groupBy === 'ticker' ? undefined : data.positions.map(p => p.ticker),
+            name,
+            pct_of_portfolio: pctOfPortfolio,
+        });
+    }
+    // Sort by exposure descending
+    return concentrations.sort((a, b) => b.exposure - a.exposure);
+}

package/dist/lib/scanner.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Market scanning and opportunity detection utilities
+ */
+import type { Market, OrderBook } from './kalshi/types.js';
+export type OpportunityType = 'balanced' | 'high_liquidity' | 'high_volume' | 'wide_spread';
+/**
+ * Calculate total liquidity from an orderbook
+ */
+export declare function calculateOrderbookLiquidity(orderbook: OrderBook): {
+    noTotal: number;
+    total: number;
+    yesTotal: number;
+};
+/**
+ * Calculate bid-ask spread from an orderbook
+ *
+ * In Kalshi orderbooks:
+ * - Lower prices in the yes array are bids (buyers)
+ * - Higher prices in the yes array are asks (sellers)
+ * - Spread = ask - bid
+ */
+export declare function calculateSpread(orderbook: OrderBook): null | {
+    spreadCents: number;
+    spreadPct: number;
+    yesAsk: number;
+    yesBid: number;
+};
+/**
+ * Score a market based on liquidity, spread, and volume
+ * Returns score from 0-100
+ */
+export declare function scoreMarket(market: Market, orderbook: OrderBook, weights?: {
+    liquidity: number;
+    spread: number;
+    volume: number;
+}): number;
+/**
+ * Classify the type of opportunity a market presents
+ */
+export declare function classifyOpportunity(spread: number, liquidity: number, volume: number): OpportunityType;
+/**
+ * Generate human-readable reason for opportunity
+ */
+export declare function generateOpportunityReason(type: OpportunityType, spread: number, liquidity: number, volume: number): string;
+/**
+ * Filter markets based on criteria
+ */
+export declare function filterMarketsByCriteria<T extends {
+    liquidity: number;
+    market: Market;
+    spread: null | number;
+    volume: number;
+}>(markets: T[], criteria: {
+    maxSpread?: number;
+    minLiquidity?: number;
+    minSpread?: number;
+    minVolume?: number;
+}): T[];