kalshi-trading-bot-cli 2.1.0

package/src/tools/kalshi/types.ts

@@ -0,0 +1,199 @@
+export interface KalshiBalance {
+  balance: number;
+  portfolio_value: number;
+  updated_ts?: number;
+}
+
+export interface KalshiMarket {
+  ticker: string;
+  event_ticker: string;
+  market_type: string;
+  title: string;
+  subtitle: string;
+  yes_sub_title: string;
+  no_sub_title: string;
+  open_time: string;
+  close_time: string;
+  expected_expiration_time: string;
+  expiration_time: string;
+  latest_expiration_time: string;
+  settlement_timer_seconds: number;
+  status: string;
+  response_price_units: string;
+  notional_value: number;
+  tick_size: number;
+  yes_bid: number;
+  yes_ask: number;
+  no_bid: number;
+  no_ask: number;
+  last_price: number;
+  previous_yes_bid: number;
+  previous_yes_ask: number;
+  previous_price: number;
+  volume: number;
+  volume_fp?: string;
+  volume_24h: number;
+  volume_24h_fp?: string;
+  liquidity: number;
+  open_interest: number;
+  result: string;
+  settlement_value: string;
+  can_close_early: boolean;
+  expiration_value: string;
+  category: string;
+  risk_limit_cents: number;
+  strike_type: string;
+  floor_strike: number;
+  cap_strike: number;
+  supports_fractional?: boolean;
+  // New API format (yes_*_dollars)
+  yes_bid_dollars?: string;
+  yes_ask_dollars?: string;
+  no_bid_dollars?: string;
+  no_ask_dollars?: string;
+  last_price_dollars?: string;
+  // Legacy API format (dollar_yes_*)
+  dollar_yes_bid?: string;
+  dollar_yes_ask?: string;
+  dollar_no_bid?: string;
+  dollar_no_ask?: string;
+  dollar_last_price?: string;
+}
+
+export interface KalshiEvent {
+  event_ticker: string;
+  series_ticker: string;
+  sub_title: string;
+  title: string;
+  mutually_exclusive: boolean;
+  category: string;
+  strike_date: string;
+  markets?: KalshiMarket[];
+}
+
+export interface KalshiSeries {
+  ticker: string;
+  frequency: string;
+  title: string;
+  category: string;
+  tags: string[];
+  settlement_sources: Array<{ url: string; name: string }>;
+  contract_url: string;
+}
+
+export interface KalshiOrder {
+  order_id: string;
+  user_id: string;
+  ticker: string;
+  client_order_id?: string;
+  status: string;
+  yes_price_dollars?: string;
+  no_price_dollars?: string;
+  /** @deprecated old API field */
+  yes_price?: number;
+  /** @deprecated old API field */
+  no_price?: number;
+  created_time: string;
+  expiration_time?: string | null;
+  action: string;
+  side: string;
+  type: string;
+  initial_count_fp?: string;
+  remaining_count_fp?: string;
+  fill_count_fp?: string;
+  /** @deprecated old API field */
+  contracts_count?: number;
+  /** @deprecated old API field */
+  remaining_count?: number;
+  maker_fees_dollars?: string;
+  taker_fees_dollars?: string;
+  maker_fill_cost_dollars?: string;
+  taker_fill_cost_dollars?: string;
+  order_group_id?: string | null;
+  subaccount_number?: number;
+  last_update_time?: string;
+}
+
+export interface KalshiPosition {
+  ticker: string;
+  event_ticker: string;
+  position: number;
+  position_fp?: number;
+  resting_orders_count: number;
+  market_exposure: number;
+  market_exposure_dollars?: string;
+  realized_pnl: number;
+  realized_pnl_dollars?: string;
+  total_traded: number;
+  total_traded_dollars?: string;
+  fees_paid: number;
+  fees_paid_dollars?: string;
+}
+
+export interface KalshiFill {
+  trade_id: string;
+  order_id: string;
+  ticker: string;
+  side: string;
+  action: string;
+  count: number;
+  yes_price: number;
+  no_price: number;
+  is_taker: boolean;
+  created_time: string;
+}
+
+export interface KalshiOrderbookEntry {
+  price: number;
+  delta: number;
+}
+
+export interface KalshiOrderbook {
+  ticker: string;
+  yes: KalshiOrderbookEntry[];
+  no: KalshiOrderbookEntry[];
+}
+
+export interface KalshiCandlestick {
+  ts: number;
+  yes_bid: { close: number; high: number; low: number; open: number };
+  yes_ask: { close: number; high: number; low: number; open: number };
+  last_price: { close: number; high: number; low: number; open: number };
+  volume: number;
+  open_interest: number;
+}
+
+export interface KalshiSettlement {
+  ticker: string;
+  settled_time: string;
+  market_result: string;
+  no_count: number;
+  no_total_cost: number;
+  yes_count: number;
+  yes_total_cost: number;
+  revenue: number;
+}
+
+export interface KalshiExchangeStatus {
+  exchange_active: boolean;
+  trading_active: boolean;
+}
+
+export interface KalshiDollarOrderRequest {
+  ticker: string;
+  action: "buy" | "sell";
+  side: "yes" | "no";
+  type: "limit" | "market";
+  count: number;
+  dollar_price?: string;
+  expiration_ts?: number;
+  client_order_id?: string;
+}
+
+export interface KalshiExchangeSchedule {
+  schedule: Array<{
+    open_time: string;
+    close_time: string;
+    maintenance_windows?: Array<{ start_time: string; end_time: string }>;
+  }>;
+}

