list_top_coins

Instructions

Implementation Reference

• coin_mcp/coingecko.py:264-307 (handler)

  The main handler for the list_top_coins tool. Decorated with @mcp.tool(), it builds query parameters and calls CoinGecko's /coins/markets endpoint via the cached HTTP helper _cg_get.

  @mcp.tool()
  async def list_top_coins(
      vs_currency: str = "usd",
      order: Literal[
          "market_cap_desc", "market_cap_asc",
          "volume_desc", "volume_asc",
          "id_asc", "id_desc",
      ] = "market_cap_desc",
      per_page: int = 100,
      page: int = 1,
      category: str = "",
      price_change_percentages: str = "24h",
  ) -> Any:
      """List top coins with market data (price, market cap, volume, change %) — sortable and paginated.
  
      The workhorse for "show me the top N coins" / "top by volume" / "top in
      DeFi" style questions. Each call returns up to 250 coins; paginate for more.
  
      Args:
          vs_currency: Quote currency (e.g. "usd").
          order: Sort order. Default is descending market cap.
          per_page: 1..250 coins per page.
          page: Page number, 1-indexed.
          category: Optional category ID to filter by (see `list_categories`),
              e.g. "decentralized-finance-defi", "layer-1", "meme-token".
          price_change_percentages: Comma list of windows to include —
              any of "1h,24h,7d,14d,30d,200d,1y".
  
      Returns:
          Array of coin objects with id, symbol, name, image, current_price,
          market_cap, market_cap_rank, total_volume, high_24h, low_24h,
          price_change_*_in_currency, ath, atl, circulating_supply, etc.
      """
      params: dict[str, Any] = {
          "vs_currency": vs_currency,
          "order": order,
          "per_page": max(1, min(per_page, 250)),
          "page": max(1, page),
          "sparkline": "false",
          "price_change_percentage": price_change_percentages,
      }
      if category:
          params["category"] = category
      return await _cg_get("/coins/markets", params)

• coin_mcp/coingecko.py:265-276 (schema)

  Input type schema and parameter defaults for list_top_coins. Parameters include vs_currency, order (Literal of sort options), per_page (1-250), page, category filter, and price_change_percentages.

  async def list_top_coins(
      vs_currency: str = "usd",
      order: Literal[
          "market_cap_desc", "market_cap_asc",
          "volume_desc", "volume_asc",
          "id_asc", "id_desc",
      ] = "market_cap_desc",
      per_page: int = 100,
      page: int = 1,
      category: str = "",
      price_change_percentages: str = "24h",
  ) -> Any:

• coin_mcp/coingecko.py:264-264 (registration)

  Tool registration via the @mcp.tool() decorator on the FastMCP instance from coin_mcp.core. The registration occurs at module import time (triggered by server.py importing coin_mcp.coingecko).

  @mcp.tool()

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

  The _cg_get helper constructs the full CoinGecko URL (choosing Pro or Public base) and delegates to the cached _http_get with 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/cache.py:31-31 (helper)

  Cache TTL rule for the /coins/markets endpoint (used by list_top_coins): 60-second TTL, labeled 'coins/markets'.

  ("/api/v3/coins/markets", 60.0, "coins/markets"),