Haiku DeFi MCP

Servidor MCP para execução DeFi — permite que agentes de IA realizem swaps, forneçam liquidez, emprestem, façam bridge e executem estratégias de yield em 22 blockchains em uma única transação.

GitHub
2
Experimente este MCPPatrocinado

Documentação

Servidor Haiku MCP

Um servidor MCP (Model Context Protocol) que permite que agentes de IA executem transações blockchain por meio da API Haiku.

npm version GitHub

Recursos

  • Descoberta de Tokens: Lista tokens suportados e ativos DeFi em 21 redes blockchain
  • Verificação de Saldos: Obtém saldos de carteiras em todas as cadeias suportadas
  • Cotações de Negociação: Obtém cotações para swaps e rebalanceamento de portfólio
  • Construção de Transações: Converte cotações em transações EVM não assinadas
  • Integração com Carteiras: Extrai payloads EIP-712 para assinatura externa de carteiras (Coinbase, AgentKit, Safe, etc.)
  • Execução Autônoma: Execução opcional de ponta a ponta com a variável de ambiente WALLET_PRIVATE_KEY
  • Descoberta de Rendimentos: Encontra as oportunidades DeFi de maior rendimento em protocolos e cadeias, filtradas por APY, TVL e categoria
  • Análise de Portfólio: Analisa as participações de uma carteira e apresenta oportunidades de rendimento específicas do contexto com base no que ela realmente possui

Instalação

npm install haiku-mcp-server

Ou execute diretamente com npx:

npx haiku-mcp-server

Configuração

Variáveis de Ambiente

VariávelObrigatóriaDescrição
HAIKU_API_KEYNãoSua chave da API Haiku para limites de taxa mais altos. Entre em contato com contact@haiku.trade para solicitar uma.
HAIKU_BASE_URLNãoURL base da API. O padrão é https://api.haiku.trade/v1
WALLET_PRIVATE_KEYNãoChave privada (hex 0x) para execução autônoma via haiku_execute.
RPC_URL_{chainId}NãoSubstitui a URL RPC para uma cadeia específica (por exemplo, RPC_URL_42161 para Arbitrum).

Observação: A API funciona sem chave, mas fornecê-la desbloqueia limites de taxa mais altos para uso em produção.

Configuração do Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "haiku": {
      "command": "npx",
      "args": ["haiku-mcp-server"]
    }
  }
}

Com chave de API para limites de taxa mais altos:

{
  "mcpServers": {
    "haiku": {
      "command": "npx",
      "args": ["haiku-mcp-server"],
      "env": {
        "HAIKU_API_KEY": "your-api-key-here"
      }
    }
  }
}

Ferramentas Disponíveis

haiku_get_tokens

Obtém tokens suportados e ativos DeFi para negociação.

Parâmetros:

  • network (opcional): Filtra por ID da cadeia (por exemplo, 42161 para Arbitrum)
  • category (opcional): Filtra por categoria de token:
    • token - Tokens padrão (ETH, USDC, etc.)
    • collateral - ex.: Aave aTokens (colateral depositado)
    • varDebt - ex.: Tokens de dívida variável da Aave
    • vault - ex.: Vaults de rendimento Yearn/Morpho
    • weightedLiquidity - ex.: Tokens LP da Balancer
    • concentratedLiquidity - ex.: Posições LP da Uniswap V3

Exemplo:

{
  "network": 42161,
  "category": "token"
}

haiku_get_balances

Obtém saldos de tokens para um endereço de carteira em todas as cadeias.

Parâmetros:

  • walletAddress (opcional): Endereço da carteira ou nome ENS. Obrigatório quando WALLET_PRIVATE_KEY não está definido; omita para derivar automaticamente de WALLET_PRIVATE_KEY quando estiver definido.

Exemplo:

{
  "walletAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
}

Omita walletAddress quando WALLET_PRIVATE_KEY estiver definido para usar o endereço derivado.

haiku_get_quote

Obtém uma cotação para um swap de token ou rebalanceamento de portfólio.

Observação: As cotações são válidas por 5 minutos, mas execute o mais rápido possível após a cotação — quanto mais você esperar, maior a probabilidade de os preços terem mudado e a transação falhar na cadeia.