package/src/tools/registry.ts

@@ -0,0 +1,160 @@
+import { StructuredToolInterface } from '@langchain/core/tools';
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+import { createKalshiSearch, KALSHI_SEARCH_DESCRIPTION } from './kalshi/kalshi-search.js';
+import { createKalshiTrade, KALSHI_TRADE_DESCRIPTION } from './kalshi/kalshi-trade.js';
+import { getExchangeStatus } from './kalshi/exchange.js';
+import { callKalshiApi } from './kalshi/api.js';
+import { tavilySearch, WEB_SEARCH_DESCRIPTION } from './search/index.js';
+import { webFetchTool, WEB_FETCH_DESCRIPTION } from './fetch/web-fetch.js';
+import { formatToolResult } from './types.js';
+import { edgeQueryTool, EDGE_QUERY_DESCRIPTION } from './v2/edge-query.js';
+import { portfolioQueryTool, PORTFOLIO_QUERY_DESCRIPTION } from './v2/portfolio-query.js';
+import { riskStatusTool, RISK_STATUS_DESCRIPTION } from './v2/risk-status.js';
+import { octagonReportTool, OCTAGON_REPORT_DESCRIPTION } from './v2/octagon-report.js';
+import { scanTool, SCAN_DESCRIPTION } from './v2/scan.js';
+import { portfolioReviewTool, PORTFOLIO_REVIEW_DESCRIPTION } from './v2/portfolio-review.js';
+
+/**
+ * A registered tool with its rich description for system prompt injection.
+ */
+export interface RegisteredTool {
+  /** Tool name (must match the tool's name property) */
+  name: string;
+  /** The actual tool instance */
+  tool: StructuredToolInterface;
+  /** Rich description for system prompt (includes when to use, when not to use, etc.) */
+  description: string;
+}
+
+// Direct portfolio overview tool (balance + positions in one call)
+const portfolioOverviewTool = new DynamicStructuredTool({
+  name: 'portfolio_overview',
+  description: 'Get a quick overview of the Kalshi portfolio: balance and open positions.',
+  schema: z.object({}),
+  func: async () => {
+    const [balanceData, positionsData] = await Promise.all([
+      callKalshiApi('GET', '/portfolio/balance'),
+      callKalshiApi('GET', '/portfolio/positions'),
+    ]);
+    return formatToolResult({ balance: balanceData, positions: positionsData });
+  },
+});
+
+const PORTFOLIO_OVERVIEW_DESCRIPTION = `
+Quick portfolio overview tool. Returns current account balance and all open positions in a single call.
+
+## When to Use
+- User asks "what's my portfolio?" or "show me my balance and positions"
+- Quick portfolio check before or after trading
+
+## When NOT to Use
+- Detailed fills or order history (use kalshi_search instead)
+`.trim();
+
+const EXCHANGE_STATUS_DESCRIPTION = `
+Check whether the Kalshi exchange is currently active and trading is enabled.
+
+## When to Use
+- "Is Kalshi open?" or "Can I trade right now?"
+`.trim();
+
+/**
+ * Get all registered tools with their descriptions.
+ *
+ * @param model - The model name (needed for sub-agent meta-tools)
+ * @returns Array of registered tools
+ */
+export function getToolRegistry(model: string): RegisteredTool[] {
+  const tools: RegisteredTool[] = [
+    {
+      name: 'kalshi_search',
+      tool: createKalshiSearch(model),
+      description: KALSHI_SEARCH_DESCRIPTION,
+    },
+    {
+      name: 'kalshi_trade',
+      tool: createKalshiTrade(model),
+      description: KALSHI_TRADE_DESCRIPTION,
+    },
+    {
+      name: 'portfolio_overview',
+      tool: portfolioOverviewTool,
+      description: PORTFOLIO_OVERVIEW_DESCRIPTION,
+    },
+    {
+      name: 'exchange_status',
+      tool: getExchangeStatus,
+      description: EXCHANGE_STATUS_DESCRIPTION,
+    },
+    {
+      name: 'web_fetch',
+      tool: webFetchTool,
+      description: WEB_FETCH_DESCRIPTION,
+    },
+    {
+      name: 'edge_query',
+      tool: edgeQueryTool,
+      description: EDGE_QUERY_DESCRIPTION,
+    },
+    {
+      name: 'portfolio_query',
+      tool: portfolioQueryTool,
+      description: PORTFOLIO_QUERY_DESCRIPTION,
+    },
+    {
+      name: 'risk_status',
+      tool: riskStatusTool,
+      description: RISK_STATUS_DESCRIPTION,
+    },
+    {
+      name: 'octagon_report',
+      tool: octagonReportTool,
+      description: OCTAGON_REPORT_DESCRIPTION,
+    },
+    {
+      name: 'scan_markets',
+      tool: scanTool,
+      description: SCAN_DESCRIPTION,
+    },
+    {
+      name: 'portfolio_review',
+      tool: portfolioReviewTool,
+      description: PORTFOLIO_REVIEW_DESCRIPTION,
+    },
+  ];
+
+  // Include web_search if Tavily API key is configured
+  if (process.env.TAVILY_API_KEY) {
+    tools.push({
+      name: 'web_search',
+      tool: tavilySearch,
+      description: WEB_SEARCH_DESCRIPTION,
+    });
+  }
+
+  return tools;
+}
+
+/**
+ * Get just the tool instances for binding to the LLM.
+ *
+ * @param model - The model name
+ * @returns Array of tool instances
+ */
+export function getTools(model: string): StructuredToolInterface[] {
+  return getToolRegistry(model).map((t) => t.tool);
+}
+
+/**
+ * Build the tool descriptions section for the system prompt.
+ * Formats each tool's rich description with a header.
+ *
+ * @param model - The model name
+ * @returns Formatted string with all tool descriptions
+ */
+export function buildToolDescriptions(model: string): string {
+  return getToolRegistry(model)
+    .map((t) => `### ${t.name}\n\n${t.description}`)
+    .join('\n\n');
+}

