get_liquidation_heatmap

Instructions

Returns clusters of long and short liquidations at specific price levels
with total dollar amounts. Critical for avoiding entries near massive
liquidation zones that could trigger cascading price moves.

Args:
    symbol: Trading pair (default: ETHUSDT)

Implementation Reference

• horus_mcp_public.py:208-220 (handler)

  The main handler for the 'get_liquidation_heatmap' tool. It is decorated with @mcp.tool(), takes a symbol parameter (default: ETHUSDT), fetches data from the /v1/intelligence/liquidation-heatmap endpoint via the _fetch helper, and returns the JSON result as a string.

  @mcp.tool()
  async def get_liquidation_heatmap(symbol: str = "ETHUSDT") -> str:
      """Get liquidation zones with dollar amounts — where leveraged positions will be force-closed.
      
      Returns clusters of long and short liquidations at specific price levels
      with total dollar amounts. Critical for avoiding entries near massive
      liquidation zones that could trigger cascading price moves.
      
      Args:
          symbol: Trading pair (default: ETHUSDT)
      """
      data = await _fetch(f"/v1/intelligence/liquidation-heatmap?symbol={symbol}")
      return json.dumps(data, indent=2)

• horus_mcp_public.py:210-218 (schema)

  The docstring serves as the schema/description for this tool. It documents that the tool returns liquidation zones with dollar amounts at specific price levels for leveraged positions.

  """Get liquidation zones with dollar amounts — where leveraged positions will be force-closed.
  
  Returns clusters of long and short liquidations at specific price levels
  with total dollar amounts. Critical for avoiding entries near massive
  liquidation zones that could trigger cascading price moves.
  
  Args:
      symbol: Trading pair (default: ETHUSDT)
  """

• horus_mcp_public.py:208-208 (registration)

  The tool is registered with MCP via the @mcp.tool() decorator on line 208, which automatically registers it with the FastMCP server instance.

  @mcp.tool()

• horus_mcp_public.py:58-89 (helper)

  The _fetch helper function that gets called by get_liquidation_heatmap. It makes an HTTP GET request to the RapidAPI endpoint, handles responses (success, 401/403 auth errors, 429 rate limits, and other errors), and returns the parsed JSON dict.

  async def _fetch(endpoint: str) -> dict:
      """Fetch data from the live RapidAPI endpoint."""
      async with httpx.AsyncClient(timeout=10.0) as client:
          try:
              resp = await client.get(
                  f"{RAPIDAPI_BASE_URL}{endpoint}",
                  headers=HEADERS,
              )
              if resp.status_code == 200:
                  return resp.json()
              elif resp.status_code in [401, 403]:
                  return {
                      "error": True,
                      "signal": "UNAUTHORIZED",
                      "detail": "Invalid or missing RAPIDAPI_KEY. Please verify your RapidAPI subscription."
                  }
              elif resp.status_code == 429:
                  return {
                      "error": True,
                      "signal": "RATE_LIMITED",
                      "detail": "You have exceeded your RapidAPI quota. Please upgrade your plan."
                  }
              return {
                  "error": True,
                  "status_code": resp.status_code,
                  "detail": resp.text,
              }
          except Exception as e:
              return {
                  "error": True,
                  "detail": f"Network Error: {str(e)}"
              }