Hyperliquid MCP Server

Instructions

Implementation Reference

• hyperliquid_mcp_server/tools/trading.py:137-172 (handler)

  The main handler function for the 'place_order' tool. It parses input arguments, constructs an OrderRequest and PlaceOrderAction, calls the HyperliquidClient's place_order method, and returns a formatted response.

  async def handle_place_order(client: HyperliquidClient, args: Dict[str, Any]) -> Dict[str, Any]:
      """Handle place order request."""
      asset_index = args["assetIndex"]
      is_buy = args["isBuy"]
      price = args["price"]
      size = args["size"]
      reduce_only = args.get("reduceOnly", False)
      time_in_force = args["timeInForce"]
      client_order_id = args.get("clientOrderId")
  
      order = OrderRequest(
          a=asset_index,
          b=is_buy,
          p=price,
          s=size,
          r=reduce_only,
          t={"limit": LimitOrderType(tif=time_in_force)},
      )
  
      if client_order_id:
          order.c = client_order_id
  
      action = PlaceOrderAction(orders=[order])
      result = await client.place_order(action)
  
      if not result.success:
          raise ValueError(f"Failed to place order: {result.error}")
  
      return {
          "content": [
              TextContent(
                  type="text",
                  text=f"Order placed successfully!\n\n{json.dumps(result.data, indent=2)}",
              )
          ]
      }

• hyperliquid_mcp_server/tools/trading.py:19-57 (schema)

  Defines the Tool object for 'place_order' including name, description, and detailed input schema for validation.

  place_order_tool = Tool(
      name="place_order",
      description="Place a limit or trigger order on Hyperliquid",
      inputSchema={
          "type": "object",
          "properties": {
              "assetIndex": {
                  "type": "number",
                  "description": "Asset index for the coin (0 for BTC, 1 for ETH, etc.)",
              },
              "isBuy": {
                  "type": "boolean",
                  "description": "True for buy order, false for sell order",
              },
              "price": {
                  "type": "string",
                  "description": "Order price as string",
              },
              "size": {
                  "type": "string",
                  "description": "Order size as string",
              },
              "reduceOnly": {
                  "type": "boolean",
                  "description": "Whether this is a reduce-only order (optional, default false)",
              },
              "timeInForce": {
                  "type": "string",
                  "description": "Time in force",
                  "enum": ["Gtc", "Ioc", "Alo"],
              },
              "clientOrderId": {
                  "type": "string",
                  "description": "Client order ID (optional)",
              },
          },
          "required": ["assetIndex", "isBuy", "price", "size", "timeInForce"],
      },
  )

• hyperliquid_mcp_server/main.py:67-85 (registration)

  Registers the 'place_order' tool (via place_order_tool) in the MCP server's list of available tools.

  @app.list_tools()
  async def list_tools() -> list:
      """List all available tools."""
      return [
          # Market data tools
          get_all_mids_tool,
          get_l2_book_tool,
          get_candle_snapshot_tool,
          # Account info tools
          get_open_orders_tool,
          get_user_fills_tool,
          get_user_fills_by_time_tool,
          get_portfolio_tool,
          # Trading tools
          place_order_tool,
          place_trigger_order_tool,
          cancel_order_tool,
          cancel_all_orders_tool,
      ]

• hyperliquid_mcp_server/main.py:107-110 (registration)

  Dispatches tool calls to the 'handle_place_order' function when 'place_order' is requested.

      result = await handle_get_portfolio(client, args)
  elif name == "place_order":
      result = await handle_place_order(client, args)
  elif name == "place_trigger_order":

• hyperliquid_mcp_server/utils/hyperliquid_client.py:183-204 (helper)

  Core helper method in HyperliquidClient that signs and submits the place order action to the Hyperliquid API.

  async def place_order(self, action: PlaceOrderAction) -> ApiResponse[Any]:
      """Place an order."""
      try:
          if not self.account:
              raise ValueError("Private key required for trading operations")
  
          nonce = self._generate_nonce()
          signature = await self._sign_action(action.model_dump(), nonce)
  
          payload = {
              "action": action.model_dump(),
              "nonce": nonce,
              "signature": signature,
              "vaultAddress": self.config.wallet_address,
          }
  
          response = await self.client.post("/exchange", json=payload)
          response.raise_for_status()
          return ApiResponse(success=True, data=response.json())
      except Exception as e:
          return ApiResponse(success=False, error=str(e))