get_user_fills_by_time
Retrieve user trading history and fill data from Hyperliquid DEX for specific time periods to analyze past trades and transaction records.
Instructions
Get trading history (fills) for a specific time range
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| endTime | No | End time in milliseconds | |
| startTime | No | Start time in milliseconds | |
| user | No | User wallet address (optional, defaults to configured wallet) |
Implementation Reference
- 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": [], }, )
- 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}", ) ] }
- 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,