🚀 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 market

• place_batch_orders - Múltiplas ordens em lote

• cancel_order - Cancelar ordem específica

• cancel_all_orders - Cancelar todas as ordens

• modify_order - Modificar preço/quantidade

• place_twap_order - Ordens TWAP para grande volume

• adjust_leverage - Ajustar alavancagem (cross/isolated)

• modify_isolated_margin - Gerenciar margem isolada

• update_dead_mans_switch - Sistema de segurança automático

👤 Gerenciamento de Conta (8 ferramentas)

• get_user_state - Estado completo da conta

• get_positions - Posições abertas com PnL

• get_open_orders - Ordens abertas

• get_user_fills - Histórico de trades

• get_historical_orders - Histórico de ordens

• get_portfolio_value - Análise completa do portfólio

• get_subaccounts - Gerenciar subcontas

• get_rate_limit_status - Status de rate limits

📊 Dados de Mercado (6 ferramentas)

• get_all_mids - Preços mid de todos os pares

• get_l2_orderbook - Order book L2 em tempo real

• get_candles - Dados históricos (OHLCV)

• get_recent_trades - Trades recentes

• get_funding_rates - Taxas de funding

• get_asset_contexts - Contexto e estatísticas de mercado

🔄 WebSocket em Tempo Real (4 ferramentas)

• subscribe_user_events - Eventos da conta

• subscribe_market_data - Dados de mercado live

• subscribe_order_updates - Atualizações de ordens

• get_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)

1. Clone ou baixe este repositório

   git clone https://github.com/seu-usuario/hyperliquid-mcp-server.git cd hyperliquid-mcp-server

2. Execute o script de instalação automática

   python3 setup.py

   O 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

3. Configure suas credenciais

   Edite o arquivo .env criado:

   nano .env

   Adicione suas credenciais da Hyperliquid:

   HYPERLIQUID_PRIVATE_KEY=0x... HYPERLIQUID_ACCOUNT_ADDRESS=0x... HYPERLIQUID_NETWORK=mainnet

4. Reinicie o Claude Desktop

   Feche completamente e reabra o Claude Desktop.

5. Verifique a instalação

   No Claude, pergunte:

   Quais ferramentas da Hyperliquid você tem disponíveis?

Instalação Manual (Avançado)

🔑 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 .env no 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

Ordem Market

Cancelar Ordens

Batch Trading

💰 Gerenciamento de Posições

Verificar Posições

Fechar Posição

Ajustar Alavancagem

📊 Análise de Mercado

Preços Atuais

Order Book

Dados Históricos

📡 Dados em Tempo Real (WebSocket)

Monitorar Order Book

Acompanhar Trades

🤖 Estratégias Avançadas

Estratégia Condicional

Análise de Portfólio

Market Making

🛠️ Configuração Avançada

Variáveis de Ambiente

Todas as configurações são gerenciadas pelo arquivo .env:

Testnet vs Mainnet

Para Desenvolvimento/Testes:

Para Trading Real:

⚠️ 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 .env no 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:

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

Soluções:

1. Verifique que o Claude Desktop foi fechado completamente antes da instalação

2. Confirme que claude_desktop_config.json está no local correto:

   • macOS: ~/Library/Application Support/Claude/

   • Linux: ~/.config/Claude/

   • Windows: %APPDATA%\Claude\

3. Reinicie Claude Desktop completamente (Quit, não apenas fechar janela)

4. Verifique logs em ~/Library/Logs/Claude/

Soluções:

1. Verifique que .env tem credenciais corretas

2. Confirme formato da private key (deve começar com 0x)

3. Certifique-se que account address corresponde à private key

4. Teste credenciais com chamada API simples

5. Verifique se está usando rede correta (testnet/mainnet)

Soluções:

1. Reduza frequência de requisições

2. Use WebSocket subscriptions em vez de polling

3. Agrupe operações relacionadas

4. Ajuste RATE_LIMIT_WEIGHT no .env

5. Verifique status com get_rate_limit_status

Soluções:

1. Verifique margem disponível suficiente

2. Confirme que leverage está configurado

3. Certifique-se que tamanho da ordem atende mínimo

4. Valide que preço está dentro de limites razoáveis

5. Verifique se mercado está em horário de trading

Soluções:

1. Verifique conectividade de rede

2. Confirme WebSocket URL correto

3. Certifique-se que firewall permite WebSocket

4. Reinicie o MCP server

5. Verifique logs para detalhes de erro

Modo Debug

Ative logs detalhados editando .env:

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:

📚 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:

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

1. Defina a tool em

2. Atualize

3. Teste a ferramenta

4. 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

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 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.

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.

Sim, o MCP server roda como parte do Claude Desktop e requer que ele esteja em execução.

Atualmente, uma conta por instalação. Suporte para múltiplas contas está no roadmap.

Aplicam-se as taxas padrão da Hyperliquid (maker/taker fees). O MCP server em si é gratuito e open-source.

Sua private key fica apenas no arquivo . Nunca é enviada para nenhum lugar além da API oficial da Hyperliquid.

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.

⚠️ 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!

⬆ Voltar ao topo

📸 Screenshots

Exemplo de Trading no Claude

Exemplo de Análise de Mercado

Happy Trading! 📈🚀