Hyperliquid Whalealert MCP

🚀 Hyperliquid WhaleAlert MCP

An MCP server that offers real - time whale alerts on Hyperliquid, identifying positions with a notional value over $1 million.

🚀 Quick Start

This MCP server is designed to provide real - time whale alerts on Hyperliquid. It helps users keep track of large - scale positions with a notional value exceeding $1 million.

✨ Features

• Tool: get_whale_alerts: Retrieves recent whale transactions and presents them as a well - formatted Markdown table using pandas.
• Prompt: summarize_whale_activity: Generates a summary of whale transactions, including metrics such as total position value and notable symbols.

📦 Installation

Prerequisites

• Python: Version 3.10 or higher.
• CoinGlass API Key: Obtain it from CoinGlass (required for API access).
• uv: Package and dependency manager (install uv).

Steps

1. Clone the Repository:

   git clone https://github.com/kukapay/hyperliquid-whalealert-mcp.git
   cd hyperliquid-whalealert-mcp
   

2. Install Dependencies:

   uv sync
   

   This command installs the dependencies specified in pyproject.toml.

3. Claude Desktop Integration: You can install the server in Claude Desktop using the following command:

   uv run mcp install mcp.py --name "Hyperliquid Whale Alert"
   

   Alternatively, you can update the configuration file manually:

   {
     "mcpServers": {
       "hyperliquid-whalealert": {
         "command": "uv",
         "args": [ "--directory", "/path/to/hyperliquid-whalealert-mcp", "run", "main.py" ],
         "env": { "COINGLASS_API_KEY": "your_api_key" }
       }
     }
   }
   

   Replace /path/to/hyperliquid-whalealert-mcp with your actual installation path and COINGLASS_API_KEY with your API key.

💻 Usage Examples

Basic Usage

Using the Tool

The get_whale_alerts tool fetches whale transaction data and returns it as a Markdown list. Here is an example output:

- **ETH Transaction**:
  - User Address: 0x3fd4444154242720c0d0c61c74a240d90c127d33
  - Position Size: 12700
  - Entry Price: $1611.62
  - Liquidation Price: $527.2521
  - Position Value (USD): $21003260
  - Action: Close
  - Create Time: 2025-05-20 12:31:57
- **BTC Transaction**:
  - User Address: 0x1cadadf0e884ac5527ae596a4fc1017a4ffd4e2c
  - Position Size: 33.54032
  - Entry Price: $87486.2
  - Liquidation Price: $44836.8126
  - Position Value (USD): $2936421.4757
  - Action: Close
  - Create Time: 2025-05-20 12:31:17

To use the tool:

• In the MCP Inspector, select get_whale_alerts and execute it.
• In Claude Desktop, use the registered server and call the tool via the UI or API.

Using the Prompt

The summarize_whale_activity prompt generates a summary of whale transactions. Here is an example interaction (in a compatible client):

/summarize_whale_activity

Response:

I'll analyze the whale transaction data and provide a summary.

This can be further extended by LLMs to provide detailed metrics like total position value or notable symbols.

📄 License

This project is licensed under the MIT License. See the LICENSE file for more details.