fathom-fyi

Instructions

Implementation Reference

• src/tools/get-event-catalyst-timeline.ts:102-242 (handler)

  The core function that calculates the event catalyst timeline, including FOMC, CPI, Jobs, options, political, and halving events.

  export async function getEventCatalystTimeline(
    cache: CacheService,
  ): Promise<CatalystTimelineOutput | ErrorOutput> {
    const cacheKey = 'event_catalyst_timeline';
    const cached = cache.get<CatalystTimelineOutput>(cacheKey);
    if (cached) return cached.data;
  
    try {
      const now = new Date();
      const catalysts: Catalyst[] = [];
  
      // FOMC
      for (const d of FOMC_DATES_2026) {
        const c = buildCatalyst(
          'FOMC Rate Decision', d, now, 'critical', 'monetary_policy',
          'Markets compress volatility 3-5 days before, expand after. Direction depends on dot plot vs expectations.',
          'Average BTC move: ±4-8% in 48h around FOMC. Highest single-event volatility driver.',
          'Reduce position sizes 48h before. Close leveraged positions. Re-enter after volatility settles (usually 4-6 hours post-announcement).',
        );
        if (c) catalysts.push(c);
      }
  
      // CPI
      for (const d of CPI_DATES_2026) {
        const c = buildCatalyst(
          'CPI Inflation Data', d, now, 'high', 'economic_data',
          'Hot CPI = risk-off (bearish crypto). Cool CPI = risk-on (bullish crypto). Inline = muted reaction.',
          'Average BTC move: ±2-5% on CPI day. Stronger reactions on surprises.',
          'If BTC/S&P correlation is high (>0.7), CPI matters significantly. Position for the surprise scenario or flatten before release.',
        );
        if (c) catalysts.push(c);
      }
  
      // Jobs
      for (const d of JOBS_DATES_2026) {
        const c = buildCatalyst(
          'Non-Farm Payrolls (Jobs Report)', d, now, 'medium', 'economic_data',
          'Strong jobs = higher rate expectations (bearish). Weak jobs = rate cut expectations (bullish). Context-dependent.',
          'Average BTC move: ±1-3% on jobs day. Lower impact than CPI/FOMC.',
          'Monitor in context of rate cycle. Currently less impactful than CPI but watch for regime shifts.',
        );
        if (c) catalysts.push(c);
      }
  
      // Options expiry
      for (const d of OPTIONS_EXPIRY_2026) {
        const isQuad = QUAD_WITCHING_2026.includes(d);
        const c = buildCatalyst(
          isQuad ? 'Quarterly Options Expiry (Quad Witching)' : 'Monthly Options Expiry',
          d, now,
          isQuad ? 'high' : 'medium',
          'options',
          'Max pain gravity pulls price toward max pain level 2-3 days before expiry. Pin risk increases.',
          isQuad ? 'Quad witching: 20-40% higher volume. Expect sharp moves and reversals.' : 'Monthly expiry: 10-20% volume increase typical. Check max pain for directional bias.',
          isQuad ? 'Avoid opening new positions 48h before quad witching. High probability of stop hunts and fakeouts.' : 'Check max pain level via get_derivatives_context. Price tends to gravitate toward it.',
        );
        if (c) catalysts.push(c);
      }
  
      // Political
      for (const pd of POLITICAL_DATES_2026) {
        const c = buildCatalyst(
          pd.event, pd.date, now, pd.impact, 'political',
          'Midterm elections historically positive for equities in the following year. Year 3 of presidential cycle averages +16%.',
          'Election week volatility typically elevated. Resolution usually bullish.',
          'Position for post-election rally if historical patterns hold. Reduce exposure going into election week.',
        );
        if (c) catalysts.push(c);
      }
  
      // BTC halving
      const halvingCatalyst = buildCatalyst(
        'Bitcoin Halving (Estimated)', BTC_HALVING_ESTIMATE, now, 'critical', 'crypto_specific',
        'Halvings historically precede 12-18 month bull runs. Supply shock takes months to manifest in price.',
        'Post-halving cycles have produced 300-2000% BTC returns over 12-18 months historically.',
        'Accumulate BTC in the 6 months leading up to halving. Historical pattern suggests patience is rewarded.',
      );
      if (halvingCatalyst) catalysts.push(halvingCatalyst);
  
      // Sort by date
      catalysts.sort((a, b) => a.hours_until - b.hours_until);
  
      const next24h = catalysts.filter(c => c.hours_until <= 24 && c.hours_until >= 0);
      const next7d = catalysts.filter(c => c.days_until <= 7 && c.days_until >= 0);
      const next30d = catalysts.filter(c => c.days_until <= 30 && c.days_until >= 0);
  
      // Catalyst density
      const criticalCount = next7d.filter(c => c.impact === 'critical' || c.impact === 'high').length;
      const density: CatalystTimelineOutput['catalyst_density'] =
        criticalCount >= 3 ? 'critical' :
        criticalCount >= 2 ? 'busy' :
        next7d.length >= 3 ? 'normal' :
        'quiet';
  
      // Risk windows
      const riskWindows: string[] = [];
      for (const c of next7d) {
        if (c.impact === 'critical' || c.impact === 'high') {
          riskWindows.push(`${c.event} in ${c.days_until}d ${c.hours_until % 24}h — ${c.impact} impact. ${c.trading_note}`);
        }
      }
  
      // Guidance
      let guidance = '';
      if (next24h.some(c => c.impact === 'critical')) {
        guidance = `CRITICAL: ${next24h.find(c => c.impact === 'critical')!.event} within 24 hours. Reduce all position sizes. Close leveraged trades. This is the highest-impact event on the calendar.`;
      } else if (next24h.some(c => c.impact === 'high')) {
        guidance = `HIGH IMPACT: ${next24h.find(c => c.impact === 'high')!.event} within 24 hours. Tighten stops, reduce leverage, prepare for elevated volatility.`;
      } else if (density === 'critical') {
        guidance = `Event-dense week ahead: ${criticalCount} high-impact catalysts in the next 7 days. Reduce overall exposure and trade smaller. Multiple volatility events compound risk.`;
      } else if (density === 'busy') {
        guidance = `Moderately busy calendar. ${next7d.length} events in the next 7 days including ${criticalCount} high-impact. Monitor positioning ahead of each event.`;
      } else if (density === 'quiet') {
        guidance = `Quiet catalyst calendar. No major events imminent. Technical and sentiment signals are more reliable in low-catalyst environments. Good window for momentum-based strategies.`;
      } else {
        guidance = `Normal catalyst density. ${next7d.length} events in the next 7 days. Standard risk management applies. Watch the next high-impact event: ${next7d.find(c => c.impact === 'critical' || c.impact === 'high')?.event || 'none in 7d'}.`;
      }
  
      const result: CatalystTimelineOutput = {
        current_date: now.toISOString().split('T')[0],
        next_24h: next24h,
        next_7d: next7d,
        next_30d: next30d,
        catalyst_density: density,
        risk_windows: riskWindows,
        agent_guidance: guidance,
      };
  
      cache.set(cacheKey, result, getCacheTtl(BASE_TTL));
      return result;
    } catch (err) {
      const msg = err instanceof Error ? err.message : 'Unknown error';
      return {
        error: true,
        error_source: 'calendar',
        agent_guidance: `Event catalyst timeline unavailable. ${msg}. Use general caution around known macro event dates.`,
        last_known_data: null,
        data_warnings: [msg],
      };
    }
  }

• src/index.ts:600-609 (registration)

  The tool registration and handler invocation in the main entry point.

  // ─── Tool: get_event_catalyst_timeline ───
  server.tool(
    'get_event_catalyst_timeline',
    'Upcoming market-moving events: FOMC, CPI, jobs reports, options expiry, quad witching, political events, BTC halving. Returns next 24h, 7d, and 30d catalysts with impact ratings, expected direction, historical volatility, and specific trading notes for each event.',
    {},
    async () => {
      const gateError = gateTool('get_event_catalyst_timeline');
      if (gateError) return { content: [{ type: 'text' as const, text: gateError }] };
  
      const text = await executeAndLog('get_event_catalyst_timeline', {}, () => getEventCatalystTimeline(cache));