@gaberoo/kalshitools 1.0.3 → 1.1.0

package/dist/lib/scanner.js

@@ -0,0 +1,160 @@
+/**
+ * Market scanning and opportunity detection utilities
+ */
+/**
+ * Calculate total liquidity from an orderbook
+ */
+export function calculateOrderbookLiquidity(orderbook) {
+    const yesTotal = orderbook.yes.reduce((sum, level) => sum + level.count * level.price, 0);
+    const noTotal = orderbook.no.reduce((sum, level) => sum + level.count * level.price, 0);
+    return {
+        noTotal,
+        total: yesTotal + noTotal,
+        yesTotal,
+    };
+}
+/**
+ * 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 function calculateSpread(orderbook) {
+    if (orderbook.yes.length === 0) {
+        return null;
+    }
+    const prices = orderbook.yes.map(level => level.price).sort((a, b) => a - b);
+    // Best bid is the lowest price (buyers)
+    const yesBid = prices[0];
+    // Best ask is the highest price (sellers)
+    const yesAsk = prices.at(-1);
+    if (!yesAsk || !yesBid) {
+        return null;
+    }
+    // If bid and ask are the same, there's no spread
+    const spreadCents = yesAsk - yesBid;
+    const midPrice = (yesBid + yesAsk) / 2;
+    const spreadPct = midPrice > 0 ? (spreadCents / midPrice) * 100 : 0;
+    return {
+        spreadCents,
+        spreadPct,
+        yesAsk,
+        yesBid,
+    };
+}
+const DEFAULT_WEIGHTS = {
+    liquidity: 40,
+    spread: 30,
+    volume: 30,
+};
+/**
+ * Score a market based on liquidity, spread, and volume
+ * Returns score from 0-100
+ */
+export function scoreMarket(market, orderbook, weights = DEFAULT_WEIGHTS) {
+    let score = 0;
+    // Liquidity score (0-40 points)
+    const liquidity = calculateOrderbookLiquidity(orderbook);
+    const liquidityScore = Math.min(weights.liquidity, (liquidity.total / 5000) * weights.liquidity);
+    score += liquidityScore;
+    // Spread score (0-30 points) - wider spreads are better for market making
+    const spread = calculateSpread(orderbook);
+    if (spread) {
+        // Spread between 0.03 (3 cents) and 0.20 (20 cents) is ideal
+        const { spreadCents } = spread;
+        let spreadScore = 0;
+        if (spreadCents >= 0.03 && spreadCents <= 0.2) {
+            spreadScore = weights.spread;
+        }
+        else if (spreadCents > 0.2) {
+            // Too wide - gradually decrease score
+            spreadScore = Math.max(0, weights.spread * (1 - (spreadCents - 0.2) / 0.3));
+        }
+        else {
+            // Too narrow - gradually decrease score
+            spreadScore = (spreadCents / 0.03) * weights.spread;
+        }
+        score += spreadScore;
+    }
+    // Volume score (0-30 points)
+    const volume = market.volume_24h || market.volume || 0;
+    const volumeScore = Math.min(weights.volume, (volume / 10_000) * weights.volume);
+    score += volumeScore;
+    return Math.round(score);
+}
+/**
+ * Classify the type of opportunity a market presents
+ */
+export function classifyOpportunity(spread, liquidity, volume) {
+    const hasWideSpread = spread >= 0.05;
+    const hasHighLiquidity = liquidity >= 2000;
+    const hasHighVolume = volume >= 5000;
+    // Check combinations
+    if (hasWideSpread && hasHighLiquidity && hasHighVolume) {
+        return 'balanced';
+    }
+    if (hasWideSpread) {
+        return 'wide_spread';
+    }
+    if (hasHighLiquidity) {
+        return 'high_liquidity';
+    }
+    if (hasHighVolume) {
+        return 'high_volume';
+    }
+    // Default to balanced if none of the above
+    return 'balanced';
+}
+/**
+ * Generate human-readable reason for opportunity
+ */
+export function generateOpportunityReason(type, spread, liquidity, volume) {
+    const spreadCents = Math.round(spread * 100);
+    switch (type) {
+        case 'balanced': {
+            return `Balanced opportunity: ${spreadCents} cent spread, $${Math.round(liquidity)} liquidity, $${Math.round(volume)} volume`;
+        }
+        case 'high_liquidity': {
+            return `Strong liquidity ($${Math.round(liquidity).toLocaleString()})`;
+        }
+        case 'high_volume': {
+            return `High trading volume ($${Math.round(volume).toLocaleString()} 24h)`;
+        }
+        case 'wide_spread': {
+            return `High liquidity with ${spreadCents} cent spread`;
+        }
+    }
+}
+/**
+ * Filter markets based on criteria
+ */
+export function filterMarketsByCriteria(markets, criteria) {
+    return markets.filter(m => {
+        // Liquidity check
+        if (criteria.minLiquidity && m.liquidity < criteria.minLiquidity) {
+            return false;
+        }
+        // Spread checks
+        if (m.spread === null) {
+            // No spread data - exclude if spread filters are specified
+            if (criteria.minSpread || criteria.maxSpread) {
+                return false;
+            }
+        }
+        else {
+            if (criteria.minSpread && m.spread < criteria.minSpread) {
+                return false;
+            }
+            if (criteria.maxSpread && m.spread > criteria.maxSpread) {
+                return false;
+            }
+        }
+        // Volume check
+        if (criteria.minVolume && m.volume < criteria.minVolume) {
+            return false;
+        }
+        return true;
+    });
+}

