Pare de colar chaves privadas no Cursor: como dar uma carteira ao seu agente de código

Você está no meio de um build. Seu agente no Cursor escreveu a chamada de contrato, escolheu a rede e está pronto para enviar uma transação de teste. Só uma coisa separa o plano de uma transação assinada: uma chave. Então você cola uma chave privada em um arquivo .env que o agente consegue ler, e continua construindo.

Essa única etapa é o motivo pelo qual muitos desenvolvedores experientes mantêm IA longe de qualquer coisa que envolva fundos reais. Uma chave privada é tudo ou nada. Uma vez que seu agente consegue lê-la, ele pode mover tudo naquela carteira, em qualquer chain, permanentemente, sem como desfazer. E um agente é probabilístico por natureza: muito bom na maior parte do tempo, ocasionalmente errado com confiança.

Existe uma forma melhor de fazer isso. Você dá ao agente uma carteira sem dar a ele a chave. Abaixo está como isso funciona com agent wallets na Alchemy CLI, e onde estão os limites reais.

O problema é a chave, não o agente

É tentador tratar o agente como o risco, mas o agente não é realmente o problema. Uma chave privada nunca foi projetada para ser compartilhada. Ela não tem noção de "você pode enviar até este valor", "somente nestas chains", "somente pela próxima hora" ou "na verdade, pare agora". É um único segredo que concede controle total, e a única forma de usá-lo é expondo-o.

Até agora, os desenvolvedores tinham duas opções, e ambas têm custos reais. Você pode colar a chave em .env e aceitar que o agente tem controle total dos fundos, o que deixa você a um prompt equivocado de distância de uma carteira esvaziada. Ou você pode conectar um SDK de carteira a um backend customizado e reconstruir autenticação, assinatura e revogação por conta própria, o que representa semanas de trabalho que a maioria das equipes não deveria assumir. A primeira opção é arriscada demais, e a segunda é cara demais.

O que você realmente quer é algo mais próximo de como você já pensa sobre acesso em qualquer outro lugar do seu stack. Você não distribui a senha de root. Você emite uma credencial com escopo definido, define o que ela pode fazer e a revoga quando termina. Uma carteira deveria funcionar da mesma forma.

Como funcionam as agent wallets

As agent wallets na Alchemy CLI permitem criar uma carteira a partir do dashboard, conceder ao seu terminal uma sessão com escopo definido e tempo limitado, e deixar o agente enviar transações reais a partir da linha de comando. A chave privada nunca passa pelo CLI, nunca passa pela Alchemy, e nunca fica em um arquivo .env. Ajuda pensar nisso como três camadas, cada uma controlada por uma parte diferente.

A camada de custódia: outra pessoa guarda a chave

A chave privada da carteira é mantida pela Privy, nossa parceira de embedded wallets, na infraestrutura dela. Ela não está no seu laptop, não está no seu repositório e não está nos nossos sistemas. É isso que muda o cálculo de risco. O segredo que você estava prestes a colar em .env agora é algo que nem você nem seu agente manipulam diretamente.

A camada de sessão: o agente recebe permissão, não o segredo

Quando você executa alchemy wallet connect, o CLI gera um novo par de chaves P-256 na sua máquina, e a metade privada desse par nunca sai do dispositivo. Seu navegador abre no dashboard da Alchemy, onde você escolhe a carteira e aprova uma sessão. A aprovação anexa a chave pública do seu CLI como signer daquela carteira, com escopo definido para capacidades específicas e limitado por uma expiração que você define.

A partir daí, toda chamada de assinatura é um desafio de duas etapas. Nosso backend monta o payload exato que a Privy espera, seu CLI assina esses bytes precisos localmente, e só então a requisição chega até a Privy. Se a sessão expirou, foi revogada, ou falha em qualquer verificação de vínculo, a próxima tentativa de assinatura é rejeitada antes mesmo de sair da nossa infraestrutura. O agente atua por meio de uma sessão que você definiu, não por meio de um segredo que ele detém.

A camada de controle: você mantém o kill switch

O dashboard é o único lugar onde uma carteira é criada ou revogada, e a revogação é um clique que tem efeito imediato. Você também pode executar alchemy wallet disconnect pelo terminal. Se uma sessão começar a fazer algo que você não pretendia, você a encerra e a assinatura para. Você nunca fica apenas esperando que uma sessão se comporte bem, porque você sempre pode encerrá-la.

O que o agente consegue realmente fazer

Uma vez que uma sessão está ativa, o agente tem uma superfície de transação completa para trabalhar. Em chains EVM, ele pode enviar tokens nativos e ERC-20s, fazer chamadas de contrato, gerenciar approvals de ERC-20, fazer swap e bridge entre mainnets. No Solana, ele pode enviar SOL e tokens SPL. As transações passam pelas nossas Wallet APIs, então sponsorship de gas via Gas Manager, batching, retentativas automáticas e pagamentos de gas em ERC-20 vêm junto.

Como o CLI foi construído como uma superfície de ferramentas para agentes, seu agente assimila esses comandos sozinho. A flag --json retorna saída estruturada, --no-interactive impede que os comandos travem em prompts, e alchemy agent-prompt emite um documento JSON descrevendo cada comando, flag e código de erro. Basta colocar isso em um system prompt e o agente aprende toda a superfície de uma vez. Não há SDK para integrar e nada para ele inferir a partir de documentação.

Para quem isso serve e em quais fluxos ele se encaixa

Isso é para o desenvolvedor que vive no Cursor ou Claude Code e constrói onchain: alguém integrando um protocolo DeFi, montando um fluxo de pagamentos, ou testando um contrato, que quer que o agente realmente execute transações em vez de parar no ponto em que uma assinatura é necessária. Se você já deixou o agente escrever o código e depois terminou a parte onchain manualmente, isso fecha essa lacuna. Dois fluxos mostram onde isso se encaixa.

