kalshi-trading-bot-cli 2.1.0

package/src/commands/formatters.ts

@@ -0,0 +1,339 @@
+import type { KalshiMarket, KalshiPosition, KalshiOrder } from '../tools/kalshi/types.js';
+
+// ─── Box header helper ───────────────────────────────────────────────────────
+
+const BOX_WIDTH = 40;
+
+export function formatBoxHeader(title: string): string[] {
+  const inner = BOX_WIDTH - 2; // space between ║ walls
+  const safeTitle = title.length > inner ? title.slice(0, inner - 1) + '…' : title;
+  const pad = inner - safeTitle.length;
+  const left = Math.floor(pad / 2);
+  const right = pad - left;
+  return [
+    '',
+    '╔' + '═'.repeat(inner) + '╗',
+    '║' + ' '.repeat(left) + safeTitle + ' '.repeat(right) + '║',
+    '╚' + '═'.repeat(inner) + '╝',
+  ];
+}
+
+/** Actual Kalshi /portfolio/balance response shape */
+export interface KalshiBalanceResponse {
+  balance: number;
+  portfolio_value: number;
+  updated_ts?: number;
+  // Legacy fields (may be present in some API versions)
+  payout?: number;
+  reserved_fees?: number;
+  fees?: number;
+}
+
+// ─── Value parsers ────────────────────────────────────────────────────────────
+// Kalshi API returns prices as "_dollars" string fields (e.g. "0.5600")
+// or as integer cents in older API versions. Handle both.
+
+function parseDollars(val: string | number | undefined | null): number | undefined {
+  if (val === undefined || val === null) return undefined;
+  const n = typeof val === 'number' ? val : parseFloat(val as string);
+  return isNaN(n) ? undefined : n;
+}
+
+function parsePosition(val: string | number | undefined | null): number | undefined {
+  if (val === undefined || val === null) return undefined;
+  const n = typeof val === 'number' ? val : parseFloat(val as string);
+  return isNaN(n) ? undefined : n;
+}
+
+/** Format a dollar amount (already in dollars, not cents) */
+function fmtDollars(val: string | number | undefined | null): string {
+  const n = parseDollars(val);
+  if (n === undefined) return '-';
+  return `$${n.toFixed(2)}`;
+}
+
+/** Format a price field that may be integer cents OR a dollars string */
+function fmtPrice(val: number | string | undefined | null): string {
+  if (val === undefined || val === null) return '-';
+  if (typeof val === 'string') {
+    const n = parseFloat(val);
+    if (isNaN(n)) return '-';
+    // If the string looks like "0.5600" (dollars format), show as-is
+    return `$${n.toFixed(2)}`;
+  }
+  // Integer cents (old API format): divide by 100
+  return `$${(val / 100).toFixed(2)}`;
+}
+
+/** Format a dollar amount from cents (integer) */
+function fmtCents(cents: number | undefined | null): string {
+  if (cents === undefined || cents === null) return '-';
+  return `$${(cents / 100).toFixed(2)}`;
+}
+
+/** Format a number with commas, safely handling null/undefined */
+function fmtNum(n: number | string | undefined | null): string {
+  if (n === undefined || n === null) return '-';
+  const val = typeof n === 'number' ? n : parseFloat(n as string);
+  if (isNaN(val)) return '-';
+  if (val === 0) return '0';
+  return val.toLocaleString();
+}
+
+/** Format ISO date string as short date */
+function fmtDate(iso: string | undefined): string {
+  if (!iso) return '-';
+  try {
+    return new Date(iso).toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: '2-digit' });
+  } catch {
+    return iso.slice(0, 10);
+  }
+}
+
+// ─── Access helpers (handle both _dollars and raw field names) ────────────────
+
+function mktYesAsk(m: any): string | number | undefined {
+  return m.yes_ask_dollars ?? m.dollar_yes_ask ?? m.yes_ask;
+}
+function mktNoAsk(m: any): string | number | undefined {
+  return m.no_ask_dollars ?? m.dollar_no_ask ?? m.no_ask;
+}
+function mktYesBid(m: any): string | number | undefined {
+  return m.yes_bid_dollars ?? m.dollar_yes_bid ?? m.yes_bid;
+}
+function mktNoBid(m: any): string | number | undefined {
+  return m.no_bid_dollars ?? m.dollar_no_bid ?? m.no_bid;
+}
+function mktLastPrice(m: any): string | number | undefined {
+  return m.last_price_dollars ?? m.dollar_last_price ?? m.last_price;
+}
+function mktVolume(m: any): string | number | undefined {
+  return m.volume_fp ?? m.volume;
+}
+function mktOpenInterest(m: any): string | number | undefined {
+  return m.open_interest_fp ?? m.open_interest;
+}
+
+// ─── Formatters ───────────────────────────────────────────────────────────────
+
+export function formatBalance(data: KalshiBalanceResponse): string {
+  const lines: string[] = [];
+  lines.push('**Account Balance**');
+  lines.push('');
+  lines.push(`Balance:         ${fmtCents(data.balance)}`);
+  lines.push(`Portfolio Value: ${fmtCents(data.portfolio_value ?? 0)}`);
+  if (data.payout !== undefined) lines.push(`Payout:          ${fmtCents(data.payout)}`);
+  if (data.reserved_fees !== undefined) lines.push(`Reserved Fees:   ${fmtCents(data.reserved_fees)}`);
+  if (data.fees !== undefined) lines.push(`Total Fees:      ${fmtCents(data.fees)}`);
+  return lines.join('\n');
+}
+
+export function formatPositions(positions: any[]): string {
+  if (!positions.length) return 'No open positions.';
+
+  const rows = positions.map((p) => {
+    // position_fp is the net position (number of contracts)
+    const pos = parsePosition(p.position_fp ?? p.position);
+    const posStr = pos === undefined ? '-' : pos > 0 ? `+${pos}` : String(pos);
+    const pnl = p.realized_pnl_dollars ?? (p.realized_pnl !== undefined ? (p.realized_pnl / 100).toFixed(2) : undefined);
+    const exposure = p.market_exposure_dollars ?? (p.market_exposure !== undefined ? (p.market_exposure / 100).toFixed(2) : undefined);
+
+    return [
+      p.ticker,
+      posStr,
+      fmtDollars(pnl),
+      fmtDollars(exposure),
+      String(p.resting_orders_count ?? 0),
+    ];
+  });
+
+  return formatTable(
+    ['Ticker', 'Position', 'Realized P&L', 'Exposure', 'Orders'],
+    rows
+  );
+}
+
+export function formatOrders(orders: KalshiOrder[]): string {
+  if (!orders.length) return 'No orders found.';
+
+  const rows = orders.map((o) => {
+    const price = o.yes_price_dollars
+      ? fmtDollars(o.yes_price_dollars)
+      : o.yes_price != null ? fmtCents(o.yes_price) : '-';
+    const remaining = o.remaining_count_fp ?? o.remaining_count ?? '-';
+    const initial = o.initial_count_fp ?? o.contracts_count ?? '-';
+    return [
+      o.ticker,
+      `${o.action}/${o.side}`,
+      price,
+      `${remaining}/${initial}`,
+      o.status,
+      (o.order_id ?? '').slice(0, 8) + '…',
+    ];
+  });
+
+  return formatTable(
+    ['Ticker', 'Action/Side', 'Price', 'Remaining', 'Status', 'Order ID'],
+    rows
+  );
+}
+
+export function formatMarkets(markets: any[]): string {
+  if (!markets.length) return 'No markets found.';
+
+  const rows = markets.map((m) => [
+    m.ticker,
+    truncate(m.title ?? '', 40),
+    fmtPrice(mktYesAsk(m)),
+    fmtPrice(mktNoAsk(m)),
+    fmtNum(mktVolume(m)),
+    fmtDate(m.close_time),
+  ]);
+
+  return formatTable(
+    ['Ticker', 'Title', 'YES Ask', 'NO Ask', 'Volume', 'Closes'],
+    rows
+  );
+}
+
+export function formatMarketDetail(market: any): string {
+  const lines: string[] = [];
+  lines.push(`**${market.ticker}**`);
+  if (market.title) lines.push(market.title);
+  if (market.subtitle) lines.push(market.subtitle);
+  lines.push('');
+  lines.push(`Status:     ${market.status ?? '-'}`);
+  lines.push(`YES Bid:    ${fmtPrice(mktYesBid(market))}   YES Ask: ${fmtPrice(mktYesAsk(market))}`);
+  lines.push(`NO Bid:     ${fmtPrice(mktNoBid(market))}   NO Ask:  ${fmtPrice(mktNoAsk(market))}`);
+  lines.push(`Last Price: ${fmtPrice(mktLastPrice(market))}`);
+  lines.push(`Volume:     ${fmtNum(mktVolume(market))}   Open Interest: ${fmtNum(mktOpenInterest(market))}`);
+  lines.push(`Closes:     ${fmtDate(market.close_time)}`);
+  if (market.result) lines.push(`Result:     ${market.result}`);
+  return lines.join('\n');
+}
+
+export function formatExchangeStatus(data: Record<string, unknown>): string {
+  const active = data.exchange_active ? '✓ Exchange Active' : '✗ Exchange Inactive';
+  const trading = data.trading_active ? '✓ Trading Active' : '✗ Trading Paused';
+  return `${active}\n${trading}`;
+}
+
+export function formatOrderConfirmation(
+  ticker: string,
+  action: 'buy' | 'sell',
+  side: 'yes' | 'no',
+  count: number,
+  price: number | undefined
+): string {
+  const priceStr = price !== undefined ? `$${(price / 100).toFixed(2)}` : 'market price';
+  const estCost = price !== undefined ? `$${((price / 100) * count).toFixed(2)}` : 'variable';
+  const lines = [
+    '**Order Preview**',
+    '',
+    `Ticker:  ${ticker}`,
+    `Action:  ${action.toUpperCase()} ${side.toUpperCase()}`,
+    `Count:   ${count} contract${count !== 1 ? 's' : ''}`,
+    `Price:   ${priceStr}`,
+    `Est. Cost: ${estCost}`,
+  ];
+  return lines.join('\n');
+}
+
+export function formatEvents(events: any[]): string {
+  if (!events.length) return 'No events found.';
+
+  const rows = events.map((e) => {
+    const markets = e.markets ?? [];
+    const marketCount = markets.length > 0 ? String(markets.length) : '-';
+
+    // Find the leading outcome (highest YES price) for the top outcome column
+    let topOutcome = '-';
+    let topPct = '-';
+    if (markets.length > 0) {
+      // For multi-market events, show the frontrunner
+      // For binary events (1 market), show the YES probability
+      const sorted = [...markets].sort((a: any, b: any) => {
+        const volA = parseFloat(a.volume_fp ?? a.volume ?? '0') || 0;
+        const volB = parseFloat(b.volume_fp ?? b.volume ?? '0') || 0;
+        return volB - volA;
+      });
+      const top = sorted[0];
+      // Handle both dollar strings ("0.1800") and integer cents (18)
+      const rawAsk = top.yes_ask_dollars ?? top.yes_ask;
+      let yesAsk = 0;
+      if (rawAsk !== undefined && rawAsk !== null) {
+        const n = parseFloat(String(rawAsk));
+        yesAsk = !isNaN(n) ? (n > 1 ? n / 100 : n) : 0;
+      }
+      topOutcome = truncate(top.yes_sub_title || top.subtitle || top.ticker?.split('-').pop() || '', 25);
+      if (yesAsk > 0) topPct = `${Math.round(yesAsk * 100)}%`;
+    }
+
+    return [
+      e.event_ticker,
+      truncate(e.title ?? '', 35),
+      marketCount,
+      topOutcome,
+      topPct,
+    ];
+  });
+
+  return formatTable(
+    ['Ticker', 'Title', 'Mkts', 'Top Outcome', 'YES'],
+    rows
+  );
+}
+
+export function formatEventDetail(event: any): string {
+  const lines: string[] = [];
+  lines.push(`**${event.event_ticker}**`);
+  if (event.title) lines.push(event.title);
+  if (event.sub_title) lines.push(event.sub_title);
+  lines.push('');
+  lines.push(`Series:   ${event.series_ticker ?? '-'}`);
+  lines.push(`Category: ${event.category ?? '-'}`);
+  lines.push(`Strike:   ${fmtDate(event.strike_date)}`);
+  if (event.mutually_exclusive !== undefined) {
+    lines.push(`Mutually Exclusive: ${event.mutually_exclusive ? 'Yes' : 'No'}`);
+  }
+
+  const markets = event.markets ?? [];
+  if (markets.length > 0) {
+    lines.push('');
+    lines.push(`**Markets (${markets.length})**`);
+    const rows = markets.map((m: any) => [
+      m.ticker,
+      truncate(m.title ?? m.subtitle ?? '', 35),
+      fmtPrice(mktYesAsk(m)),
+      fmtPrice(mktNoAsk(m)),
+      fmtNum(mktVolume(m)),
+    ]);
+    lines.push(formatTable(['Ticker', 'Title', 'YES Ask', 'NO Ask', 'Volume'], rows));
+  }
+
+  return lines.join('\n');
+}
+
+function truncate(s: string, max: number): string {
+  return s.length > max ? s.slice(0, max - 1) + '…' : s;
+}
+
+function formatTable(headers: string[], rows: string[][]): string {
+  const colWidths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length))
+  );
+
+  const pad = (s: string, w: number) => s.padEnd(w);
+  const sep = '─';
+
+  const topBorder = '┌' + colWidths.map((w) => sep.repeat(w + 2)).join('┬') + '┐';
+  const headerRow = '│' + headers.map((h, i) => ` ${pad(h, colWidths[i])} `).join('│') + '│';
+  const midBorder = '├' + colWidths.map((w) => sep.repeat(w + 2)).join('┼') + '┤';
+  const bottomBorder = '└' + colWidths.map((w) => sep.repeat(w + 2)).join('┴') + '┘';
+
+  const dataRows = rows.map(
+    (row) => '│' + colWidths.map((w, i) => ` ${pad(row[i] ?? '', w)} `).join('│') + '│'
+  );
+
+  return [topBorder, headerRow, midBorder, ...dataRows, bottomBorder].join('\n');
+}

