get_user_trade_history

Retrieve trade history for a Hyperliquid account to analyze transaction patterns and track performance over time.

Instructions

Fetch the trade fill history for a specific user account.

Parameters:
    account_address (str): The Hyperliquid account address (e.g., '0xcd5051944f780a621ee62e39e493c489668acf4d').
    ctx (Context): The MCP context object for accessing server state.

Returns:
    str: A JSON string containing a list of trade fills, each with details such as symbol, size, price, timestamp,
        and trade ID. Returns a JSON string with an error message if the query fails.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`account_address`	Yes

Implementation Reference

main.py:83-101 (handler)

The handler function decorated with @mcp.tool() implements the get_user_trade_history tool. It takes an account_address and ctx, calls info.user_fills(account_address) from the Hyperliquid SDK to fetch trade fills, and returns them as JSON or an error message. The docstring provides input/output schema details.

# Tool: Get user trade history
@mcp.tool()
async def get_user_trade_history(account_address: str, ctx: Context) -> str:
    """
    Fetch the trade fill history for a specific user account.

    Parameters:
        account_address (str): The Hyperliquid account address (e.g., '0xcd5051944f780a621ee62e39e493c489668acf4d').
        ctx (Context): The MCP context object for accessing server state.

    Returns:
        str: A JSON string containing a list of trade fills, each with details such as symbol, size, price, timestamp,
            and trade ID. Returns a JSON string with an error message if the query fails.
    """
    try:
        fills = info.user_fills(account_address)
        return json.dumps(fills)
    except Exception as e:
        return json.dumps({"error": f"Failed to fetch user fills: {str(e)}"})

main.py:14-14 (helper)
Global 'info' instance from hyperliquid.info.Info used by the tool to call user_fills(account_address).
```
info = Info(constants.MAINNET_API_URL, skip_ws=True)  # Initialize Info for mainnet
```

main.py:391-397 (helper)

A prompt function 'analyze_positions' that instructs to use get_user_trade_history among other tools for analysis.

return [
    base.UserMessage(f"Please analyze the trading positions for account {account_address}:"),
    base.UserMessage("Use the get_user_state, get_user_open_orders, get_user_trade_history, get_user_funding_history, and get_user_fees tools to fetch data."),
    base.AssistantMessage(
        "I'll analyze the user's trading positions, open orders, trade history, funding payments, and fees to provide insights on risk and performance."
    )
]

hyperliquid-info-mcp