Parâmetros:

  • inputPositions (obrigatório): Mapa de IID de token para valor a gastar
  • targetWeights (obrigatório): Mapa de IID de token de saída para peso (deve somar 1)
  • slippage (opcional): Slippage máximo como decimal (padrão: 0,003)
  • receiver: Endereço da carteira receptora. Obrigatório quando WALLET_PRIVATE_KEY não está definido — deve ser fornecido explicitamente. Quando WALLET_PRIVATE_KEY está definido, é derivado automaticamente se omitido. Quando WALLET_PRIVATE_KEY não está definido (Caminho B), você deve passar receiver explicitamente.

Exemplo:

{
  "inputPositions": {
    "arb:0x82aF49447D8a07e3bd95BD0d56f35241523fBab1": "1.0"
  },
  "targetWeights": {
    "arb:0xaf88d065e77c8cC2239327C5EDb3A432268e5831": 0.5,
    "arb:0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9": 0.5
  },
  "slippage": 0.005
}

O exemplo acima omite receiver (válido quando WALLET_PRIVATE_KEY está definido). Para o Caminho B, inclua "receiver": "0x...".

haiku_prepare_signatures

Extrai e normaliza payloads de assinatura EIP-712 de uma cotação para assinatura externa de carteira (somente Caminho B). Ao usar quoteId, a cotação deve ter sido obtida na mesma sessão.

Use isto quando um MCP de carteira lidar com a assinatura (Coinbase Payments MCP, wallet-agent, AgentKit, Safe, etc.). Retorna dados tipados padronizados que qualquer signTypedData de carteira pode consumir, além de instruções passo a passo.

Parâmetros:

  • quoteId (preferido): ID da cotação de haiku_get_quote — o servidor resolve a cotação completa do cache da sessão. O QuoteId só funciona quando a cotação foi retornada por haiku_get_quote na mesma sessão MCP; caso contrário, use quoteResponse.
  • quoteResponse (alternativa): Objeto de resposta completo de haiku_get_quote, se o quoteId não estiver disponível

Retorna:

  • requiresPermit2: Se a assinatura Permit2 é necessária
  • permit2: Payload EIP-712 para passar para signTypedData (se necessário)
  • requiresBridgeSignature: Se a assinatura de ponte é necessária
  • bridgeIntent: Payload EIP-712 para passar para signTypedData (se necessário)
  • sourceChainId: ID da cadeia para a transação
  • instructions: Instruções passo a passo para concluir o fluxo

Exemplo:

{
  "quoteId": "abc123..."
}

haiku_discover_yields

Descobre oportunidades de rendimento em protocolos DeFi, classificadas por APY ou TVL.

Use isto para responder perguntas como "melhores rendimentos de empréstimo na Arbitrum", "vaults com maior APY com pelo menos US$ 1M em TVL" ou "o que posso fazer com USDC na Base". O campo iid nos resultados pode ser usado diretamente como chave no objeto targetWeights em haiku_get_quote.

Parâmetros:

  • network (opcional): Filtra por ID da cadeia (por exemplo, 42161 para Arbitrum)
  • category (opcional): lending (colateral Aave), vault (Yearn/Morpho), lp (Balancer/Uniswap), all (padrão)
  • minApy (opcional): APY mínimo como porcentagem (por exemplo, 5 significa ≥5% APY)
  • minTvl (opcional): TVL mínimo em USD (por exemplo, 1000000 significa ≥US$ 1M). Filtra para vaults estabelecidos no mercado mainstream.
  • sortBy (opcional): apy (padrão) ou tvl, decrescente
  • limit (opcional): Máximo de resultados (padrão 20)

Exemplo:

{
  "network": 42161,
  "category": "lending",
  "minTvl": 1000000,
  "sortBy": "apy",
  "limit": 10
}

haiku_analyze_portfolio

Analisa o portfólio DeFi de uma carteira e apresenta oportunidades de rendimento relevantes.

Retorna posições atuais enriquecidas com opções de APY disponíveis, fatores de saúde de colateral e oportunidades específicas do contexto com base no que a carteira realmente possui. Combine com haiku_discover_yields para contexto de mercado mais amplo e depois use haiku_get_quote para executar.

Parâmetros:

  • walletAddress (obrigatório): Endereço da carteira (0x...) para analisar

Exemplo:

{
  "walletAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
}

haiku_execute

Executa uma cotação. Dois caminhos distintos, dependendo de quem detém a chave privada.

Caminho A — Autônomo (WALLET_PRIVATE_KEY definido no env): Haiku assina payloads Permit2/ponte internamente e transmite. Retorna um hash de transação.