package/src/commands/help.ts

@@ -0,0 +1,263 @@
+// ─── Shared help content for both TUI slash commands and CLI batch mode ─────
+
+/** Context determines prefix style: slash commands use "/", CLI uses "kalshi" */
+type HelpContext = 'slash' | 'cli';
+
+function prefix(ctx: HelpContext): string {
+  return ctx === 'slash' ? '/' : 'kalshi ';
+}
+
+function buildTopics(ctx: HelpContext): Record<string, string> {
+  const p = prefix(ctx);
+  return {
+    search: `**${p}search** — Discovery
+
+${p}search [theme|ticker|query]  Search events by theme, ticker, or free-text
+${p}search themes                List all available themes and subcategories
+${p}search edge                  Scan all markets by Octagon model edge
+${p}search edge --min-edge 30    Markets with ≥30pp edge
+${p}search edge --limit 50       Top 50 results
+${p}search edge --category crypto Filter by category
+
+Examples:
+  ${p}search crypto
+  ${p}search crypto:btc
+  ${p}search "bitcoin price"
+  ${p}search edge --min-edge 30 --category crypto`,
+
+    portfolio: `**${p}portfolio** — Account state
+
+${p}portfolio                    Full overview: positions, P&L, risk snapshot
+${p}portfolio positions          Open positions with P&L
+${p}portfolio orders             Resting orders
+${p}portfolio balance            Account balance
+${p}portfolio status             Exchange status${ctx === 'cli' ? ' and setup verification' : ''}
+${ctx === 'cli' ? `
+Flags:
+  --performance                     Include win rate, Sharpe, Brier scores
+  --json                            JSON output` : ''}`,
+
+    analyze: `**${p}analyze** — Deep market analysis
+
+${p}analyze <ticker>             Full analysis: edge, drivers, catalysts, Kelly sizing
+${p}analyze <ticker> ${ctx === 'cli' ? '--' : ''}refresh     Force fresh Octagon report
+${ctx === 'cli' ? `
+Legacy aliases (still work):
+  ${p}edge [--ticker X]          Edge history / snapshots (default: last 24h)
+  ${p}edge --since <date>        Edges since date (e.g. 2026-03-01)` : ''}`,
+
+    watch: `**${p}watch** — Live monitoring
+
+Modes:
+  ${p}watch <ticker>               Per-ticker price/orderbook feed (5s default)
+  ${p}watch --theme <theme>        Continuous theme scan${ctx === 'cli' ? ' (default: every 60m)' : ' (press Esc to stop)'}
+${ctx === 'cli' ? `
+Flags:
+  --interval <minutes>              Scan interval for theme mode (min 15)
+  --live                            Force 15m interval
+  --json                            NDJSON output (one line per tick/cycle)
+  --dry-run                         Scan without persisting edges
+
+Press Ctrl+C to stop.` : `
+Per-ticker mode shows live price, bid/ask, spread, volume, and top-5 orderbook.
+Theme mode runs recurring Octagon scans and displays an edge table.`}`,
+
+    buy: `**${p}buy** — Buy contracts
+
+${p}buy <ticker> <count> [price${ctx === 'cli' ? '_in_cents' : ''}] [yes|no]${ctx === 'slash' ? '   Buy contracts (price in cents)' : ''}
+
+Example${ctx === 'cli' ? 's' : ''}:
+  ${p}buy KXBTC-26MAR14-T50049 10 ${ctx === 'cli' ? '          Buy at best ask (10 YES contracts)' : '56'}
+  ${p}buy KXBTC-26MAR14-T50049 10 ${ctx === 'cli' ? '56        Limit order at $0.56' : '56 no   Buy NO contracts'}
+${ctx === 'cli' ? `  ${p}buy KXBTC-26MAR14-T50049 10 56 no   Limit order for NO contracts at $0.56` : ''}
+Side defaults to YES if omitted.`,
+
+    sell: `**${p}sell** — Sell contracts
+
+${p}sell <ticker> <count> [price${ctx === 'cli' ? '_in_cents' : ''}] [yes|no]${ctx === 'slash' ? '  Sell contracts (price in cents)' : ''}
+
+Example${ctx === 'cli' ? 's' : ''}:
+  ${p}sell KXBTC-26MAR14-T50049 10 ${ctx === 'cli' ? '         Sell at best ask (10 YES contracts)' : '72'}
+  ${p}sell KXBTC-26MAR14-T50049 10 ${ctx === 'cli' ? '72       Limit order at $0.72' : '72 no   Sell NO contracts'}
+${ctx === 'cli' ? `  ${p}sell KXBTC-26MAR14-T50049 10 72 no  Limit order for NO contracts at $0.72` : ''}
+Side defaults to YES if omitted.`,
+
+    cancel: `**${p}cancel** — Cancel a resting order
+
+${p}cancel <order_id>`,
+
+    backtest: `**${p}backtest** — Model accuracy scorecard & edge scanner
+
+${p}backtest                              15-day lookback, both sections (default)
+${p}backtest --days 30                    30-day lookback
+${p}backtest --max-age 14                 Reject predictions older than 14 days (default = --days)
+${p}backtest --resolved                   Resolved markets only
+${p}backtest --unresolved                 Unresolved markets only
+${p}backtest --category crypto            Filter by category
+${p}backtest --min-edge 10                Stricter edge threshold in pp (default 0.5pp)
+${p}backtest --min-volume 10              Per-contract volume gate (default 1)
+${p}backtest --min-price 5 --max-price 95 Tradeable price band 0-100 (defaults: 5 / 95)
+${p}backtest --export results.csv         Per-market detail CSV
+${p}backtest --json                       Machine-readable output
+
+Looks back N days, compares what the model said then to where the market is now.
+Resolved markets: scored against Kalshi settlement (0 or 100).
+Unresolved markets: mark-to-market vs current Kalshi trading price.
+Per-contract entry: mp/kp come from the per-contract outcome_probabilities on the
+Octagon snapshot (no event-level fallback). Volume gate uses per-contract volume
+from the snapshot when available, else current Kalshi lifetime volume.
+ROI is capital-weighted: sum(pnl) / sum(capital) across edge signals, where capital
+is kp/100 for YES edges and (100-kp)/100 for NO edges (matches Supabase methodology).`,
+
+    'clear-cache': `**${ctx === 'cli' ? '' : 'bun start '}clear-cache** — Delete local cache
+
+${ctx === 'cli' ? `${p}` : 'bun start '}clear-cache                Delete the local SQLite database (~/.kalshi-bot/kalshi-bot.db)
+                               A fresh database will be created on next command.
+
+Use this when the local cache is corrupted or you want to start fresh.${ctx !== 'cli' ? '\nRun from terminal: bun start clear-cache' : ''}`,
+
+    init: `**${p}init** — Re-run setup wizard
+
+${p}init                       Launch the TUI with the setup wizard open
+                               Use this to configure or reconfigure API keys and preferences.`,
+
+    help: `**${p}help** — Show help
+
+${p}help                       Show all commands
+${p}help <command>             Show detailed help for a command`,
+  };
+}
+
+function buildOverview(ctx: HelpContext): string {
+  const p = prefix(ctx);
+  if (ctx === 'cli') {
+    return `**Kalshi Trading Bot CLI — CLI Commands**
+
+Quick start:
+  kalshi search crypto          Find markets by keyword or theme
+  kalshi analyze <ticker>       Deep analysis + trade recommendation
+  kalshi watch --theme crypto   Continuous scan across a theme
+
+Discovery:
+  search [theme|ticker|query]   Find markets by keyword or theme
+  search --refresh <query>      Force index rebuild then search
+  search themes                 List all themes and subcategories
+  search edge [--min-edge N]    Scan all markets by Octagon model edge
+  watch <ticker>                Live price/orderbook feed
+  watch --theme <theme>         Continuous theme scan (Ctrl+C to stop)
+  watch --refresh               Force index rebuild before watching
+
+Analysis & Trading:
+  analyze <ticker>              Full report: edge, drivers, Kelly sizing
+  analyze <ticker> --refresh    Force fresh Octagon report
+  buy <ticker> <n> [price] [yes|no]   Buy contracts (price in cents)
+  sell <ticker> <n> [price] [yes|no]  Sell contracts
+  cancel <order_id>                   Cancel a resting order
+
+Analysis:
+  backtest                      Model accuracy scorecard + live edge scanner
+  backtest --resolved           Resolved markets scorecard only
+  backtest --unresolved         Live edge scanner only
+
+Account:
+  portfolio                     Overview: positions, P&L, risk snapshot
+  portfolio positions           Open positions
+  portfolio orders              Resting orders
+  portfolio balance             Account balance
+
+System:
+  init                          Launch with setup wizard (configure API keys)
+  clear-cache                   Delete local SQLite cache and start fresh
+  setup                         Re-run setup wizard
+  help [command]                Show help for a command
+
+Flags: --json, --refresh, --performance, --dry-run, --verbose
+Backtest flags: --days, --max-age, --resolved, --unresolved, --category, --min-edge,
+                --min-volume, --min-price, --max-price, --export
+Run "kalshi help <command>" for detailed usage.`;
+  }
+
+  return `**Kalshi Trading Bot CLI — Commands**
+
+Quick start:
+  /search crypto          Find markets by keyword or theme
+  /analyze <ticker>       Deep analysis + trade recommendation
+  /watch --theme crypto   Continuous scan across a theme
+
+Discovery:
+  /search [theme|ticker|query]   Find markets by keyword or theme
+  /search --refresh <query>      Force index rebuild then search
+  /search themes                 List all themes and subcategories
+  /search edge [--min-edge N]    Scan all markets by Octagon model edge
+  /watch <ticker>                Live price/orderbook feed
+  /watch --theme <theme>         Continuous theme scan (Esc to stop)
+  /watch --refresh               Force index rebuild before watching
+
+Analysis:
+  /backtest                      Model accuracy scorecard + live edge scanner
+  /analyze <ticker>              Full report: edge, drivers, Kelly sizing
+  /analyze <ticker> refresh      Force fresh Octagon report
+  /buy <ticker> <n> [price] [yes|no]   Buy contracts (price in cents)
+  /sell <ticker> <n> [price] [yes|no]  Sell contracts
+  /review                              Review positions for close signals
+  /cancel <order_id>                   Cancel a resting order
+
+Account:
+  /portfolio                     Overview: positions, P&L, risk snapshot
+  /portfolio positions           Open positions
+  /portfolio orders              Resting orders
+  /portfolio balance             Account balance
+
+System:
+  /model                         Change LLM model/provider
+  /setup                         Re-run setup wizard
+  init                           Launch with setup wizard (run: bun start init)
+  clear-cache                    Delete local cache (run: bun start clear-cache)
+  /help [command]                Show help for a command
+  /quit                          Quit
+
+Tips:
+  Type natural language — e.g. "analyze KXBTC", "show my portfolio"
+  Press Esc to cancel a running query`;
+}
+
+export function buildHelp(ctx: HelpContext, topic?: string): { text: string } | { error: string } {
+  const topics = buildTopics(ctx);
+
+  if (topic && topics[topic]) {
+    return { text: topics[topic] };
+  }
+
+  if (topic) {
+    return { error: `Unknown help topic: "${topic}". Available: ${Object.keys(topics).join(', ')}` };
+  }
+
+  return { text: buildOverview(ctx) };
+}
+
+/** Shared trade argument validation for both dispatch and slash handlers. */
+export function validateTradeArgs(
+  countStr: string,
+  priceStr?: string,
+): { count: number; price: number | undefined } | { error: string } {
+  if (!/^\d+$/.test(countStr)) {
+    return { error: `Invalid count: ${countStr}` };
+  }
+  const count = Number(countStr);
+  if (count <= 0) {
+    return { error: `Invalid count: ${countStr}` };
+  }
+
+  let price: number | undefined;
+  if (priceStr !== undefined) {
+    if (!/^\d+$/.test(priceStr)) {
+      return { error: `Invalid price: ${priceStr}. Price must be 1-99 (cents).` };
+    }
+    price = Number(priceStr);
+    if (price < 1 || price > 99) {
+      return { error: `Invalid price: ${priceStr}. Price must be 1-99 (cents).` };
+    }
+  }
+
+  return { count, price };
+}

