Em resumo
Agentes de IA podem pagar por APIs e dados a cada requisição, em stablecoins, por meio de protocolos abertos de pagamento para agentes. Com a Blockradar, um agente paga a partir de uma carteira cuja chave privada nunca sai da Blockradar, usando o endpoint de Assinatura de Dados Tipados que você já tem.
Agentes de IA podem pagar por APIs e dados a cada requisição, em stablecoins, por meio de protocolos abertos de pagamento para agentes. Com a Blockradar, um agente paga a partir de uma carteira cuja chave privada nunca sai da Blockradar, usando o endpoint de Assinatura de Dados Tipados que você já tem.
Protocolos Suportados
Pré-requisitos
1
Chave API
Obtenha sua chave API no Painel da Blockradar. Navegue até Developers para gerar uma.
2
Carteira Principal EVM
Crie uma carteira principal pelo painel na chain em que a API cobra, como a Base (consulte Criar uma Carteira Principal). Pagamentos por agentes via Blockradar funcionam apenas em EVM.
3
USDC Habilitado
Habilite o USDC na carteira para que saldos e depósitos sejam rastreados. Consulte Gestão de Ativos.
Dê ao Agente um Orçamento Próprio
Um endereço filho com a varredura automática desativada funciona bem como orçamento de um agente. Abasteça-o com o valor que o agente pode gastar, e o agente nunca poderá pagar mais do que esse saldo.Mantenha
disableAutoSweep: true no endereço de um agente. Com a varredura automática ativada, o USDC que você envia para abastecer o agente é varrido para a carteira principal, e os pagamentos do agente falham por falta de fundos.addressId. Todo o saldo da carteira principal fica então ao alcance do agente, então faça isso apenas com uma carteira principal dedicada ao agente.
No Plano de Checkout, as operações com endereços filhos não estão disponíveis, então use uma carteira principal dedicada ao agente.
Como o x402 Funciona
O x402 é um protocolo aberto que permite que uma API cobre por requisição: ela responde com HTTP402 Payment Required, e quem chamou repete a requisição com um pagamento em USDC assinado. O x402 tem três partes: o comprador (seu agente), o vendedor (a API que está sendo paga) e um facilitador que verifica o pagamento e o submete on-chain.
1
A API pede o pagamento
O agente chama um endpoint pago. A API responde com
402 Payment Required e um header PAYMENT-REQUIRED listando o que aceita: rede, token, valor e o endereço payTo.2
A Blockradar assina o pagamento
O agente transforma uma dessas opções em um
TransferWithAuthorization EIP-3009 e o assina com o endpoint de dados tipados da Blockradar. Nada é enviado on-chain ainda.3
O agente repete a requisição com a assinatura
O agente repete a requisição com o pagamento assinado no header
PAYMENT-SIGNATURE.4
O facilitador liquida
O facilitador do vendedor verifica a assinatura e submete a transferência on-chain, pagando ele mesmo o gas. A API retorna a resposta, com o resultado da liquidação em um header
PAYMENT-RESPONSE.Pagar com x402
Abasteça primeiro o endereço do agente, conforme descrito em Dê ao Agente um Orçamento Próprio.Opção 1: Usar o SDK cliente do x402
O cliente oficial@x402/fetch cuida da troca 402 para você. Ele só precisa de um signer com um address e um método signTypedData. O adaptador abaixo implementa esse signer sobre o endpoint de dados tipados da Blockradar, de modo que a chave permanece na Blockradar.
JavaScript
eip155:84532 para a Base Sepolia durante os testes), com uma carteira nessa chain por trás de cada um.
Opção 2: Montar o pagamento você mesmo
Sem o SDK, ou em outra linguagem, um pagamento exige três chamadas HTTP: a primeira requisição, a chamada de assinatura à Blockradar e a nova tentativa paga. Os passos abaixo pagam 0,01 USDC na Base.Passo 1: Ler os requisitos de pagamento
Chame a API. Uma resposta402 traz um header PAYMENT-REQUIRED codificado em base64. Decodificado, ele fica assim:
accepts que sua carteira possa pagar:
schemeéexact.networké a chain da carteira.eip155:8453é a Base mainnet.extra.assetTransferMethodestá ausente ou éeip3009. O métodopermit2exige antes uma aprovação de token on-chain, que custa gas, por isso este guia não o aborda.
amount está na menor unidade do token. O USDC tem 6 casas decimais, então 10000 equivale a 0,01 USDC.
Passo 2: Assinar a autorização
Monte oTransferWithAuthorization a partir dos requisitos e assine-o a partir do endereço do agente:
POST /v1/wallets/{walletId}/signing/typed-data e defina from como o endereço da carteira principal. A resposta é a resposta de dados tipados padrão; a assinatura fica em data.signedTransaction.signature.
Passo 3: Repetir a requisição com o pagamento
Envolva a assinatura e a autorização em um payload de pagamento, codifique-o em base64 e envie-o no headerPAYMENT-SIGNATURE na mesma requisição:
JavaScript
Passo 4: Verificar a liquidação
Uma resposta bem-sucedida inclui um headerPAYMENT-RESPONSE codificado em base64:
transaction é o hash on-chain da transferência de USDC. Se o pagamento falhar, a API responde 402 novamente, e o PAYMENT-RESPONSE traz um errorReason como insufficient_funds.
Chamando uma API x402 v1
Chamando uma API x402 v1
Servidores na versão 1 do x402 diferem do fluxo acima em quatro pontos:
- Os requisitos de pagamento vêm no corpo da resposta
402, não em um header. - As redes têm nomes (
base,base-sepolia) em vez deeip155:<chainId>. A Base tem chain ID8453; a Base Sepolia,84532. - O campo de valor é
maxAmountRequired, nãoamount. - O pagamento vai no header
X-PAYMENTcomo JSON codificado em base64 comx402Version: 1,scheme,networke o mesmo objetopayload, e a liquidação volta emX-PAYMENT-RESPONSE.
Regras de assinatura que costumam quebrar integrações
Cada assinatura é registrada como uma transação
SIGNED e dispara um webhook signed.success, o que dá a você uma trilha de auditoria de cada pagamento que seu agente autorizou. Uma assinatura não é um pagamento: o USDC só se move quando o facilitador do vendedor o liquida. Quando o vendedor está fora da Blockradar, a liquidação aparece como uma transferência de saída a partir do endereço do agente. Para conciliar, compare os webhooks signed.success com a transação on-chain do cabeçalho PAYMENT-RESPONSE.
Como o MPP Funciona
O MPP (Machine Payments Protocol) é um protocolo aberto para pagar por requisição via HTTP. O charge EVM dele funciona como o x402: o agente assina o mesmoTransferWithAuthorization EIP-3009 com a Blockradar, o servidor o liquida on-chain e paga o gas, e a carteira do agente precisa de USDC, mas não de gas. O que muda é o envelope em torno da assinatura:
Pagar com MPP
O cliente oficialmppx cuida da troca do MPP, incluindo o nonce vinculado ao desafio, e assina credenciais authorization EIP-3009. Ele recebe uma conta viem, então o adaptador abaixo expõe o endpoint de dados tipados da Blockradar como uma. A requisição de assinatura que ele envia é a mesma do x402.
JavaScript
maxAmount é um limite por pagamento imposto pelo cliente: acima dele, o mppx recusa antes de chamar a Blockradar, então nada é assinado. A própria Blockradar não limita o que assina, então defina-o.
Para conciliar, compare os webhooks signed.success com o reference de cada Payment-Receipt, que é o hash da transação on-chain.
Montar o pagamento MPP você mesmo
Montar o pagamento MPP você mesmo
A requisição de assinatura para a Blockradar é a do Passo 2, com três diferenças:
- Leia o desafio do cabeçalho
WWW-Authenticate: Payment. O parâmetrorequestdele é um JSON codificado em base64url comamount,currency,recipientemethodDetails.chainId. - Defina
noncecomokeccak256(abi.encodePacked(challenge.id, challenge.realm))evalidBeforecomo o horárioexpiresdo desafio. Obtenhadomain.nameedomain.versiondo contrato do token. - Envie a credencial como
Authorization: Payment <base64url JSON>, com o desafio devolvido e umpayloaddetype: "authorization"mais os campos assinados.
Limitações
- Apenas EVM. Os pagamentos são assinados com dados tipados EIP-712, que a Blockradar suporta apenas em chains EVM. Solana e outras redes não EVM não são suportadas.
- Apenas pagamentos EIP-3009. Tokens com
transferWithAuthorization, como o USDC, funcionam. O método de transferênciapermit2do x402 e as credenciaispermit2,transactionehashdo MPP não são suportados. - MPP na Tempo chega em breve. Até lá, charges na Tempo e sessões MPP não são suportados.
- Sem nanopagamentos do Circle Gateway. A opção de pagamentos em lote abaixo de um centavo da Circle não é suportada.
- Pagar outra empresa Blockradar. Quando o vendedor também recebe em um endereço Blockradar, o pagamento de saída do agente geralmente não aparece no histórico de transações dele e não dispara nenhum webhook. Os saldos estão corretos. Concilie com o hash da transação no
PAYMENT-RESPONSEou noPayment-Receipt.
Melhores Práticas
- Imponha limites no seu agente. A Blockradar assina qualquer requisição bem formada de uma chave API válida. Coloque limites por pagamento e por dia no código do seu agente (com o MPP,
maxAmountcobre o limite por pagamento) e limite a exposição total com o saldo do endereço do agente. - Um endereço por agente. Orçamentos separados deixam claro qual agente gastou o quê e permitem cortar um agente esvaziando o endereço dele.
- Verifique o preço antes de assinar. Compare
amountcom o máximo que seu agente deveria pagar por aquele recurso e recuse qualquer valor acima disso. - Verifique o destinatário. Se seu agente só paga APIs conhecidas, mantenha uma allowlist de endereços
payTo(x402) ourecipient(MPP). - Use
metadatae webhooks. Marque os endereços dos agentes commetadatae concilie os webhookssigned.successcom a transação on-chain de cadaPAYMENT-RESPONSEouPayment-Receipt. - Restrinja o acesso à API. Aceite requisições de API apenas dos seus próprios servidores com IP Whitelisting, para que uma chave vazada não possa ser usada em outro lugar.
- Teste primeiro na Base Sepolia. Use uma carteira de testnet,
eip155:84532, e USDC de testnet dos faucets antes de gastar fundos reais.