Parâmetros:

  • quoteId (obrigatório): ID da cotação de haiku_get_quote
  • sourceChainId (recomendado): ID da cadeia da resposta da cotação. Omita somente se a cotação foi obtida na mesma sessão — o servidor pode recuperar do cache.
  • permit2SigningPayload (opcional): Repasse de haiku_get_quote se presente
  • bridgeSigningPayload (opcional): Repasse de haiku_get_quote se presente (somente entre cadeias)
  • approvals (opcional): Repasse de haiku_get_quote se presente

Exemplo:

{
  "quoteId": "abc123...",
  "sourceChainId": 42161,
  "permit2SigningPayload": { /* from haiku_get_quote, if present */ },
  "approvals": [ /* from haiku_get_quote, if present */ ]
}

Caminho B — Carteira externa (sem WALLET_PRIVATE_KEY, usando um MCP de carteira): Você assina e transmite. broadcast: false é obrigatório — sem WALLET_PRIVATE_KEY, o haiku não pode assinar ou enviar a transação EVM final. Se você chamar haiku_execute com broadcast: true e sem WALLET_PRIVATE_KEY, o servidor retorna um erro orientando você a definir broadcast: false e transmitir a transação retornada via seu MCP de carteira.

Antes de chamar haiku_execute:

  1. Se approvals não estiver vazio na cotação: transmita cada aprovação como uma transação { to, data, value } (inclua value quando presente, por exemplo, para token nativo) via seu MCP de carteira e aguarde a confirmação.
  2. Se assinaturas forem necessárias: chame haiku_prepare_signatures com o quoteId, assine os payloads EIP-712 retornados via seu MCP de carteira e depois passe as assinaturas aqui.

Parâmetros:

  • quoteId (obrigatório): ID da cotação de haiku_get_quote
  • sourceChainId (recomendado): ID da cadeia da resposta da cotação. Omita somente se a cotação foi obtida na mesma sessão — o servidor pode recuperar do cache.
  • broadcast (obrigatório): Deve ser false — o haiku retorna a transação não assinada para você transmitir
  • permit2Signature (opcional): Assinatura da assinatura do payload Permit2 via seu MCP de carteira
  • userSignature (opcional): Assinatura da assinatura do payload de ponte via seu MCP de carteira (somente entre cadeias)

Exemplo:

{
  "quoteId": "abc123...",
  "sourceChainId": 42161,
  "broadcast": false,
  "permit2Signature": "0x..."
}

Retorna { transaction: { to, data, value, chainId } } — passe transaction para o sendTransaction do seu MCP de carteira.

Formato de IID de Token

Os tokens são identificados usando o formato IID: chainSlug:tokenAddress

Exemplos:

  • arb:0x82aF49447D8a07e3bd95BD0d56f35241523fBab1 - WETH na Arbitrum
  • arb:0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee - ETH nativo na Arbitrum
  • base:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 - USDC na Base

Cadeias Suportadas

CadeiaID da CadeiaSlug
Arbitrum42161arb
Avalanche43114avax
Base8453base
Berachain80094bera
BNB Smart Chain56bsc
Bob60808bob
Ethereum1eth
Gnosis100gnosis
Hyperliquid999hype
Katana747474katana
Lisk1135lisk
MegaETH4326megaeth
Monad143monad
Optimism10opt
Plasma9745plasma
Polygon137poly
Scroll534352scroll
Sei1329sei
Sonic146sonic
Unichain130uni
World Chain480worldchain
ApeChain33139ape

Exemplos de Fluxo de Trabalho

Caminho A: Swap Autônomo (WALLET_PRIVATE_KEY definido)

O Haiku lida com toda a assinatura e transmissão. Retorna um hash de transação.

1. haiku_get_quote(inputPositions, targetWeights) → returns quoteId, sourceChainId, permit2SigningPayload?, bridgeSigningPayload?, approvals
2. haiku_execute(quoteId, sourceChainId, permit2SigningPayload?, bridgeSigningPayload?, approvals)
   → Haiku broadcasts approvals, signs Permit2/bridge internally, broadcasts swap, returns tx hash

Caminho B: Carteira Externa (MCP de carteira lida com assinatura + transmissão)

Use quando WALLET_PRIVATE_KEY não está definido e um MCP de carteira separado detém as chaves.

Swap simples (sem assinaturas Permit2 ou de ponte necessárias, ex.: entrada de ETH nativo):

