get_chain_context

Retrieve DeFi context for blockchain networks including TVL, dominance, trends, top protocols, and market share movement. Supports major chains like Ethereum, Solana, Base, Arbitrum, and others.

Instructions

Get DeFi context for a specific blockchain: TVL, dominance, trend, top protocols, and whether the chain is gaining or losing market share. Supports: ethereum, solana, base, arbitrum, optimism, polygon, avalanche, bsc, tron, bitcoin.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`chain`	Yes	Chain name (e.g. "ethereum", "solana", "base", "arbitrum")

Implementation Reference

src/tools/get-chain-context.ts:39-125 (handler)

The main handler for the 'get_chain_context' tool, which fetches chain TVL, dominance, and protocol data.

export async function getChainContext(cache: CacheService, chain: string): Promise<ChainContextOutput | ErrorOutput> {
  const chainName = resolveChainName(chain);
  const cacheKey = `chain_context_${chainName.toLowerCase()}`;
  const cached = cache.get<ChainContextOutput>(cacheKey);
  if (cached) return cached.data;

  try {
    const [chains, protocols, history] = await Promise.all([
      getChains(),
      getProtocols(),
      getChainHistoricalTvl(chainName).catch(() => []),
    ]);

    const chainData = chains.find(c => c.name.toLowerCase() === chainName.toLowerCase());
    if (!chainData) {
      return {
        error: true, error_source: 'get_chain_context',
        agent_guidance: 'Chain not found. Verify the chain name and retry.',
        last_known_data: null, data_warnings: ['Chain not found in DeFiLlama data.'],
      };
    }

    const totalTvl = chains.reduce((sum, c) => sum + c.tvl, 0);
    const dominancePct = totalTvl > 0 ? Math.round((chainData.tvl / totalTvl) * 10000) / 100 : 0;

    // TVL changes from history
    let tvlChange7d = 0;
    let tvlChange30d = 0;
    if (history.length > 7) {
      const current = history[history.length - 1]?.tvl ?? chainData.tvl;
      const weekAgo = history[history.length - 8]?.tvl ?? current;
      tvlChange7d = weekAgo > 0 ? Math.round(((current - weekAgo) / weekAgo) * 10000) / 100 : 0;
      if (history.length > 30) {
        const monthAgo = history[history.length - 31]?.tvl ?? current;
        tvlChange30d = monthAgo > 0 ? Math.round(((current - monthAgo) / monthAgo) * 10000) / 100 : 0;
      }
    }

    let tvlTrend: ChainContextOutput['tvl_trend'] = 'stable';
    if (tvlChange7d > 10) tvlTrend = 'expanding';
    else if (tvlChange7d > 3) tvlTrend = 'expanding';
    else if (tvlChange7d < -10) tvlTrend = 'collapsing';
    else if (tvlChange7d < -3) tvlTrend = 'contracting';

    // Top protocols on this chain
    const chainProtocols = protocols
      .filter(p => p.chain.toLowerCase() === chainName.toLowerCase() || p.chain === '-')
      .sort((a, b) => b.tvl - a.tvl)
      .slice(0, 10);

    const topProtocols = chainProtocols.map(p => ({
      name: p.name,
      tvl_usd: p.tvl,
      category: p.category,
      dominance_on_chain: chainData.tvl > 0 ? Math.round((p.tvl / chainData.tvl) * 10000) / 100 : 0,
    }));

    // Dominance shift
    let dominanceShift: ChainContextOutput['chain_dominance_shift'] = 'stable';
    if (tvlChange7d > 5 && tvlChange7d > tvlChange30d / 4) dominanceShift = 'gaining';
    else if (tvlChange7d < -5) dominanceShift = 'losing';

    const guidance = generateChainGuidance(chainName, chainData.tvl, dominancePct, tvlTrend, dominanceShift, tvlChange7d);

    const result: ChainContextOutput = {
      chain: chainName,
      chain_tvl_usd: chainData.tvl,
      chain_dominance_pct: dominancePct,
      tvl_change_7d: tvlChange7d,
      tvl_change_30d: tvlChange30d,
      tvl_trend: tvlTrend,
      top_protocols: topProtocols,
      protocol_count: chainProtocols.length,
      chain_dominance_shift: dominanceShift,
      agent_guidance: guidance,
    };

    cache.set(cacheKey, result, getCacheTtl(BASE_TTL));
    return result;
  } catch {
    return {
      error: true, error_source: 'get_chain_context',
      agent_guidance: 'Chain context temporarily unavailable. Retry shortly.',
      last_known_data: null, data_warnings: ['Chain data source temporarily unavailable.'],
    };
  }
}

src/tools/get-chain-context.ts:26-37 (schema)

Type definition for the output of 'get_chain_context'.

export interface ChainContextOutput {
  chain: string;
  chain_tvl_usd: number;
  chain_dominance_pct: number;
  tvl_change_7d: number;
  tvl_change_30d: number;
  tvl_trend: 'expanding' | 'stable' | 'contracting' | 'collapsing';
  top_protocols: Array<{ name: string; tvl_usd: number; category: string; dominance_on_chain: number }>;
  protocol_count: number;
  chain_dominance_shift: 'gaining' | 'stable' | 'losing';
  agent_guidance: string;
}

fathom-fyi