🚀 Hyperliquid MCP Server
Conecte Claude Code ao poder da Hyperliquid DEX
Desenvolvido por Caio Vicentino com Claude Code
Para as comunidades: Yield Hacker, Renda Cripto e Cultura Builder
Instalação • Recursos • Exemplos • Documentação • FAQ
📖 O que é este projeto?
O Hyperliquid MCP Server é uma implementação completa do Model Context Protocol (MCP) da Anthropic que permite ao Claude Desktop interagir diretamente com a exchange descentralizada Hyperliquid.
Com este servidor MCP, você pode:
- 💬 Tradear usando linguagem natural através do Claude
- 📊 Analisar mercados com dados em tempo real
- 🤖 Automatizar estratégias com a inteligência do Claude
- 🔐 Manter controle total das suas chaves e fundos
O que é MCP?
Model Context Protocol (MCP) é um padrão criado pela Anthropic para conectar assistentes de IA (como Claude) a ferramentas e fontes de dados externas. Pense nele como "plugins" para Claude Desktop.
O que é Hyperliquid?
Hyperliquid é uma exchange descentralizada (DEX) de alta performance para trading de futuros perpétuos, oferecendo:
- 📈 Orderbook on-chain com performance de CEX
- ⚡ Execução de baixa latência
- 💰 Taxas competitivas e funding rates
- 🔒 Full self-custody - você controla suas chaves
- 🎯 Alavancagem até 50x em diversos ativos
✨ Recursos
27 Ferramentas Poderosas em 4 Categorias
📈 Trading (9 ferramentas)
place_order- Ordens limit e marketplace_batch_orders- Múltiplas ordens em lotecancel_order- Cancelar ordem específicacancel_all_orders- Cancelar todas as ordensmodify_order- Modificar preço/quantidadeplace_twap_order- Ordens TWAP para grande volumeadjust_leverage- Ajustar alavancagem (cross/isolated)modify_isolated_margin- Gerenciar margem isoladaupdate_dead_mans_switch- Sistema de segurança automático
👤 Gerenciamento de Conta (8 ferramentas)
get_user_state- Estado completo da contaget_positions- Posições abertas com PnLget_open_orders- Ordens abertasget_user_fills- Histórico de tradesget_historical_orders- Histórico de ordensget_portfolio_value- Análise completa do portfólioget_subaccounts- Gerenciar subcontasget_rate_limit_status- Status de rate limits
📊 Dados de Mercado (6 ferramentas)
get_all_mids- Preços mid de todos os paresget_l2_orderbook- Order book L2 em tempo realget_candles- Dados históricos (OHLCV)get_recent_trades- Trades recentesget_funding_rates- Taxas de fundingget_asset_contexts- Contexto e estatísticas de mercado
🔄 WebSocket em Tempo Real (4 ferramentas)
subscribe_user_events- Eventos da contasubscribe_market_data- Dados de mercado livesubscribe_order_updates- Atualizações de ordensget_active_subscriptions- Gerenciar assinaturas
🚀 Instalação
Pré-requisitos
- Python 3.8+ instalado
- Claude Desktop instalado (baixar aqui)
- Conta Hyperliquid com credenciais de API
- macOS, Linux ou Windows
Instalação Rápida (Recomendado)
-
Clone ou baixe este repositório
git clone https://github.com/seu-usuario/hyperliquid-mcp-server.git cd hyperliquid-mcp-server -
Execute o script de instalação automática
python3 setup.pyO script irá:
- ✅ Criar ambiente virtual Python
- ✅ Instalar todas as dependências
- ✅ Gerar arquivos de configuração
- ✅ Configurar Claude Desktop automaticamente
- ✅ Guiá-lo através da configuração de credenciais
-
Configure suas credenciais
Edite o arquivo
.envcriado:nano .envAdicione suas credenciais da Hyperliquid:
HYPERLIQUID_PRIVATE_KEY=0x... HYPERLIQUID_ACCOUNT_ADDRESS=0x... HYPERLIQUID_NETWORK=mainnet -
Reinicie o Claude Desktop
Feche completamente e reabra o Claude Desktop.
-
Verifique a instalação
No Claude, pergunte:
Quais ferramentas da Hyperliquid você tem disponíveis?
Instalação Manual (Avançado)
Clique para expandir instruções manuais
# 1. Criar ambiente virtual
python3 -m venv venv
# 2. Ativar ambiente virtual
# macOS/Linux:
source venv/bin/activate
# Windows:
venv\Scripts\activate
# 3. Instalar dependências
pip install -r requirements.txt
# 4. Copiar template de configuração
cp .env.example .env
# 5. Editar .env com suas credenciais
nano .env
# 6. Configurar Claude Desktop
# Adicione ao arquivo de configuração do Claude:
# macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
# Linux: ~/.config/Claude/claude_desktop_config.json
# Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"hyperliquid": {
"command": "/caminho/completo/para/venv/bin/python",
"args": ["/caminho/completo/para/server.py"],
"env": {
"HYPERLIQUID_PRIVATE_KEY": "sua_chave_privada",
"HYPERLIQUID_ACCOUNT_ADDRESS": "seu_endereco"
}
}
}
}
🔑 Obtendo Suas Credenciais
1. Private Key (Chave Privada)
Exporte sua private key da carteira (MetaMask, Trust Wallet, etc.):
- Deve estar no formato
0x...(64 caracteres hexadecimais após o 0x) - NUNCA compartilhe esta chave com ninguém
- Mantenha em local seguro
2. Account Address (Endereço da Conta)
Seu endereço Ethereum (também formato 0x...):
- Endereço público da sua carteira
- Visível publicamente on-chain
⚠️ Segurança das Credenciais
- 🔒 Armazene credenciais apenas no arquivo
.env - ❌ NUNCA faça commit do
.envno git - 🧪 Use testnet para testes iniciais
- 🔄 Rotacione chaves periodicamente
- 💼 Use carteiras separadas para trading/holding
💡 Exemplos de Uso
Uma vez instalado, você pode interagir com a Hyperliquid através de linguagem natural no Claude Desktop:
📈 Trading
Colocar Ordem Limit
Você: "Coloque uma ordem de compra de 0.1 BTC a $45,000"
Claude irá:
✅ Validar sua solicitação
✅ Colocar a ordem
✅ Confirmar com order ID e status
Ordem Market
Você: "Compre 0.5 ETH a mercado"
Claude irá:
✅ Executar ordem imediatamente
✅ Mostrar preço de execução e taxas
✅ Atualizar sua posição
Cancelar Ordens
Você: "Cancele todas minhas ordens de BTC"
Claude irá usar: cancel_all_orders
✅ Cancelar todas as ordens de BTC
✅ Mostrar resumo de cancelamento
Batch Trading
Você: "Coloque 5 ordens de compra de ETH de $3000 a $2900 em intervalos de $25"
Claude irá usar: place_batch_orders
✅ Criar grid de ordens
✅ Executar em única transação
✅ Confirmar todas as ordens
💰 Gerenciamento de Posições
Verificar Posições
Você: "Quais são minhas posições abertas e seus PnLs?"
Claude mostrará:
📊 Todas as posições abertas
💵 Preços de entrada
📈 PnL (realizado e não realizado)
⚡ Alavancagem utilizada
⚠️ Preços de liquidação
Fechar Posição
Você: "Feche minha posição de ETH a mercado"
Claude irá:
✅ Fechar posição inteira
✅ Mostrar preço de saída
✅ Calcular PnL final
Ajustar Alavancagem
Você: "Configure alavancagem de 10x para trades de BTC"
Claude irá:
✅ Atualizar configuração de leverage
✅ Mostrar requisitos de margem
✅ Avisar sobre riscos
📊 Análise de Mercado
Preços Atuais
Você: "Qual o preço atual do BTC na Hyperliquid?"
Claude mostrará:
💰 Preço bid/ask
📊 Mark price
🎯 Index price
📈 Spread atual
Order Book
Você: "Mostre o order book do ETH"
Claude mostrará:
📗 Níveis de bid
📕 Níveis de ask
💹 Liquidez em cada nível
📊 Análise de spread
Dados Históricos
Você: "Pegue candles de 1 hora do BTC das últimas 24 horas"
Claude retornará:
📈 Dados OHLCV
📊 Volume
🔍 Pode analisar padrões
📡 Dados em Tempo Real (WebSocket)
Monitorar Order Book
Você: "Inscreva no order book do BTC e me alerte sobre ordens grandes"
Claude irá:
✅ Conectar ao WebSocket
✅ Stream do order book em tempo real
✅ Monitorar atividade de "baleias"
✅ Alertar sobre mudanças significativas
Acompanhar Trades
Você: "Monitore trades de ETH em tempo real"
Claude irá:
✅ Feed de trades ao vivo
✅ Analisar fluxo de compra/venda
✅ Detectar atividade incomum
🤖 Estratégias Avançadas
Estratégia Condicional
Você: "Se BTC cair abaixo de $44,000, compre 0.2 BTC com alavancagem 5x"
Claude irá:
1️⃣ Monitorar preço (subscribe_market_data)
2️⃣ Quando acionado, ajustar leverage
3️⃣ Colocar ordem
4️⃣ Confirmar execução
Análise de Portfólio
Você: "Analise o risco do meu portfólio atual"
Claude irá:
1️⃣ Buscar posições (get_positions)
2️⃣ Verificar saldo (get_user_state)
3️⃣ Calcular exposição por ativo
4️⃣ Avaliar utilização de margem
5️⃣ Recomendar ajustes
Market Making
Você: "Coloque ordens nos dois lados do ETH com spread de 1%, 0.1 ETH cada"
Claude irá usar: place_batch_orders
✅ Ordens simultâneas de compra/venda
✅ Configurar grid de market making
✅ Monitorar e ajustar
🛠️ Configuração Avançada
Variáveis de Ambiente
Todas as configurações são gerenciadas pelo arquivo .env:
# Credenciais (OBRIGATÓRIO)
HYPERLIQUID_PRIVATE_KEY=0x... # Chave privada Ethereum
HYPERLIQUID_ACCOUNT_ADDRESS=0x... # Endereço da carteira
# Rede
HYPERLIQUID_NETWORK=mainnet # ou 'testnet'
# Endpoints (configurado automaticamente baseado na rede)
HYPERLIQUID_API_URL=https://api.hyperliquid.xyz
HYPERLIQUID_WS_URL=wss://api.hyperliquid.xyz/ws
# Configurações Opcionais
LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR
RATE_LIMIT_WEIGHT=1200 # Max API weight por minuto
HTTP_TIMEOUT=30 # Timeout HTTP (segundos)
WS_TIMEOUT=60 # Timeout WebSocket (segundos)
Testnet vs Mainnet
Para Desenvolvimento/Testes:
HYPERLIQUID_NETWORK=testnet
HYPERLIQUID_API_URL=https://api.hyperliquid-testnet.xyz
HYPERLIQUID_WS_URL=wss://api.hyperliquid-testnet.xyz/ws
Para Trading Real:
HYPERLIQUID_NETWORK=mainnet
HYPERLIQUID_API_URL=https://api.hyperliquid.xyz
HYPERLIQUID_WS_URL=wss://api.hyperliquid.xyz/ws
⚠️ ATENÇÃO: Sempre teste em testnet primeiro!
🔒 Segurança
Gerenciamento de Chaves API
✅ FAÇA:
- Armazene chaves apenas no
.env - Use testnet para desenvolvimento
- Rotacione chaves periodicamente
- Configure whitelists de saques
- Use margem isolada para trades arriscados
- Mantenha backups seguros das chaves
❌ NÃO FAÇA:
- Commitar
.envno git - Compartilhar chaves em logs ou mensagens de erro
- Usar chaves de mainnet em desenvolvimento
- Armazenar chaves diretamente no código
- Compartilhar sua private key com ninguém
Segurança da Private Key
Sua private key tem controle total sobre sua conta:
- 🔐 Trate como uma senha bancária
- 🚫 Nunca compartilhe com ninguém
- 💾 Mantenha backups em locais seguros
- 🔧 Considere usar hardware wallet
- 👥 Use contas separadas para trading/holding
Dead Man's Switch
Configure um sistema de segurança automático:
"Configure dead man's switch para 300 segundos"
Se você não atualizar o switch no prazo:
- ⚠️ TODAS as ordens abertas serão canceladas automaticamente
- 🛡️ Proteção contra perda de conectividade
- 🔒 Segurança adicional para sua conta
🐛 Troubleshooting
Problemas Comuns
❌ "MCP server não encontrado no Claude Desktop"
Soluções:
- Verifique que o Claude Desktop foi fechado completamente antes da instalação
- Confirme que
claude_desktop_config.jsonestá no local correto:- macOS:
~/Library/Application Support/Claude/ - Linux:
~/.config/Claude/ - Windows:
%APPDATA%\Claude\
- macOS:
- Reinicie Claude Desktop completamente (Quit, não apenas fechar janela)
- Verifique logs em
~/Library/Logs/Claude/
❌ "Authentication failed"
Soluções:
- Verifique que
.envtem credenciais corretas - Confirme formato da private key (deve começar com
0x) - Certifique-se que account address corresponde à private key
- Teste credenciais com chamada API simples
- Verifique se está usando rede correta (testnet/mainnet)
❌ "Rate limit exceeded"
Soluções:
- Reduza frequência de requisições
- Use WebSocket subscriptions em vez de polling
- Agrupe operações relacionadas
- Ajuste
RATE_LIMIT_WEIGHTno.env - Verifique status com
get_rate_limit_status
❌ "Order placement failed"
Soluções:
- Verifique margem disponível suficiente
- Confirme que leverage está configurado
- Certifique-se que tamanho da ordem atende mínimo
- Valide que preço está dentro de limites razoáveis
- Verifique se mercado está em horário de trading
❌ "WebSocket disconnected"
Soluções:
- Verifique conectividade de rede
- Confirme WebSocket URL correto
- Certifique-se que firewall permite WebSocket
- Reinicie o MCP server
- Verifique logs para detalhes de erro
Modo Debug
Ative logs detalhados editando .env:
LOG_LEVEL=DEBUG
DEBUG=true
Isso mostrará:
- 📡 Todas as requisições/respostas de API
- 💬 Mensagens WebSocket
- ⏱️ Rastreamento de rate limits
- 🐛 Stack traces de erros
Testando o Servidor
Teste o MCP server isoladamente:
# Ative o ambiente virtual
source venv/bin/activate
# Execute o inspetor MCP
mcp dev server.py
# Isso abre uma interface de teste interativa
📚 Documentação Completa
APIs e SDKs
- Hyperliquid Docs: https://hyperliquid.gitbook.io/hyperliquid-docs/
- Python SDK: https://github.com/hyperliquid-dex/hyperliquid-python-sdk
- WebSocket API: https://hyperliquid.gitbook.io/hyperliquid-docs/websocket-api
- Trading Guide: https://hyperliquid.gitbook.io/hyperliquid-docs/trading
Model Context Protocol
- MCP Specification: https://modelcontextprotocol.io/
- MCP SDK: https://github.com/anthropics/mcp
- Claude Desktop: https://docs.anthropic.com/claude/docs/mcp
Rate Limits
Hyperliquid implementa rate limiting baseado em sistema de pesos:
| Tipo | Weight | Limite |
|---|---|---|
| Market Data | 1-2 | 1200/min |
| Account Data | 2-5 | 1200/min |
| Trading | 5-10 | 1200/min |
| WebSocket | 0 | Ilimitado |
Melhores Práticas:
- ✅ Use WebSocket para dados em tempo real
- ✅ Agrupe operações quando possível
- ✅ Cache dados que não mudam frequentemente
- ✅ Monitore uso de rate limit
🤝 Contribuindo
Contribuições são muito bem-vindas! Veja como adicionar novas ferramentas:
Adicionando uma Nova Tool
- Defina a tool em
server.py
@mcp.tool()
async def sua_nova_tool(param1: str, param2: int, ctx: Context = None) -> Dict[str, Any]:
"""
Descrição da ferramenta para Claude.
Args:
param1: Descrição do parâmetro 1
param2: Descrição do parâmetro 2
Returns:
Descrição do resultado
"""
if ctx: ctx.info(f"Executando sua_nova_tool...")
result = await app_context.sua_categoria.metodo(param1, param2)
return result
- Atualize
mcp.json
{
"name": "sua_nova_tool",
"description": "O que a ferramenta faz"
}
- Teste a ferramenta
mcp dev server.py
- Envie um pull request
Diretrizes de Desenvolvimento
- ✅ Siga o estilo de código existente
- ✅ Adicione type hints
- ✅ Inclua docstrings
- ✅ Trate erros graciosamente
- ✅ Considere rate limits
- ✅ Teste completamente
❓ FAQ
É seguro usar com dinheiro real?
O servidor é open-source e usa SDKs oficiais da Hyperliquid. No entanto, trading sempre carrega riscos. Sempre comece com testnet e pequenas quantias.
Claude pode tradear automaticamente?
Claude pode executar trades quando você solicitar, mas não irá tradear sem sua instrução explícita para cada ação. Você mantém controle total.
Qual a diferença de usar Hyperliquid diretamente?
Este MCP permite interação com linguagem natural através do Claude, facilitando análise de mercados e execução de estratégias complexas. Claude pode ajudar a interpretar dados, sugerir trades e executar múltiplas operações coordenadas.
Preciso manter Claude Desktop aberto?
Sim, o MCP server roda como parte do Claude Desktop e requer que ele esteja em execução.
Posso usar múltiplas contas Hyperliquid?
Atualmente, uma conta por instalação. Suporte para múltiplas contas está no roadmap.
Quais são as taxas?
Aplicam-se as taxas padrão da Hyperliquid (maker/taker fees). O MCP server em si é gratuito e open-source.
Minha private key é segura?
Sua private key fica apenas no arquivo .env na sua máquina local. Nunca é enviada para nenhum lugar além da API oficial da Hyperliquid.
Posso usar em Windows/Linux?
Sim! O MCP server é compatível com Windows, macOS e Linux.
🗺️ Roadmap
Funcionalidades planejadas:
- Order types avançados (stop-loss, take-profit)
- Analytics e reporting de portfólio
- Ferramentas de gerenciamento de risco
- Estratégias de trading automatizadas
- Suporte para múltiplas contas
- Dashboard de métricas de performance
- Integração com backtesting
- Sistema de alertas para preços/posições
- Exportação de dados de trades para CSV
- Integração com TradingView
📜 Licença
Este projeto está licenciado sob a MIT License - veja o arquivo LICENSE para detalhes.
MIT License
Copyright (c) 2025 Caio Vicentino
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
⚠️ Disclaimer
Este software é fornecido "como está", sem garantias de qualquer tipo.
Trading de criptomoedas carrega risco significativo.
- 📉 Você pode perder todo seu capital investido
- ⚠️ Apenas trade com fundos que você pode perder
- 🎓 Educação e gestão de risco são essenciais
- 🔬 Sempre teste em testnet primeiro
Os autores não são responsáveis por quaisquer perdas financeiras incorridas através do uso deste software.
Use por sua conta e risco.
🙏 Agradecimentos
- Anthropic pelo Model Context Protocol e Claude
- Hyperliquid Team pela excelente DEX e API
- Python MCP SDK Contributors
- Comunidades: Yield Hacker, Renda Cripto e Cultura Builder
- Comunidade Open Source
💬 Suporte e Comunidade
- Issues: GitHub Issues
- Discussões: GitHub Discussions
- Hyperliquid Discord: https://discord.gg/hyperliquid
- MCP Support: https://github.com/anthropics/mcp
👨💻 Sobre o Desenvolvedor
Desenvolvido por Caio Vicentino com Claude Code
Este projeto foi criado para democratizar o acesso a ferramentas profissionais de trading, permitindo que qualquer pessoa possa interagir com a Hyperliquid usando linguagem natural através do Claude.
Dedicado às comunidades:
- 🎯 Yield Hacker - Maximizando retornos DeFi
- 💰 Renda Cripto - Educação financeira em cripto
- 🏗️ Cultura Builder - Construindo o futuro com AI
🚀 Desenvolvido com Claude Code + Hyperliquid
Se este projeto foi útil, dê uma ⭐ no repositório!
📸 Screenshots
Exemplo de Trading no Claude
Você: "Mostre minhas posições abertas e calcule meu PnL total"
Claude: Deixe-me buscar suas posições atuais...
📊 POSIÇÕES ABERTAS:
1. BTC-PERP
• Tamanho: 0.5 BTC (Long)
• Preço de Entrada: $45,230.00
• Preço Atual: $46,150.00
• PnL não realizado: +$460.00 (+2.03%)
• Alavancagem: 5x
• Liquidação: $38,500.00
2. ETH-PERP
• Tamanho: 10 ETH (Long)
• Preço de Entrada: $2,420.00
• Preço Atual: $2,485.00
• PnL não realizado: +$650.00 (+2.69%)
• Alavancagem: 3x
• Liquidação: $2,050.00
💰 RESUMO:
• PnL Total não realizado: +$1,110.00
• ROE médio: +2.36%
• Margem utilizada: $8,450.00
• Margem disponível: $11,550.00
Exemplo de Análise de Mercado
Você: "Analise o mercado de BTC e sugira uma estratégia"
Claude: Vou analisar o mercado de BTC para você...
📊 ANÁLISE DE MERCADO - BTC
Preços Atuais:
• Preço Mark: $46,150.00
• Bid: $46,148.00 / Ask: $46,152.00
• Spread: $4.00 (0.009%)
Order Book:
• Suporte forte em: $46,000 (150 BTC)
• Resistência em: $46,500 (200 BTC)
• Liquidez: Excelente (spread tight)
Funding:
• Rate atual: 0.0085% (8h)
• Rate anualizado: +9.29%
• Próximo funding: em 3h 24min
Volume 24h:
• Volume: $2.4B
• Trades: 45,230
• Sentimento: Bullish (65% compra)
💡 SUGESTÃO DE ESTRATÉGIA:
Dado o funding positivo e resistência próxima, sugiro:
1. ENTRY: Ordem limit em $46,000 (suporte forte)
2. TAMANHO: 0.2 BTC (risco moderado)
3. ALAVANCAGEM: 3-5x
4. STOP LOSS: $45,700 (abaixo do suporte)
5. TAKE PROFIT: $46,800 (acima da resistência)
Risk/Reward: 1:2.66 (favorável)
Quer que eu execute esta estratégia?
Happy Trading! 📈🚀