recon-crypto-mcp

VaultPilot MCP

DeFi com autocustódia para agentes de IA. O agente propõe, você aprova no seu Ledger — projetado para o modelo de ameaça em que o agente, o MCP e o host podem estar todos comprometidos. Apenas o dispositivo é confiável; chaves privadas nunca saem dele.

Leia posições on-chain e prepare transações em Ethereum, Arbitrum, Polygon, Base, Optimism, TRON, Solana, Bitcoin e Litecoin. Protocolos suportados: Aave V3, Compound V3, Morpho Blue, Uniswap V3 (verbos de swap + LP), Curve, Lido, EigenLayer, Rocket Pool, Safe (Gnosis) multisig em EVM, MarginFi, Kamino, Marinade, Jito em Solana, SunSwap em TRON, além de LiFi (EVM + EVM↔Solana + TRON + swap/bridge BTC) e Jupiter v6 (swap Solana), com 1inch como verificação cruzada opcional de cotações em EVM. Assinaturas EVM via WalletConnect → Ledger Live; TRON, Solana, Bitcoin e Litecoin assinam via USB HID diretamente no dispositivo (a ponte WalletConnect do Ledger Live não suporta esses namespaces hoje). Funciona com Claude Code (CLI/terminal), Cursor e qualquer cliente compatível com MCP via stdio. Claude.ai chat (web + app desktop nativo) precisa de um endpoint MCP hospedado — no roadmap, ainda não lançado.

Agentes: leia AGENTS.md. Prompt de uma linha para colar no Claude Code / Cursor / qualquer agente compatível com MCP:

Instale o VaultPilot MCP de https://github.com/szhygulin/vaultpilot-mcp seguindo AGENTS.md.

Recursos

• Portfólio — saldos entre cadeias, agregação de posições DeFi, totais em USD, coleções de NFTs (EVM + Solana via Helius DAS), PnL no nível da carteira (mtd / ytd / 30d / 7d / 1d), briefing diário
• Posições — Aave, Compound, Morpho, Uniswap V3 LP, Curve, MarginFi, Kamino, Safe (Gnosis) multisig; alertas de health factor multi-protocolo; simulação de risco de liquidação
• Staking — Lido (stake / unstake / wrap stETH↔wstETH) + EigenLayer + Rocket Pool (EVM); TRON Stake 2.0 (freeze / unfreeze / vote / claim); Solana (Marinade, Jito, delegate/deactivate/withdraw nativo)
• Swaps + bridges — LiFi (rotas EVM + EVM↔Solana + TRON + BTC, verificação cruzada opcional com 1inch), Jupiter v6 (Solana), Uniswap V3 direto, Curve, SunSwap (TRON)
• Execução — prepare/sign para cada protocolo suportado + envios nativos/token, aprovações ERC-20 + revoke, wrap/unwrap WETH, prepare_custom_call como saída de emergência para chamadas arbitrárias a contratos verificados. Envios Solana usam uma conta de nonce durável por carteira para que a revisão no Ledger não dispute com a janela de ~60s do blockhash; cada prepare Solana executa uma verificação simulateTransaction para que reverts no nível do programa falhem no prepare, não no broadcast.
• Bitcoin + Litecoin — envios nativos segwit + taproot, aumento de taxa BIP-125 RBF, PSBT multisig (combine / sign / finalize), assinatura de mensagens BIP-137, estimativa de taxa via mempool.space, RPC opcional do Bitcoin Core / Litecoin Core para leituras forenses de cadeia (forks, censo de mempool, percentis de taxa)
• Segurança — verificação de contratos, verificações de upgradeability, enumeração de papéis privilegiados, score de risco baseado em DefiLlama, atestação no dispositivo Ledger + pin de versão de firmware, verify_tx_decode para verificação cruzada bytes-vs-intenção com segundo LLM, contatos/agenda assinados em disco
• Utilitários — resolução ENS, registro símbolo→contrato resolve_token, saldos de tokens, enumeração de allowances, status de tx, explain_tx decode post-hoc, compare_yields entre adaptadores de empréstimo + LST
• Modo demo — personas selecionadas (whale / defi-degen / stable-saver / staking-maxi) para primeiro contato sem chaves RPC / Ledger / arquivo de configuração