O primeiro é o ciclo de build-and-test. Você está integrando com um protocolo, e seu agente escreveu o código. Para saber se funciona de fato, alguém precisa enviar transações reais: financiar o contrato, chamá-lo, verificar o estado resultante, ajustar e executar de novo. Fazer isso manualmente significa aprovar e colar cada transação você mesmo, o que é exatamente a tediosidade que você trouxe o agente para eliminar. Com uma sessão, você cria uma carteira, a financia com um saldo pequeno, aprova uma sessão com escopo definido e expiração curta, e deixa o agente rodar todo o ciclo. Ele envia, lê o resultado e itera enquanto você observa, e quando a sessão expira, o acesso dele termina sozinho.

O segundo é um agente que executa uma tarefa onchain com múltiplas etapas. Algum trabalho é uma sequência em vez de uma única chamada: trocar um token na mainnet, fazer bridge do resultado para uma L2, e depois depositar em uma posição. Você pode descrever o resultado esperado e deixar o agente executar as etapas por meio da sessão, em vez de executar cada uma você mesmo. A sessão limita quais capacidades o agente pode usar e por quanto tempo — não quanto ele pode mover — então financie a carteira com o que a tarefa precisa, defina uma expiração curta, e revogue quando terminar.

Um olhar honesto sobre os limites

Uma ferramenta que lida com dinheiro é mais fácil de confiar quando seus criadores são claros sobre onde ela para. Aqui estão alguns limites que vale a pena conhecer antes de confiar nisso em produção.

Políticas de gas e sponsorship de taxa controlam as taxas de transação. Elas não são limites de gasto da carteira, então não trate uma política do Gas Manager como um teto para o que o agente pode mover. Swaps e bridges são, por enquanto, apenas para EVM mainnet. O session signer não faz assinatura direta de transação EVM bruta; as ações são executadas por meio de chamadas da Alchemy Wallet API, como wallet_prepareCalls e wallet_sendCalls. E a sessão tem exatamente o escopo que você definir no dashboard, então a expiração e as capacidades que você define são o limite real, não uma sugestão.

Nada disso é uma solução alternativa; é como o sistema foi feito para funcionar. A carteira mantém a custódia, a sessão carrega a permissão, e você mantém a capacidade de encerrá-la.

Começando

As agent wallets no CLI já estão disponíveis, sem lista de espera e sem tier separado. Você precisa do Node 22 ou superior e de uma conta Alchemy. Três comandos levam você até uma carteira controlável por agente:

A etapa de connect abre o dashboard, onde você aprova a sessão e define seu escopo e expiração. Antes de qualquer workflow que altere estado, faça o agente verificar a sessão primeiro:

Quando o trabalho terminar, encerre a sessão:

As equipes que constroem os produtos mais exigentes onchain já rodam na Alchemy, movimentando mais de um trilhão de dólares por ano em mais de 100 chains. O objetivo das agent wallets é que a mesma infraestrutura agora sustente a carteira que você entrega ao seu agente de código, sem entregar a chave. Em vez de colar uma chave privada no Cursor, você pode dar ao agente uma sessão com escopo definido e manter a capacidade de revogá-la a qualquer momento.

Leia a documentação de agent wallets, explore Alchemy for agents, ou instale o CLI para experimentar.

FAQ

Como dou a um agente de código de IA uma carteira sem compartilhar minha chave privada?

Crie uma carteira no dashboard da Alchemy, depois execute alchemy wallet connect --mode session no seu terminal. O CLI gera um par de chaves local e o dashboard aprova uma sessão com escopo definido e tempo limitado. O agente envia transações por meio dessa sessão, enquanto a chave privada fica com o provedor de carteira e nunca é exposta.

Onde a chave privada é realmente armazenada?

A chave privada da carteira é mantida pela Privy, parceira de embedded wallets da Alchemy, na infraestrutura dela. Ela nunca é gravada na sua máquina, no seu repositório, ou em um arquivo .env, e nunca passa pelo CLI ou pelos sistemas da própria Alchemy. Seu agente atua por meio de uma sessão aprovada, e não por meio da chave em si.

Posso revogar o acesso de um agente à carteira?

Sim. Revogue a sessão no dashboard da Alchemy com um clique, ou execute alchemy wallet disconnect pelo terminal. A revogação tem efeito imediato, e a próxima tentativa de assinatura daquela sessão é rejeitada. As sessões também expiram automaticamente no momento que você definir ao aprová-las.

O que o agente pode fazer com uma agent wallet?

Em chains EVM, um agente pode enviar tokens nativos e ERC-20s, fazer chamadas de contrato, gerenciar approvals, fazer swap e bridge entre mainnets. No Solana, ele pode enviar SOL e tokens SPL. As transações passam pelas Wallet APIs da Alchemy, então sponsorship de gas, batching, retentativas e pagamentos de gas em ERC-20 estão disponíveis.

As políticas de sponsorship limitam quanto um agente pode gastar?

Não. Políticas de gas e sponsorship de taxa controlam as taxas de transação, não os saldos da carteira. Elas não são limites de gasto. O limite real sobre o que um agente pode fazer são as capacidades e a expiração que você define na sessão no dashboard, então defina o escopo da sessão com cuidado.

O que preciso para começar?

Você precisa do Node 22 ou superior e de uma conta Alchemy. As agent wallets no CLI já estão disponíveis, sem lista de espera e sem tier separado. Instale com npm i -g @alchemy/cli@latest, execute alchemy auth, depois alchemy wallet connect --mode session para aprovar uma sessão a partir do dashboard.