package/src/tools/search/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Rich description for the web_search tool.
+ */
+export const WEB_SEARCH_DESCRIPTION = `
+Search the web for current information on any topic. Returns relevant search results with URLs and content snippets.
+
+## When to Use
+
+- Background research on real-world events behind prediction markets
+- Current events, breaking news, recent developments
+- Verifying claims about real-world state
+- Researching topics to inform market analysis
+
+## When NOT to Use
+
+- Kalshi market data (use kalshi_search instead)
+- Questions you can answer from knowledge
+
+## Usage Notes
+
+- Provide specific, well-formed search queries for best results
+- Returns up to 5 results with URLs and content snippets
+`.trim();
+
+export { tavilySearch } from './tavily.js';

package/src/tools/search/tavily.ts

@@ -0,0 +1,35 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { TavilySearch } from '@langchain/tavily';
+import { z } from 'zod';
+import { formatToolResult, parseSearchResults } from '../types.js';
+import { logger } from '../../utils/logger.js';
+
+// Lazily initialized to avoid errors when API key is not set
+let tavilyClient: TavilySearch | null = null;
+
+function getTavilyClient(): TavilySearch {
+  if (!tavilyClient) {
+    tavilyClient = new TavilySearch({ maxResults: 5 });
+  }
+  return tavilyClient;
+}
+
+export const tavilySearch = new DynamicStructuredTool({
+  name: 'web_search',
+  description:
+    'Search the web for current information on any topic. Returns relevant search results with URLs and content snippets.',
+  schema: z.object({
+    query: z.string().describe('The search query to look up on the web'),
+  }),
+  func: async (input) => {
+    try {
+      const result = await getTavilyClient().invoke({ query: input.query });
+      const { parsed, urls } = parseSearchResults(result);
+      return formatToolResult(parsed, urls);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.error(`[Tavily API] error: ${message}`);
+      throw new Error(`[Tavily API] ${message}`);
+    }
+  },
+});

