hyperliquid-whalealert-mcp

Instructions

Implementation Reference

• main.py:82-87 (handler)

  The handler function for get_whale_alerts tool that fetches whale data using the helper function and formats it to markdown before returning.

  @mcp.tool()
  async def get_whale_alerts(ctx: Context) -> str:
      """Fetch recent whale alerts and return as a Markdown table"""
      client = ctx.request_context.lifespan_context.client
      data = await fetch_whale_data(client)
      return json_to_markdown_list(data)

• main.py:82-82 (registration)

  Decorator that registers the get_whale_alerts function as an MCP tool.

  @mcp.tool()

• main.py:40-52 (helper)

  Helper function to fetch whale alert data from the Coinglass API.

  async def fetch_whale_data(client: httpx.AsyncClient) -> List[Dict[str, Any]]:
      try:
          response = await client.get(API_BASE_URL)
          response.raise_for_status()
          data = response.json()
          if data.get("code") != "0":
              raise ValueError(f"API error: {data.get('msg')}")
          return data.get("data", [])
      except httpx.HTTPStatusError as e:
          raise ValueError(f"HTTP error: {str(e)}")
      except Exception as e:
          raise ValueError(f"Failed to fetch whale data: {str(e)}")

• main.py:54-79 (helper)

  Helper function to convert whale alert JSON data into a formatted Markdown list.

  def json_to_markdown_list(data: List[Dict[str, Any]]) -> str:
      if not data:
          return "No whale alert data available."
      
      markdown_lines = []
      for tx in data:
          # Map position_action to human-readable
          action = "Open" if tx.get("position_action") == 1 else "Close"
          
          # Convert timestamp (milliseconds) to readable format
          create_time = datetime.fromtimestamp(tx.get("create_time") / 1000.0).strftime("%Y-%m-%d %H:%M:%S")
          
          # Format transaction as Markdown list item
          item = (
              f"- **{tx.get('symbol')} Transaction**:\n"
              f"  - User Address: {tx.get('user')}\n"
              f"  - Position Size: {tx.get('position_size')}\n"
              f"  - Entry Price: ${tx.get('entry_price')}\n"
              f"  - Liquidation Price: ${tx.get('liq_price')}\n"
              f"  - Position Value (USD): ${tx.get('position_value_usd')}\n"
              f"  - Action: {action}\n"
              f"  - Create Time: {create_time}"
          )
          markdown_lines.append(item)
      
      return "\n".join(markdown_lines)