hl_vault_leaderboard

Instructions

Implementation Reference

• falsifylab_alpha_mcp.py:75-107 (registration)

  Tool definition/registration for hl_vault_leaderboard in the TOOLS list, with input schema (limit, sort_by).

  TOOLS = [
      {
          "name": "top_yield_farms",
          "description": "Latest 24h top DeFi yield farm picks with realistic "
                         "APY (emissions stripped), risk notes, TVL, protocol. "
                         "Sourced from FalsifyLab daily aggregator.",
          "inputSchema": {
              "type": "object",
              "properties": {
                  "limit": {"type": "integer", "default": 10,
                             "description": "max results (1-50)"},
                  "min_apy": {"type": "number", "default": 0,
                               "description": "filter floor in pct"},
                  "asset": {"type": "string",
                             "description": "filter by asset symbol (BTC, ETH, SOL, etc.)"},
              },
          },
      },
      {
          "name": "hl_vault_leaderboard",
          "description": "Hyperliquid vault leaderboard with NAV, 30d return, "
                         "max drawdown, follower count, composite score. "
                         "Real-time scrape of HL info API.",
          "inputSchema": {
              "type": "object",
              "properties": {
                  "limit": {"type": "integer", "default": 10},
                  "sort_by": {"type": "string",
                                "enum": ["score", "tvl", "return_30d", "followers"],
                                "default": "score"},
              },
          },
      },

• falsifylab_alpha_mcp.py:190-194 (handler)

  Handler dispatch for hl_vault_leaderboard — calls backend API endpoint /api/hl_vaults via _api_get helper.

  def call_tool(name: str, args: dict) -> dict:
      if name == "top_yield_farms":
          return _api_get("/api/yield/top", args)
      if name == "hl_vault_leaderboard":
          return _api_get("/api/hl_vaults", args)

• falsifylab_alpha_mcp.py:51-70 (helper)

  Helper function _api_get that makes the actual HTTP GET request to the backend API; used by all tool handlers including hl_vault_leaderboard.

  def _api_get(path: str, params: dict | None = None) -> dict:
      if params:
          from urllib.parse import urlencode
          path = f"{path}?{urlencode(params)}"
      req = urllib.request.Request(
          f"{API_BASE}{path}",
          headers={
              "User-Agent": USER_AGENT,
              "Accept": "application/json",
              **({"Authorization": f"Bearer {API_KEY}"} if API_KEY else {}),
          },
      )
      try:
          with urllib.request.urlopen(req, timeout=20) as r:
              return json.loads(r.read())
      except urllib.error.HTTPError as e:
          body = e.read().decode(errors="ignore")[:400]
          return {"error": f"HTTP {e.code}: {body}"}
      except Exception as e:
          return {"error": str(e)[:200]}