get_correlation_matrix

Analyze Bitcoin's 30-day correlation with S&P 500 and Gold to determine if it's trading as a risk asset, safe haven, or independently, helping assess macro spillover risk.

Instructions

BTC correlation with traditional finance: 30-day Pearson correlation with S&P 500 and Gold, plus current TradFi prices. Shows whether BTC is trading as a risk asset, safe haven, or independently. Critical for understanding macro spillover risk.

Input Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Implementation Reference

src/tools/get-correlation-matrix.ts:23-58 (handler)

The main handler function for the get_correlation_matrix tool. It retrieves correlation data, generates summary/guidance, and handles caching and error cases.

export async function getCorrelationMatrixTool(cache: CacheService): Promise<CorrelationMatrixOutput | ErrorOutput> {
  const cached = cache.get<CorrelationMatrixOutput>(CACHE_KEY);
  if (cached) return cached.data;

  try {
    const data = await getCorrelationData();

    const summary = generateSummary(data);
    const guidance = generateGuidance(data);

    const result: CorrelationMatrixOutput = {
      btc_sp500_correlation: data.btc_sp500.correlation_30d,
      btc_sp500_classification: data.btc_sp500.classification,
      btc_gold_correlation: data.btc_gold.correlation_30d,
      btc_gold_classification: data.btc_gold.classification,
      sp500_price: data.sp500_price,
      sp500_change_pct: data.sp500_change_pct,
      gold_price: data.gold_price,
      gold_change_pct: data.gold_change_pct,
      macro_risk_appetite: data.macro_risk_appetite,
      correlation_summary: summary,
      agent_guidance: guidance,
    };

    cache.set(CACHE_KEY, result, getCacheTtl(BASE_TTL));
    return result;
  } catch (err) {
    return {
      error: true,
      error_source: 'get_correlation_matrix',
      agent_guidance: 'TradFi correlation data unavailable. Cannot assess BTC relationship to equities or gold. Assume moderate positive correlation with S&P 500 as a safe default. Do not use absence of this data as a reason to increase risk.',
      last_known_data: cache.get<CorrelationMatrixOutput>(CACHE_KEY)?.data ?? null,
      data_warnings: ['TradFi correlation data temporarily unavailable (Yahoo Finance).'],
    };
  }
}

src/tools/get-correlation-matrix.ts:9-21 (schema)

The output interface schema for the tool.

export interface CorrelationMatrixOutput {
  btc_sp500_correlation: number;
  btc_sp500_classification: string;
  btc_gold_correlation: number;
  btc_gold_classification: string;
  sp500_price: number;
  sp500_change_pct: number;
  gold_price: number;
  gold_change_pct: number;
  macro_risk_appetite: string;
  correlation_summary: string;
  agent_guidance: string;
}

fathom-fyi