package/docs/TRADING_STRATEGIES.md

@@ -0,0 +1,538 @@
+# Trading Strategies Guide for AI Agents
+
+This guide demonstrates how to use kalshitools' advanced analytics and scanning features to implement automated trading strategies. All examples use JSON output for programmatic integration.
+
+## Table of Contents
+
+- [Portfolio Analytics](#portfolio-analytics)
+- [Risk Management](#risk-management)
+- [Market Discovery](#market-discovery)
+- [Strategy Examples](#strategy-examples)
+- [Best Practices](#best-practices)
+
+---
+
+## Portfolio Analytics
+
+### Understanding Performance Metrics
+
+Get comprehensive portfolio analytics:
+
+```bash
+kalshitools portfolio analytics --period 30 --json
+```
+
+**Key Metrics:**
+
+```json
+{
+  "success": true,
+  "data": {
+    "trades": {
+      "total": 45,
+      "winning": 28,
+      "losing": 17,
+      "win_rate": 0.622
+    },
+    "pnl": {
+      "total_pnl": 1250.50,
+      "realized_pnl": 980.30,
+      "unrealized_pnl": 270.20,
+      "avg_win": 85.20,
+      "avg_loss": -42.30,
+      "total_return_pct": 12.51
+    },
+    "portfolio": {
+      "current_value": 11250.50,
+      "exposure": 2750.50,
+      "exposure_ratio": 0.244
+    },
+    "risk": {
+      "largest_position_pct": 15.2
+    }
+  }
+}
+```
+
+### Strategy Evaluation
+
+**Assessing Strategy Effectiveness:**
+
+```bash
+# Get 7-day performance
+kalshitools portfolio analytics --period 7 --json | jq '.data.trades.win_rate'
+
+# Get 30-day performance
+kalshitools portfolio analytics --period 30 --json | jq '.data.trades.win_rate'
+
+# Compare to determine if strategy is improving
+```
+
+**Key Questions to Answer:**
+
+1. **Is the win rate acceptable?** Target: > 55% for market-making, > 60% for directional
+2. **Is the average win > average loss?** Positive expectancy requires this
+3. **Is exposure ratio appropriate?** < 50% for conservative, < 80% for aggressive
+4. **Are fees eating into profits?** Monitor `fee_impact_pct`
+
+---
+
+## Risk Management
+
+### Real-Time Risk Assessment
+
+Check portfolio risk before adding new positions:
+
+```bash
+kalshitools portfolio risk --threshold 20 --json
+```
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "data": {
+    "risk_score": 45,
+    "risk_level": "MEDIUM",
+    "total_exposure": 2750.50,
+    "exposure_ratio": 0.244,
+    "concentrations": {
+      "by_ticker": [
+        {
+          "ticker": "MARKET-A",
+          "exposure": 1710.00,
+          "pct_of_portfolio": 15.2,
+          "alert": false
+        }
+      ]
+    },
+    "alerts": [],
+    "recommendations": {
+      "max_new_position_size": 2250.00
+    }
+  }
+}
+```
+
+### Position Sizing Strategy
+
+**Before Opening a Position:**
+
+```bash
+# Check recommended max position size
+MAX_SIZE=$(kalshitools portfolio risk --json | jq -r '.data.recommendations.max_new_position_size')
+
+# Use this to size your order
+kalshitools orders create \
+  --ticker MARKET-A \
+  --action buy \
+  --side yes \
+  --quantity $(echo "$MAX_SIZE / 0.50" | bc) \
+  --type limit \
+  --price 0.50
+```
+
+### Correlation Monitoring
+
+Detect correlated positions (multiple positions in same event):
+
+```bash
+kalshitools portfolio risk --group-by event --json | jq '.data.correlations'
+```
+
+**Use Case:**
+- Avoid over-exposure to single events
+- Diversify across uncorrelated markets
+- Reduce systematic risk
+
+---
+
+## Market Discovery
+
+### Finding Trading Opportunities
+
+Scan markets for high-quality opportunities:
+
+```bash
+kalshitools markets scan \
+  --min-liquidity 200 \
+  --min-spread 0.05 \
+  --max-spread 0.20 \
+  --min-volume 1000 \
+  --sort-by score \
+  --limit 20 \
+  --json
+```
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "data": {
+    "markets": [
+      {
+        "ticker": "MARKET-A",
+        "score": 85.5,
+        "spread": {
+          "yes_bid": 0.62,
+          "yes_ask": 0.68,
+          "spread_cents": 0.06
+        },
+        "liquidity": {
+          "total": 2430.00
+        },
+        "volume": {
+          "volume_24h": 8500.00
+        },
+        "opportunity_type": "wide_spread"
+      }
+    ]
+  }
+}
+```
+
+### Market-Making Strategy
+
+**Criteria for Market-Making:**
+- Wide spreads (> 0.05): Room for profit
+- High liquidity (> 200): Can enter/exit easily
+- Active volume (> 1000): Market is moving
+
+**Implementation:**
+
+```bash
+# Find markets with wide spreads
+MARKETS=$(kalshitools markets scan \
+  --min-spread 0.05 \
+  --min-liquidity 300 \
+  --sort-by spread \
+  --json | jq -r '.data.markets[].ticker')
+
+# For each market, place limit orders on both sides
+for TICKER in $MARKETS; do
+  # Get current orderbook
+  ORDERBOOK=$(kalshitools markets orderbook $TICKER --json)
+
+  # Calculate fair value and place orders
+  # (implementation depends on your pricing model)
+done
+```
+
+### Arbitrage Scanner
+
+Look for mispriced markets within the same event:
+
+```bash
+# Get all markets in an event
+EVENT_MARKETS=$(kalshitools markets list \
+  --event-ticker EVENT-2024 \
+  --status active \
+  --json)
+
+# Scan for opportunities
+kalshitools markets scan \
+  --event-ticker EVENT-2024 \
+  --min-liquidity 100 \
+  --json | jq '.data.markets[] | select(.spread.spread_cents > 0.10)'
+```
+
+---
+
+## Strategy Examples
+
+### 1. Mean Reversion Strategy
+
+**Goal:** Buy when price drops below historical average, sell when it rises above.
+
+**Implementation:**
+
+```bash
+# Step 1: Get historical performance for a ticker
+HISTORY=$(kalshitools portfolio history \
+  --ticker MARKET-A \
+  --group-by day \
+  --json)
+
+# Step 2: Calculate average price (pseudocode)
+AVG_PRICE=$(echo "$HISTORY" | jq '[.data.time_series.daily[].avg_price] | add / length')
+
+# Step 3: Get current price
+CURRENT_PRICE=$(kalshitools markets show MARKET-A --json | jq '.data.yes_bid')
+
+# Step 4: Trade if deviation > threshold
+if (( $(echo "$CURRENT_PRICE < $AVG_PRICE * 0.9" | bc -l) )); then
+  # Price is 10% below average - buy
+  kalshitools orders create --ticker MARKET-A --action buy --side yes ...
+fi
+```
+
+### 2. Momentum Strategy
+
+**Goal:** Follow trends by trading in the direction of recent price movement.
+
+**Implementation:**
+
+```bash
+# Get recent trading activity
+HISTORY=$(kalshitools portfolio history \
+  --ticker MARKET-A \
+  --group-by day \
+  --limit 10 \
+  --json)
+
+# Calculate momentum indicators
+# - Volume trend (increasing = strong momentum)
+# - Price trend (rising = bullish, falling = bearish)
+
+# Trade with the trend
+# (implementation depends on your momentum calculation)
+```
+
+### 3. Portfolio Rebalancing
+
+**Goal:** Maintain target exposure levels and concentration limits.
+
+**Implementation:**
+
+```bash
+# Step 1: Check current risk
+RISK=$(kalshitools portfolio risk --threshold 15 --json)
+
+# Step 2: Identify over-concentrated positions
+OVER_LIMIT=$(echo "$RISK" | jq -r '.data.concentrations.by_ticker[] | select(.alert == true) | .name')
+
+# Step 3: Reduce positions that exceed threshold
+for TICKER in $OVER_LIMIT; do
+  # Get current position
+  POSITION=$(kalshitools portfolio positions --json | \
+    jq -r ".data[] | select(.ticker == \"$TICKER\") | .position")
+
+  # Calculate amount to sell to reach target (15%)
+  TARGET_SIZE=$(echo "$RISK" | jq -r '.data.recommendations.max_new_position_size')
+
+  # Place sell order to reduce position
+  kalshitools orders create \
+    --ticker $TICKER \
+    --action sell \
+    --side yes \
+    --quantity $REDUCE_BY \
+    --type market
+done
+```
+
+### 4. Statistical Arbitrage
+
+**Goal:** Exploit pricing inefficiencies between correlated markets.
+
+**Implementation:**
+
+```bash
+# Step 1: Find correlated markets in same event
+kalshitools markets list --event-ticker EVENT-2024 --json
+
+# Step 2: Compare prices and liquidity
+kalshitools markets scan --event-ticker EVENT-2024 --json
+
+# Step 3: Identify spread > expected
+# If Market A + Market B should sum to 1.00, but sum to 1.10:
+# - Sell the overpriced side
+# - Buy the underpriced side
+# - Profit from convergence
+```
+
+---
+
+## Best Practices
+
+### 1. Pre-Trade Risk Checks
+
+**Always check risk before trading:**
+
+```bash
+# Create a pre-trade checklist function
+pre_trade_check() {
+  TICKER=$1
+  SIZE=$2
+
+  # Check 1: Portfolio risk
+  RISK_SCORE=$(kalshitools portfolio risk --json | jq -r '.data.risk_score')
+  if (( $(echo "$RISK_SCORE > 70" | bc -l) )); then
+    echo "ERROR: Portfolio risk too high ($RISK_SCORE/100)"
+    return 1
+  fi
+
+  # Check 2: Position size limit
+  MAX_SIZE=$(kalshitools portfolio risk --json | jq -r '.data.recommendations.max_new_position_size')
+  if (( $(echo "$SIZE > $MAX_SIZE" | bc -l) )); then
+    echo "ERROR: Position size exceeds limit ($SIZE > $MAX_SIZE)"
+    return 1
+  fi
+
+  # Check 3: Market liquidity
+  LIQUIDITY=$(kalshitools markets orderbook $TICKER --json | jq -r '.data.liquidity')
+  if (( $(echo "$LIQUIDITY < 100" | bc -l) )); then
+    echo "ERROR: Insufficient liquidity ($LIQUIDITY)"
+    return 1
+  fi
+
+  echo "Pre-trade checks passed"
+  return 0
+}
+
+# Use before every trade
+if pre_trade_check "MARKET-A" 500; then
+  kalshitools orders create --ticker MARKET-A ...
+fi
+```
+
+### 2. Performance Monitoring
+
+**Regular strategy evaluation:**
+
+```bash
+# Daily: Check win rate and P&L
+kalshitools portfolio analytics --period 1 --json > daily_analytics.json
+
+# Weekly: Compare to baseline
+kalshitools portfolio analytics --period 7 --json > weekly_analytics.json
+
+# Monthly: Full performance review
+kalshitools portfolio analytics --period 30 --json > monthly_analytics.json
+
+# Track metrics over time
+echo "$(date),$(jq -r '.data.trades.win_rate' daily_analytics.json)" >> performance_log.csv
+```
+
+### 3. Diversification
+
+**Spread risk across multiple markets:**
+
+```bash
+# Target: No single position > 20% of portfolio
+kalshitools portfolio risk --threshold 20 --json
+
+# Target: Max 3 positions per event
+kalshitools portfolio risk --group-by event --json | \
+  jq '.data.concentrations.by_event[] | select(.markets | length > 3)'
+
+# Rebalance if limits exceeded
+```
+
+### 4. Fee Optimization
+
+**Prefer maker orders to minimize fees:**
+
+```bash
+# Check maker vs taker ratio
+kalshitools portfolio history --json | jq '.data.maker_taker'
+
+# Target: > 70% maker fills for optimal fee structure
+# Maker fee: 0.5%, Taker fee: 1.5%
+# Use limit orders instead of market orders when possible
+```
+
+### 5. Rate Limiting
+
+**Respect API rate limits (20 req/sec for reads, 10 req/sec for writes):**
+
+```bash
+# Use sleep between API calls
+for TICKER in $TICKERS; do
+  kalshitools markets show $TICKER --json
+  sleep 0.1  # 100ms delay = max 10 req/sec
+done
+
+# Batch requests when possible
+kalshitools markets list --tickers "TICKER1,TICKER2,TICKER3" --json
+```
+
+---
+
+## Integration with OpenClaw
+
+kalshitools is designed for seamless integration with AI trading agents:
+
+```python
+import subprocess
+import json
+
+class KalshiAgent:
+    def get_analytics(self, period=30):
+        """Get portfolio analytics"""
+        result = subprocess.run(
+            ['kalshitools', 'portfolio', 'analytics',
+             '--period', str(period), '--json'],
+            capture_output=True, text=True
+        )
+        return json.loads(result.stdout)
+
+    def check_risk(self, threshold=20):
+        """Check portfolio risk"""
+        result = subprocess.run(
+            ['kalshitools', 'portfolio', 'risk',
+             '--threshold', str(threshold), '--json'],
+            capture_output=True, text=True
+        )
+        return json.loads(result.stdout)
+
+    def scan_markets(self, min_liquidity=200, min_spread=0.05):
+        """Scan for opportunities"""
+        result = subprocess.run(
+            ['kalshitools', 'markets', 'scan',
+             '--min-liquidity', str(min_liquidity),
+             '--min-spread', str(min_spread),
+             '--json'],
+            capture_output=True, text=True
+        )
+        return json.loads(result.stdout)
+
+    def make_decision(self):
+        """Example trading decision logic"""
+        # Get current portfolio state
+        analytics = self.get_analytics(period=7)
+        risk = self.check_risk(threshold=20)
+
+        # Check if we should trade
+        if analytics['data']['trades']['win_rate'] < 0.5:
+            return "SKIP", "Win rate too low"
+
+        if risk['data']['risk_score'] > 70:
+            return "SKIP", "Portfolio risk too high"
+
+        # Find opportunities
+        opportunities = self.scan_markets()
+
+        if len(opportunities['data']['markets']) == 0:
+            return "SKIP", "No opportunities found"
+
+        # Take best opportunity
+        best = opportunities['data']['markets'][0]
+        max_size = risk['data']['recommendations']['max_new_position_size']
+
+        return "TRADE", {
+            'ticker': best['ticker'],
+            'size': max_size,
+            'reason': best['reason']
+        }
+```
+
+---
+
+## Summary
+
+kalshitools provides four key capabilities for automated trading:
+
+1. **Portfolio Analytics**: Measure strategy performance
+2. **Risk Management**: Control exposure and concentration
+3. **Historical Analysis**: Learn from past trades
+4. **Market Scanner**: Discover opportunities systematically
+
+All commands output structured JSON for easy integration with AI agents and automated systems.
+
+**Next Steps:**
+- Start with manual exploration using the CLI
+- Build analytics dashboards using the JSON output
+- Implement automated strategies with proper risk controls
+- Monitor performance and iterate on your approach