{"id":49873790,"url":"https://github.com/caiovicentino/hyperliquid-mcp-server","last_synced_at":"2026-05-15T11:32:36.646Z","repository":{"id":323419560,"uuid":"1093169889","full_name":"caiovicentino/hyperliquid-mcp-server","owner":"caiovicentino","description":"🚀 MCP Server para Hyperliquid DEX - Trade com Claude usando linguagem natural. Desenvolvido por Caio Vicentino para as comunidades Yield Hacker, Renda Cripto e Cultura Builder","archived":false,"fork":false,"pushed_at":"2025-11-10T02:19:52.000Z","size":56,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-10T04:15:39.642Z","etag":null,"topics":["ai","automation","blockchain","claude","crypto","defi","hyperliquid","mcp","python","trading"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/caiovicentino.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-10T02:16:02.000Z","updated_at":"2025-11-10T02:26:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/caiovicentino/hyperliquid-mcp-server","commit_stats":null,"previous_names":["caiovicentino/hyperliquid-mcp-server"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/caiovicentino/hyperliquid-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiovicentino%2Fhyperliquid-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiovicentino%2Fhyperliquid-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiovicentino%2Fhyperliquid-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiovicentino%2Fhyperliquid-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/caiovicentino","download_url":"https://codeload.github.com/caiovicentino/hyperliquid-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiovicentino%2Fhyperliquid-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33065334,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-15T02:00:06.351Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","automation","blockchain","claude","crypto","defi","hyperliquid","mcp","python","trading"],"created_at":"2026-05-15T11:32:35.919Z","updated_at":"2026-05-15T11:32:36.638Z","avatar_url":"https://github.com/caiovicentino.png","language":"Python","funding_links":[],"categories":["DeFi, Markets, and Trading"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🚀 Hyperliquid MCP Server\n\n[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)\n[![MCP](https://img.shields.io/badge/MCP-1.0%2B-green.svg)](https://modelcontextprotocol.io/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Hyperliquid](https://img.shields.io/badge/Hyperliquid-DEX-purple.svg)](https://hyperliquid.xyz)\n\n**Conecte Claude Code ao poder da Hyperliquid DEX**\n\nDesenvolvido por **Caio Vicentino** com **Claude Code**\n\n*Para as comunidades: Yield Hacker, Renda Cripto e Cultura Builder*\n\n[Instalação](#-instalação) • [Recursos](#-recursos) • [Exemplos](#-exemplos-de-uso) • [Documentação](#-documentação-completa) • [FAQ](#-faq)\n\n\u003c/div\u003e\n\n---\n\n## 📖 O que é este projeto?\n\nO **Hyperliquid MCP Server** é uma implementação completa do [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) da Anthropic que permite ao **Claude Desktop** interagir diretamente com a exchange descentralizada **Hyperliquid**.\n\nCom este servidor MCP, você pode:\n- 💬 **Tradear usando linguagem natural** através do Claude\n- 📊 **Analisar mercados** com dados em tempo real\n- 🤖 **Automatizar estratégias** com a inteligência do Claude\n- 🔐 **Manter controle total** das suas chaves e fundos\n\n### O que é MCP?\n\n**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.\n\n### O que é Hyperliquid?\n\n**Hyperliquid** é uma exchange descentralizada (DEX) de alta performance para trading de futuros perpétuos, oferecendo:\n- 📈 **Orderbook on-chain** com performance de CEX\n- ⚡ **Execução de baixa latência**\n- 💰 **Taxas competitivas** e funding rates\n- 🔒 **Full self-custody** - você controla suas chaves\n- 🎯 **Alavancagem até 50x** em diversos ativos\n\n---\n\n## ✨ Recursos\n\n### 27 Ferramentas Poderosas em 4 Categorias\n\n#### 📈 Trading (9 ferramentas)\n- `place_order` - Ordens limit e market\n- `place_batch_orders` - Múltiplas ordens em lote\n- `cancel_order` - Cancelar ordem específica\n- `cancel_all_orders` - Cancelar todas as ordens\n- `modify_order` - Modificar preço/quantidade\n- `place_twap_order` - Ordens TWAP para grande volume\n- `adjust_leverage` - Ajustar alavancagem (cross/isolated)\n- `modify_isolated_margin` - Gerenciar margem isolada\n- `update_dead_mans_switch` - Sistema de segurança automático\n\n#### 👤 Gerenciamento de Conta (8 ferramentas)\n- `get_user_state` - Estado completo da conta\n- `get_positions` - Posições abertas com PnL\n- `get_open_orders` - Ordens abertas\n- `get_user_fills` - Histórico de trades\n- `get_historical_orders` - Histórico de ordens\n- `get_portfolio_value` - Análise completa do portfólio\n- `get_subaccounts` - Gerenciar subcontas\n- `get_rate_limit_status` - Status de rate limits\n\n#### 📊 Dados de Mercado (6 ferramentas)\n- `get_all_mids` - Preços mid de todos os pares\n- `get_l2_orderbook` - Order book L2 em tempo real\n- `get_candles` - Dados históricos (OHLCV)\n- `get_recent_trades` - Trades recentes\n- `get_funding_rates` - Taxas de funding\n- `get_asset_contexts` - Contexto e estatísticas de mercado\n\n#### 🔄 WebSocket em Tempo Real (4 ferramentas)\n- `subscribe_user_events` - Eventos da conta\n- `subscribe_market_data` - Dados de mercado live\n- `subscribe_order_updates` - Atualizações de ordens\n- `get_active_subscriptions` - Gerenciar assinaturas\n\n---\n\n## 🚀 Instalação\n\n### Pré-requisitos\n\n- **Python 3.8+** instalado\n- **Claude Desktop** instalado ([baixar aqui](https://claude.ai/download))\n- **Conta Hyperliquid** com credenciais de API\n- **macOS, Linux ou Windows**\n\n### Instalação Rápida (Recomendado)\n\n1. **Clone ou baixe este repositório**\n   ```bash\n   git clone https://github.com/seu-usuario/hyperliquid-mcp-server.git\n   cd hyperliquid-mcp-server\n   ```\n\n2. **Execute o script de instalação automática**\n   ```bash\n   python3 setup.py\n   ```\n\n   O script irá:\n   - ✅ Criar ambiente virtual Python\n   - ✅ Instalar todas as dependências\n   - ✅ Gerar arquivos de configuração\n   - ✅ Configurar Claude Desktop automaticamente\n   - ✅ Guiá-lo através da configuração de credenciais\n\n3. **Configure suas credenciais**\n\n   Edite o arquivo `.env` criado:\n   ```bash\n   nano .env\n   ```\n\n   Adicione suas credenciais da Hyperliquid:\n   ```env\n   HYPERLIQUID_PRIVATE_KEY=0x...\n   HYPERLIQUID_ACCOUNT_ADDRESS=0x...\n   HYPERLIQUID_NETWORK=mainnet\n   ```\n\n4. **Reinicie o Claude Desktop**\n\n   Feche completamente e reabra o Claude Desktop.\n\n5. **Verifique a instalação**\n\n   No Claude, pergunte:\n   ```\n   Quais ferramentas da Hyperliquid você tem disponíveis?\n   ```\n\n### Instalação Manual (Avançado)\n\n\u003cdetails\u003e\n\u003csummary\u003eClique para expandir instruções manuais\u003c/summary\u003e\n\n```bash\n# 1. Criar ambiente virtual\npython3 -m venv venv\n\n# 2. Ativar ambiente virtual\n# macOS/Linux:\nsource venv/bin/activate\n# Windows:\nvenv\\Scripts\\activate\n\n# 3. Instalar dependências\npip install -r requirements.txt\n\n# 4. Copiar template de configuração\ncp .env.example .env\n\n# 5. Editar .env com suas credenciais\nnano .env\n\n# 6. Configurar Claude Desktop\n# Adicione ao arquivo de configuração do Claude:\n# macOS: ~/Library/Application Support/Claude/claude_desktop_config.json\n# Linux: ~/.config/Claude/claude_desktop_config.json\n# Windows: %APPDATA%\\Claude\\claude_desktop_config.json\n\n{\n  \"mcpServers\": {\n    \"hyperliquid\": {\n      \"command\": \"/caminho/completo/para/venv/bin/python\",\n      \"args\": [\"/caminho/completo/para/server.py\"],\n      \"env\": {\n        \"HYPERLIQUID_PRIVATE_KEY\": \"sua_chave_privada\",\n        \"HYPERLIQUID_ACCOUNT_ADDRESS\": \"seu_endereco\"\n      }\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n---\n\n## 🔑 Obtendo Suas Credenciais\n\n### 1. Private Key (Chave Privada)\n\nExporte sua private key da carteira (MetaMask, Trust Wallet, etc.):\n- Deve estar no formato `0x...` (64 caracteres hexadecimais após o 0x)\n- **NUNCA compartilhe esta chave com ninguém**\n- Mantenha em local seguro\n\n### 2. Account Address (Endereço da Conta)\n\nSeu endereço Ethereum (também formato `0x...`):\n- Endereço público da sua carteira\n- Visível publicamente on-chain\n\n### ⚠️ Segurança das Credenciais\n\n- 🔒 Armazene credenciais apenas no arquivo `.env`\n- ❌ **NUNCA** faça commit do `.env` no git\n- 🧪 Use **testnet** para testes iniciais\n- 🔄 Rotacione chaves periodicamente\n- 💼 Use carteiras separadas para trading/holding\n\n---\n\n## 💡 Exemplos de Uso\n\nUma vez instalado, você pode interagir com a Hyperliquid através de linguagem natural no Claude Desktop:\n\n### 📈 Trading\n\n**Colocar Ordem Limit**\n```\nVocê: \"Coloque uma ordem de compra de 0.1 BTC a $45,000\"\n\nClaude irá:\n✅ Validar sua solicitação\n✅ Colocar a ordem\n✅ Confirmar com order ID e status\n```\n\n**Ordem Market**\n```\nVocê: \"Compre 0.5 ETH a mercado\"\n\nClaude irá:\n✅ Executar ordem imediatamente\n✅ Mostrar preço de execução e taxas\n✅ Atualizar sua posição\n```\n\n**Cancelar Ordens**\n```\nVocê: \"Cancele todas minhas ordens de BTC\"\n\nClaude irá usar: cancel_all_orders\n✅ Cancelar todas as ordens de BTC\n✅ Mostrar resumo de cancelamento\n```\n\n**Batch Trading**\n```\nVocê: \"Coloque 5 ordens de compra de ETH de $3000 a $2900 em intervalos de $25\"\n\nClaude irá usar: place_batch_orders\n✅ Criar grid de ordens\n✅ Executar em única transação\n✅ Confirmar todas as ordens\n```\n\n### 💰 Gerenciamento de Posições\n\n**Verificar Posições**\n```\nVocê: \"Quais são minhas posições abertas e seus PnLs?\"\n\nClaude mostrará:\n📊 Todas as posições abertas\n💵 Preços de entrada\n📈 PnL (realizado e não realizado)\n⚡ Alavancagem utilizada\n⚠️ Preços de liquidação\n```\n\n**Fechar Posição**\n```\nVocê: \"Feche minha posição de ETH a mercado\"\n\nClaude irá:\n✅ Fechar posição inteira\n✅ Mostrar preço de saída\n✅ Calcular PnL final\n```\n\n**Ajustar Alavancagem**\n```\nVocê: \"Configure alavancagem de 10x para trades de BTC\"\n\nClaude irá:\n✅ Atualizar configuração de leverage\n✅ Mostrar requisitos de margem\n✅ Avisar sobre riscos\n```\n\n### 📊 Análise de Mercado\n\n**Preços Atuais**\n```\nVocê: \"Qual o preço atual do BTC na Hyperliquid?\"\n\nClaude mostrará:\n💰 Preço bid/ask\n📊 Mark price\n🎯 Index price\n📈 Spread atual\n```\n\n**Order Book**\n```\nVocê: \"Mostre o order book do ETH\"\n\nClaude mostrará:\n📗 Níveis de bid\n📕 Níveis de ask\n💹 Liquidez em cada nível\n📊 Análise de spread\n```\n\n**Dados Históricos**\n```\nVocê: \"Pegue candles de 1 hora do BTC das últimas 24 horas\"\n\nClaude retornará:\n📈 Dados OHLCV\n📊 Volume\n🔍 Pode analisar padrões\n```\n\n### 📡 Dados em Tempo Real (WebSocket)\n\n**Monitorar Order Book**\n```\nVocê: \"Inscreva no order book do BTC e me alerte sobre ordens grandes\"\n\nClaude irá:\n✅ Conectar ao WebSocket\n✅ Stream do order book em tempo real\n✅ Monitorar atividade de \"baleias\"\n✅ Alertar sobre mudanças significativas\n```\n\n**Acompanhar Trades**\n```\nVocê: \"Monitore trades de ETH em tempo real\"\n\nClaude irá:\n✅ Feed de trades ao vivo\n✅ Analisar fluxo de compra/venda\n✅ Detectar atividade incomum\n```\n\n### 🤖 Estratégias Avançadas\n\n**Estratégia Condicional**\n```\nVocê: \"Se BTC cair abaixo de $44,000, compre 0.2 BTC com alavancagem 5x\"\n\nClaude irá:\n1️⃣ Monitorar preço (subscribe_market_data)\n2️⃣ Quando acionado, ajustar leverage\n3️⃣ Colocar ordem\n4️⃣ Confirmar execução\n```\n\n**Análise de Portfólio**\n```\nVocê: \"Analise o risco do meu portfólio atual\"\n\nClaude irá:\n1️⃣ Buscar posições (get_positions)\n2️⃣ Verificar saldo (get_user_state)\n3️⃣ Calcular exposição por ativo\n4️⃣ Avaliar utilização de margem\n5️⃣ Recomendar ajustes\n```\n\n**Market Making**\n```\nVocê: \"Coloque ordens nos dois lados do ETH com spread de 1%, 0.1 ETH cada\"\n\nClaude irá usar: place_batch_orders\n✅ Ordens simultâneas de compra/venda\n✅ Configurar grid de market making\n✅ Monitorar e ajustar\n```\n\n---\n\n## 🛠️ Configuração Avançada\n\n### Variáveis de Ambiente\n\nTodas as configurações são gerenciadas pelo arquivo `.env`:\n\n```bash\n# Credenciais (OBRIGATÓRIO)\nHYPERLIQUID_PRIVATE_KEY=0x...        # Chave privada Ethereum\nHYPERLIQUID_ACCOUNT_ADDRESS=0x...    # Endereço da carteira\n\n# Rede\nHYPERLIQUID_NETWORK=mainnet          # ou 'testnet'\n\n# Endpoints (configurado automaticamente baseado na rede)\nHYPERLIQUID_API_URL=https://api.hyperliquid.xyz\nHYPERLIQUID_WS_URL=wss://api.hyperliquid.xyz/ws\n\n# Configurações Opcionais\nLOG_LEVEL=INFO                       # DEBUG, INFO, WARNING, ERROR\nRATE_LIMIT_WEIGHT=1200              # Max API weight por minuto\nHTTP_TIMEOUT=30                     # Timeout HTTP (segundos)\nWS_TIMEOUT=60                       # Timeout WebSocket (segundos)\n```\n\n### Testnet vs Mainnet\n\n**Para Desenvolvimento/Testes:**\n```bash\nHYPERLIQUID_NETWORK=testnet\nHYPERLIQUID_API_URL=https://api.hyperliquid-testnet.xyz\nHYPERLIQUID_WS_URL=wss://api.hyperliquid-testnet.xyz/ws\n```\n\n**Para Trading Real:**\n```bash\nHYPERLIQUID_NETWORK=mainnet\nHYPERLIQUID_API_URL=https://api.hyperliquid.xyz\nHYPERLIQUID_WS_URL=wss://api.hyperliquid.xyz/ws\n```\n\n⚠️ **ATENÇÃO:** Sempre teste em testnet primeiro!\n\n---\n\n## 🔒 Segurança\n\n### Gerenciamento de Chaves API\n\n#### ✅ FAÇA:\n- Armazene chaves apenas no `.env`\n- Use testnet para desenvolvimento\n- Rotacione chaves periodicamente\n- Configure whitelists de saques\n- Use margem isolada para trades arriscados\n- Mantenha backups seguros das chaves\n\n#### ❌ NÃO FAÇA:\n- Commitar `.env` no git\n- Compartilhar chaves em logs ou mensagens de erro\n- Usar chaves de mainnet em desenvolvimento\n- Armazenar chaves diretamente no código\n- Compartilhar sua private key com ninguém\n\n### Segurança da Private Key\n\nSua private key tem **controle total** sobre sua conta:\n- 🔐 Trate como uma senha bancária\n- 🚫 Nunca compartilhe com ninguém\n- 💾 Mantenha backups em locais seguros\n- 🔧 Considere usar hardware wallet\n- 👥 Use contas separadas para trading/holding\n\n### Dead Man's Switch\n\nConfigure um sistema de segurança automático:\n```\n\"Configure dead man's switch para 300 segundos\"\n```\n\nSe você não atualizar o switch no prazo:\n- ⚠️ **TODAS** as ordens abertas serão canceladas automaticamente\n- 🛡️ Proteção contra perda de conectividade\n- 🔒 Segurança adicional para sua conta\n\n---\n\n## 🐛 Troubleshooting\n\n### Problemas Comuns\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e❌ \"MCP server não encontrado no Claude Desktop\"\u003c/b\u003e\u003c/summary\u003e\n\n**Soluções:**\n1. Verifique que o Claude Desktop foi fechado completamente antes da instalação\n2. Confirme que `claude_desktop_config.json` está no local correto:\n   - macOS: `~/Library/Application Support/Claude/`\n   - Linux: `~/.config/Claude/`\n   - Windows: `%APPDATA%\\Claude\\`\n3. Reinicie Claude Desktop completamente (Quit, não apenas fechar janela)\n4. Verifique logs em `~/Library/Logs/Claude/`\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e❌ \"Authentication failed\"\u003c/b\u003e\u003c/summary\u003e\n\n**Soluções:**\n1. Verifique que `.env` tem credenciais corretas\n2. Confirme formato da private key (deve começar com `0x`)\n3. Certifique-se que account address corresponde à private key\n4. Teste credenciais com chamada API simples\n5. Verifique se está usando rede correta (testnet/mainnet)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e❌ \"Rate limit exceeded\"\u003c/b\u003e\u003c/summary\u003e\n\n**Soluções:**\n1. Reduza frequência de requisições\n2. Use WebSocket subscriptions em vez de polling\n3. Agrupe operações relacionadas\n4. Ajuste `RATE_LIMIT_WEIGHT` no `.env`\n5. Verifique status com `get_rate_limit_status`\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e❌ \"Order placement failed\"\u003c/b\u003e\u003c/summary\u003e\n\n**Soluções:**\n1. Verifique margem disponível suficiente\n2. Confirme que leverage está configurado\n3. Certifique-se que tamanho da ordem atende mínimo\n4. Valide que preço está dentro de limites razoáveis\n5. Verifique se mercado está em horário de trading\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e❌ \"WebSocket disconnected\"\u003c/b\u003e\u003c/summary\u003e\n\n**Soluções:**\n1. Verifique conectividade de rede\n2. Confirme WebSocket URL correto\n3. Certifique-se que firewall permite WebSocket\n4. Reinicie o MCP server\n5. Verifique logs para detalhes de erro\n\n\u003c/details\u003e\n\n### Modo Debug\n\nAtive logs detalhados editando `.env`:\n\n```bash\nLOG_LEVEL=DEBUG\nDEBUG=true\n```\n\nIsso mostrará:\n- 📡 Todas as requisições/respostas de API\n- 💬 Mensagens WebSocket\n- ⏱️ Rastreamento de rate limits\n- 🐛 Stack traces de erros\n\n### Testando o Servidor\n\nTeste o MCP server isoladamente:\n\n```bash\n# Ative o ambiente virtual\nsource venv/bin/activate\n\n# Execute o inspetor MCP\nmcp dev server.py\n\n# Isso abre uma interface de teste interativa\n```\n\n---\n\n## 📚 Documentação Completa\n\n### APIs e SDKs\n\n- **Hyperliquid Docs**: https://hyperliquid.gitbook.io/hyperliquid-docs/\n- **Python SDK**: https://github.com/hyperliquid-dex/hyperliquid-python-sdk\n- **WebSocket API**: https://hyperliquid.gitbook.io/hyperliquid-docs/websocket-api\n- **Trading Guide**: https://hyperliquid.gitbook.io/hyperliquid-docs/trading\n\n### Model Context Protocol\n\n- **MCP Specification**: https://modelcontextprotocol.io/\n- **MCP SDK**: https://github.com/anthropics/mcp\n- **Claude Desktop**: https://docs.anthropic.com/claude/docs/mcp\n\n### Rate Limits\n\nHyperliquid implementa rate limiting baseado em sistema de pesos:\n\n| Tipo | Weight | Limite |\n|------|--------|--------|\n| Market Data | 1-2 | 1200/min |\n| Account Data | 2-5 | 1200/min |\n| Trading | 5-10 | 1200/min |\n| WebSocket | 0 | Ilimitado |\n\n**Melhores Práticas:**\n- ✅ Use WebSocket para dados em tempo real\n- ✅ Agrupe operações quando possível\n- ✅ Cache dados que não mudam frequentemente\n- ✅ Monitore uso de rate limit\n\n---\n\n## 🤝 Contribuindo\n\nContribuições são muito bem-vindas! Veja como adicionar novas ferramentas:\n\n### Adicionando uma Nova Tool\n\n1. **Defina a tool em `server.py`**\n\n```python\n@mcp.tool()\nasync def sua_nova_tool(param1: str, param2: int, ctx: Context = None) -\u003e Dict[str, Any]:\n    \"\"\"\n    Descrição da ferramenta para Claude.\n\n    Args:\n        param1: Descrição do parâmetro 1\n        param2: Descrição do parâmetro 2\n\n    Returns:\n        Descrição do resultado\n    \"\"\"\n    if ctx: ctx.info(f\"Executando sua_nova_tool...\")\n\n    result = await app_context.sua_categoria.metodo(param1, param2)\n    return result\n```\n\n2. **Atualize `mcp.json`**\n\n```json\n{\n  \"name\": \"sua_nova_tool\",\n  \"description\": \"O que a ferramenta faz\"\n}\n```\n\n3. **Teste a ferramenta**\n\n```bash\nmcp dev server.py\n```\n\n4. **Envie um pull request**\n\n### Diretrizes de Desenvolvimento\n\n- ✅ Siga o estilo de código existente\n- ✅ Adicione type hints\n- ✅ Inclua docstrings\n- ✅ Trate erros graciosamente\n- ✅ Considere rate limits\n- ✅ Teste completamente\n\n---\n\n## ❓ FAQ\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eÉ seguro usar com dinheiro real?\u003c/b\u003e\u003c/summary\u003e\n\nO servidor é open-source e usa SDKs oficiais da Hyperliquid. No entanto, trading sempre carrega riscos. **Sempre comece com testnet e pequenas quantias.**\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude pode tradear automaticamente?\u003c/b\u003e\u003c/summary\u003e\n\nClaude 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.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eQual a diferença de usar Hyperliquid diretamente?\u003c/b\u003e\u003c/summary\u003e\n\nEste 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.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ePreciso manter Claude Desktop aberto?\u003c/b\u003e\u003c/summary\u003e\n\n**Sim**, o MCP server roda como parte do Claude Desktop e requer que ele esteja em execução.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ePosso usar múltiplas contas Hyperliquid?\u003c/b\u003e\u003c/summary\u003e\n\nAtualmente, uma conta por instalação. Suporte para múltiplas contas está no roadmap.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eQuais são as taxas?\u003c/b\u003e\u003c/summary\u003e\n\nAplicam-se as taxas padrão da Hyperliquid (maker/taker fees). O MCP server em si é **gratuito e open-source**.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eMinha private key é segura?\u003c/b\u003e\u003c/summary\u003e\n\nSua private key fica **apenas no arquivo `.env` na sua máquina local**. Nunca é enviada para nenhum lugar além da API oficial da Hyperliquid.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ePosso usar em Windows/Linux?\u003c/b\u003e\u003c/summary\u003e\n\n**Sim!** O MCP server é compatível com Windows, macOS e Linux.\n\n\u003c/details\u003e\n\n---\n\n## 🗺️ Roadmap\n\nFuncionalidades planejadas:\n\n- [ ] Order types avançados (stop-loss, take-profit)\n- [ ] Analytics e reporting de portfólio\n- [ ] Ferramentas de gerenciamento de risco\n- [ ] Estratégias de trading automatizadas\n- [ ] Suporte para múltiplas contas\n- [ ] Dashboard de métricas de performance\n- [ ] Integração com backtesting\n- [ ] Sistema de alertas para preços/posições\n- [ ] Exportação de dados de trades para CSV\n- [ ] Integração com TradingView\n\n---\n\n## 📜 Licença\n\nEste projeto está licenciado sob a **MIT License** - veja o arquivo [LICENSE](LICENSE) para detalhes.\n\n```\nMIT License\n\nCopyright (c) 2025 Caio Vicentino\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n\n---\n\n## ⚠️ Disclaimer\n\nEste software é fornecido **\"como está\"**, sem garantias de qualquer tipo.\n\n**Trading de criptomoedas carrega risco significativo.**\n\n- 📉 Você pode perder todo seu capital investido\n- ⚠️ Apenas trade com fundos que você pode perder\n- 🎓 Educação e gestão de risco são essenciais\n- 🔬 Sempre teste em testnet primeiro\n\n**Os autores não são responsáveis por quaisquer perdas financeiras incorridas através do uso deste software.**\n\nUse por sua conta e risco.\n\n---\n\n## 🙏 Agradecimentos\n\n- **Anthropic** pelo Model Context Protocol e Claude\n- **Hyperliquid Team** pela excelente DEX e API\n- **Python MCP SDK Contributors**\n- **Comunidades**: Yield Hacker, Renda Cripto e Cultura Builder\n- **Comunidade Open Source**\n\n---\n\n## 💬 Suporte e Comunidade\n\n- **Issues**: [GitHub Issues](https://github.com/seu-usuario/hyperliquid-mcp-server/issues)\n- **Discussões**: [GitHub Discussions](https://github.com/seu-usuario/hyperliquid-mcp-server/discussions)\n- **Hyperliquid Discord**: https://discord.gg/hyperliquid\n- **MCP Support**: https://github.com/anthropics/mcp\n\n---\n\n## 👨‍💻 Sobre o Desenvolvedor\n\n**Desenvolvido por Caio Vicentino com Claude Code**\n\nEste 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.\n\n**Dedicado às comunidades:**\n- 🎯 **Yield Hacker** - Maximizando retornos DeFi\n- 💰 **Renda Cripto** - Educação financeira em cripto\n- 🏗️ **Cultura Builder** - Construindo o futuro com AI\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n### 🚀 Desenvolvido com Claude Code + Hyperliquid\n\n**Se este projeto foi útil, dê uma ⭐ no repositório!**\n\n[⬆ Voltar ao topo](#-hyperliquid-mcp-server)\n\n\u003c/div\u003e\n\n---\n\n## 📸 Screenshots\n\n### Exemplo de Trading no Claude\n```\nVocê: \"Mostre minhas posições abertas e calcule meu PnL total\"\n\nClaude: Deixe-me buscar suas posições atuais...\n\n📊 POSIÇÕES ABERTAS:\n\n1. BTC-PERP\n   • Tamanho: 0.5 BTC (Long)\n   • Preço de Entrada: $45,230.00\n   • Preço Atual: $46,150.00\n   • PnL não realizado: +$460.00 (+2.03%)\n   • Alavancagem: 5x\n   • Liquidação: $38,500.00\n\n2. ETH-PERP\n   • Tamanho: 10 ETH (Long)\n   • Preço de Entrada: $2,420.00\n   • Preço Atual: $2,485.00\n   • PnL não realizado: +$650.00 (+2.69%)\n   • Alavancagem: 3x\n   • Liquidação: $2,050.00\n\n💰 RESUMO:\n   • PnL Total não realizado: +$1,110.00\n   • ROE médio: +2.36%\n   • Margem utilizada: $8,450.00\n   • Margem disponível: $11,550.00\n```\n\n### Exemplo de Análise de Mercado\n```\nVocê: \"Analise o mercado de BTC e sugira uma estratégia\"\n\nClaude: Vou analisar o mercado de BTC para você...\n\n📊 ANÁLISE DE MERCADO - BTC\n\nPreços Atuais:\n• Preço Mark: $46,150.00\n• Bid: $46,148.00 / Ask: $46,152.00\n• Spread: $4.00 (0.009%)\n\nOrder Book:\n• Suporte forte em: $46,000 (150 BTC)\n• Resistência em: $46,500 (200 BTC)\n• Liquidez: Excelente (spread tight)\n\nFunding:\n• Rate atual: 0.0085% (8h)\n• Rate anualizado: +9.29%\n• Próximo funding: em 3h 24min\n\nVolume 24h:\n• Volume: $2.4B\n• Trades: 45,230\n• Sentimento: Bullish (65% compra)\n\n💡 SUGESTÃO DE ESTRATÉGIA:\n\nDado o funding positivo e resistência próxima, sugiro:\n\n1. ENTRY: Ordem limit em $46,000 (suporte forte)\n2. TAMANHO: 0.2 BTC (risco moderado)\n3. ALAVANCAGEM: 3-5x\n4. STOP LOSS: $45,700 (abaixo do suporte)\n5. TAKE PROFIT: $46,800 (acima da resistência)\n\nRisk/Reward: 1:2.66 (favorável)\n\nQuer que eu execute esta estratégia?\n```\n\n---\n\n**Happy Trading! 📈🚀**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaiovicentino%2Fhyperliquid-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaiovicentino%2Fhyperliquid-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaiovicentino%2Fhyperliquid-mcp-server/lists"}