get_user_state
Retrieve user trading positions, margin details, and withdrawable balance from Hyperliquid to monitor account status and manage risk.
Instructions
Query user state including trading positions, margin, and withdrawable balance.
Parameters:
account_address (str): The Hyperliquid account address (e.g., '0xcd5051944f780a621ee62e39e493c489668acf4d').
check_spot (bool, optional): If True, queries spot user state; otherwise, queries perpetuals state. Defaults to False.
ctx (Context, optional): The MCP context object for accessing server state.
Returns:
str: A JSON string containing the user state, including a list of positions (with symbol, size, entry_price,
current_price, unrealized_pnl), margin_summary, and withdrawable balance. Returns a JSON string with an
error message if the query fails.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| account_address | Yes | ||
| check_spot | No |
Implementation Reference
- main.py:23-42 (handler)The handler function implementing the 'get_user_state' tool logic. It conditionally queries spot or perpetuals user state via the Hyperliquid Info API, serializes to JSON, and handles exceptions.
@mcp.tool() async def get_user_state(account_address: str, check_spot: bool=False, ctx: Context=None) -> str: """ Query user state including trading positions, margin, and withdrawable balance. Parameters: account_address (str): The Hyperliquid account address (e.g., '0xcd5051944f780a621ee62e39e493c489668acf4d'). check_spot (bool, optional): If True, queries spot user state; otherwise, queries perpetuals state. Defaults to False. ctx (Context, optional): The MCP context object for accessing server state. Returns: str: A JSON string containing the user state, including a list of positions (with symbol, size, entry_price, current_price, unrealized_pnl), margin_summary, and withdrawable balance. Returns a JSON string with an error message if the query fails. """ try: user_state = info.spot_user_state(account_address) if check_spot else info.user_state(account_address) return json.dumps(user_state) except Exception as e: return json.dumps({"error": f"Failed to fetch user state: {str(e)}"})