Modelo de segurança

Modelo de comprometimento: o agente de IA, o servidor MCP e o computador host podem estar todos sob controle do atacante. Apenas o Ledger é confiável. Cada transação é criptograficamente vinculada em cada camada, de modo que adulteração — um destinatário trocado, uma rota de swap reescrita, uma aprovação contrabandeada — seja evidente na tela do dispositivo antes da assinatura.

user-intent ──► agent ──► MCP server ──► WalletConnect / USB-HID ──► Ledger Live / host ──► Ledger device

Defesa em profundidade: fingerprint prepare↔send no servidor, verificação independente de seletor via 4byte.directory, decode ABI no lado do agente + recálculo de hash pré-assinatura, correspondência clear-sign ou blind-sign-hash no dispositivo, verificação cruzada de session-topic do WalletConnect, verificação previewToken/userDecision e get_verification_artifact para verificação cruzada com segundo LLM em fluxos de alto valor. Veja SECURITY.md para o modelo de ameaça completo, tabela de defesas, riscos residuais e receitas de verificação.

Endurecimento no lado do agente (fortemente recomendado)

As diretivas CHECKS PERFORMED do próprio MCP podem ser omitidas silenciosamente por um servidor comprometido. Instale o vaultpilot-security-skill complementar para que o agente aplique invariantes de integridade criptográfica independentemente do que o MCP disser — decode de bytes, allowlist de destino de dispatch, recálculo de hash, cadeia-deve-ser-explícita, verificação cruzada de destinatário de bridge, superfície de classe de aprovação, oferta sempre opcional de segundo LLM em cada preview, verificação de intenção em nível de conjunto, fonte de verdade com binding durável:

git clone https://github.com/szhygulin/vaultpilot-security-skill.git \
  ~/.claude/skills/vaultpilot-preflight

Reinicie o Claude Code. O SHA-256 do arquivo de skill é fixado no código-fonte do servidor; adulteração em disco ou colisão de plugin aparece como integrity check FAILED.

/setup conversacional (opcional)

Para onboarding orientado a chat que detecta a configuração atual e coleta apenas as chaves que você realmente precisa, instale o vaultpilot-setup-skill complementar:

git clone https://github.com/szhygulin/vaultpilot-setup-skill.git \
  ~/.claude/skills/vaultpilot-setup

Reinicie e digite /setup.

Cadeias suportadas

EVM — Ethereum, Arbitrum, Polygon, Base, Optimism. Leituras do Lido em Ethereum + Arbitrum, escritas do Lido apenas em Ethereum. EigenLayer + Morpho Blue + Rocket Pool apenas em Ethereum. Compound V3 + Aave V3 + Uniswap V3 + LiFi + Safe multisig abrangem as cinco cadeias; a cobertura de endereços por protocolo varia — leitores fazem short-circuit limpo onde um protocolo não está implantado.

TRON — TRX + stablecoins TRC-20 canônicas (USDT, USDC, USDD, TUSD); Stake 2.0 freeze/unfreeze/withdraw-expire-unfreeze + reivindicações de recompensas de votação; SunSwap (swaps TRX↔TRC-20 na mesma cadeia); bridge TRON↔EVM roteada via LiFi. Sem lending/LP (Aave/Compound/Morpho/Uniswap não estão implantados). Pareie uma vez por sessão via pair_ledger_tron.

Solana — saldos SOL + SPL, lending MarginFi + Kamino, leituras de contas de stake Marinade / Jito / nativas com valoração equivalente em SOL, cotações Jupiter v6, portfólio NFT via Helius DAS. Escritas cobrem transferências SOL/SPL, supply/withdraw/borrow/repay em MarginFi + Kamino, swaps Jupiter, stake Marinade + immediate-unstake, depósito no stake-pool Jito, delegate/deactivate/withdraw SOL nativo e bridge EVM↔Solana roteada via LiFi. Conta de nonce durável por carteira (~0,00144 SOL de rent, recuperável) protege envios contra expiração de blockhash durante a revisão no Ledger (prepare_solana_nonce_init / _close). SPL / MarginFi / Kamino / Jupiter / Jito usam blind-sign contra um Message Hash — habilite Allow blind signing nas Configurações do app Solana; transferências SOL nativas usam clear-sign. Pareie uma vez por sessão via pair_ledger_solana.

