kalshi-trading-bot-cli 2.1.0

package/src/tools/kalshi/kalshi-trade.ts

@@ -0,0 +1,102 @@
+import { DynamicStructuredTool, StructuredToolInterface } from '@langchain/core/tools';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import { AIMessage, ToolCall } from '@langchain/core/messages';
+import { z } from 'zod';
+import { callLlm } from '../../model/llm.js';
+import { formatToolResult } from '../types.js';
+import { getCurrentDate } from '../../agent/prompts.js';
+import { placeOrder, amendOrder, cancelOrder, cancelOrders, placeBatchOrders } from './trading.js';
+
+const TRADING_TOOLS: StructuredToolInterface[] = [
+  placeOrder,
+  amendOrder,
+  cancelOrder,
+  cancelOrders,
+  placeBatchOrders,
+];
+
+const TRADING_TOOL_MAP = new Map(TRADING_TOOLS.map((t) => [t.name, t]));
+
+export const KALSHI_TRADE_DESCRIPTION = `
+Execute trading actions on Kalshi prediction markets. Routes natural language trade instructions to the correct API endpoints.
+
+## When to Use
+
+- Placing buy or sell orders (limit or market)
+- Amending resting orders (price or quantity)
+- Canceling one or more resting orders
+- Placing batch orders
+
+## IMPORTANT
+
+- NEVER call this tool without explicit user confirmation of trade details
+- Always confirm: ticker, side (yes/no), action (buy/sell), count, and price
+- Prices are in cents: $0.56 = 56 cents
+`.trim();
+
+function buildTradingRouterPrompt(): string {
+  return `You are a Kalshi trading execution assistant.
+Current date: ${getCurrentDate()}
+
+Given a trading instruction, call the appropriate trading tool.
+
+## Key Facts
+- Prices are in cents (1-99): $0.56 → yes_price: 56
+- side: "yes" or "no" (the contract type)
+- action: "buy" or "sell"
+- type: "limit" (use yes_price) or "market" (no price needed)
+- To cancel by order_id, use cancel_order
+- For multiple cancels, use cancel_orders with order_ids array
+
+Execute the trading action now.`;
+}
+
+const KalshiTradeInputSchema = z.object({
+  action: z.string().describe('Natural language description of the trade to execute'),
+});
+
+export function createKalshiTrade(model: string): DynamicStructuredTool {
+  return new DynamicStructuredTool({
+    name: 'kalshi_trade',
+    description: KALSHI_TRADE_DESCRIPTION,
+    schema: KalshiTradeInputSchema,
+    func: async (input, _runManager, config?: RunnableConfig) => {
+      const onProgress = config?.metadata?.onProgress as ((msg: string) => void) | undefined;
+
+      onProgress?.('Preparing trade...');
+      const { response } = await callLlm(input.action, {
+        model,
+        systemPrompt: buildTradingRouterPrompt(),
+        tools: TRADING_TOOLS,
+      });
+      const aiMessage = response as AIMessage;
+
+      const toolCalls = aiMessage.tool_calls as ToolCall[];
+      if (!toolCalls || toolCalls.length === 0) {
+        return formatToolResult({ error: 'Could not parse trade instruction into a valid order' });
+      }
+
+      const results = [];
+      for (const tc of toolCalls) {
+        onProgress?.(`Executing ${tc.name.replace(/_/g, ' ')}...`);
+        try {
+          const tool = TRADING_TOOL_MAP.get(tc.name);
+          if (!tool) throw new Error(`Tool '${tc.name}' not found`);
+          const rawResult = await tool.invoke(tc.args);
+          const result = typeof rawResult === 'string' ? rawResult : JSON.stringify(rawResult);
+          const parsed = JSON.parse(result);
+          results.push({ tool: tc.name, args: tc.args, data: parsed.data, error: null });
+        } catch (error) {
+          results.push({
+            tool: tc.name,
+            args: tc.args,
+            data: null,
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+
+      return formatToolResult({ results });
+    },
+  });
+}

package/src/tools/kalshi/markets.ts

@@ -0,0 +1,76 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+import { callKalshiApi } from './api.js';
+import { formatToolResult } from '../types.js';
+
+export const getMarkets = new DynamicStructuredTool({
+  name: 'get_markets',
+  description: 'Get a list of Kalshi markets, optionally filtered by event ticker, series ticker, status, or specific tickers.',
+  schema: z.object({
+    event_ticker: z.string().optional().describe('Filter by event ticker'),
+    series_ticker: z.string().optional().describe('Filter by series ticker'),
+    status: z.enum(['open', 'closed', 'settled']).optional().describe('Market status filter'),
+    tickers: z.array(z.string()).optional().describe('Specific market tickers to fetch'),
+    limit: z.number().optional().describe('Max markets to return (default 100)'),
+  }),
+  func: async (input) => {
+    const params: Record<string, string | number | undefined> = {};
+    if (input.event_ticker) params.event_ticker = input.event_ticker;
+    if (input.series_ticker) params.series_ticker = input.series_ticker;
+    if (input.status) params.status = input.status;
+    if (input.tickers?.length) params.tickers = input.tickers.join(',');
+    if (input.limit) params.limit = input.limit;
+
+    const data = await callKalshiApi('GET', '/markets', { params });
+    return formatToolResult(data);
+  },
+});
+
+export const getMarket = new DynamicStructuredTool({
+  name: 'get_market',
+  description: 'Get details for a specific Kalshi market by ticker.',
+  schema: z.object({
+    ticker: z.string().describe('Market ticker (e.g. KXBTC-26MAR-B50000)'),
+  }),
+  func: async (input) => {
+    const data = await callKalshiApi('GET', `/markets/${input.ticker}`);
+    return formatToolResult(data);
+  },
+});
+
+export const getMarketOrderbook = new DynamicStructuredTool({
+  name: 'get_market_orderbook',
+  description: 'Get the current orderbook for a Kalshi market.',
+  schema: z.object({
+    ticker: z.string().describe('Market ticker'),
+    depth: z.number().optional().describe('Number of price levels to return'),
+  }),
+  func: async (input) => {
+    const params: Record<string, number | undefined> = {};
+    if (input.depth) params.depth = input.depth;
+    const data = await callKalshiApi('GET', `/markets/${input.ticker}/orderbook`, { params });
+    return formatToolResult(data);
+  },
+});
+
+export const getMarketCandlesticks = new DynamicStructuredTool({
+  name: 'get_market_candlesticks',
+  description: 'Get candlestick price data for a Kalshi market.',
+  schema: z.object({
+    ticker: z.string().describe('Market ticker'),
+    start_ts: z.number().optional().describe('Start timestamp (Unix seconds)'),
+    end_ts: z.number().optional().describe('End timestamp (Unix seconds)'),
+    period_interval: z.number().optional().describe('Candlestick interval in minutes (default 60)'),
+  }),
+  func: async (input) => {
+    const now = Math.floor(Date.now() / 1000);
+    const params: Record<string, string | number | undefined> = {
+      market_tickers: input.ticker,
+      start_ts: input.start_ts ?? now - 7 * 24 * 3600,
+      end_ts: input.end_ts ?? now,
+      period_interval: input.period_interval,
+    };
+    const data = await callKalshiApi('GET', '/markets/candlesticks', { params });
+    return formatToolResult(data);
+  },
+});

package/src/tools/kalshi/portfolio.ts

@@ -0,0 +1,100 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+import { callKalshiApi } from './api.js';
+import { formatToolResult } from '../types.js';
+
+export const getBalance = new DynamicStructuredTool({
+  name: 'get_balance',
+  description: 'Get the current Kalshi account balance.',
+  schema: z.object({}),
+  func: async () => {
+    const data = await callKalshiApi('GET', '/portfolio/balance');
+    return formatToolResult(data);
+  },
+});
+
+export const getPositions = new DynamicStructuredTool({
+  name: 'get_positions',
+  description: 'Get current open positions in Kalshi markets.',
+  schema: z.object({
+    event_ticker: z.string().optional().describe('Filter by event ticker'),
+    ticker: z.string().optional().describe('Filter by market ticker'),
+  }),
+  func: async (input) => {
+    const params: Record<string, string | undefined> = {};
+    if (input.event_ticker) params.event_ticker = input.event_ticker;
+    if (input.ticker) params.ticker = input.ticker;
+    const data = await callKalshiApi('GET', '/portfolio/positions', { params });
+    return formatToolResult(data);
+  },
+});
+
+export const getFills = new DynamicStructuredTool({
+  name: 'get_fills',
+  description: 'Get trade fills (executed orders) from the portfolio.',
+  schema: z.object({
+    ticker: z.string().optional().describe('Filter by market ticker'),
+    order_id: z.string().optional().describe('Filter by order ID'),
+    min_ts: z.number().optional().describe('Min timestamp (Unix seconds)'),
+    max_ts: z.number().optional().describe('Max timestamp (Unix seconds)'),
+    limit: z.number().optional().describe('Max fills to return'),
+  }),
+  func: async (input) => {
+    const params: Record<string, string | number | undefined> = {};
+    if (input.ticker) params.ticker = input.ticker;
+    if (input.order_id) params.order_id = input.order_id;
+    if (input.min_ts) params.min_ts = input.min_ts;
+    if (input.max_ts) params.max_ts = input.max_ts;
+    if (input.limit) params.limit = input.limit;
+    const data = await callKalshiApi('GET', '/portfolio/fills', { params });
+    return formatToolResult(data);
+  },
+});
+
+export const getSettlements = new DynamicStructuredTool({
+  name: 'get_settlements',
+  description: 'Get settlement history for resolved markets.',
+  schema: z.object({
+    ticker: z.string().optional().describe('Filter by market ticker'),
+    limit: z.number().optional().describe('Max settlements to return'),
+  }),
+  func: async (input) => {
+    const params: Record<string, string | number | undefined> = {};
+    if (input.ticker) params.ticker = input.ticker;
+    if (input.limit) params.limit = input.limit;
+    const data = await callKalshiApi('GET', '/portfolio/settlements', { params });
+    return formatToolResult(data);
+  },
+});
+
+export const getOrders = new DynamicStructuredTool({
+  name: 'get_orders',
+  description: 'Get orders from the portfolio.',
+  schema: z.object({
+    ticker: z.string().optional().describe('Filter by market ticker'),
+    event_ticker: z.string().optional().describe('Filter by event ticker'),
+    status: z.enum(['resting', 'canceled', 'executed', 'all']).optional().describe('Order status filter'),
+    limit: z.number().optional().describe('Max orders to return'),
+  }),
+  func: async (input) => {
+    const params: Record<string, string | number | undefined> = {};
+    if (input.ticker) params.ticker = input.ticker;
+    if (input.event_ticker) params.event_ticker = input.event_ticker;
+    if (input.status) params.status = input.status;
+    if (input.limit) params.limit = input.limit;
+    const data = await callKalshiApi('GET', '/portfolio/orders', { params });
+    return formatToolResult(data);
+  },
+});
+
+export const getOrder = new DynamicStructuredTool({
+  name: 'get_order',
+  description: 'Get details for a specific order by order ID.',
+  schema: z.object({
+    order_id: z.string().describe('Order ID'),
+  }),
+  func: async (input) => {
+    const data = await callKalshiApi('GET', `/portfolio/orders/${input.order_id}`);
+    return formatToolResult(data);
+  },
+});

package/src/tools/kalshi/search-index.ts

@@ -0,0 +1,198 @@
+import { getDb } from '../../db/index.js';
+import { clearAndPopulateIndex, getIndexAge, setLastRefresh } from '../../db/event-index.js';
+import { callKalshiApi, fetchAllPages } from './api.js';
+import { logger } from '../../utils/logger.js';
+import type { KalshiEvent, KalshiSeries } from './types.js';
+
+/** Stale threshold: triggers background refresh */
+const INDEX_STALE_MS = 2 * 60 * 60 * 1000; // 2 hours
+
+/** Hard TTL: data still usable but stale */
+const INDEX_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+/** Singleton promise to prevent concurrent refreshes */
+let _refreshPromise: Promise<void> | null = null;
+
+/** Max concurrent series fetches during index refresh */
+const SERIES_CONCURRENCY = 20;
+
+// --- Progress observable ---
+
+export type IndexProgressPhase = 'fetching_events' | 'fetching_series' | 'populating';
+
+export interface IndexProgressInfo {
+  phase: IndexProgressPhase;
+  fetchedItems: number;
+  page: number;
+  maxPages: number;
+  detail?: string;
+}
+
+export type IndexProgressListener = (info: IndexProgressInfo) => void;
+
+const _progressListeners = new Set<IndexProgressListener>();
+
+/** Subscribe to index refresh progress. Returns an unsubscribe function. */
+export function onIndexProgress(listener: IndexProgressListener): () => void {
+  _progressListeners.add(listener);
+  return () => { _progressListeners.delete(listener); };
+}
+
+function emitProgress(info: IndexProgressInfo): void {
+  for (const listener of _progressListeners) {
+    try { listener(info); } catch { /* ignore listener errors */ }
+  }
+}
+
+/** Get the current refresh promise so callers can await it if desired. */
+export function getRefreshPromise(): Promise<void> | null {
+  return _refreshPromise;
+}
+
+/**
+ * Fetch series tags for a set of unique series tickers.
+ * Returns a map of series_ticker → tags array.
+ */
+async function fetchSeriesTags(seriesTickers: string[], totalEvents: number): Promise<Map<string, string[]>> {
+  const tagsMap = new Map<string, string[]>();
+  // Process in batches to limit concurrency
+  for (let i = 0; i < seriesTickers.length; i += SERIES_CONCURRENCY) {
+    const batch = seriesTickers.slice(i, i + SERIES_CONCURRENCY);
+    const results = await Promise.allSettled(
+      batch.map(async (ticker) => {
+        const data = await callKalshiApi('GET', `/series/${ticker}`);
+        const series = (data.series ?? data) as KalshiSeries;
+        return { ticker, tags: series.tags ?? [] };
+      }),
+    );
+    for (const result of results) {
+      if (result.status === 'fulfilled' && result.value.tags.length > 0) {
+        tagsMap.set(result.value.ticker, result.value.tags);
+      }
+    }
+    emitProgress({
+      phase: 'fetching_series',
+      fetchedItems: Math.min(i + SERIES_CONCURRENCY, seriesTickers.length),
+      page: 0,
+      maxPages: 0,
+      detail: `Series tags: ${Math.min(i + SERIES_CONCURRENCY, seriesTickers.length)}/${seriesTickers.length} (${totalEvents} events)`,
+    });
+  }
+  return tagsMap;
+}
+
+/**
+ * Refresh the local event index by fetching all open events from Kalshi API.
+ */
+async function refreshIndex(): Promise<void> {
+  const db = getDb();
+  logger.info('[search-index] Refreshing event index from Kalshi API...');
+  const start = Date.now();
+
+  try {
+    // Fetch events with nested markets — the API now includes volume_24h_fp
+    // and last_price_dollars on nested markets, so no separate enrichment needed
+    const events = await fetchAllPages<KalshiEvent>(
+      '/events',
+      { status: 'open', with_nested_markets: true },
+      'events',
+      20,
+      (info) => {
+        emitProgress({
+          phase: 'fetching_events',
+          fetchedItems: info.fetchedItems,
+          page: info.page,
+          maxPages: info.maxPages,
+        });
+      }
+    );
+
+    // Fetch series tags in parallel with index write
+    const uniqueSeries = [...new Set(events.map((e) => e.series_ticker).filter(Boolean))];
+    const seriesTagsPromise = fetchSeriesTags(uniqueSeries, events.length);
+
+    emitProgress({
+      phase: 'populating',
+      fetchedItems: events.length,
+      page: 0,
+      maxPages: 0,
+      detail: `Writing ${events.length} events to index...`,
+    });
+
+    // Write events with nested markets directly to the index
+    clearAndPopulateIndex(
+      db,
+      events.map((e) => ({
+        event_ticker: e.event_ticker,
+        series_ticker: e.series_ticker,
+        title: e.title,
+        category: e.category,
+        strike_date: e.strike_date,
+        sub_title: e.sub_title,
+        markets: e.markets,
+      })),
+    );
+
+    // Update tags on index rows
+    const seriesTags = await seriesTagsPromise;
+    if (seriesTags.size > 0) {
+      const updateTags = db.prepare('UPDATE event_index SET tags = $tags WHERE series_ticker = $series_ticker');
+      db.transaction(() => {
+        for (const [seriesTicker, tags] of seriesTags) {
+          updateTags.run({ $tags: tags.join(','), $series_ticker: seriesTicker });
+        }
+      })();
+    }
+
+    setLastRefresh(db, Date.now());
+
+    const elapsed = ((Date.now() - start) / 1000).toFixed(1);
+    logger.info(`[search-index] Index refreshed: ${events.length} events in ${elapsed}s`);
+  } catch (error) {
+    logger.error('[search-index] Failed to refresh index:', error);
+    throw error;
+  }
+}
+
+/**
+ * Force an immediate index rebuild, bypassing the 2-hour stale check.
+ * If a refresh is already in progress, waits for it to complete first,
+ * then starts a new one.
+ */
+export async function forceRefreshIndex(): Promise<void> {
+  if (_refreshPromise) {
+    await _refreshPromise;
+  }
+  _refreshPromise = refreshIndex().finally(() => {
+    _refreshPromise = null;
+  });
+  await _refreshPromise;
+}
+
+/**
+ * Ensure the local event index is fresh. If stale or empty, triggers a refresh.
+ * Always returns immediately (never blocks).
+ *
+ * - age < 2h: nothing to do
+ * - age >= 2h but < Infinity: fire-and-forget refresh, serve stale data
+ * - age === Infinity (first run): fire-and-forget refresh, return immediately
+ */
+export async function ensureIndex(): Promise<void> {
+  const db = getDb();
+  const age = getIndexAge(db);
+
+  // Fresh index — nothing to do
+  if (age < INDEX_STALE_MS) return;
+
+  // Stale or first-run: trigger background refresh if not already running
+  if (!_refreshPromise) {
+    _refreshPromise = refreshIndex()
+      .catch((err) => {
+        logger.error('[search-index] Background refresh failed:', err);
+      })
+      .finally(() => {
+        _refreshPromise = null;
+      });
+  }
+  // Never block — return immediately regardless of first-run or stale
+}

package/src/tools/kalshi/series.ts

@@ -0,0 +1,16 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+import { callKalshiApi } from './api.js';
+import { formatToolResult } from '../types.js';
+
+export const getSeries = new DynamicStructuredTool({
+  name: 'get_series',
+  description: 'Get details for a Kalshi series by series ticker.',
+  schema: z.object({
+    series_ticker: z.string().describe('Series ticker (e.g. KXBTC)'),
+  }),
+  func: async (input) => {
+    const data = await callKalshiApi('GET', `/series/${input.series_ticker}`);
+    return formatToolResult(data);
+  },
+});

package/src/tools/kalshi/trading.ts

@@ -0,0 +1,115 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+import { callKalshiApi, toDollarString } from './api.js';
+import { formatToolResult } from '../types.js';
+
+export const placeOrder = new DynamicStructuredTool({
+  name: 'place_order',
+  description: 'Place a new order on a Kalshi market.',
+  schema: z.object({
+    ticker: z.string().describe('Market ticker'),
+    action: z.enum(['buy', 'sell']).describe('Buy or sell'),
+    side: z.enum(['yes', 'no']).describe('Yes or No side'),
+    type: z.enum(['limit', 'market']).describe('Order type'),
+    count: z.number().int().positive().describe('Number of contracts'),
+    yes_price: z.number().int().min(1).max(99).optional().describe('Price in cents (1-99) for limit orders'),
+    expiration_ts: z.number().optional().describe('Order expiration Unix timestamp'),
+    client_order_id: z.string().optional().describe('Optional client-provided order ID'),
+  }),
+  func: async (input) => {
+    const body: Record<string, unknown> = {
+      ticker: input.ticker,
+      action: input.action,
+      side: input.side,
+      type: input.type,
+      count: input.count,
+    };
+    if (input.yes_price !== undefined) {
+      body.yes_price = input.yes_price;
+      body.dollar_price = toDollarString(input.yes_price);
+    }
+    if (input.expiration_ts !== undefined) body.expiration_ts = input.expiration_ts;
+    if (input.client_order_id) body.client_order_id = input.client_order_id;
+
+    const data = await callKalshiApi('POST', '/portfolio/orders', { body });
+    return formatToolResult(data);
+  },
+});
+
+export const amendOrder = new DynamicStructuredTool({
+  name: 'amend_order',
+  description: 'Amend an existing resting order.',
+  schema: z.object({
+    order_id: z.string().describe('Order ID to amend'),
+    count: z.number().int().positive().optional().describe('New contract count'),
+    yes_price: z.number().int().min(1).max(99).optional().describe('New price in cents'),
+    expiration_ts: z.number().optional().describe('New expiration timestamp'),
+  }),
+  func: async (input) => {
+    const body: Record<string, unknown> = {};
+    if (input.count !== undefined) body.count = input.count;
+    if (input.yes_price !== undefined) {
+      body.yes_price = input.yes_price;
+      body.dollar_price = toDollarString(input.yes_price);
+    }
+    if (input.expiration_ts !== undefined) body.expiration_ts = input.expiration_ts;
+
+    const data = await callKalshiApi('POST', `/portfolio/orders/${input.order_id}/amend`, { body });
+    return formatToolResult(data);
+  },
+});
+
+export const cancelOrder = new DynamicStructuredTool({
+  name: 'cancel_order',
+  description: 'Cancel an existing resting order.',
+  schema: z.object({
+    order_id: z.string().describe('Order ID to cancel'),
+  }),
+  func: async (input) => {
+    const data = await callKalshiApi('DELETE', `/portfolio/orders/${input.order_id}`);
+    return formatToolResult(data);
+  },
+});
+
+export const cancelOrders = new DynamicStructuredTool({
+  name: 'cancel_orders',
+  description: 'Cancel multiple resting orders in batch.',
+  schema: z.object({
+    order_ids: z.array(z.string()).describe('List of order IDs to cancel'),
+  }),
+  func: async (input) => {
+    const body = { order_ids: input.order_ids };
+    const data = await callKalshiApi('DELETE', '/portfolio/orders/batched', { body });
+    return formatToolResult(data);
+  },
+});
+
+export const placeBatchOrders = new DynamicStructuredTool({
+  name: 'place_batch_orders',
+  description: 'Place multiple orders in a single batch request.',
+  schema: z.object({
+    orders: z
+      .array(
+        z.object({
+          ticker: z.string(),
+          action: z.enum(['buy', 'sell']),
+          side: z.enum(['yes', 'no']),
+          type: z.enum(['limit', 'market']),
+          count: z.number().int().positive(),
+          yes_price: z.number().int().min(1).max(99).optional(),
+        })
+      )
+      .describe('List of orders to place'),
+  }),
+  func: async (input) => {
+    const orders = input.orders.map((o) => {
+      if (o.yes_price !== undefined) {
+        return { ...o, dollar_price: toDollarString(o.yes_price) };
+      }
+      return o;
+    });
+    const body = { orders };
+    const data = await callKalshiApi('POST', '/portfolio/orders/batched', { body });
+    return formatToolResult(data);
+  },
+});