@gaberoo/kalshitools 1.0.3 → 1.1.0

package/README.md

@@ -16,6 +16,10 @@ A powerful CLI tool for interacting with the Kalshi prediction markets API. Buil
 - 🛡️ **Safety First**: Demo environment default, confirmations, and order limits
 - 📈 **Order Book Analysis**: Real-time order depth and liquidity assessment
 - 🔍 **Market Discovery**: Event/series filtering, nested markets, multi-ticker batch queries
+- 📊 **Portfolio Analytics**: Comprehensive performance metrics, win rate, P&L analysis, fee tracking
+- ⚠️ **Risk Management**: Real-time risk assessment, concentration analysis, correlation detection
+- 📈 **Historical Analysis**: Time-series performance data, maker/taker statistics, trend analysis
+- 🔎 **Market Scanner**: Automated opportunity discovery based on liquidity, spreads, and volume
 
 ## Quick Start
 
@@ -120,6 +124,86 @@ kalshitools orders create \
 
 # View order history
 kalshitools orders list
+
+# Analyze portfolio performance
+kalshitools portfolio analytics --period 30 --json
+
+# Check portfolio risk
+kalshitools portfolio risk --threshold 20
+
+# View historical performance
+kalshitools portfolio history --group-by week
+
+# Scan markets for opportunities
+kalshitools markets scan --min-liquidity 200 --min-spread 0.05
+```
+
+## Advanced Features for AI Trading Agents
+
+kalshitools provides powerful analytics and scanning capabilities designed for automated trading systems:
+
+### Portfolio Analytics
+
+Get comprehensive performance metrics for strategy evaluation:
+
+```bash
+# Full analytics for last 30 days
+kalshitools portfolio analytics --period 30 --json
+
+# Custom date range
+kalshitools portfolio analytics \
+  --min-ts 2026-01-01T00:00:00Z \
+  --max-ts 2026-02-01T00:00:00Z \
+  --json
+
+# Returns: win rate, avg P&L, total return, exposure ratio, concentration, fees
+```
+
+### Risk Management
+
+Real-time risk assessment to prevent over-concentration:
+
+```bash
+# Check portfolio risk with 20% position limit
+kalshitools portfolio risk --threshold 20 --json
+
+# Analyze concentration by event
+kalshitools portfolio risk --group-by event --json
+
+# Returns: risk score, concentrations, correlations, alerts, recommendations
+```
+
+### Historical Performance
+
+Deep dive into trading history with time-series analytics:
+
+```bash
+# Daily performance breakdown
+kalshitools portfolio history --group-by day --json
+
+# Filter by specific market
+kalshitools portfolio history --ticker MARKET-A --json
+
+# Returns: time-series data, maker/taker stats, performance by ticker
+```
+
+### Market Opportunity Scanner
+
+Discover high-quality trading opportunities:
+
+```bash
+# Scan for markets with good liquidity and spreads
+kalshitools markets scan \
+  --min-liquidity 200 \
+  --min-spread 0.05 \
+  --max-spread 0.20 \
+  --min-volume 1000 \
+  --json
+
+# Filter to specific event
+kalshitools markets scan --event-ticker EVENT-2024 --json
+
+# Returns: scored opportunities with liquidity, spread, and volume data
 ```
 
 ## Configuration
@@ -171,6 +255,22 @@ export LOG_LEVEL=info
 * [Place an order (with confirmation)](#place-an-order-with-confirmation)
 * [Use --dry-run to simulate without placing order](#use---dry-run-to-simulate-without-placing-order)
 * [View order history](#view-order-history)
+* [Analyze portfolio performance](#analyze-portfolio-performance)
+* [Check portfolio risk](#check-portfolio-risk)
+* [View historical performance](#view-historical-performance)
+* [Scan markets for opportunities](#scan-markets-for-opportunities)
+* [Full analytics for last 30 days](#full-analytics-for-last-30-days)
+* [Custom date range](#custom-date-range)
+* [Returns: win rate, avg P&L, total return, exposure ratio, concentration, fees](#returns-win-rate-avg-pl-total-return-exposure-ratio-concentration-fees)
+* [Check portfolio risk with 20% position limit](#check-portfolio-risk-with-20-position-limit)
+* [Analyze concentration by event](#analyze-concentration-by-event)
+* [Returns: risk score, concentrations, correlations, alerts, recommendations](#returns-risk-score-concentrations-correlations-alerts-recommendations)
+* [Daily performance breakdown](#daily-performance-breakdown)
+* [Filter by specific market](#filter-by-specific-market)
+* [Returns: time-series data, maker/taker stats, performance by ticker](#returns-time-series-data-makertaker-stats-performance-by-ticker)
+* [Scan for markets with good liquidity and spreads](#scan-for-markets-with-good-liquidity-and-spreads)
+* [Filter to specific event](#filter-to-specific-event)
+* [Returns: scored opportunities with liquidity, spread, and volume data](#returns-scored-opportunities-with-liquidity-spread-and-volume-data)
 * [Usage](#usage)
 * [Commands](#commands)
 <!-- tocstop -->
@@ -181,7 +281,7 @@ $ npm install -g @gaberoo/kalshitools
 $ kalshitools COMMAND
 running command...
 $ kalshitools (--version)
-@gaberoo/kalshitools/1.0.3 darwin-arm64 node-v22.20.0
+@gaberoo/kalshitools/1.1.0 darwin-arm64 node-v22.20.0
 $ kalshitools --help [COMMAND]
 USAGE
   $ kalshitools COMMAND
@@ -195,6 +295,7 @@ USAGE
 * [`kalshitools help [COMMAND]`](#kalshitools-help-command)
 * [`kalshitools markets list`](#kalshitools-markets-list)
 * [`kalshitools markets orderbook TICKER`](#kalshitools-markets-orderbook-ticker)
+* [`kalshitools markets scan`](#kalshitools-markets-scan)
 * [`kalshitools markets show TICKER`](#kalshitools-markets-show-ticker)
 * [`kalshitools orders cancel ORDERID`](#kalshitools-orders-cancel-orderid)
 * [`kalshitools orders create`](#kalshitools-orders-create)
@@ -209,9 +310,12 @@ USAGE
 * [`kalshitools plugins uninstall [PLUGIN]`](#kalshitools-plugins-uninstall-plugin)
 * [`kalshitools plugins unlink [PLUGIN]`](#kalshitools-plugins-unlink-plugin)
 * [`kalshitools plugins update`](#kalshitools-plugins-update)
+* [`kalshitools portfolio analytics`](#kalshitools-portfolio-analytics)
 * [`kalshitools portfolio balance`](#kalshitools-portfolio-balance)
 * [`kalshitools portfolio fills`](#kalshitools-portfolio-fills)
+* [`kalshitools portfolio history`](#kalshitools-portfolio-history)
 * [`kalshitools portfolio positions`](#kalshitools-portfolio-positions)
+* [`kalshitools portfolio risk`](#kalshitools-portfolio-risk)
 
 ## `kalshitools config init`
 
@@ -237,7 +341,7 @@ EXAMPLES
   $ kalshitools config init --env production
 ```
 