Bitcoin + Litecoin — leitores de saldo, UTXO, estimativa de taxa e histórico de transações via Esplora (mempool.space / litecoinspace.org). Envios nativos segwit + taproot, aumento de taxa BIP-125 RBF, PSBT multisig (combine / sign / finalize), assinatura de mensagens BIP-137, swaps BTC→EVM/Solana roteados via LiFi. JSON-RPC opcional do Bitcoin Core / Litecoin Core desbloqueia ferramentas forenses que o Esplora não consegue servir (tips de cadeia, estatísticas de bloco, resumo de mempool) — veja INSTALL.md §9 para configuração. Pareie uma vez via pair_ledger_btc / pair_ledger_ltc.

A ponte WalletConnect do Ledger Live não honra o namespace tron: (verificado em 2026-04-14), não expõe contas Solana (verificado em 2026-04-23) e não expõe namespaces BTC/LTC — por isso esses caminhos usam USB HID. Leitores fazem short-circuit limpo em cadeias onde um protocolo não está implantado.

Roadmap

ROADMAP.md.

Ferramentas

~190 ferramentas nas categorias leitura / parear-Ledger / prepare / sign+send / verify / diagnóstico. Destaques abaixo; cada ferramenta tem schema de entrada Zod e descrição detalhada — consulte o tools/list do servidor MCP para a superfície canônica.

Portfólio + posições (somente leitura):

• get_portfolio_summary, get_portfolio_diff, get_pnl_summary, get_daily_briefing — agregação USD entre cadeias; tronAddress / solanaAddress opcionais incluem essas cadeias
• get_lending_positions (Aave), get_compound_positions, get_morpho_positions, get_marginfi_positions, get_kamino_positions, get_curve_positions, get_safe_positions — posições por protocolo + health factors
• get_lp_positions — Uniswap V3 LP + estimativa de IL
• get_staking_positions, get_staking_rewards, estimate_staking_yield — Lido + EigenLayer + Rocket Pool
• get_solana_staking_positions — enumeração de contas de stake Marinade + Jito + nativas com status de ativação e valoração equivalente em SOL
• get_tron_staking, list_tron_witnesses — estado do TRON Stake 2.0 + lista de SRs
• get_nft_portfolio (EVM + Solana DAS), get_nft_collection, get_nft_history, get_nft_listings (EVM)
• get_btc_balance / _balances / _account_balance / _multisig_balance / _multisig_utxos / _tx_history / _fee_estimates, get_ltc_balance — leituras BTC + LTC via Esplora
• get_compound_market_info — snapshot Comet sem carteira
• get_health_alerts, simulate_position_change — ferramentas de risco de liquidação multi-protocolo
• compare_yields — ranking de APRs de lending entre Aave / Compound / Morpho / Marinade / Jito / Kamino-lend / MarginFi
• get_marginfi_diagnostics — registra o que o SDK empacotado pulou, com causa raiz

Tokens, preços, histórico:

• get_token_balance, get_token_price, get_token_metadata, get_token_allowances, get_coin_price — saldos + preços DefiLlama em EVM/TRON/Solana; get_token_metadata detecta proxies EIP-1967
• get_transaction_history — leitor de transações mesclado (externas / ERC-20 / internas / program_interaction Solana) com métodos decodificados via 4byte + USD histórico
• get_transaction_status — consulta inclusão por hash
• explain_tx — decode post-hoc de uma transação histórica
• resolve_token, resolve_ens_name, reverse_resolve_ens

Leituras forenses de cadeia (exigem RPC do Bitcoin/Litecoin Core):

• get_btc_block_tip / _block_stats / _blocks_recent / _chain_tips / _mempool_summary, equivalentes get_ltc_*
• build_incident_report, get_market_incident_status — varredura de pausa + utilização Compound/Aave e pacote de tip de cadeia / anomalia de mempool BTC/LTC

Cotações + sinais de segurança:

