Hyperliquid MCP Server

Instructions

Implementation Reference

• hyperliquid_mcp_server/tools/account_info.py:41-62 (schema)

  Tool schema definition with input validation for user, startTime, and endTime parameters.

  get_user_fills_by_time_tool = Tool(
      name="get_user_fills_by_time",
      description="Get trading history (fills) for a specific time range",
      inputSchema={
          "type": "object",
          "properties": {
              "user": {
                  "type": "string",
                  "description": "User wallet address (optional, defaults to configured wallet)",
              },
              "startTime": {
                  "type": "number",
                  "description": "Start time in milliseconds",
              },
              "endTime": {
                  "type": "number",
                  "description": "End time in milliseconds",
              },
          },
          "required": [],
      },
  )

• hyperliquid_mcp_server/tools/account_info.py:154-189 (handler)

  Primary handler function that processes tool arguments, fetches fills via client, handles errors, and returns formatted text content with trade details.

  async def handle_get_user_fills_by_time(client: HyperliquidClient, args: Dict[str, Any]) -> Dict[str, Any]:
      """Handle get user fills by time request."""
      user = args.get("user")
      start_time = args.get("startTime")
      end_time = args.get("endTime")
  
      result = await client.get_user_fills_by_time(user, start_time, end_time)
  
      if not result.success:
          raise ValueError(f"Failed to get user fills by time: {result.error}")
  
      fills = result.data or []
  
      if not fills:
          return {
              "content": [
                  TextContent(
                      type="text",
                      text="No trading history found for the specified time range.",
                  )
              ]
          }
  
      fills_text = "\n".join(
          f"{datetime.fromtimestamp(fill['time'] / 1000).isoformat()}: {fill['coin']} {'BUY' if fill['side'] == 'B' else 'SELL'} {fill['sz']} @ {fill['px']} (Fee: {fill['fee']})"
          for fill in fills
      )
  
      return {
          "content": [
              TextContent(
                  type="text",
                  text=f"Trading History ({len(fills)} fills):\n\n{fills_text}",
              )
          ]
      }

• hyperliquid_mcp_server/utils/hyperliquid_client.py:146-167 (helper)

  Core API client method that sends POST request to Hyperliquid's /info endpoint with 'userFillsByTime' type and optional time filters to retrieve user fills.

  async def get_user_fills_by_time(
      self,
      user: Optional[str] = None,
      start_time: Optional[int] = None,
      end_time: Optional[int] = None,
  ) -> ApiResponse[List[UserFill]]:
      """Get trading history for a specific time range."""
      try:
          payload = {
              "type": "userFillsByTime",
              "user": user or self.config.wallet_address,
          }
          if start_time is not None:
              payload["startTime"] = start_time
          if end_time is not None:
              payload["endTime"] = end_time
  
          response = await self.client.post("/info", json=payload)
          response.raise_for_status()
          return ApiResponse(success=True, data=response.json())
      except Exception as e:
          return ApiResponse(success=False, error=str(e))

• hyperliquid_mcp_server/main.py:104-105 (registration)

  Tool registration in the main call_tool dispatcher, mapping tool name to handler execution.

  elif name == "get_user_fills_by_time":
      result = await handle_get_user_fills_by_time(client, args)

• hyperliquid_mcp_server/http_server.py:50-50 (registration)

  Tool handler mapping in HTTP server's TOOL_HANDLERS dictionary for HTTP deployment.

  "get_user_fills_by_time": handle_get_user_fills_by_time,