get_macro_blocks

Instructions

Returns SPY macro climate (market mode, buy ratio) and list of recent
block trades over $200K with symbol, direction, and size.
Use this to understand where institutional money is flowing.

Implementation Reference

• horus_mcp_public.py:164-188 (handler)

  The main handler function for the 'get_macro_blocks' tool. It fetches macro block trade data from the /v1/flow/equity/macro-blocks endpoint, parses the SPY macro climate and recent block trades, and formats a human-readable summary string with emoji indicators.

  async def get_macro_blocks() -> str:
      """Get US equity market macro trend and recent institutional block trades.
      
      Returns SPY macro climate (market mode, buy ratio) and list of recent
      block trades over $200K with symbol, direction, and size.
      Use this to understand where institutional money is flowing.
      """
      data = await _fetch("/v1/flow/equity/macro-blocks")
      if data.get("error"):
          return json.dumps(data, indent=2)
      
      climate = data.get("spy_macro_climate", {})
      blocks = data.get("recent_block_trades", [])
      
      result = f"🦅 SPY MACRO CLIMATE: {climate.get('market_mode')} (Buy Ratio: {climate.get('spy_buy_ratio')})\n\n"
      result += f"🐋 RECENT BLOCK TRADES (>200k) (Total: {data.get('block_count')}):\n"
      
      if not blocks:
          result += "- None in the last 5 minutes.\n"
      else:
          for b in blocks:
              action = "SELL 🔴" if b["is_sell"] else "BUY 🟢"
              result += f"- {b['symbol']} | {action} | ${b['notional']:,.2f} | {b['seconds_ago']}s ago\n"
              
      return result

• horus_mcp_public.py:163-163 (registration)

  The tool is registered via the @mcp.tool() decorator from FastMCP, which automatically registers 'get_macro_blocks' as an MCP tool.

  @mcp.tool()

• horus_mcp_public.py:165-170 (schema)

  The docstring serves as the schema/description for the tool. It has no parameters (empty signature) and returns a formatted string with SPY macro climate and block trade info.

  """Get US equity market macro trend and recent institutional block trades.
  
  Returns SPY macro climate (market mode, buy ratio) and list of recent
  block trades over $200K with symbol, direction, and size.
  Use this to understand where institutional money is flowing.
  """

• horus_mcp_public.py:58-89 (helper)

  The _fetch helper function is used by get_macro_blocks to make HTTP requests to the RapidAPI endpoint, handling auth errors, rate limiting, and network issues.

  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)}"
              }