hyperliquid-mcp

🟢 Hyperliquid MCP

Controle seus perpétuos da Hyperliquid a partir do Claude (ou qualquer cliente MCP) usando linguagem natural.

"Qual é o meu PnL de BTC?" → O Claude busca suas posições e responde em segundos.
"Comprar 0,1 ETH a mercado" → O Claude coloca a ordem via API da Hyperliquid.

Construído com o Model Context Protocol — o padrão aberto para conectar IA a ferramentas externas.

---

✨ Recursos

Ferramenta	Descrição
hl_get_all_mids	Preços de todos os ativos
hl_get_orderbook	Bids/asks L2 para qualquer ativo
hl_get_meta	Informações de mercado (alavancagem, tamanho do tick)
hl_get_candles	Histórico OHLCV (1m → 1d)
hl_get_user_state	Posições, patrimônio, margem, PnL
hl_get_open_orders	Ordens ativas
hl_get_fills	Histórico de negociações
hl_get_user_fills_by_coin	Histórico de negociações filtrado por moeda, com taxa de vitória e PnL
hl_get_funding_history	Histórico de taxas de funding
hl_get_predicted_fundings	Funding previsto para as próximas 8h em várias plataformas
hl_get_asset_contexts	Mark, oracle, funding, OI, variação 24h para BTC/ETH/XRP/SOL
hl_get_recent_trades	Tape ao vivo com desequilíbrio de compra/venda
hl_place_order	Colocar ordens limitadas ou a mercado
hl_cancel_order	Cancelar ordem específica
hl_cancel_all_orders	Cancelar todas as ordens (opcional: por moeda)
hl_close_position	Fechar posição inteira
hl_set_leverage	Definir alavancagem (cruzada ou isolada)

---

🚀 Início Rápido

1. Instalação

pip install hyperliquid-mcp

Ou execute diretamente sem instalar:

uvx hyperliquid-mcp

2. Configurar o Claude Desktop

Abra ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows) e adicione:

Modo somente leitura (posições, preços, histórico — nenhuma chave privada necessária):

{
  "mcpServers": {
    "hyperliquid": {
      "command": "uvx",
      "args": ["hyperliquid-mcp"],
      "env": {
        "HL_WALLET_ADDRESS": "0xYourWalletAddressHere"
      }
    }
  }
}

Modo de negociação (colocar ordens, cancelar, fechar posições):

{
  "mcpServers": {
    "hyperliquid": {
      "command": "uvx",
      "args": ["hyperliquid-mcp"],
      "env": {
        "HL_PRIVATE_KEY": "0xYourPrivateKeyHere"
      }
    }
  }
}

⚠️ Nunca compartilhe sua chave privada. Ela permanece na sua máquina — este servidor roda localmente via stdio, nenhum dado é enviado para qualquer lugar exceto a API oficial da Hyperliquid.

3. Reinicie o Claude Desktop e comece a conversar

What are my open positions?
What's the ETH funding rate this week?
Place a limit order to buy 0.5 SOL at $150

---

🔧 Configuração Manual (a partir do código-fonte)

git clone https://github.com/erscoder/hyperliquid-mcp
cd hyperliquid-mcp
pip install -e .
cp .env.example .env
# Edit .env with your wallet address or private key

Depois, em claude_desktop_config.json:

{
  "mcpServers": {
    "hyperliquid": {
      "command": "python",
      "args": ["-m", "hyperliquid_mcp"],
      "cwd": "/path/to/hyperliquid-mcp",
      "env": {
        "HL_WALLET_ADDRESS": "0xYourWalletAddressHere"
      }
    }
  }
}

---

🔒 Segurança

• Suas chaves nunca saem da sua máquina. O servidor roda localmente via transporte stdio.
• Somente leitura por padrão. Defina apenas HL_WALLET_ADDRESS se você não quiser negociação habilitada.
• Negociação requer HL_PRIVATE_KEY. Sem isso, todas as ferramentas de negociação retornam um erro.
• Use uma carteira de negociação dedicada com fundos limitados para segurança extra.

---

🤖 Uso em Agentes de IA

MCP não é apenas para clientes de chat. Use hyperliquid-mcp como a camada de negociação dentro de qualquer agente autônomo.

LangChain / LangGraph

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "hyperliquid": {
        "command": "uvx",
        "args": ["hyperliquid-mcp"],
        "transport": "stdio",
        "env": {"HL_WALLET_ADDRESS": "0xYourWallet"}
    }
})

tools = await client.get_tools()
# tools now includes hl_get_user_state, hl_get_orderbook, etc.
# Pass them to any LangChain agent or LangGraph node

CrewAI

from crewai import Agent
from crewai_tools import MCPTool

hl_tools = MCPTool.from_server(
    command="uvx",
    args=["hyperliquid-mcp"],
    env={"HL_WALLET_ADDRESS": "0xYourWallet"}
)

trader = Agent(
    role="Trading Analyst",
    goal="Monitor Hyperliquid positions and funding rates",
    tools=hl_tools
)

Agente personalizado (MCP Python SDK)

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

server_params = StdioServerParameters(
    command="uvx",
    args=["hyperliquid-mcp"],
    env={"HL_WALLET_ADDRESS": "0xYourWallet"}
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool("hl_get_user_state", {})
        print(result.content)

Ideias de agentes:

• Monitor de portfólio que alerta quando as taxas de funding disparam acima do limite
• Gerenciador de risco que fecha posições automaticamente quando o drawdown excede o limite
• Scanner de arbitragem comparando funding entre ativos
• Agente de briefing matinal que resume PnL noturno e posições abertas

---

💬 Outros Clientes MCP

Funciona com qualquer cliente compatível com MCP:

• Claude Desktop — veja o Início Rápido acima
• VS Code (Copilot) — adicione em .vscode/mcp.json
• Cursor — adicione nas configurações de MCP
• Continue.dev — adicione na configuração

---

📄 Licença

MIT — livre para usar, fazer fork e contribuir.

---

🌟 Histórico de Estrelas

Se isso economizou seu tempo, uma ⭐ ajuda muito!