• get_swap_quote (LiFi, EVM), get_solana_swap_quote (Jupiter v6)
• check_contract_security, check_permission_risks, get_protocol_risk_score, get_contract_abi, read_contract
• simulate_transaction — preview eth_call EVM (equivalente Solana roda dentro de preview_solana_send)
• verify_tx_decode, get_verification_artifact, get_tx_verification — verificação cruzada com segundo LLM + reemissão de handle com TTL de 15 min (detalhes)

Diagnóstico:

• get_solana_setup_status — sonda nonce + PDAs de conta MarginFi
• get_vaultpilot_config_status — diagnóstico de configuração local (fontes RPC, presença de chaves, contagens de contas pareadas, sufixo de tópico WC, estado de skill). Apenas booleanos / contagens — nenhum valor secreto.
• get_ledger_device_info, get_ledger_status, verify_ledger_attestation / _firmware / _live_codesign — descoberta de dispositivo + sessão, atestação no dispositivo, pin de versão de firmware

Contatos + compartilhamento somente leitura:

• add_contact / remove_contact / list_contacts / verify_contacts — agenda local assinada pelo Ledger em ~/.vaultpilot-mcp/contacts.json
• generate_readonly_link / import_readonly_token / list_readonly_invites / revoke_readonly_invite — emite links de portfólio somente leitura com escopo
• share_strategy / import_strategy — snapshots de portfólio anonimizados

Execução (assinado pelo Ledger):

• pair_ledger_live (EVM/WC), pair_ledger_tron / _solana / _btc / _ltc (USB HID)
• prepare_aave_*, prepare_compound_*, prepare_morpho_* — empréstimos EVM (fornecer / tomar emprestado / retirar / pagar)
• prepare_lido_stake / _unstake / _wrap / _unwrap (stETH↔wstETH), prepare_eigenlayer_deposit, prepare_rocketpool_stake / _unstake
• prepare_swap (LiFi), prepare_native_send, prepare_token_send, prepare_token_approve, prepare_revoke_approval, prepare_weth_unwrap
• prepare_uniswap_swap — swap V3 direto, mesma cadeia, seleciona automaticamente a faixa de taxa entre 100/500/3000/10000 bps. Use apenas quando o usuário mencionar Uniswap; caso contrário, prefira LiFi
• prepare_uniswap_v3_mint / _increase_liquidity / _decrease_liquidity / _collect / _burn / _rebalance — conjunto completo de verbos de LP
• prepare_curve_swap, prepare_curve_add_liquidity
• prepare_safe_tx_propose / _approve / _execute, submit_safe_tx_signature — fluxo de proposta multisig Safe
• prepare_custom_call — saída de emergência para chamadas arbitrárias a contratos verificados (portão acknowledgeNonProtocolTarget: true; ignora a allowlist de despacho canônico por design)
• prepare_tron_* — transferências nativas + TRC-20, WithdrawBalance, Stake 2.0, voto, reivindicação de recompensas, aprovação TRC-20, swap LiFi, swap SunSwap (prepare_sunswap_swap)
• prepare_solana_nonce_init / _close — configuração/remoção única de PDA com nonce durável
• prepare_solana_native_send, _spl_send (inclui automaticamente criação de ATA), prepare_solana_swap (Jupiter), prepare_solana_lifi_swap
• prepare_marginfi_init, _supply, _withdraw, _borrow, _repay
• prepare_kamino_init_user, _supply, _withdraw, _borrow, _repay
• prepare_marinade_stake / _unstake_immediate (taxa aplicável; caminho adiado de unstake-ticket adiado), prepare_jito_stake (somente stake — unstake adiado), list_solana_validators
• prepare_native_stake_delegate / _deactivate / _withdraw — staking nativo de SOL
• prepare_btc_send, prepare_btc_rbf_bump, prepare_btc_multisig_send, register_btc_multisig_wallet / unregister_btc_multisig_wallet, combine_btc_psbts, sign_btc_multisig_psbt, finalize_btc_psbt, sign_message_btc, prepare_btc_lifi_swap, rescan_btc_account
• prepare_litecoin_native_send, sign_message_ltc, rescan_ltc_account
• preview_send (EVM) — fixa o gas, emite LEDGER BLIND-SIGN HASH para pré-correspondência, cunha previewToken; obrigatório entre cada prepare_* e send_transaction EVM
• preview_solana_send — fixa nonce/blockhash, calcula o Message Hash para correspondência no dispositivo, executa simulação, emite CHECKS PERFORMED; obrigatório entre cada prepare_solana_* e send_transaction
• send_transaction — encaminha para Ledger (EVM via WC, TRON/Solana/BTC/LTC via USB HID)