package/src/tools/types.ts

@@ -0,0 +1,53 @@
+export interface ToolResult {
+  data: unknown;
+  sourceUrls?: string[];
+}
+
+export function formatToolResult(data: unknown, sourceUrls?: string[]): string {
+  const result: ToolResult = { data };
+  if (sourceUrls?.length) {
+    result.sourceUrls = sourceUrls;
+  }
+  return JSON.stringify(result);
+}
+
+/**
+ * Parse search results from a search provider response.
+ * Handles both string and object responses, extracting URLs from results.
+ * Supports multiple response shapes from different providers.
+ */
+export function parseSearchResults(result: unknown): { parsed: unknown; urls: string[] } {
+  // Safely parse JSON strings
+  let parsed: unknown;
+  if (typeof result === 'string') {
+    try {
+      parsed = JSON.parse(result);
+    } catch {
+      // If parsing fails, treat the string as the result itself
+      parsed = result;
+    }
+  } else {
+    parsed = result;
+  }
+
+  // Extract URLs from multiple possible response shapes
+  let urls: string[] = [];
+
+  // Shape 1: { results: [{ url: string }] } (Exa format)
+  if (parsed && typeof parsed === 'object' && 'results' in parsed) {
+    const results = (parsed as { results?: unknown[] }).results;
+    if (Array.isArray(results)) {
+      urls = results
+        .map((r) => (r && typeof r === 'object' && 'url' in r ? (r as { url?: string }).url : null))
+        .filter((url): url is string => Boolean(url));
+    }
+  }
+  // Shape 2: [{ url: string }] (direct array, Tavily format)
+  else if (Array.isArray(parsed)) {
+    urls = parsed
+      .map((r) => (r && typeof r === 'object' && 'url' in r ? (r as { url?: string }).url : null))
+      .filter((url): url is string => Boolean(url));
+  }
+
+  return { parsed, urls };
+}

package/src/tools/v2/edge-query.ts

