kalshi-trading-bot-cli 2.1.0

package/src/scan/octagon-events-api.ts

@@ -0,0 +1,105 @@
+/**
+ * A single event entry from the Octagon Prediction Markets Events API.
+ * Probabilities are percentages (0-100).
+ */
+export interface OctagonEventEntry {
+  history_id: number;
+  run_id: string;
+  captured_at: string;
+  event_ticker: string;
+  name: string;
+  slug: string;
+  image_url?: string;
+  series_category: string;
+  available_on_brokers: boolean;
+  mutually_exclusive: boolean;
+  analysis_last_updated: string;
+  confidence_score: number;
+  model_probability: number;
+  market_probability: number;
+  edge_pp: number;
+  expected_return: number;
+  r_score: number;
+  total_volume: number;
+  total_open_interest: number;
+  close_time: string;
+  key_takeaway: string;
+  has_history?: boolean;
+  outcome_probabilities?: Array<{
+    market_ticker: string;
+    outcome_name?: string;
+    model_probability: number;
+    market_probability: number;
+    volume?: number | null;
+    volume_24h?: number | null;
+  }> | null;
+  current_state_summary_richtext?: string;
+  short_answer_richtext?: string;
+  executive_summary_richtext?: string;
+}
+
+interface EventsPage {
+  data: OctagonEventEntry[];
+  next_cursor: string | null;
+  has_more: boolean;
+}
+
+const EVENTS_API_BASE = 'https://api.octagonai.co/v1';
+const PAGE_LIMIT = 200;
+const TIMEOUT_MS = 60_000;
+
+/**
+ * Fetch all events from the Octagon Prediction Markets Events API,
+ * paginating through all pages.
+ * @param opts.hasHistory - When true, only return events with multiple historical snapshots.
+ *   Note: The events list endpoint now returns `has_history` per event, so this filter
+ *   is only needed if you want to reduce response size.
+ */
+export async function fetchAllOctagonEvents(opts?: { hasHistory?: boolean }): Promise<OctagonEventEntry[]> {
+  const apiKey = process.env.OCTAGON_API_KEY;
+  if (!apiKey) throw new Error('OCTAGON_API_KEY not set');
+
+  const all: OctagonEventEntry[] = [];
+  let cursor: string | null = null;
+
+  do {
+    const params = new URLSearchParams({ limit: String(PAGE_LIMIT) });
+    if (opts?.hasHistory) params.set('has_history', 'true');
+    if (cursor) params.set('cursor', cursor);
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+    let resp: Response;
+    try {
+      resp = await fetch(`${EVENTS_API_BASE}/prediction-markets/events?${params}`, {
+        headers: { Authorization: `Bearer ${apiKey}` },
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+
+    if (!resp.ok) {
+      const body = await resp.text().catch(() => '');
+      throw new Error(`Octagon events API ${resp.status}: ${body.slice(0, 200)}`);
+    }
+
+    const page = (await resp.json()) as unknown;
+    if (!page || typeof page !== 'object') {
+      throw new Error('Octagon events API returned invalid response shape');
+    }
+    const p = page as Record<string, unknown>;
+    if (!Array.isArray(p.data)) {
+      throw new Error('Octagon events API response missing data array');
+    }
+    const hasMore = typeof p.has_more === 'boolean' ? p.has_more : false;
+    if (hasMore && !p.next_cursor) {
+      throw new Error('Octagon events API has_more=true but next_cursor is missing');
+    }
+    all.push(...(p.data as OctagonEventEntry[]));
+    cursor = hasMore ? (p.next_cursor as string) : null;
+  } while (cursor);
+
+  return all;
+}

package/src/scan/octagon-prefetch.ts

@@ -0,0 +1,172 @@
+import type { Database } from 'bun:sqlite';
+import { fetchAllOctagonEvents, type OctagonEventEntry } from './octagon-events-api.js';
+import { insertReport, getLatestReport, getTtlForCloseTime } from '../db/octagon-cache.js';
+import { insertEdge } from '../db/edge.js';
+
+const PREFETCH_COOLDOWN_MS = 60 * 60 * 1000; // 1 hour
+const META_KEY = 'octagon_prefetch_at';
+
+/**
+ * Check if a prefetch is needed (more than 1h since last one).
+ */
+function shouldPrefetch(db: Database): boolean {
+  const row = db.query("SELECT value FROM event_index_meta WHERE key = $key").get({
+    $key: META_KEY,
+  }) as { value: string } | null;
+  if (!row) return true;
+  const lastPrefetch = parseInt(row.value, 10);
+  if (!Number.isFinite(lastPrefetch)) return true;
+  return Date.now() - lastPrefetch > PREFETCH_COOLDOWN_MS;
+}
+
+function markPrefetchDone(db: Database): void {
+  db.query("INSERT OR REPLACE INTO event_index_meta (key, value) VALUES ($key, $value)").run({
+    $key: META_KEY,
+    $value: String(Date.now()),
+  });
+}
+
+/**
+ * Infer a mispricing signal from the edge.
+ */
+function inferSignal(modelProb: number, marketProb: number): string {
+  const edge = modelProb - marketProb;
+  if (Math.abs(edge) < 0.03) return 'fair_value';
+  return edge > 0 ? 'underpriced' : 'overpriced';
+}
+
+/**
+ * Classify confidence from absolute edge.
+ */
+function classifyConfidence(absEdge: number): string {
+  if (absEdge >= 0.10) return 'very_high';
+  if (absEdge >= 0.05) return 'high';
+  if (absEdge >= 0.02) return 'moderate';
+  return 'low';
+}
+
+/**
+ * Convert an Octagon event entry to local DB records and persist.
+ * Returns true if a new record was inserted, false if skipped.
+ */
+function persistEvent(db: Database, event: OctagonEventEntry): boolean {
+  const capturedDate = new Date(event.captured_at);
+  const closeDate = new Date(event.close_time);
+  if (isNaN(capturedDate.getTime()) || isNaN(closeDate.getTime())) return false;
+  const capturedAt = Math.floor(capturedDate.getTime() / 1000);
+  const closeTime = Math.floor(closeDate.getTime() / 1000);
+
+  // Probabilities from the events API are percentages (0-100)
+  const modelProb = event.model_probability / 100;
+  const marketProb = event.market_probability / 100;
+
+  // Skip events with no model analysis — unless they have per-market outcome data
+  const hasOutcomes = Array.isArray(event.outcome_probabilities) && event.outcome_probabilities.length > 0;
+  if ((event.model_probability === 0 || event.model_probability == null) && !hasOutcomes) return false;
+
+  // Always update close_time on existing events-api reports (backfill)
+  db.prepare(
+    "UPDATE octagon_reports SET close_time = $ct WHERE event_ticker = $et AND variant_used = 'events-api' AND close_time IS NULL",
+  ).run({ $et: event.event_ticker, $ct: event.close_time ?? null });
+
+  // Skip if we already have a fresher report for this event
+  const existing = getLatestReport(db, event.event_ticker);
+  if (existing && existing.fetched_at >= capturedAt) return false;
+
+  const ttl = getTtlForCloseTime(Math.max(0, closeTime - capturedAt));
+  const reportId = `events-api-${event.event_ticker}-${capturedAt}`;
+
+  // Insert report and set metadata in a single transaction
+  db.transaction(() => {
+    insertReport(db, {
+      report_id: reportId,
+      ticker: event.event_ticker,
+      event_ticker: event.event_ticker,
+      model_prob: modelProb,
+      market_prob: marketProb,
+      mispricing_signal: inferSignal(modelProb, marketProb),
+      drivers_json: JSON.stringify([{
+        claim: event.key_takeaway || event.name,
+        category: (event.series_category || 'other').toLowerCase(),
+        impact: 'medium',
+      }]),
+      catalysts_json: null,
+      sources_json: null,
+      resolution_history_json: null,
+      contract_snapshot_json: null,
+      raw_response: null,
+      variant_used: 'events-api',
+      fetched_at: capturedAt,
+      expires_at: capturedAt + ttl,
+    });
+
+    db.prepare(
+      `UPDATE octagon_reports SET has_history = $hh, mutually_exclusive = $me, series_category = $sc,
+         confidence_score = $cs, outcome_probabilities_json = $opj, close_time = $ct
+       WHERE report_id = $rid`,
+    ).run({
+      $rid: reportId,
+      $hh: event.has_history ? 1 : 0,
+      $me: event.mutually_exclusive ? 1 : 0,
+      $sc: event.series_category ?? null,
+      $cs: event.confidence_score ?? null,
+      $opj: event.outcome_probabilities ? JSON.stringify(event.outcome_probabilities) : null,
+      $ct: event.close_time ?? null,
+    });
+  })();
+
+  // Also persist to edge_history
+  const edge = modelProb - marketProb;
+  try {
+    insertEdge(db, {
+      ticker: event.event_ticker,
+      event_ticker: event.event_ticker,
+      timestamp: capturedAt,
+      model_prob: modelProb,
+      market_prob: marketProb,
+      edge,
+      octagon_report_id: reportId,
+      drivers_json: null,
+      sources_json: null,
+      catalysts_json: null,
+      cache_hit: 1,
+      cache_miss: 0,
+      confidence: classifyConfidence(Math.abs(edge)),
+    });
+  } catch (err) {
+    // Only swallow UNIQUE constraint violations (duplicate ticker+timestamp)
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/UNIQUE constraint failed/i.test(msg)) {
+      // Expected — edge already exists for this ticker+timestamp
+    } else {
+      throw err;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Fetch all Octagon events via the REST API and persist them locally.
+ * Runs only if the last prefetch was more than 1h ago.
+ */
+export async function prefetchOctagonEvents(db: Database): Promise<{ inserted: number; skipped: number }> {
+  if (!shouldPrefetch(db)) {
+    return { inserted: 0, skipped: 0 };
+  }
+
+  const events = await fetchAllOctagonEvents();
+  let inserted = 0;
+  let skipped = 0;
+
+  for (const event of events) {
+    if (persistEvent(db, event)) {
+      inserted++;
+    } else {
+      skipped++;
+    }
+  }
+
+  markPrefetchDone(db);
+  return { inserted, skipped };
+}

package/src/scan/theme-resolver.ts

@@ -0,0 +1,179 @@
+import type { Database } from 'bun:sqlite';
+import type { AuditTrail } from '../audit/trail.js';
+import { callKalshiApi, fetchAllPages } from '../tools/kalshi/api.js';
+import type { KalshiEvent, KalshiMarket, KalshiSeries } from '../tools/kalshi/types.js';
+import { ensureIndex, getRefreshPromise } from '../tools/kalshi/search-index.js';
+import { upsertEvent, deactivateExpired } from '../db/events.js';
+import { getThemeTickers } from '../db/themes.js';
+
+/** Maps lowercase theme IDs → exact Kalshi category labels */
+export const CATEGORY_MAP: Record<string, string> = {
+  'climate': 'Climate and Weather',
+  'companies': 'Companies',
+  'crypto': 'Crypto',
+  'economics': 'Economics',
+  'elections': 'Elections',
+  'entertainment': 'Entertainment',
+  'financials': 'Financials',
+  'health': 'Health',
+  'mentions': 'Mentions',
+  'politics': 'Politics',
+  'science': 'Science and Technology',
+  'social': 'Social',
+  'sports': 'Sports',
+  'transportation': 'Transportation',
+  'world': 'World',
+};
+
+/**
+ * Fetch all series from Kalshi and build a map of category → sorted subcategory tags.
+ * Each series has a `tags` field; we collect unique tags per category.
+ */
+export async function fetchSubcategories(): Promise<Record<string, string[]>> {
+  const allSeries = await fetchAllPages<KalshiSeries>('/series', {}, 'series', 50);
+  const catTags: Record<string, Set<string>> = {};
+
+  for (const s of allSeries) {
+    const cat = s.category;
+    if (!cat) continue;
+    if (!catTags[cat]) catTags[cat] = new Set();
+    for (const tag of s.tags ?? []) {
+      catTags[cat].add(tag);
+    }
+  }
+
+  const result: Record<string, string[]> = {};
+  for (const [cat, tags] of Object.entries(catTags)) {
+    result[cat] = [...tags].sort((a, b) => a.localeCompare(b, undefined, { sensitivity: 'base' }));
+  }
+  return result;
+}
+
+export class ThemeResolver {
+  private db: Database;
+  private audit: AuditTrail;
+
+  constructor(db: Database, audit: AuditTrail) {
+    this.db = db;
+    this.audit = audit;
+  }
+
+  async resolve(themeName: string): Promise<string[]> {
+    const now = Math.floor(Date.now() / 1000);
+    let eventTickers: string[];
+
+    if (themeName === 'top50') {
+      eventTickers = await this.resolveTop50();
+    } else if (themeName.includes(':')) {
+      // Subcategory filter: "crypto:btc", "sports:football"
+      eventTickers = await this.resolveSubcategory(themeName);
+    } else if (CATEGORY_MAP[themeName]) {
+      eventTickers = await this.resolveCategory(themeName);
+    } else {
+      eventTickers = getThemeTickers(this.db, themeName);
+    }
+
+    // Upsert resolved events
+    for (const ticker of eventTickers) {
+      upsertEvent(this.db, { ticker, active: 1, updated_at: now });
+    }
+
+    // Deactivate expired events
+    deactivateExpired(this.db, now);
+
+    // Audit log
+    this.audit.log({
+      type: 'SCAN_START',
+      theme: themeName,
+      events_count: eventTickers.length,
+    });
+
+    return eventTickers;
+  }
+
+  private async resolveTop50(): Promise<string[]> {
+    const markets = await fetchAllPages<KalshiMarket>(
+      '/markets',
+      { status: 'open', limit: 200 },
+      'markets',
+      3
+    );
+
+    // Sort by volume_24h descending
+    markets.sort((a, b) => (b.volume_24h ?? 0) - (a.volume_24h ?? 0));
+
+    // Take top 50 unique event tickers
+    const seen = new Set<string>();
+    const result: string[] = [];
+    for (const m of markets) {
+      if (!seen.has(m.event_ticker)) {
+        seen.add(m.event_ticker);
+        result.push(m.event_ticker);
+        if (result.length >= 50) break;
+      }
+    }
+    return result;
+  }
+
+  private async resolveCategory(themeName: string): Promise<string[]> {
+    const categoryLabel = CATEGORY_MAP[themeName];
+    // Kalshi /events API does not support server-side category filtering,
+    // so query the local SQLite index instead of fetching all open events
+    await ensureIndex();
+    // If ensureIndex kicked off a background refresh (first run / empty index),
+    // await it so we don't query an unpopulated event_index table
+    const pending = getRefreshPromise();
+    if (pending) await pending;
+    const rows = this.db.query(
+      `SELECT event_ticker FROM event_index WHERE category = ?`,
+    ).all(categoryLabel) as { event_ticker: string }[];
+    return rows.map((r) => r.event_ticker);
+  }
+
+  private async resolveSubcategory(themeName: string): Promise<string[]> {
+    const [catKey, ...subParts] = themeName.split(':');
+    const subTag = subParts.join(':').toLowerCase();
+    const categoryLabel = CATEGORY_MAP[catKey];
+    if (!categoryLabel) return [];
+
+    // Find series in this category with matching tag
+    const allSeries = await fetchAllPages<KalshiSeries>('/series', { category: categoryLabel }, 'series', 50);
+    const matchingSeries = new Set<string>();
+    for (const s of allSeries) {
+      if (s.category !== categoryLabel) continue;
+      const hasTag = (s.tags ?? []).some((t) => {
+        const tagLower = t.toLowerCase();
+        const tagKebab = tagLower.replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+        return tagLower === subTag || tagKebab === subTag;
+      });
+      if (hasTag) matchingSeries.add(s.ticker);
+    }
+
+    if (matchingSeries.size === 0) return [];
+
+    // Fetch open events for matching series in parallel (server-side filtered)
+    const results = await Promise.all(
+      [...matchingSeries].map((seriesTicker) =>
+        fetchAllPages<KalshiEvent>(
+          '/events',
+          { status: 'open', series_ticker: seriesTicker },
+          'events',
+          50
+        )
+      )
+    );
+
+    const seen = new Set<string>();
+    const eventTickers: string[] = [];
+    for (const events of results) {
+      for (const e of events) {
+        if (!seen.has(e.event_ticker)) {
+          seen.add(e.event_ticker);
+          eventTickers.push(e.event_ticker);
+        }
+      }
+    }
+
+    return eventTickers;
+  }
+}

package/src/scan/types.ts

@@ -0,0 +1,62 @@
+export type OctagonVariant = 'default' | 'cache' | 'refresh';
+
+export type MispricingSignal = 'overpriced' | 'underpriced' | 'fair_value';
+
+export type OctagonInvoker = (ticker: string, variant: OctagonVariant) => Promise<string>;
+
+export type DriverCategory = 'political' | 'economic' | 'sentiment' | 'technical';
+export type DriverImpact = 'high' | 'medium' | 'low';
+
+export interface PriceDriver {
+  claim: string;
+  category: DriverCategory;
+  impact: DriverImpact;
+  sourceUrl?: string;
+}
+
+export interface Catalyst {
+  date: string; // ISO date
+  event: string;
+  impact: DriverImpact;
+  potentialMove: string;
+}
+
+export interface Source {
+  url: string;
+  title?: string;
+}
+
+export interface OctagonReport {
+  ticker: string;
+  eventTicker: string;
+  modelProb: number;
+  marketProb: number;
+  mispricingSignal: MispricingSignal;
+  drivers: PriceDriver[];
+  catalysts: Catalyst[];
+  sources: Source[];
+  resolutionHistory: string;
+  contractSnapshot: string;
+  variantUsed: OctagonVariant;
+  fetchedAt: number; // epoch seconds
+  rawResponse: string; // full raw Octagon API response
+  cacheMiss: boolean; // true when cache returned no meaningful data
+  reportId: string; // persisted DB report_id (UUID)
+}
+
+export type ConfidenceLevel = 'low' | 'moderate' | 'high' | 'very_high';
+
+export interface EdgeSnapshot {
+  ticker: string;            // market ticker e.g. 'KXBTC-26MAR-B80000'
+  eventTicker: string;       // event ticker e.g. 'KXBTC-26MAR'
+  modelProb: number;         // Octagon probability [0, 1]
+  marketProb: number;        // Kalshi mid price as probability [0, 1]
+  edge: number;              // modelProb - marketProb (signed)
+  confidence: ConfidenceLevel;
+  drivers: PriceDriver[];
+  catalysts: Catalyst[];
+  sources: Source[];
+  octagonReportId: string;
+  cacheHit: boolean;
+  timestamp: number;         // epoch seconds
+}

package/src/scan/watchdog.ts

@@ -0,0 +1,126 @@
+import type { Database } from 'bun:sqlite';
+import type { AuditTrail } from '../audit/trail.js';
+import type { Position } from '../db/positions.js';
+import type { Catalyst } from './types.js';
+import { getOpenPositions } from '../db/positions.js';
+import { getLatestEdge } from '../db/edge.js';
+import { getEvent } from '../db/events.js';
+
+export type WatchdogAlertType =
+  | 'CONVERGENCE'
+  | 'ADVERSE_MOVE'
+  | 'EXPIRY_APPROACHING'
+  | 'CATALYST_APPROACHING';
+
+export interface WatchdogAlert {
+  ticker: string;
+  alertType: WatchdogAlertType;
+  edge: number;
+  entryEdge: number;
+  message: string;
+  position: Position;
+}
+
+const CONVERGENCE_THRESHOLD = 0.02;
+const EXPIRY_WINDOW = 24 * 3600;
+const CATALYST_WINDOW = 24 * 3600;
+
+export class PositionWatchdog {
+  private audit: AuditTrail;
+
+  constructor(audit: AuditTrail) {
+    this.audit = audit;
+  }
+
+  check(db: Database, now?: number): WatchdogAlert[] {
+    const currentTime = now ?? Math.floor(Date.now() / 1000);
+    const positions = getOpenPositions(db);
+    const alerts: WatchdogAlert[] = [];
+
+    for (const position of positions) {
+      const edgeRow = getLatestEdge(db, position.ticker);
+      if (!edgeRow) continue;
+
+      const currentEdge = edgeRow.edge;
+      const entryEdge = position.entry_edge ?? 0;
+      const statuses: string[] = [];
+
+      // CONVERGENCE: edge has shrunk to near zero
+      if (Math.abs(currentEdge) < CONVERGENCE_THRESHOLD) {
+        statuses.push('CONVERGENCE');
+        alerts.push({
+          ticker: position.ticker,
+          alertType: 'CONVERGENCE',
+          edge: currentEdge,
+          entryEdge,
+          message: `Edge converged to ${currentEdge.toFixed(4)} (threshold ${CONVERGENCE_THRESHOLD})`,
+          position,
+        });
+      }
+
+      // ADVERSE_MOVE: edge flipped sign from entry
+      if (entryEdge * currentEdge < 0) {
+        statuses.push('ADVERSE_MOVE');
+        alerts.push({
+          ticker: position.ticker,
+          alertType: 'ADVERSE_MOVE',
+          edge: currentEdge,
+          entryEdge,
+          message: `Edge flipped sign: entry=${entryEdge.toFixed(4)}, current=${currentEdge.toFixed(4)}`,
+          position,
+        });
+      }
+
+      // EXPIRY_APPROACHING: event expires within 24h
+      const event = getEvent(db, position.event_ticker);
+      if (event?.expiry && event.expiry - currentTime < EXPIRY_WINDOW) {
+        statuses.push('EXPIRY_APPROACHING');
+        const hoursLeft = Math.max(0, (event.expiry - currentTime) / 3600);
+        alerts.push({
+          ticker: position.ticker,
+          alertType: 'EXPIRY_APPROACHING',
+          edge: currentEdge,
+          entryEdge,
+          message: `Event ${position.event_ticker} expires in ${hoursLeft.toFixed(1)}h`,
+          position,
+        });
+      }
+
+      // CATALYST_APPROACHING: high-impact catalyst within 24h
+      if (edgeRow.catalysts_json) {
+        try {
+          const catalysts: Catalyst[] = JSON.parse(edgeRow.catalysts_json);
+          for (const catalyst of catalysts) {
+            if (catalyst.impact === 'high') {
+              const catalystTime = new Date(catalyst.date).getTime() / 1000;
+              if (catalystTime - currentTime > 0 && catalystTime - currentTime < CATALYST_WINDOW) {
+                statuses.push('CATALYST_APPROACHING');
+                alerts.push({
+                  ticker: position.ticker,
+                  alertType: 'CATALYST_APPROACHING',
+                  edge: currentEdge,
+                  entryEdge,
+                  message: `High-impact catalyst "${catalyst.event}" approaching: ${catalyst.date}`,
+                  position,
+                });
+              }
+            }
+          }
+        } catch {
+          // Ignore malformed catalysts JSON
+        }
+      }
+
+      const status = statuses.length > 0 ? statuses.join(',') : 'healthy';
+      this.audit.log({
+        type: 'WATCHDOG_CHECK',
+        ticker: position.ticker,
+        entry_edge: entryEdge,
+        current_edge: currentEdge,
+        status,
+      });
+    }
+
+    return alerts;
+  }
+}