Meta:

• request_capability — registrar uma issue de recurso ausente no GitHub. O padrão retorna uma URL pré-preenchida (sem envio automático); limitado a 3/hora
• set_etherscan_api_key, set_helius_api_key, set_demo_wallet, exit_demo_mode, get_demo_wallet, get_update_command — ajustes de runtime

Requisitos

• Node.js ≥ 18.17
• Leituras sem configuração: PublicNode (EVM) + mainnet pública Solana — limitado por taxa, mas suficiente para primeiro contato e uso leve.
• Uso real: RPC personalizado (Infura / Alchemy / Helius / QuickNode / Triton) via variáveis de ambiente ou vaultpilot-mcp setup.
• Chaves opcionais (solicitadas sob demanda): Etherscan, 1inch (habilita comparação de cotações de swap), WalletConnect project ID (obrigatório para assinatura EVM Ledger), TronGrid (eleva o limite anônimo de ~15 req/min).
• Assinatura TRON / Solana: acesso USB HID a um Ledger com o aplicativo Tron / Solana instalado. Linux: instale as regras udev da Ledger (vaultpilot-mcp setup imprime o one-liner exato). Debian/Ubuntu também precisam de sudo apt install libudev-dev build-essential para node-hid compilar.

Instalação

Três caminhos — instruções completas, configuração do cliente MCP, tratamento de Gatekeeper / SmartScreen, atualização / desinstalação em INSTALL.md.

Caminho	Resumo
Binário empacotado (sem Node)	Baixe da última versão, chmod +x, <binary> setup.
Do npm	npm install -g vaultpilot-mcp && vaultpilot-mcp setup
Do código-fonte	git clone https://github.com/szhygulin/vaultpilot-mcp.git && cd vaultpilot-mcp && npm install --legacy-peer-deps && npm run build && npm run setup

Configuração

npm run setup

Seleciona provedores de RPC, valida chaves, opcionalmente pareia Ledger Live, grava ~/.vaultpilot-mcp/config.json. Variáveis de ambiente sobrescrevem a configuração.

Modo demo

Experimente sem chaves de RPC, pareamento Ledger ou o assistente:

claude mcp add vaultpilot-mcp --env VAULTPILOT_DEMO=true -- npx -y vaultpilot-mcp

--demo é o sinalizador CLI equivalente; env explícito vence, então VAULTPILOT_DEMO=false é uma opção determinística de exclusão para invocações via script.

• Leituras executam contra RPC real; cada carteira é uma persona pública curada (whale, defi-degen, stable-saver, staking-maxi).
• send_transaction retorna um envelope de simulação: a transação não assinada é passada por simulate_transaction para detecção de revert, nada é assinado, nada é transmitido.
• pair_ledger_*, request_capability, sign_message_* são recusados de imediato. Sem persona selecionada, ferramentas de classe de assinatura recusam com um erro estruturado apontando para set_demo_wallet.
• Fluxos de múltiplas etapas cujas pré-condições são mudanças de estado (ex.: prepare_solana_nonce_init → marinade_stake) não podem ser ensaiados de ponta a ponta — envios simulados não mutam o estado da cadeia. O MCP exibe uma dica única quando detecta a armadilha do loop de agente.

get_demo_wallet lista personas + endereços + rehearsableFlows. set_demo_wallet({ persona }) ativa uma. O estado é local ao processo. exit_demo_mode retorna um guia de transferência para configuração permanente. Demo é um andaime para primeiro contato, não uma sandbox — sem sobreposição de cadeia virtual.

Para limitação de RPC Solana sob fan-out multi-ferramenta, injete uma chave Helius em runtime: set_helius_api_key({ key }). O modo demo avisa proativamente após 10 erros de limitação de RPC público.