package/src/commands/helpers.ts

@@ -0,0 +1,48 @@
+import { callKalshiApi } from '../tools/kalshi/api.js';
+
+/**
+ * Parse a market quote from API response, handling both cent and dollar-string fields.
+ * Returns cents (1-99) or NaN if no valid quote found.
+ */
+function parseQuoteCents(market: Record<string, unknown>, field: 'yes_ask' | 'yes_bid' | 'no_ask' | 'no_bid'): number {
+  // Try dollar-string fields first (new API: yes_ask_dollars, legacy: dollar_yes_ask)
+  const dollarKey = `${field}_dollars`;      // e.g. yes_ask_dollars
+  const legacyDollarKey = `dollar_${field}`;  // e.g. dollar_yes_ask
+
+  const dollarStr = market[dollarKey] as string | undefined;
+  const legacyStr = market[legacyDollarKey] as string | undefined;
+
+  const d = dollarStr != null ? parseFloat(dollarStr) : legacyStr != null ? parseFloat(legacyStr) : NaN;
+  if (Number.isFinite(d) && d > 0) return Math.round(d * 100);
+
+  // Fall back to cent field
+  const cents = Number(market[field] ?? 0);
+  if (Number.isFinite(cents) && cents > 0) return cents;
+
+  return NaN;
+}
+
+/**
+ * Fetch the best available quote for a market order.
+ * Returns cents for the appropriate side/action, or an error message.
+ */
+export async function fetchMarketQuote(
+  ticker: string,
+  action: 'buy' | 'sell',
+  side: 'yes' | 'no' = 'yes',
+): Promise<{ cents: number } | { error: string }> {
+  const marketData = await callKalshiApi('GET', `/markets/${ticker}`) as Record<string, unknown>;
+  const market = (marketData.market ?? marketData) as Record<string, unknown>;
+
+  const field = side === 'no'
+    ? (action === 'sell' ? 'no_bid' : 'no_ask')
+    : (action === 'sell' ? 'yes_bid' : 'yes_ask');
+  const cents = parseQuoteCents(market, field);
+
+  if (!Number.isFinite(cents) || cents <= 0) {
+    const label = action === 'sell' ? 'bid' : 'ask';
+    return { error: `No ${label} available for ${ticker} — cannot place market order. Specify a price.` };
+  }
+
+  return { cents };
+}