get_market_chart

Instructions

Implementation Reference

• coin_mcp/coingecko.py:130-168 (handler)

  The actual implementation of the `get_market_chart` tool. It is an async function decorated with @mcp.tool() that validates coin_id, builds params (vs_currency, days, optional interval), and calls the CoinGecko API endpoint /coins/{coin_id}/market_chart.

  @mcp.tool()
  async def get_market_chart(
      coin_id: str,
      vs_currency: str = "usd",
      days: str = "30",
      interval: Literal["", "daily"] = "",
  ) -> Any:
      """Get historical price, market cap and total volume time series for a coin.
  
      Use this to draw line charts or compute returns/volatility over a window.
      For candlestick (OHLC) data use `get_aggregated_ohlc` instead.
  
      Granularity is auto-selected by CoinGecko based on `days`:
        - days <= 1   -> ~5-minute datapoints
        - days <= 90  -> ~hourly datapoints
        - days >  90  -> daily datapoints
  
      Args:
          coin_id: CoinGecko coin ID (e.g. "bitcoin").
          vs_currency: Quote currency (e.g. "usd", "eur", "btc").
          days: Window in days. Examples: "1", "7", "14", "30", "90", "180",
              "365", or "max" for the full history.
          interval: Force daily granularity by passing "daily". Leave empty for auto.
  
      Returns:
          Object with three arrays of [unix_ms, value] pairs:
            - prices
            - market_caps
            - total_volumes
  
      Note: `coin_id` is validated against `^[a-z0-9][a-z0-9._-]{0,127}$`.
      """
      err = _validate_id(coin_id, "coin_id")
      if err is not None:
          return err
      params: dict[str, Any] = {"vs_currency": vs_currency, "days": days}
      if interval:
          params["interval"] = interval
      return await _cg_get(f"/coins/{coin_id}/market_chart", params)

• coin_mcp/coingecko.py:136-161 (schema)

  The docstring/type signature and input schema for `get_market_chart` — defines parameters coin_id (str), vs_currency (str, default 'usd'), days (str, default '30'), interval (Literal['', 'daily'], default ''), and the return shape with prices/market_caps/total_volumes arrays.

  ) -> Any:
      """Get historical price, market cap and total volume time series for a coin.
  
      Use this to draw line charts or compute returns/volatility over a window.
      For candlestick (OHLC) data use `get_aggregated_ohlc` instead.
  
      Granularity is auto-selected by CoinGecko based on `days`:
        - days <= 1   -> ~5-minute datapoints
        - days <= 90  -> ~hourly datapoints
        - days >  90  -> daily datapoints
  
      Args:
          coin_id: CoinGecko coin ID (e.g. "bitcoin").
          vs_currency: Quote currency (e.g. "usd", "eur", "btc").
          days: Window in days. Examples: "1", "7", "14", "30", "90", "180",
              "365", or "max" for the full history.
          interval: Force daily granularity by passing "daily". Leave empty for auto.
  
      Returns:
          Object with three arrays of [unix_ms, value] pairs:
            - prices
            - market_caps
            - total_volumes
  
      Note: `coin_id` is validated against `^[a-z0-9][a-z0-9._-]{0,127}$`.
      """

