# 🔮 Hyperliquid MCP Server

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**The first MCP server for DeFi perpetual futures trading.** Let AI agents trade on [Hyperliquid](https://hyperliquid.xyz) — the #1 decentralized derivatives exchange ($50B+ weekly volume).

> Trade perps, check positions, manage risk — all through natural language via Claude, GPT, or any MCP-compatible AI agent.

## ⚡ Features

| Tool | Description |
|------|-------------|
| `get_account_info` | Wallet balance, margin, withdrawable funds |
| `list_markets` | All available perpetual futures markets |
| `get_market_info` | Price, funding rate, OI, 24h volume |
| `get_orderbook` | Live orderbook with configurable depth |
| `get_open_orders` | All pending orders |
| `get_positions` | Open positions with PnL & liquidation price |
| `place_order` | Limit or market orders |
| `cancel_order` | Cancel by order ID |
| `set_leverage` | Set leverage (cross or isolated) |
| `close_position` | Close positions (market or limit) |

## 🚀 Quick Start

### 1. Install

```bash
pip install -e .
```

Or install dependencies directly:

```bash
pip install "mcp[server]" hyperliquid-python-sdk python-dotenv
```

### 2. Configure

```bash
cp .env.example .env
```

Edit `.env`:

```env
HYPERLIQUID_PRIVATE_KEY=your_private_key_here
HYPERLIQUID_WALLET_ADDRESS=0xYourAddress
HYPERLIQUID_TESTNET=true
```

> ⚠️ **Start with testnet!** Set `HYPERLIQUID_TESTNET=true` for paper trading.

### 3. Run

```bash
hyperliquid-mcp
# or
python -m hyperliquid_mcp.server
```

## 🤖 Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "hyperliquid": {
      "command": "python",
      "args": ["-m", "hyperliquid_mcp.server"],
      "cwd": "/path/to/hyperliquid-mcp",
      "env": {
        "HYPERLIQUID_PRIVATE_KEY": "your_key",
        "HYPERLIQUID_WALLET_ADDRESS": "0xYourAddress",
        "HYPERLIQUID_TESTNET": "true"
      }
    }
  }
}
```

Or if installed via pip:

```json
{
  "mcpServers": {
    "hyperliquid": {
      "command": "hyperliquid-mcp",
      "env": {
        "HYPERLIQUID_PRIVATE_KEY": "your_key",
        "HYPERLIQUID_WALLET_ADDRESS": "0xYourAddress",
        "HYPERLIQUID_TESTNET": "true"
      }
    }
  }
}
```

## 💬 Example Prompts

Once connected, try asking your AI agent:

- *"What's the current BTC funding rate on Hyperliquid?"*
- *"Show me the ETH orderbook, top 5 levels"*
- *"Set leverage to 5x on SOL and buy 10 SOL at market"*
- *"What are my open positions and total PnL?"*
- *"Close my ETH position at market price"*
- *"List all available markets and their max leverage"*

## 🔒 Security

- **Never commit your `.env` file** — it contains your private key
- **Start with testnet** — always test with paper money first
- **Review orders before confirming** — AI agents can make mistakes
- Private keys are only used locally — never transmitted except to Hyperliquid's API

## 📋 Requirements

- Python 3.10+
- A Hyperliquid wallet (testnet or mainnet)
- An MCP-compatible client (Claude Desktop, etc.)

## License

MIT