Uso com Claude Code (CLI) / Cursor / Claude Desktop

vaultpilot-mcp setup detecta clientes instalados e registra vaultpilot-mcp com cada um (configs existentes com backup em <file>.vaultpilot.bak). Configs por projeto / por workspace são ignoradas — o assistente executa a partir de qualquer CWD. Para configuração manual ou caminhos de config por cliente, veja INSTALL.md §5.

Chat Claude.ai — limitação. MCP stdio local instalado via assistente registra-se limpo com o aplicativo nativo de desktop Claude.ai, mas a allowlist de HTTP de saída do ambiente host bloqueia provedores de RPC de cadeia (PublicNode, mainnet pública Solana, Alchemy, Helius, etc.). O MCP inicializa e processa chamadas de ferramenta, mas toda leitura que atinge um RPC externo falha com 403 / "Host not in allowlist". O mesmo se aplica ao Claude Code executando dentro da sandbox em nuvem do Claude.ai. Funcionando hoje: Claude Code CLI no seu terminal, Cursor, Claude Desktop em um host com HTTP de saída irrestrito. Futuro: um endpoint MCP hospedado (roadmap, ainda não lançado) dará ao chat Claude.ai um backend sem restrição de rede; assinatura USB-HID TRON / Solana / Bitcoin / Litecoin requer um Ledger local e permanece no caminho do terminal CLI / Cursor independentemente.

Variáveis de ambiente

Todas opcionais se o campo correspondente estiver em ~/.vaultpilot-mcp/config.json; env vence.

• ETHEREUM_RPC_URL, ARBITRUM_RPC_URL, POLYGON_RPC_URL, BASE_RPC_URL, SOLANA_RPC_URL — endpoints RPC personalizados
• RPC_PROVIDER (infura | alchemy) + RPC_API_KEY — alternativa a URLs personalizadas
• ETHERSCAN_API_KEY, ONEINCH_API_KEY, TRON_API_KEY, WALLETCONNECT_PROJECT_ID
• RPC_BATCH=1 — optar por agrupamento JSON-RPC (desativado por padrão; muitos endpoints públicos lidam mal com POSTs agrupados)
• VAULTPILOT_ALLOW_INSECURE_RPC=1 — optar por não fazer verificações de RPC https/IP privado (apenas anvil/hardhat local)
• VAULTPILOT_FEEDBACK_ENDPOINT — proxy https opcional para POSTs diretos de request_capability. O cliente não autentica; o proxy DEVE.
• VAULTPILOT_SKILL_MARKER_PATH — suprimir o aviso de habilidade de pré-voo (usuários somente leitura que optam por participar)
• VAULTPILOT_DISABLE_SKILL_AUTOINSTALL=1 — pular o git clone preguiçoso de primeira execução de habilidades complementares (air-gapped / sem egresso)
• VAULTPILOT_DEMO=true — habilitar modo demo; apenas literal "true", outros valores rejeitados
• VAULTPILOT_DISABLE_UPDATE_CHECK=1 — pular a verificação de atualização registry.npmjs.org uma vez por sessão (air-gapped)

Desenvolvimento

npm run dev      # tsc --watch
npm test         # vitest run
npm run test:watch

Contribuindo

PRs são bem-vindos. O bot CLA Assistant pedirá que você assine o Contributor License Agreement no seu primeiro PR — uma assinatura cobre todos os PRs futuros. O CLA concede ao projeto o direito de relicenciar sua contribuição; sem ele, a conversão automática BUSL-1.1 → Apache 2.0 em 2030 ficaria travada. O proprietário do repositório e o Dependabot estão isentos.

Licença

Business Source License 1.1 — veja LICENSE.

• Uso pessoal de autocustódia é gratuito, incluindo yield / swap / lend / stake em seu próprio nome.
• Uso organizacional interno é gratuito.
• Serviços hospedados e redistribuição embutida exigem licença comercial — abra uma issue ou contate o mantenedor.
• Converte automaticamente para Apache 2.0 em 2030-04-26. As restrições de cada versão expiram quatro anos após o lançamento.
• Versões ≤ 0.8.2 permanecem MIT. A mudança de licença se aplica a partir da v0.9.0.