• coin_mcp/core.py:58-180 (registration)

  The FastMCP instance `mcp` from core is imported by coingecko.py (line 7: `from .core import ... mcp`). The @mcp.tool() decorator on line 130 registers `get_market_chart` with the MCP server.

  mcp = FastMCP(
      name="coin-mcp",
      instructions="""\
  This MCP server provides comprehensive cryptocurrency market data from
  multiple complementary sources:
  
  - **CoinGecko** — aggregated market data (volume-weighted prices, market cap,
    OHLC, history, exchange directory, NFTs, categories, derivatives directory,
    public-company crypto treasuries, trending searches, search index).
  - **CCXT** — real-time per-exchange data via a unified API for 100+ centralized
    exchanges (order books, recent trades, tickers, OHLCV candles, market lists,
    perpetual-futures funding rates).
  - **DefiLlama** — protocol-level TVL, chain TVL, stablecoin caps, yield pools,
    DEX volumes, fees & revenue, oracle token prices.
  - **DexScreener** — DEX-side prices and liquidity for tokens too small or new
    for CoinGecko aggregation, across all major chains.
  - **Alternative.me** — Crypto Fear & Greed Index sentiment indicator.
  - **Local technical indicators** — RSI, MACD, Bollinger, EMA/SMA, ATR
    computed in-process from any OHLCV input.
  
  ================================================================
  HOW TO PICK THE RIGHT TOOL  (43 tools total)
  ================================================================
  
  | Question | Tool |
  |----------|------|
  | What's BTC's price right now? | get_price |
  | Tell me about Solana | get_coin_details |
  | 30-day price/volume/market-cap chart | get_market_chart |
  | Daily candlesticks for ETH (aggregated) | get_aggregated_ohlc |
  | Which exchanges support a coin? | get_coin_tickers |
  | Coin name -> CoinGecko ID (also exchanges/categories/NFTs) | search |
  | Top 100 coins by market cap | list_top_coins |
  | What's hot/trending today? | get_trending |
  | Biggest 24h gainers and losers | get_top_gainers_losers |
  | Total market cap, BTC dominance | get_global_market |
  | DeFi TVL totals (high level, CoinGecko view) | get_global_defi |
  | Categories (Layer 1, DeFi, Meme...) | list_categories |
  | Browse all exchanges (CoinGecko directory) | list_exchanges_directory |
  | Single-exchange metadata (CoinGecko directory) | get_exchange_info |
  | Derivatives platforms | list_derivatives_exchanges |
  | NFT collections list | list_nfts |
  | Single NFT collection detail | get_nft_collection |
  | Public companies holding BTC/ETH | get_companies_holdings |
  | What exchanges can I query in real time? | list_supported_exchanges |
  | All trading pairs on Binance/etc. | get_exchange_markets |
  | Best bid/ask/last on a specific exchange | get_exchange_ticker |
  | Real-time order book on a specific exchange | get_orderbook |
  | Recent public trades on a specific exchange | get_recent_trades |
  | 1-minute candles on Binance for BTC/USDT | get_exchange_ohlcv |
  | Funding rate for a perp | get_funding_rate |
  | Sentiment: fearful or greedy? | get_fear_greed_index |
  | Compute RSI/MACD/Bollinger/ATR/etc on OHLCV | compute_indicators |
  | Per-protocol TVL / TVL history | get_protocol_tvl |
  | Browse DefiLlama protocols by TVL | list_protocols |
  | Chain-level TVL ranking (Ethereum, Solana, ...) | list_chains_tvl |
  | Historical TVL for one chain or all of DeFi | get_chain_tvl_history |
  | Stablecoin caps and chain breakdown | list_stablecoins |
  | Yield-pool APYs | list_yield_pools |
  | DEX 24h volume rankings | list_dex_volumes |
  | Per-protocol fees and revenue | list_fees_revenue |
  | DefiLlama oracle price for `chain:address` tokens | get_token_dex_price |
  | DEX price for a small/new token (any chain) | dex_search |
  | All DEX pairs for a given token address | get_dex_token_pairs |
  | Single DEX pair detail | get_dex_pair |
  | Newly profiled DEX tokens | list_latest_dex_tokens |
  | Currently boosted (paid) DEX tokens | list_top_boosted_tokens |
  | What's currently cached (rate-limit relief) | cache_stats |
  | Drop the HTTP cache | clear_cache |
  | Funding-rate time series for a perp | get_funding_rate_history |
  | Current open interest for a perp | get_open_interest |
  | Compare funding rates across exchanges | compare_funding_rates |
  | Are all data sources healthy / fast? | health_check |
  | Same coin's price across CG + multiple CEX + DEX | compare_prices |
  | Best bid/ask merged across many exchanges | get_consolidated_orderbook |
  
  ================================================================
  KEY THINGS TO REMEMBER
  ================================================================
  
  1. **CoinGecko uses coin IDs**, not ticker symbols. IDs look like "bitcoin",
     "ethereum", "solana". Resolve unknown names via `search` first.
  
  2. **CCXT uses unified symbols + exchange IDs.** Symbols: "BTC/USDT", "ETH/USD".
     Linear perps use settle suffix: "BTC/USDT:USDT". Exchange IDs are lowercase
     ("binance", "okx", "coinbase", "kraken", "bybit", "kucoin").
  
  3. **Aggregated vs per-exchange.** CoinGecko = volume-weighted across all
     venues. CCXT = one specific exchange. Use CoinGecko for "the market";
     use CCXT for venue-specific or sub-hour granularity.
  
  4. **DEX vs CEX prices.** For tokens listed on CoinGecko, prefer CoinGecko/
     CCXT. For new/long-tail tokens, use DexScreener (`dex_search`,
     `get_dex_token_pairs`, `get_dex_pair`) or DefiLlama (`get_token_dex_price`).
  
  5. **Default vs_currency is "usd"**. CCXT symbols already encode quote currency.
  
  6. **Rate limits.** CoinGecko public allows ~30 req/min — but this server
     caches responses with TTLs tuned per endpoint. Repeated identical calls
     come from cache; check `cache_stats` if surprised by stale data, and
     `clear_cache` to force-refresh everything.
  
  7. **Time ranges.** `get_market_chart` and `get_aggregated_ohlc` accept a
     `days` parameter. CoinGecko auto-selects granularity: minute when days<=1,
     hourly when days<=90, daily otherwise.
  
  8. **Presentation.** Tools return raw numbers. Format prices/percentages/
     timestamps appropriately when answering the user.
  
  ================================================================
  NAMING & VALIDATION CONVENTIONS
  ================================================================
  
  - Coin / exchange / NFT IDs must match `^[a-z0-9._-]+$` (lowercase slugs).
  - Token addresses are either EVM (`0x` followed by 40 hex chars) or Solana
    base58 (32-44 chars). Tools validate the shape before sending requests.
  - Tools never run network requests until validation passes — invalid input
    returns a `{"error": ...}` envelope synchronously.
  - Tools may return `{"error": ...}` envelopes on upstream failure. Callers
    should check the result with the structured-error helper before assuming
    success and indexing into other fields.
  """,
  )

• coin_mcp/core.py:220-225 (helper)

  The `_cg_get` helper used by `get_market_chart` to make the actual HTTP GET request to CoinGecko, combining the base URL with the path and params and auth headers.

  async def _cg_get(path: str, params: dict[str, Any] | None = None) -> Any:
      return await _http_get(
          f"{_coingecko_base()}{path}",
          params=params,
          headers=_coingecko_headers(),
      )

• coin_mcp/prompts.py:24-25 (registration)

  References `get_market_chart` in the analyze_coin prompt template, demonstrating its usage context.

  f"3. Call `get_market_chart(coin_id='{coin_id}', vs_currency='{vs_currency}', days=90)` "
  "and describe the 90-day shape (uptrend / downtrend / range, volume regime, notable moves).\n"