get_user_state
Query trading positions, margin details, and withdrawable balance for Hyperliquid accounts to monitor portfolio status and risk exposure.
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
| Name | Required | Description | Default |
|---|---|---|---|
| account_address | Yes | ||
| check_spot | No |
Input Schema (JSON Schema)
{
"properties": {
"account_address": {
"title": "Account Address",
"type": "string"
},
"check_spot": {
"default": false,
"title": "Check Spot",
"type": "boolean"
}
},
"required": [
"account_address"
],
"type": "object"
}
Implementation Reference
- main.py:22-42 (handler)The handler function for the 'get_user_state' tool, including the @mcp.tool() decorator for registration. It fetches the user's trading state (perpetuals or spot) from the Hyperliquid API using the 'info' client and returns it as a JSON string, with error handling.# Tool: Get user state @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)}"})
- main.py:22-23 (registration)The @mcp.tool() decorator registers the get_user_state function as an MCP tool.# Tool: Get user state @mcp.tool()
- main.py:392-397 (helper)A prompt that references the get_user_state tool as part of analyzing user positions.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." ) ]