Como criar agentes onchain: carteiras, pagamentos e dados em tempo real
Autor: Uttam Singh
A maioria dos tutoriais de "agente de IA" para no LLM. A parte difícil começa quando o agente precisa de uma carteira, de uma forma de pagar pelos serviços que chama, e de uma visão ao vivo da chain sobre a qual está agindo.
Para construir agentes onchain, dê ao agente três primitivas: uma carteira com escopo definido para assinatura, um trilho de pagamento como o x402, e um feed de dados em tempo real via webhooks, WebSockets ou gRPC. O modelo decide; essas primitivas permitem que ele aja onchain.
Um LLM que escreve código é um copiloto. Um agente que guarda dinheiro, assina transações e reage a eventos onchain em tempo real é outra coisa: um participante da economia. A infraestrutura existe, mas está espalhada entre primitivas de carteira, pagamento e dados em tempo real. Este guia percorre as três que você realmente precisa e como conectá-las. O Alchemy CLI e nossos produtos agênticos entregam cada uma delas como uma primitiva que você pode usar diretamente.
O que muda ao construir um agente onchain?
A maior parte da stack de um agente de IA comum ainda funciona onchain: o modelo, o framework, o padrão de tool-calling, o loop de orquestração, o eval harness, o armazenamento de prompts. Tudo isso se transfere. Se você já construiu um bot do Slack, um agente de código ou um agente de pesquisa, a metade superior da stack já é familiar.
Três coisas não se transferem: a carteira, o trilho de pagamento e o feed de dados em tempo real. Nenhuma das três tem um equivalente limpo no mundo das ferramentas de LLM, nenhuma é resolvida escolhendo um modelo mais inteligente, e errar qualquer uma delas é o tipo de erro que esvazia uma carteira ou trava um agente em produção.
- Identidade é uma chave privada, não um endereço de e-mail. O que o agente pode assinar, ele pode gastar. A custódia de chaves vira um modelo de segurança, não um arquivo de configuração.
- Pagamentos acontecem na camada de protocolo. O Stripe não aceita "sou um agente" como pagador. Trilhos cripto aceitam, através de padrões como HTTP 402/x402.
- Dados em tempo real são o modo padrão, não um recurso. Os tempos de bloco são curtos e a finalidade importa. Polling consome orçamento; o agente precisa que a chain empurre o estado até ele.
Cada uma das três partes abaixo mapeia uma dessas mudanças.
Quais são os três blocos de construção de um agente onchain?
Um agente onchain em produção geralmente precisa de três coisas:
- Carteira. O agente pode assinar com ela, com escopo definido para que um prompt comprometido não consiga esvaziá-la.
- Trilho de pagamento. O agente paga por APIs offchain e gas onchain sem um humano no loop.
- Pipe de dados em tempo real. O agente reage a novos blocos, transações e eventos de contrato no instante em que acontecem.
O restante deste guia traz uma seção por bloco de construção, mais um walkthrough final que junta tudo.
Como dar a um agente uma carteira sem vazar suas chaves?
O padrão ingênuo é o que todo mundo tenta primeiro: colocar uma chave privada em um arquivo .env, carregá-la com dotenv, assinar transações com ela de dentro do loop do agente. Funciona em uma demo local. Está a um prompt injection de distância de uma carteira esvaziada em produção.
Dois padrões estão emergindo como opções padrão mais seguras.
O primeiro padrão são smart accounts embarcadas (contratos de carteira programáveis, não contas de chave privada crua) com assinatura delegada. A chave vive dentro de um serviço de custódia (Privy, Turnkey, Coinbase MPC para computação multipartidária). Seu agente nunca a vê. Ele chama uma API de assinatura, o serviço verifica a requisição contra uma política, e a transação assinada volta. O agente pode assinar dentro das regras que você define (valor máximo por tx, contratos permitidos, limites diários) e nada além disso.
O segundo padrão são carteiras com escopo de sessão aprovadas a partir de uma superfície de desenvolvedor. O agente recebe uma sessão com tempo limitado e revogável, vinculada a uma carteira específica. Você aprova a sessão a partir de uma UI que você controla. A revogação é um clique.
A abordagem mais recente do padrão 2 é o recurso de agent wallet no Alchemy CLI, que vem embutido no próprio CLI:
# Install the latest Alchemy CLI
npm i -g @alchemy/cli@latest
# Authenticate your CLI session
alchemy auth
# Connect the wallet your agent will use
alchemy wallet connectalchemy wallet connect abre nosso dashboard em um navegador. Você escolhe a carteira que quer que o agente use, aprova a sessão, e a partir daí o CLI pode assinar em nome do agente. A chave privada fica com a Privy. Toda chamada de assinatura passa por um fluxo de dois passos: nosso backend constrói o payload, o CLI assina localmente, a requisição chega à Privy. Se a sessão expirou, foi revogada, ou falha nas verificações de vinculação, a requisição é rejeitada antes de sair da nossa infraestrutura.
O CLI foi projetado como uma superfície de ferramentas para agentes, não apenas para humanos. Estes comandos importam:
# Run any command with structured output and no prompts
alchemy <command> --json --no-interactive
# Print the JSON manifest of every command and flag
alchemy --json --no-interactive agent-prompt
# Install Alchemy Skills for agent clients
npx skills add alchemyplatform/skills --yesalchemy --json --no-interactive agent-prompt é a parte que torna isso nativo para agentes. Em vez de pedir ao seu LLM para memorizar a superfície do CLI, você alimenta o manifesto JSON no início da sessão e o modelo conhece todo o espaço de comandos, códigos de erro e exemplos de invocação. Isso elimina uma categoria inteira de falhas do tipo "o agente alucinou uma flag que não existe". Conecte o servidor MCP hospedado separadamente para ferramentas de dados de chain ao vivo.
Como escolher entre os dois padrões:
Seja qual for sua escolha, a regra é a mesma: o agente nunca vê uma chave privada crua. Se o seu design tem uma em memória, você construiu uma vulnerabilidade, não um agente.
Como o agente paga pelos serviços que chama?
Assim que o agente tem uma carteira, ele ainda precisa pagar por coisas. Dois tipos de coisas:
- Custos onchain. Gas, taxas de swap, taxas de bridge, qualquer coisa que a chain cobra por mudanças de estado.
- Custos offchain. Requisições de RPC, APIs de dados indexados, inferência, qualquer coisa que o agente precise de um servidor.
Custos onchain são resolvidos com patrocínio de gas. Muitos provedores de account abstraction expõem uma paymaster API, onde um paymaster é um contrato que paga gas em nome de outra pessoa. O agente submete uma user operation (o equivalente de transação da ERC-4337 para smart accounts), o paymaster cobre, e você reconcilia o uso do seu lado. Esse padrão já é comum em sistemas de smart account.
Custos offchain são o problema mais difícil, porque o agente não tem um cartão de crédito cadastrado e você não quer provisionar chaves de API para cada agente. O padrão que está convergindo no ecossistema é o x402: o código de status HTTP 402 Payment Required, mais um pequeno payload que diz ao agente como pagar.
Eis o fluxo completo:
- O agente faz uma requisição HTTP a um serviço.
- O serviço responde
402 Payment Requiredcom um corpo JSON descrevendo o preço, o token aceito e a chain. - O agente constrói um pagamento (USDC na Base é o padrão comum), assina com sua carteira, e refaz a requisição original com uma prova de pagamento em um header.
- O serviço verifica, liquida e retorna os dados.
Implementamos isso de ponta a ponta. Um agente pode acessar nossa RPC API, Token API, Portfolio API, NFT API e Prices API sem chave de API e sem cadastro no dashboard. A primeira requisição recebe um 402; requisições subsequentes pagam o valor cotado pelo endpoint em USDC na Base e retornam os dados. Sem humano no loop.
Um handler mínimo do lado do cliente se parece com isto:
async function paidFetch(url: string, wallet: AgentWallet) {
let res = await fetch(url);
if (res.status === 402) {
const requirement = await res.json();
const payment = await wallet.signX402Payment(requirement);
res = await fetch(url, {
headers: { "X-PAYMENT": payment },
});
}
return res.json();
}O agente refaz a mesma URL com o header de pagamento assinado. O endpoint liquida o pagamento onchain, entrega os dados, e o agente segue em frente. O padrão se compõe entre provedores: qualquer serviço que fale x402 pode aceitar pagamentos de agentes sem escrever autenticação customizada.
Como o agente se mantém sincronizado com a chain?
Chains não empurram dados para o seu app por padrão. Se o seu agente faz polling em eth_blockNumber a cada segundo para descobrir o que está acontecendo, você está pagando pelo polling e chegando atrasado em todo evento que importa.
Três padrões cobrem quase todo caso de uso em tempo real. O detalhamento completo está na comparação entre webhooks, WebSockets e gRPC, mas aqui vai a versão curta para quem constrói agentes:
Para a maioria dos agentes, webhooks mais algumas chamadas à Data API (saldos de token, histórico de transações, portfolio) já bastam. O webhook dispara, o agente acorda, consulta o estado enriquecido, decide o que fazer, assina uma transação e volta a dormir.
Juntando tudo: uma arquitetura mínima de agente onchain
Aqui está um esboço de arquitetura compacto que combina os três blocos de construção. Ele observa sua própria carteira, consulta um endpoint pago quando algo chega, pergunta a um LLM o que fazer, e assina uma transação de resposta. Substitua o helper de assinatura x402 pelo seu provedor de custódia antes de rodar isso em produção.
import { createPublicClient, webSocket } from "viem";
import { base } from "viem/chains";
import { execFile } from "node:child_process";
import { promisify } from "node:util";
import OpenAI from "openai";
const run = promisify(execFile);
const openai = new OpenAI();
const agentWallet = process.env.AGENT_WALLET_ADDRESS!.toLowerCase();
const client = createPublicClient({
chain: base,
transport: webSocket(process.env.ALCHEMY_RPC_WSS!),
});
async function signX402Payment(requirement: unknown) {
// Plug in your x402 client and custody provider here.
// The signer should construct the payment payload and sign it with the agent wallet.
throw new Error("Implement x402 signing with your wallet provider");
}
// 1. Signing through the agent wallet session (no private key in process).
// Use the session approved via `alchemy wallet connect` to sign and broadcast.
async function refund(to: string, amountEth: string) {
// Plug in your agent wallet signing provider here.
throw new Error("Implement refund signing with your agent wallet session");
}
// 2. Paid data fetch via x402 against an Alchemy endpoint.
async function paidFetch(url: string) {
let res = await fetch(url);
if (res.status === 402) {
const requirement = await res.json();
const payment = await signX402Payment(requirement);
res = await fetch(url, { headers: { "X-PAYMENT": payment } });
}
return res.json();
}
// 3. Real-time trigger: react to inbound transactions on the agent wallet.
client.watchBlocks({
includeTransactions: true,
onBlock: async (block) => {
for (const tx of block.transactions) {
if (tx.to?.toLowerCase() !== agentWallet) continue;
const portfolio = await paidFetch(
`https://api.g.alchemy.com/data/v1/portfolio/${tx.from}`
);
const decision = await openai.chat.completions.create({
model: "gpt-4o",
messages: [
{
role: "system",
content: "You are a treasury agent. Decide whether to refund.",
},
{
role: "user",
content: JSON.stringify({ tx, sender_portfolio: portfolio }),
},
],
});
const action = JSON.parse(decision.choices[0].message.content!);
if (action.refund) {
await refund(tx.from, action.amount);
}
}
},
});Três coisas valem a pena notar nessa estrutura:
- Nenhuma chave privada no processo. Toda chamada de assinatura passa pela sessão do CLI, que conversa com a Privy. Se esse processo for comprometido, o atacante ganha uma sessão revogável, não uma carteira.
- Nenhuma chave de API para a chamada de dados.
paidFetchfunciona contra qualquer endpoint que fale x402. O endpoint cobra por requisição em USDC. - O LLM é a menor peça. A maior parte da área de superfície é carteiras, pagamentos e a infraestrutura de dados. O modelo apenas decide.
Esse é o padrão. Troque o gatilho (mensagem no Discord, cron, evento de marketplace), troque a ação (swap, voto, bridge, mint), troque o modelo, e você tem um agente diferente.
Construa com Claude
Ou faça o Claude construir para você. Instale os Alchemy Skills e conecte o servidor MCP hospedado:
npx skills add alchemyplatform/skills --yes
# Claude Code — see the MCP server docs for other clients
claude mcp add alchemy --transport http https://mcp.alchemy.com/mcpDepois cole este prompt no Claude Code:
Build a TypeScript onchain agent on Base that:
1. Watches a wallet address for incoming transactions in real time
2. When a transaction arrives, queries an x402-payable portfolio API for the sender's holdings
3. Asks an LLM whether to refund
4. Signs the refund without holding the private key in the process
Use production-grade primitives.O resultado espelha o script acima: um WebSocket do viem contra nossa RPC, nossa Portfolio API por trás do x402, e assinatura via CLI através da sessão de agent wallet aprovada para o reembolso. Nenhuma chave privada no processo.
Qual framework de agente você deve usar?
Os frameworks se sobrepõem às três primitivas acima. Eles cuidam do loop do agente, do registro de ferramentas, da memória e (em alguns casos) de clientes de plataformas sociais. A escolha certa depende se você está otimizando para profundidade em uma chain, amplitude multi-chain, ou um runtime completo.
Para um build de ponta a ponta nativo de uma chain com configuração de carteira, integração RPC e swaps do Jupiter, veja o guia de construção de agente de IA na Solana. Para uma comparação de provedores independente de chain, veja as melhores APIs de blockchain para agentes onchain autônomos.
Os frameworks são intercambiáveis de uma forma que os blocos de construção não são. Você pode trocar o LangChain pelo GOAT em uma tarde. Trocar como seu agente assina é uma revisão de segurança.
O que construir a seguir
Os três blocos de construção se compõem. Uma vez que você tem um agente que mantém uma carteira com escopo de sessão, paga por dados com x402 e reage a eventos em tempo real, a questão deixa de ser "o agente consegue fazer isso" e passa a ser "o que o agente deveria fazer?"
Entregamos cada um dos três blocos de construção como uma primitiva. Nosso CLI lida com carteiras através de sessões revogáveis apoiadas pela Privy. Nossas APIs de RPC, Token, Portfolio, NFT e Prices falam x402 diretamente. Sem chave de API, sem cadastro no dashboard, sem contrato. Webhooks, assinaturas WebSocket e streaming gRPC na Solana cobrem o feed de dados em tempo real.
Rode npx skills add alchemyplatform/skills --yes, conecte o servidor MCP hospedado, depois aponte o LangChain, GOAT, ElizaOS, ou seu framework para as APIs da Alchemy. Comece com npm i -g @alchemy/cli@latest e alchemy auth. Saiba mais em alchemy.com/agents.
Perguntas frequentes
O que é um agente onchain?
Um agente onchain é um agente de IA que consegue ler o estado da blockchain, manter ou controlar uma carteira, e assinar transações com base em uma política ou decisão do modelo. O modelo decide o que fazer; a carteira, o trilho de pagamento e o feed de dados permitem que ele aja.
Como construir um agente onchain?
Comece com três primitivas: uma carteira com escopo definido para assinatura, um trilho de pagamento como o x402 para chamadas de API pagas, e um feed de dados em tempo real via webhooks, WebSockets ou gRPC. Depois conecte essas primitivas ao framework de agente ou loop de orquestração que você já usa.
Qual carteira um agente de IA deve usar?
Use um padrão de carteira que mantenha chaves privadas cruas fora do processo do agente. Smart accounts embarcadas com assinatura delegada funcionam bem para apps voltados ao usuário final, enquanto carteiras de CLI com escopo de sessão funcionam bem para agentes de desenvolvedor, automação interna e protótipos.
Como agentes onchain pagam por APIs?
Eles podem usar pagamentos x402. O agente faz uma requisição, recebe uma resposta 402 Payment Required com detalhes do pagamento, assina o pagamento com sua carteira, e refaz a requisição com uma prova de pagamento.
Agentes onchain devem usar webhooks, WebSockets ou gRPC?
Use webhooks quando o agente roda como um serviço e pode receber eventos empurrados. Use WebSockets quando o agente roda como um processo persistente e precisa de logs ou transações pendentes com baixa latência. Use streaming gRPC para cargas de trabalho de alto throughput no estilo Solana, onde a latência importa o suficiente para justificar mais esforço de integração.
Qual é o melhor framework para agentes onchain?
O melhor framework depende do loop de que você precisa. LangChain ou LangGraph são flexíveis para orquestração geral, GOAT é útil para cobertura de ferramentas multi-chain, ElizaOS é feito para agentes sociais, Solana Agent Kit vai fundo na Solana, e o Vercel AI SDK é uma boa opção para UIs de agente voltadas ao navegador.
A infraestrutura central está pronta para construir. O que você faz com ela é a parte que ninguém mais pode escrever por você.
Newsletter da Alchemy
Seja o primeiro a saber sobre lançamentos
Assine nossa newsletter
Receba as últimas atualizações de produtos e recursos da Alchemy
Ao inserir seu endereço de e-mail, você concorda em receber nossas comunicações de marketing e atualizações de produtos. Você reconhece que a Alchemy processa as informações que recebemos de acordo com nosso Aviso de Privacidade. Você pode cancelar a inscrição a qualquer momento.
Artigos relacionados
Glamsterdam: o guia completo para desenvolvedores de Ethereum
Glamsterdam já está na Sepolia. O guia completo sobre o que isso significa para desenvolvedores e como a Alchemy se preparou para a atualização da rede.
Por que equipes de trading escolhem a Alchemy para RPC de baixa latência
Equipes de trading escolhem a Alchemy por leituras e escritas de baixa latência quando o mercado se move, e por um registro confiável quando o dinheiro liquida, mesmo no pico de volume.
Em qual provedor de RPC você deve construir em Tóquio?
Comparamos cinco dos provedores de RPC que atendem Tóquio em cinco chains. Veja como eles se comparam e onde as diferenças importam para equipes sensíveis à latência.