@@ -0,0 +1,135 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+import { getDb } from '../../db/index.js';
+import { getLatestEdge, getActionableEdges, getEdgesByExactConfidence, getEdgeHistory } from '../../db/edge.js';
+import { formatToolResult } from '../types.js';
+
+export const edgeQueryTool = new DynamicStructuredTool({
+  name: 'edge_query',
+  description: 'Query edge signals and mispricing data from the local scan database.',
+  schema: z.object({
+    ticker: z.string().optional().describe('Specific market ticker to query'),
+    theme: z.string().optional().describe('Theme ID to filter by'),
+    minConfidence: z.enum(['low', 'moderate', 'high', 'very_high']).optional().describe('Minimum confidence level (returns this level and above). Use exactConfidence instead if user wants only one level.'),
+    exactConfidence: z.enum(['low', 'moderate', 'high', 'very_high']).optional().describe('Exact confidence level (returns only this level, not above). Use when user says "moderate edges" or "only high confidence".'),
+    excludeKeywords: z.array(z.string()).optional().describe('Exclude edges whose ticker or event title contains any of these keywords (case-insensitive). Use for "skip trump", "exclude crypto", etc.'),
+  }),
+  func: async ({ ticker, theme, minConfidence, exactConfidence, excludeKeywords }) => {
+    const db = getDb();
+
+    if (ticker) {
+      const latest = getLatestEdge(db, ticker);
+      if (!latest) return formatToolResult({ message: `No edge data found for ${ticker}` });
+
+      const history = getEdgeHistory(db, ticker, 0).slice(-10); // last 10 entries
+      return formatToolResult({
+        latest: {
+          ...latest,
+          drivers: latest.drivers_json ? JSON.parse(latest.drivers_json) : [],
+          sources: latest.sources_json ? JSON.parse(latest.sources_json) : [],
+          catalysts: latest.catalysts_json ? JSON.parse(latest.catalysts_json) : [],
+        },
+        recentHistory: history.map((h) => ({
+          timestamp: h.timestamp,
+          edge: h.edge,
+          modelProb: h.model_prob,
+          marketProb: h.market_prob,
+          confidence: h.confidence,
+        })),
+      });
+    }
+
+    if (theme) {
+      const themeRows = db.query(
+        `SELECT DISTINCT ticker FROM edge_history
+         WHERE event_ticker IN (SELECT event_ticker FROM events WHERE theme_id = $theme)`
+      ).all({ $theme: theme }) as { ticker: string }[];
+
+      let edges = themeRows
+        .map((t) => getLatestEdge(db, t.ticker))
+        .filter((r) => r !== null)
+        .sort((a, b) => Math.abs(b!.edge) - Math.abs(a!.edge));
+
+      if (excludeKeywords?.length) {
+        edges = applyKeywordExclusion(db, edges, excludeKeywords);
+      }
+
+      return formatToolResult({ theme, edges, count: edges.length });
+    }
+
+    // Default: actionable edges
+    let edges = exactConfidence
+      ? getEdgesByExactConfidence(db, exactConfidence)
+      : getActionableEdges(db, minConfidence ?? 'moderate');
+    edges.sort((a, b) => Math.abs(b.edge) - Math.abs(a.edge));
+
+    if (excludeKeywords?.length) {
+      edges = applyKeywordExclusion(db, edges, excludeKeywords);
+    }
+
+    const confidenceFilter = exactConfidence
+      ? { exactConfidence }
+      : { minConfidence: minConfidence ?? 'moderate' };
+
+    return formatToolResult({
+      edges: edges.slice(0, 20).map((e) => ({
+        ticker: e.ticker,
+        edge: e.edge,
+        edgePct: `${(e.edge * 100).toFixed(1)}%`,
+        modelProb: e.model_prob,
+        marketProb: e.market_prob,
+        confidence: e.confidence,
+        timestamp: e.timestamp,
+      })),
+      count: edges.length,
+      filter: confidenceFilter,
+    });
+  },
+});
+
+/** Filter out edges whose ticker or event title matches any excluded keyword. */
+function applyKeywordExclusion<T extends { ticker: string; event_ticker: string }>(
+  db: ReturnType<typeof getDb>,
+  edges: T[],
+  keywords: string[],
+): T[] {
+  const lowerKeywords = keywords.map((k) => k.toLowerCase());
+
+  // Build a title lookup from event_index for all relevant event tickers
+  const eventTickers = [...new Set(edges.map((e) => e.event_ticker))];
+  const titleMap = new Map<string, string>();
+  if (eventTickers.length > 0) {
+    const placeholders = eventTickers.map(() => '?').join(', ');
+    const rows = db.query(
+      `SELECT event_ticker, title FROM event_index WHERE event_ticker IN (${placeholders})`
+    ).all(...eventTickers) as { event_ticker: string; title: string }[];
+    for (const row of rows) {
+      titleMap.set(row.event_ticker, row.title.toLowerCase());
+    }
+  }
+
+  return edges.filter((e) => {
+    const tickerLower = e.ticker.toLowerCase();
+    const titleLower = titleMap.get(e.event_ticker) ?? '';
+    return !lowerKeywords.some((kw) => tickerLower.includes(kw) || titleLower.includes(kw));
+  });
+}
+
+export const EDGE_QUERY_DESCRIPTION = `
+Query edge signals and mispricing data from the local scan database.
+
+## When to Use
+- User asks about current edges, mispricings, or opportunities
+- "What's the edge on crypto?" or "Show me high-confidence edges"
+- Checking if a specific market has an actionable edge signal
+- Filtering edges: "show moderate edges", "skip trump", "exclude crypto"
+
+## When NOT to Use
+- For live market data from Kalshi (use kalshi_search)
+- For placing trades (use kalshi_trade)
+
+## Parameters
+- **minConfidence**: Returns edges at this level AND above. "high" → high + very_high.
+- **exactConfidence**: Returns edges at ONLY this level. "moderate" → moderate only, not high/very_high. Prefer this when the user asks for a specific level like "show moderate edges".
+- **excludeKeywords**: Filters out edges whose ticker or event title contains any keyword. Use for "skip trump", "but not crypto", etc.
+`.trim();