@gaberoo/kalshitools 1.0.2 → 1.1.0

package/dist/commands/portfolio/risk.js

@@ -0,0 +1,206 @@
+import { Flags } from '@oclif/core';
+import chalk from 'chalk';
+import { BaseCommand } from '../../lib/base-command.js';
+import { createClientFromConfig } from '../../lib/kalshi/index.js';
+import { logger } from '../../lib/logger.js';
+import { calculateConcentrationByGroup, calculatePortfolioRiskScore, detectCorrelatedPositions, identifyHighRiskPositions, suggestMaxPositionSize, } from '../../lib/risk.js';
+export default class PortfolioRisk extends BaseCommand {
+    static description = 'Real-time portfolio risk analysis and warnings';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+        '<%= config.bin %> <%= command.id %> --threshold 15',
+        '<%= config.bin %> <%= command.id %> --group-by event',
+        '<%= config.bin %> <%= command.id %> --json',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        'group-by': Flags.string({
+            default: 'ticker',
+            description: 'Grouping for concentration analysis',
+            options: ['event', 'series', 'ticker'],
+        }),
+        'threshold': Flags.integer({
+            default: 20,
+            description: 'Alert threshold for position concentration (%)',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(PortfolioRisk);
+        try {
+            const client = createClientFromConfig();
+            // Fetch data
+            const [balance, positions] = await Promise.all([
+                client.getBalance(),
+                client.getPositions({ settlement_status: 'open' }),
+            ]);
+            if (positions.length === 0) {
+                if (this.formatter.isJSONMode()) {
+                    this.formatter.success({
+                        alerts: [],
+                        concentrations: { by_event: [], by_ticker: [] },
+                        correlations: [],
+                        exposure_ratio: 0,
+                        position_count: 0,
+                        recommendations: {
+                            max_new_position_size: balance.balance / 100,
+                            max_single_position_pct: flags.threshold,
+                        },
+                        risk_level: 'LOW',
+                        risk_score: 0,
+                        total_exposure: 0,
+                    });
+                }
+                else {
+                    this.log(chalk.yellow('No open positions'));
+                }
+                return;
+            }
+            const portfolioValue = balance.portfolio_value / 100;
+            // Fetch market details for all positions to enable grouping
+            const tickers = positions.map(p => p.ticker).join(',');
+            const marketsResult = await client.getMarkets({ limit: positions.length, tickers });
+            const { markets } = marketsResult;
+            // Calculate risk metrics
+            const totalExposure = positions.reduce((sum, pos) => sum + pos.market_exposure, 0);
+            const exposureRatio = portfolioValue > 0 ? totalExposure / portfolioValue : 0;
+            const riskScore = calculatePortfolioRiskScore(positions, portfolioValue);
+            const highRiskPositions = identifyHighRiskPositions(positions, portfolioValue, flags.threshold);
+            // Concentration analysis
+            const concentrationByTicker = calculateConcentrationByGroup(positions, markets, portfolioValue, 'ticker', flags.threshold);
+            const concentrationByEvent = calculateConcentrationByGroup(positions, markets, portfolioValue, 'event', flags.threshold);
+            // Detect correlations
+            const correlations = detectCorrelatedPositions(positions, markets);
+            const correlationWarnings = [...correlations.entries()].map(([event, data]) => ({
+                event,
+                markets: data.markets,
+                total_exposure: data.exposure,
+                warning: 'Multiple positions in same event',
+            }));
+            // Identify alerts
+            const alerts = [];
+            if (riskScore.level === 'HIGH') {
+                alerts.push({
+                    message: `High portfolio risk score: ${riskScore.score}/100`,
+                    severity: 'high',
+                });
+            }
+            for (const pos of highRiskPositions) {
+                const pct = (pos.market_exposure / portfolioValue) * 100;
+                alerts.push({
+                    message: `${pos.ticker} exceeds threshold: ${pct.toFixed(1)}% of portfolio`,
+                    severity: pct > flags.threshold * 1.5 ? 'high' : 'medium',
+                });
+            }
+            if (exposureRatio > 0.8) {
+                alerts.push({
+                    message: `High exposure ratio: ${(exposureRatio * 100).toFixed(1)}%`,
+                    severity: exposureRatio > 1 ? 'high' : 'medium',
+                });
+            }
+            // Recommendations
+            const maxNewPositionSize = suggestMaxPositionSize(balance.balance / 100, portfolioValue, flags.threshold);
+            if (this.formatter.isJSONMode()) {
+                this.formatter.success({
+                    alerts,
+                    concentrations: {
+                        by_event: concentrationByEvent,
+                        by_ticker: concentrationByTicker,
+                    },
+                    correlations: correlationWarnings,
+                    exposure_ratio: exposureRatio,
+                    position_count: positions.length,
+                    recommendations: {
+                        max_new_position_size: maxNewPositionSize,
+                        max_single_position_pct: flags.threshold,
+                    },
+                    risk_level: riskScore.level,
+                    risk_score: riskScore.score,
+                    total_exposure: totalExposure,
+                });
+            }
+            else {
+                // Human-readable output
+                this.log(chalk.cyan.bold('Portfolio Risk Analysis'));
+                this.log();
+                // Overall Risk
+                const riskLevelColor = riskScore.level === 'HIGH' ? chalk.red : riskScore.level === 'MEDIUM' ? chalk.yellow : chalk.green;
+                this.log(chalk.yellow('Overall Risk:'));
+                this.log(`  Risk Score: ${riskLevelColor(riskScore.score + '/100')}`);
+                this.log(`  Risk Level: ${riskLevelColor(riskScore.level)}`);
+                this.log(`  Total Exposure: ${chalk.cyan('$' + totalExposure.toFixed(2))}`);
+                this.log(`  Exposure Ratio: ${exposureRatio > 0.8 ? chalk.red((exposureRatio * 100).toFixed(1) + '%') : chalk.cyan((exposureRatio * 100).toFixed(1) + '%')}`);
+                this.log(`  Positions: ${positions.length}`);
+                this.log();
+                // Alerts
+                if (alerts.length > 0) {
+                    this.log(chalk.yellow('⚠️  Alerts:'));
+                    for (const alert of alerts) {
+                        const color = alert.severity === 'high' ? chalk.red : alert.severity === 'medium' ? chalk.yellow : chalk.blue;
+                        this.log(`  ${color('•')} ${alert.message}`);
+                    }
+                    this.log();
+                }
+                // Concentration
+                this.log(chalk.yellow('Concentration by Ticker:'));
+                const topConcentrations = concentrationByTicker.slice(0, 10);
+                if (topConcentrations.length > 0) {
+                    const rows = topConcentrations.map(c => [
+                        c.name,
+                        '$' + c.exposure.toFixed(2),
+                        c.pct_of_portfolio.toFixed(1) + '%',
+                        c.alert ? chalk.red('⚠️  ALERT') : chalk.green('OK'),
+                    ]);
+                    this.formatter.outputTable(['Ticker', 'Exposure', '% of Portfolio', 'Status'], rows);
+                }
+                else {
+                    this.log('  No positions');
+                }
+                this.log();
+                // Event concentration
+                if (concentrationByEvent.length > 0) {
+                    this.log(chalk.yellow('Concentration by Event:'));
+                    const topEvents = concentrationByEvent.slice(0, 5);
+                    const eventRows = topEvents.map(c => [
+                        c.name,
+                        (c.markets || []).length.toString() + ' markets',
+                        '$' + c.exposure.toFixed(2),
+                        c.pct_of_portfolio.toFixed(1) + '%',
+                        c.alert ? chalk.red('⚠️  ALERT') : chalk.green('OK'),
+                    ]);
+                    this.formatter.outputTable(['Event', 'Markets', 'Exposure', '% of Portfolio', 'Status'], eventRows);
+                    this.log();
+                }
+                // Correlations
+                if (correlationWarnings.length > 0) {
+                    this.log(chalk.yellow('⚠️  Correlation Warnings:'));
+                    for (const corr of correlationWarnings) {
+                        this.log(`  ${chalk.cyan(corr.event)}: ${corr.markets.length} positions, $${corr.total_exposure.toFixed(2)} total exposure`);
+                        this.log(`    Markets: ${corr.markets.join(', ')}`);
+                    }
+                    this.log();
+                }
+                // Recommendations
+                this.log(chalk.yellow('Recommendations:'));
+                this.log(`  Max New Position Size: ${chalk.cyan('$' + maxNewPositionSize.toFixed(2))} (${flags.threshold}% of portfolio)`);
+                this.log(`  Position Size Threshold: ${chalk.cyan(flags.threshold + '%')}`);
+                if (riskScore.level === 'HIGH') {
+                    this.log();
+                    this.log(chalk.red('⚠️  Consider reducing exposure or diversifying positions'));
+                }
+                else if (riskScore.level === 'MEDIUM') {
+                    this.log();
+                    this.log(chalk.yellow('ℹ️  Monitor positions and avoid over-concentration'));
+                }
+            }
+            logger.info({
+                alerts: alerts.length,
+                correlations: correlationWarnings.length,
+                risk_level: riskScore.level,
+                risk_score: riskScore.score,
+            }, 'Risk analysis completed');
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+}

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/base-command.d.ts

@@ -4,10 +4,10 @@ import { OutputFormatter } from './output/formatter.js';
  * Base command class that all kalshitools commands extend
  */
 export declare abstract class BaseCommand extends Command {
-    protected formatter: OutputFormatter;
     static baseFlags: {
         json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
-    init(): Promise<void>;
+    protected formatter: OutputFormatter;
     protected catch(error: Error): Promise<unknown>;
+    init(): Promise<void>;
 }

package/dist/lib/base-command.js

@@ -6,20 +6,15 @@ import { OutputFormatter } from './output/formatter.js';
  * Base command class that all kalshitools commands extend
  */
 export class BaseCommand extends Command {
-    formatter;
     static baseFlags = {
         json: Flags.boolean({
-            description: 'Output in JSON format',
             default: false,
+            description: 'Output in JSON format',
         }),
     };
-    async init() {
-        await super.init();
-        const { flags } = await this.parse(this.constructor);
-        this.formatter = new OutputFormatter(flags.json, this.id);
-    }
+    formatter;
     async catch(error) {
-        logger.error({ error, command: this.id }, 'Command failed');
+        logger.error({ command: this.id, error }, 'Command failed');
         if (error instanceof KalshiToolsError) {
             if (this.formatter?.isJSONMode()) {
                 this.formatter.error(error.code, error.message, error.details);
@@ -35,4 +30,9 @@ export class BaseCommand extends Command {
         }
         throw error;
     }
+    async init() {
+        await super.init();
+        const { flags } = await this.parse(this.constructor);
+        this.formatter = new OutputFormatter(flags.json, this.id);
+    }
 }

package/dist/lib/config/manager.d.ts

@@ -1,45 +1,37 @@
-import { type Config, type ApiEnvConfig } from './schema.js';
+import { type ApiEnvConfig, type Config } from './schema.js';
 /**
  * Configuration manager for kalshitools
  */
 export declare class ConfigManager {
-    private store;
     private static instance;
+    private store;
     constructor();
     /**
      * Get singleton instance
      */
     static getInstance(): ConfigManager;
-    /**
-     * Get the full configuration
-     */
-    getConfig(): Config;
-    /**
-     * Get the current environment (demo or production)
-     */
-    getEnvironment(): 'demo' | 'production';
-    /**
-     * Set the environment
-     */
-    setEnvironment(env: 'demo' | 'production'): void;
     /**
      * Get API configuration for the current environment
      */
     getApiConfig(): ApiEnvConfig;
     /**
-     * Read private key from file
+     * Get the full configuration
      */
-    readPrivateKey(): string;
+    getConfig(): Config;
     /**
-     * Set API configuration for an environment
+     * Get the configuration file path
      */
-    setApiConfig(env: 'demo' | 'production', config: Partial<ApiEnvConfig>): void;
+    getConfigPath(): string;
+    /**
+     * Get the current environment (demo or production)
+     */
+    getEnvironment(): 'demo' | 'production';
     /**
      * Get output configuration
      */
     getOutputConfig(): {
-        defaultFormat: "json" | "table";
         colors: boolean;
+        defaultFormat: "json" | "table";
     };
     /**
      * Get trading configuration
@@ -49,21 +41,29 @@ export declare class ConfigManager {
         maxOrderSize: number;
     };
     /**
-     * Set a configuration value
+     * Check if configuration is initialized
      */
-    set<K extends keyof Config>(key: K, value: Config[K]): void;
+    isConfigured(): boolean;
     /**
-     * Get the configuration file path
+     * Read private key from file
      */
-    getConfigPath(): string;
+    readPrivateKey(): string;
     /**
      * Reset configuration to defaults
      */
     reset(): void;
     /**
-     * Check if configuration is initialized
+     * Set a configuration value
      */
-    isConfigured(): boolean;
+    set<K extends keyof Config>(key: K, value: Config[K]): void;
+    /**
+     * Set API configuration for an environment
+     */
+    setApiConfig(env: 'demo' | 'production', config: Partial<ApiEnvConfig>): void;
+    /**
+     * Set the environment
+     */
+    setEnvironment(env: 'demo' | 'production'): void;
 }
 /**
  * Get the global configuration manager instance