1. haiku_get_quote(inputPositions, targetWeights, receiver) → returns quoteId, sourceChainId, approvals
2. For each item in approvals: broadcast as transaction { to, data, value } (include value when present) via wallet MCP and wait for confirmation
3. haiku_execute(quoteId, sourceChainId, broadcast: false)
   → returns { transaction: { to, data, value, chainId } }
4. Broadcast transaction via wallet MCP

Com assinaturas Permit2 ou de ponte (ex.: entrada de ERC-20 ou swap entre cadeias):

1. haiku_get_quote(inputPositions, targetWeights, receiver) → returns quoteId, sourceChainId, approvals, permit2SigningPayload?, bridgeSigningPayload?
2. For each item in approvals: broadcast as transaction { to, data, value } (include value when present) via wallet MCP and wait for confirmation
3. haiku_prepare_signatures(quoteId) → returns normalized EIP-712 payloads + step-by-step instructions
4. Sign payloads via wallet MCP (e.g. coinbase_sign_typed_data) → get permit2Signature?, userSignature?
5. haiku_execute(quoteId, sourceChainId, permit2Signature?, userSignature?, broadcast: false)
   → returns { transaction: { to, data, value, chainId } }
6. Broadcast transaction via wallet MCP (e.g. coinbase_send_transaction)

Descoberta de Rendimentos

1. haiku_discover_yields with category/network/minTvl filters → find opportunities, note iid
2. haiku_get_quote with the chosen iid as a key in targetWeights
3. Execute via Path A or Path B above

Análise e Otimização de Portfólio

1. haiku_analyze_portfolio with wallet address → review positions and opportunities
2. Optionally haiku_discover_yields for broader market context
3. haiku_get_quote to rebalance into higher-yielding positions
4. Execute via Path A or Path B above

Assinatura de Transações

Dois modos, dependendo da sua configuração:

Autônomo (WALLET_PRIVATE_KEY definido): haiku_execute assina tudo internamente e transmite. Retorna um hash de transação. Nenhuma assinatura externa necessária.

Carteira externa (sem WALLET_PRIVATE_KEY): Use haiku_execute com broadcast: false (obrigatório — o haiku não pode assinar ou transmitir sem a chave privada). Se você chamar haiku_execute com broadcast: true e sem WALLET_PRIVATE_KEY, o servidor retorna um erro orientando você a definir broadcast: false e transmitir a transação retornada via seu MCP de carteira. Retorna { transaction: { to, data, value, chainId } } para seu MCP de carteira transmitir. Se assinaturas Permit2 ou de ponte forem necessárias, chame haiku_prepare_signatures primeiro. Se aprovações estiverem presentes na cotação, transmita cada aprovação { to, data, value } (inclua value quando presente, por exemplo, para token nativo) via seu MCP de carteira antes de chamar haiku_execute.

O design de carteira externa permite que agentes usem qualquer infraestrutura de assinatura (MCPs de carteira, carteiras de hardware, serviços de custódia, MPC, etc.).

Assinaturas de Ponte Entre Cadeias

Para swaps entre cadeias, a cotação pode retornar isComplexBridge: true, indicando que uma assinatura de intenção de ponte é necessária além (ou em vez) do Permit2.

Autônomo (Caminho A): Passe bridgeSigningPayload da cotação para haiku_execute — ele lida com a assinatura de ponte internamente.

Carteira externa (Caminho B): Chame haiku_prepare_signatures com o quoteId — ele retorna um payload EIP-712 bridgeIntent normalizado. Assine-o via seu MCP de carteira e passe o resultado como userSignature para haiku_execute.

Modos de Transporte

Stdio (padrão)

Transporte MCP stdio padrão — usado pelo Claude Desktop, Cursor, etc.

npx haiku-mcp-server

HTTP Streamable

Transporte HTTP para hospedagem remota, Smithery e clientes MCP baseados na web.

npx haiku-mcp-server --http
npx haiku-mcp-server --http --port=8080

Endpoints:

  • POST /mcp — endpoint HTTP Streamable do MCP
  • GET /health — verificação de saúde

Desenvolvimento

# Install dependencies
npm install

# Build
npm run build

# Run locally (stdio, works without API key)
npm start

# Run locally (HTTP)
npm run start:http

# Run with API key for higher rate limits
HAIKU_API_KEY=your-key npm start

Licença

MIT