-_See code: [src/commands/config/init.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.3/src/commands/config/init.ts)_
+_See code: [src/commands/config/init.ts](https://github.com/kalshitools/kalshitools/blob/v1.1.0/src/commands/config/init.ts)_
 
 ## `kalshitools config show`
 
@@ -259,7 +363,7 @@ EXAMPLES
   $ kalshitools config show --json
 ```
 
-_See code: [src/commands/config/show.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.3/src/commands/config/show.ts)_
+_See code: [src/commands/config/show.ts](https://github.com/kalshitools/kalshitools/blob/v1.1.0/src/commands/config/show.ts)_
 
 ## `kalshitools help [COMMAND]`
 
@@ -317,7 +421,7 @@ EXAMPLES
   $ kalshitools markets list --json
 ```
 
-_See code: [src/commands/markets/list.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.3/src/commands/markets/list.ts)_
+_See code: [src/commands/markets/list.ts](https://github.com/kalshitools/kalshitools/blob/v1.1.0/src/commands/markets/list.ts)_
 
 ## `kalshitools markets orderbook TICKER`
 
@@ -345,7 +449,47 @@ EXAMPLES
   $ kalshitools markets orderbook TICKER --json
 ```
 
-_See code: [src/commands/markets/orderbook.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.3/src/commands/markets/orderbook.ts)_
+_See code: [src/commands/markets/orderbook.ts](https://github.com/kalshitools/kalshitools/blob/v1.1.0/src/commands/markets/orderbook.ts)_
+
+## `kalshitools markets scan`
+
+Scan markets for trading opportunities based on liquidity and spreads
+
+```
+USAGE
+  $ kalshitools markets scan [--json] [--depth <value>] [--event-ticker <value>] [--limit <value>] [--max-spread
+    <value>] [--min-liquidity <value>] [--min-spread <value>] [--min-volume <value>] [--series-ticker <value>]
+    [--sort-by liquidity|score|spread|volume]
+
+FLAGS
+  --depth=<value>          [default: 5] Orderbook depth to fetch for analysis
+  --event-ticker=<value>   Filter to specific event
+  --json                   Output in JSON format
+  --limit=<value>          [default: 50] Maximum markets to scan
+  --max-spread=<value>     [default: 0.30] Maximum spread in cents (e.g., 0.30 = 30 cents)
+  --min-liquidity=<value>  [default: 100] Minimum orderbook depth in dollars
+  --min-spread=<value>     [default: 0.03] Minimum spread in cents (e.g., 0.03 = 3 cents)
+  --min-volume=<value>     [default: 500] Minimum 24h volume in dollars
+  --series-ticker=<value>  Filter to specific series
+  --sort-by=<option>       [default: score] Ranking criteria
+                           <options: liquidity|score|spread|volume>
+
+DESCRIPTION
+  Scan markets for trading opportunities based on liquidity and spreads
+
+EXAMPLES
+  $ kalshitools markets scan
+
+  $ kalshitools markets scan --min-liquidity 200 --min-spread 0.05
+
+  $ kalshitools markets scan --event-ticker EVENT-2024
+
+  $ kalshitools markets scan --sort-by liquidity --limit 20
+
+  $ kalshitools markets scan --json
+```
+
+_See code: [src/commands/markets/scan.ts](https://github.com/kalshitools/kalshitools/blob/v1.1.0/src/commands/markets/scan.ts)_
 
 ## `kalshitools markets show TICKER`
 
@@ -370,7 +514,7 @@ EXAMPLES
   $ kalshitools markets show TICKER --json
 ```
 
-_See code: [src/commands/markets/show.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.3/src/commands/markets/show.ts)_
+_See code: [src/commands/markets/show.ts](https://github.com/kalshitools/kalshitools/blob/v1.1.0/src/commands/markets/show.ts)_
 
 ## `kalshitools orders cancel ORDERID`
 
@@ -398,7 +542,7 @@ EXAMPLES
   $ kalshitools orders cancel ORDER_ID --json
 ```
 
-_See code: [src/commands/orders/cancel.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.3/src/commands/orders/cancel.ts)_
+_See code: [src/commands/orders/cancel.ts](https://github.com/kalshitools/kalshitools/blob/v1.1.0/src/commands/orders/cancel.ts)_
 
 ## `kalshitools orders create`
 
@@ -436,7 +580,7 @@ EXAMPLES
   $ kalshitools orders create --ticker TICKER --action buy --side yes --quantity 100 --dry-run
 ```
 
-_See code: [src/commands/orders/create.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.3/src/commands/orders/create.ts)_
+_See code: [src/commands/orders/create.ts](https://github.com/kalshitools/kalshitools/blob/v1.1.0/src/commands/orders/create.ts)_
 
 ## `kalshitools orders list`
 
@@ -467,7 +611,7 @@ EXAMPLES
   $ kalshitools orders list --json
 ```
 
-_See code: [src/commands/orders/list.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.3/src/commands/orders/list.ts)_
+_See code: [src/commands/orders/list.ts](https://github.com/kalshitools/kalshitools/blob/v1.1.0/src/commands/orders/list.ts)_
 
 ## `kalshitools plugins`
 
@@ -759,6 +903,35 @@ DESCRIPTION
 
 _See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v5.4.56/src/commands/plugins/update.ts)_
 
+## `kalshitools portfolio analytics`
+
+Comprehensive portfolio performance analytics
+
+```
+USAGE
+  $ kalshitools portfolio analytics [--json] [--max-ts <value>] [--min-ts <value>] [--period <value>]
+
+FLAGS
+  --json            Output in JSON format
+  --max-ts=<value>  End date for analysis (ISO-8601 format)
+  --min-ts=<value>  Start date for analysis (ISO-8601 format)
+  --period=<value>  Analysis period in days (overridden by min-ts/max-ts)
+
+DESCRIPTION
+  Comprehensive portfolio performance analytics
+
+EXAMPLES
+  $ kalshitools portfolio analytics
+
+  $ kalshitools portfolio analytics --period 7
+
+  $ kalshitools portfolio analytics --min-ts 2026-01-01T00:00:00Z
+
+  $ kalshitools portfolio analytics --json
+```
+
+_See code: [src/commands/portfolio/analytics.ts](https://github.com/kalshitools/kalshitools/blob/v1.1.0/src/commands/portfolio/analytics.ts)_
+
 ## `kalshitools portfolio balance`
 
 View account balance
@@ -779,7 +952,7 @@ EXAMPLES
   $ kalshitools portfolio balance --json
 ```
 
-_See code: [src/commands/portfolio/balance.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.3/src/commands/portfolio/balance.ts)_
+_See code: [src/commands/portfolio/balance.ts](https://github.com/kalshitools/kalshitools/blob/v1.1.0/src/commands/portfolio/balance.ts)_
 
 ## `kalshitools portfolio fills`
 
@@ -807,7 +980,42 @@ EXAMPLES
   $ kalshitools portfolio fills --json
 ```
 
-_See code: [src/commands/portfolio/fills.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.3/src/commands/portfolio/fills.ts)_
+_See code: [src/commands/portfolio/fills.ts](https://github.com/kalshitools/kalshitools/blob/v1.1.0/src/commands/portfolio/fills.ts)_
+
+## `kalshitools portfolio history`
+
+Historical performance analysis with time-series data
+
+```
+USAGE
+  $ kalshitools portfolio history [--json] [--group-by day|week|month] [--limit <value>] [--max-ts <value>] [--min-ts
+    <value>] [--ticker <value>]
+
+FLAGS
+  --group-by=<option>  [default: day] Time aggregation level
+                       <options: day|week|month>
+  --json               Output in JSON format
+  --limit=<value>      [default: 500] Maximum fills to fetch (handles pagination)
+  --max-ts=<value>     End date (ISO-8601 format)
+  --min-ts=<value>     Start date (ISO-8601 format)
+  --ticker=<value>     Filter by specific market ticker
+
+DESCRIPTION
+  Historical performance analysis with time-series data
+
+EXAMPLES
+  $ kalshitools portfolio history
+
+  $ kalshitools portfolio history --ticker MARKET-A
+
+  $ kalshitools portfolio history --group-by week
+
+  $ kalshitools portfolio history --min-ts 2026-01-01T00:00:00Z --max-ts 2026-02-01T00:00:00Z
+
+  $ kalshitools portfolio history --json
+```
+
+_See code: [src/commands/portfolio/history.ts](https://github.com/kalshitools/kalshitools/blob/v1.1.0/src/commands/portfolio/history.ts)_
 
 ## `kalshitools portfolio positions`
 
@@ -835,5 +1043,34 @@ EXAMPLES
   $ kalshitools portfolio positions --json
 ```
 
-_See code: [src/commands/portfolio/positions.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.3/src/commands/portfolio/positions.ts)_
+_See code: [src/commands/portfolio/positions.ts](https://github.com/kalshitools/kalshitools/blob/v1.1.0/src/commands/portfolio/positions.ts)_
+
+## `kalshitools portfolio risk`
+
+Real-time portfolio risk analysis and warnings
+
+```
+USAGE
+  $ kalshitools portfolio risk [--json] [--group-by event|series|ticker] [--threshold <value>]
+
+FLAGS
+  --group-by=<option>  [default: ticker] Grouping for concentration analysis
+                       <options: event|series|ticker>
+  --json               Output in JSON format
+  --threshold=<value>  [default: 20] Alert threshold for position concentration (%)
+
+DESCRIPTION
+  Real-time portfolio risk analysis and warnings
+
+EXAMPLES
+  $ kalshitools portfolio risk
+
+  $ kalshitools portfolio risk --threshold 15
+
+  $ kalshitools portfolio risk --group-by event
+
+  $ kalshitools portfolio risk --json
+```
+
+_See code: [src/commands/portfolio/risk.ts](https://github.com/kalshitools/kalshitools/blob/v1.1.0/src/commands/portfolio/risk.ts)_
 <!-- commandsstop -->

package/dist/commands/markets/scan.d.ts

@@ -0,0 +1,18 @@
+import { BaseCommand } from '../../lib/base-command.js';
+export default class MarketsScan extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        depth: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        'event-ticker': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        'max-spread': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'min-liquidity': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'min-spread': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'min-volume': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'series-ticker': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'sort-by': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/markets/scan.js

@@ -0,0 +1,237 @@
+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 { calculateOrderbookLiquidity, calculateSpread, classifyOpportunity, filterMarketsByCriteria, generateOpportunityReason, scoreMarket, } from '../../lib/scanner.js';
+export default class MarketsScan extends BaseCommand {
+    static description = 'Scan markets for trading opportunities based on liquidity and spreads';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+        '<%= config.bin %> <%= command.id %> --min-liquidity 200 --min-spread 0.05',
+        '<%= config.bin %> <%= command.id %> --event-ticker EVENT-2024',
+        '<%= config.bin %> <%= command.id %> --sort-by liquidity --limit 20',
+        '<%= config.bin %> <%= command.id %> --json',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        'depth': Flags.integer({
+            default: 5,
+            description: 'Orderbook depth to fetch for analysis',
+        }),
+        'event-ticker': Flags.string({
+            description: 'Filter to specific event',
+        }),
+        'limit': Flags.integer({
+            default: 50,
+            description: 'Maximum markets to scan',
+        }),
+        'max-spread': Flags.string({
+            default: '0.30',
+            description: 'Maximum spread in cents (e.g., 0.30 = 30 cents)',
+        }),
+        'min-liquidity': Flags.string({
+            default: '100',
+            description: 'Minimum orderbook depth in dollars',
+        }),
+        'min-spread': Flags.string({
+            default: '0.03',
+            description: 'Minimum spread in cents (e.g., 0.03 = 3 cents)',
+        }),
+        'min-volume': Flags.string({
+            default: '500',
+            description: 'Minimum 24h volume in dollars',
+        }),
+        'series-ticker': Flags.string({
+            description: 'Filter to specific series',
+        }),
+        'sort-by': Flags.string({
+            default: 'score',
+            description: 'Ranking criteria',
+            options: ['liquidity', 'score', 'spread', 'volume'],
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(MarketsScan);
+        try {
+            const client = createClientFromConfig();
+            // Parse numeric flags
+            const minLiquidity = Number.parseFloat(flags['min-liquidity']);
+            const minSpread = Number.parseFloat(flags['min-spread']);
+            const maxSpread = Number.parseFloat(flags['max-spread']);
+            const minVolume = Number.parseFloat(flags['min-volume']);
+            if (!this.formatter.isJSONMode()) {
+                this.log(chalk.cyan.bold('Scanning Markets for Opportunities...'));
+                this.log();
+            }
+            // Fetch active markets
+            const marketsResult = await client.getMarkets({
+                event_ticker: flags['event-ticker'],
+                limit: flags.limit,
+                series_ticker: flags['series-ticker'],
+                status: 'active',
+            });
+            const { markets } = marketsResult;
+            if (markets.length === 0) {
+                if (this.formatter.isJSONMode()) {
+                    this.formatter.success({
+                        markets: [],
+                        opportunities: 0,
+                        scanned: 0,
+                        stats: {
+                            avg_liquidity: 0,
+                            avg_spread: 0,
+                            avg_volume_24h: 0,
+                        },
+                    });
+                }
+                else {
+                    this.log(chalk.yellow('No active markets found'));
+                }
+                return;
+            }
+            if (!this.formatter.isJSONMode()) {
+                this.log(`Found ${markets.length} active markets. Fetching orderbooks...`);
+                this.log(chalk.gray('(This may take a few seconds due to rate limiting)'));
+                this.log();
+            }
+            // Fetch orderbooks for all markets (rate limited automatically by client)
+            const marketData = [];
+            for (const market of markets) {
+                try {
+                    const orderbook = await client.getOrderBook(market.ticker, flags.depth);
+                    const liquidity = calculateOrderbookLiquidity(orderbook);
+                    const spreadData = calculateSpread(orderbook);
+                    const volume = market.volume_24h || market.volume || 0;
+                    const score = scoreMarket(market, orderbook);
+                    marketData.push({
+                        liquidity: liquidity.total,
+                        market,
+                        orderbook,
+                        score,
+                        spread: spreadData ? spreadData.spreadCents : null,
+                        volume,
+                    });
+                }
+                catch (error) {
+                    logger.debug({ error, ticker: market.ticker }, 'Failed to fetch orderbook');
+                    // Skip markets with orderbook fetch errors
+                    continue;
+                }
+            }
+            // Filter markets by criteria
+            const filtered = filterMarketsByCriteria(marketData, {
+                maxSpread,
+                minLiquidity,
+                minSpread,
+                minVolume,
+            });
+            // Sort markets
+            const sorted = [...filtered];
+            if (flags['sort-by'] === 'liquidity') {
+                sorted.sort((a, b) => b.liquidity - a.liquidity);
+            }
+            else if (flags['sort-by'] === 'spread') {
+                sorted.sort((a, b) => (b.spread || 0) - (a.spread || 0));
+            }
+            else if (flags['sort-by'] === 'volume') {
+                sorted.sort((a, b) => b.volume - a.volume);
+            }
+            else {
+                // Default to score
+                sorted.sort((a, b) => b.score - a.score);
+            }
+            // Calculate statistics
+            const avgLiquidity = filtered.length > 0
+                ? filtered.reduce((sum, m) => sum + m.liquidity, 0) / filtered.length
+                : 0;
+            const avgSpread = filtered.length > 0
+                ? filtered.filter(m => m.spread !== null).reduce((sum, m) => sum + (m.spread || 0), 0) / filtered.filter(m => m.spread !== null).length
+                : 0;
+            const avgVolume24h = filtered.length > 0
+                ? filtered.reduce((sum, m) => sum + m.volume, 0) / filtered.length
+                : 0;
+            if (this.formatter.isJSONMode()) {
+                const opportunities = sorted.map(m => {
+                    const spreadData = m.orderbook ? calculateSpread(m.orderbook) : null;
+                    const liquidityData = m.orderbook ? calculateOrderbookLiquidity(m.orderbook) : { noTotal: 0, total: 0, yesTotal: 0 };
+                    const opportunityType = classifyOpportunity(m.spread || 0, m.liquidity, m.volume);
+                    return {
+                        liquidity: {
+                            no_total: liquidityData.noTotal,
+                            total: liquidityData.total,
+                            yes_total: liquidityData.yesTotal,
+                        },
+                        opportunity_type: opportunityType,
+                        reason: generateOpportunityReason(opportunityType, m.spread || 0, m.liquidity, m.volume),
+                        score: m.score,
+                        spread: spreadData ? {
+                            spread_cents: spreadData.spreadCents,
+                            spread_pct: spreadData.spreadPct,
+                            yes_ask: spreadData.yesAsk,
+                            yes_bid: spreadData.yesBid,
+                        } : null,
+                        ticker: m.market.ticker,
+                        title: m.market.title,
+                        volume: {
+                            volume_24h: m.volume,
+                        },
+                    };
+                });
+                this.formatter.success({
+                    markets: opportunities,
+                    opportunities: filtered.length,
+                    scanned: markets.length,
+                    stats: {
+                        avg_liquidity: avgLiquidity,
+                        avg_spread: avgSpread,
+                        avg_volume_24h: avgVolume24h,
+                    },
+                });
+            }
+            else {
+                // Human-readable output
+                this.log(chalk.cyan.bold('Market Opportunities'));
+                this.log();
+                this.log(chalk.yellow('Summary:'));
+                this.log(`  Markets Scanned: ${markets.length}`);
+                this.log(`  Opportunities Found: ${filtered.length}`);
+                this.log(`  Avg Liquidity: ${chalk.cyan('$' + avgLiquidity.toFixed(2))}`);
+                this.log(`  Avg Spread: ${chalk.cyan(avgSpread.toFixed(3))} cents`);
+                this.log(`  Avg 24h Volume: ${chalk.cyan('$' + avgVolume24h.toFixed(2))}`);
+                this.log();
+                if (sorted.length > 0) {
+                    this.log(chalk.yellow('Top Opportunities:'));
+                    const rows = sorted.slice(0, 20).map(m => {
+                        const spreadData = m.orderbook ? calculateSpread(m.orderbook) : null;
+                        return [
+                            m.market.ticker,
+                            m.score.toString(),
+                            spreadData ? spreadData.spreadCents.toFixed(3) : 'N/A',
+                            '$' + m.liquidity.toFixed(0),
+                            '$' + m.volume.toFixed(0),
+                            m.market.title.length > 40 ? m.market.title.slice(0, 37) + '...' : m.market.title,
+                        ];
+                    });
+                    this.formatter.outputTable(['Ticker', 'Score', 'Spread', 'Liquidity', '24h Vol', 'Title'], rows);
+                    if (sorted.length > 20) {
+                        this.log();
+                        this.log(chalk.gray(`  ... showing top 20 of ${sorted.length} opportunities`));
+                    }
+                }
+                else {
+                    this.log(chalk.yellow('No opportunities found matching criteria'));
+                }
+                this.log();
+                this.log(chalk.gray('Tip: Use --json for full data including orderbook details'));
+            }
+            logger.info({
+                filtered: filtered.length,
+                scanned: markets.length,
+            }, 'Market scan completed');
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+}

package/dist/commands/portfolio/analytics.d.ts

@@ -0,0 +1,12 @@
+import { BaseCommand } from '../../lib/base-command.js';
+export default class PortfolioAnalytics extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'max-ts': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'min-ts': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        period: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}