Realizar Pagamentos com Agentes

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.

Protocolos Suportados

Protocolo	Redes e tokens
x402	Chains EVM, USDC (EIP-3009)

Vende para agentes? Consulte Aceitar Pagamentos de Agentes.

Pré-requisitos

Chave API

Obtenha sua chave API no Painel da Blockradar. Navegue até Developers para gerar uma.

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.

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

A assinatura não tem limite de gasto por pagamento
Qualquer pessoa com uma chave API com acesso a uma carteira pode assinar um pagamento de qualquer valor a partir dessa carteira ou de seus endereços. A Blockradar não limita o que um agente assina. Reduza o estrago que um agente com mau comportamento ou uma chave vazada pode causar dando ao agente um endereço dedicado que guarde apenas o que ele tem permissão para gastar.

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.

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "name": "Research agent budget",
    "disableAutoSweep": true,
    "metadata": {
      "purpose": "agent-payments"
    }
  }'

const response = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/addresses`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      name: 'Research agent budget',
      disableAutoSweep: true,
      metadata: { purpose: 'agent-payments' }
    })
  }
).then(r => r.json());

console.log('Agent address:', response.data.address);
console.log('Address ID:', response.data.id);

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.

Pagar a partir da carteira principal também funciona. Use os endpoints da carteira principal nos exemplos abaixo e omita o 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 HTTP 402 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.

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.

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.

O agente repete a requisição com a assinatura

O agente repete a requisição com o pagamento assinado no header PAYMENT-SIGNATURE.

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.

A carteira do agente precisa de USDC, mas não de gas. A assinatura autoriza uma única transferência de um valor exato para um endereço exato, e o facilitador não pode alterar nenhum dos dois.

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.

npm install @x402/fetch @x402/evm

JavaScript

import { wrapFetchWithPaymentFromConfig, decodePaymentResponseHeader } from '@x402/fetch';
import { ExactEvmScheme } from '@x402/evm';

// An x402 signer whose key stays in Blockradar. Pass addressId to pay from a child address.
function blockradarSigner({ apiKey, walletId, addressId, address }) {
  const path = addressId
    ? `/wallets/${walletId}/addresses/${addressId}/signing/typed-data`
    : `/wallets/${walletId}/signing/typed-data`;

  return {
    address,
    async signTypedData({ domain, types, message }) {
      // Blockradar derives the domain type from `domain`, so EIP712Domain must not be in `types`
      const { EIP712Domain, ...signTypes } = types;

      const res = await fetch(`https://api.blockradar.co/v1${path}`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey },
        // x402 passes uint256 values as BigInt, which JSON.stringify cannot serialize
        body: JSON.stringify({ domain, types: signTypes, message }, (_, v) =>
          typeof v === 'bigint' ? v.toString() : v
        ),
      });
      const body = await res.json();
      if (!res.ok) {
        throw new Error(`Blockradar signing failed: ${JSON.stringify(body.message)}`);
      }
      if (body.data.senderAddress.toLowerCase() !== address.toLowerCase()) {
        throw new Error(`Signed by ${body.data.senderAddress}, expected ${address}`);
      }
      return body.data.signedTransaction.signature;
    },
  };
}

const signer = blockradarSigner({
  apiKey: process.env.BLOCKRADAR_API_KEY,
  walletId: process.env.BLOCKRADAR_WALLET_ID,
  addressId: process.env.BLOCKRADAR_ADDRESS_ID, // omit to pay from the master wallet
  address: process.env.AGENT_ADDRESS,           // the address that holds the USDC
});

const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: 'eip155:8453', client: new ExactEvmScheme(signer) }], // Base mainnet
});

const response = await fetchWithPayment('https://api.example.com/premium-data');
console.log(await response.json());

const settlement = response.headers.get('PAYMENT-RESPONSE');
if (settlement) {
  console.log(decodePaymentResponseHeader(settlement)); // { success, transaction, network, payer }
}

Registre um scheme por rede em que o agente paga (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 resposta 402 traz um header PAYMENT-REQUIRED codificado em base64. Decodificado, ele fica assim:

{
  "x402Version": 2,
  "error": "PAYMENT-SIGNATURE header is required",
  "resource": {
    "url": "https://api.example.com/premium-data",
    "description": "Access to premium market data",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "10000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
      "maxTimeoutSeconds": 60,
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }
  ]
}

Escolha uma entrada em accepts que sua carteira possa pagar:

scheme é exact.
network é a chain da carteira. eip155:8453 é a Base mainnet.
extra.assetTransferMethod está ausente ou é eip3009. O método permit2 exige 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 o TransferWithAuthorization a partir dos requisitos e assine-o a partir do endereço do agente:

Campo	Valor
`domain.name`, `domain.version`	`extra.name` e `extra.version`
`domain.chainId`	O número após `eip155:` em `network`, como um número JSON
`domain.verifyingContract`	`asset`, o contrato do USDC
`message.from`	O endereço do agente
`message.to`	`payTo`
`message.value`	`amount`
`message.validAfter`	Um horário Unix um pouco no passado, como agora menos 600 segundos
`message.validBefore`	Agora mais `maxTimeoutSeconds`
`message.nonce`	32 bytes aleatórios em hex. Gere um novo para cada pagamento

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/signing/typed-data \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "domain": {
      "name": "USD Coin",
      "version": "2",
      "chainId": 8453,
      "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
    },
    "types": {
      "TransferWithAuthorization": [
        { "name": "from", "type": "address" },
        { "name": "to", "type": "address" },
        { "name": "value", "type": "uint256" },
        { "name": "validAfter", "type": "uint256" },
        { "name": "validBefore", "type": "uint256" },
        { "name": "nonce", "type": "bytes32" }
      ]
    },
    "message": {
      "from": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a",
      "to": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
      "value": "10000",
      "validAfter": "1791106604",
      "validBefore": "1791107264",
      "nonce": "0x312a453ed3d129ba71de863aa623245c0e5e120bad410d995cea6739aa8ee98b"
    }
  }'

import { randomBytes } from 'node:crypto';

const now = Math.floor(Date.now() / 1000);
const authorization = {
  from: agentAddress,
  to: accepted.payTo,
  value: accepted.amount,
  validAfter: String(now - 600),
  validBefore: String(now + accepted.maxTimeoutSeconds),
  nonce: '0x' + randomBytes(32).toString('hex'),
};

const res = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/addresses/${addressId}/signing/typed-data`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey },
    body: JSON.stringify({
      domain: {
        name: accepted.extra.name,
        version: accepted.extra.version,
        chainId: Number(accepted.network.split(':')[1]),
        verifyingContract: accepted.asset,
      },
      types: {
        TransferWithAuthorization: [
          { name: 'from', type: 'address' },
          { name: 'to', type: 'address' },
          { name: 'value', type: 'uint256' },
          { name: 'validAfter', type: 'uint256' },
          { name: 'validBefore', type: 'uint256' },
          { name: 'nonce', type: 'bytes32' },
        ],
      },
      message: authorization,
    }),
  }
);
const signed = await res.json();
if (!res.ok) throw new Error(`Signing failed: ${JSON.stringify(signed.message)}`);

const signature = signed.data.signedTransaction.signature;

Para assinar a partir da carteira principal, use 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 header PAYMENT-SIGNATURE na mesma requisição:

JavaScript

const paymentPayload = {
  x402Version: 2,
  resource: paymentRequired.resource,
  accepted,                              // the entry you chose from `accepts`
  payload: { signature, authorization },
};

const paid = await fetch('https://api.example.com/premium-data', {
  headers: {
    'PAYMENT-SIGNATURE': Buffer.from(JSON.stringify(paymentPayload)).toString('base64'),
  },
});

Passo 4: Verificar a liquidação

Uma resposta bem-sucedida inclui um header PAYMENT-RESPONSE codificado em base64:

{
  "success": true,
  "transaction": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "network": "eip155:8453",
  "payer": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a"
}

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

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 de eip155:<chainId>. A Base tem chain ID 8453; a Base Sepolia, 84532.
O campo de valor é maxAmountRequired, não amount.
O pagamento vai no header X-PAYMENT como JSON codificado em base64 com x402Version: 1, scheme, network e o mesmo objeto payload, e a liquidação volta em X-PAYMENT-RESPONSE.

O passo de assinatura com a Blockradar é idêntico.

Regras de assinatura que costumam quebrar integrações

Regra	O que acontece caso contrário
`domain.chainId` é um número JSON que corresponde à chain da carteira	`400 Chain ID mismatch`. `"8453"` como string também falha.
`types` contém apenas `TransferWithAuthorization`	Incluir `EIP712Domain` em `types` falha com um erro `ambiguous primary types or unused types`. A Blockradar monta o tipo do domínio a partir de `domain`.
`message.from` é o endereço que assina	O facilitador rejeita o pagamento porque a assinatura recupera um endereço diferente.
Um `nonce` novo para cada pagamento	O USDC rejeita um nonce reutilizado, então o pagamento não pode ser liquidado.
O endereço pagador tem USDC suficiente	O facilitador rejeita o pagamento com um motivo de saldo insuficiente. Gas não é necessário.

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.

Limitações do x402

Apenas EVM. Os pagamentos são assinados com dados tipados EIP-712, que a Blockradar suporta apenas em chains EVM. Solana e outras redes x402 não EVM não são suportadas.
Apenas pagamentos exact EIP-3009. Tokens com transferWithAuthorization, como o USDC, funcionam. O método de transferência permit2 e outros schemes não são abordados.
Sem nanopagamentos do Circle Gateway. A opção de pagamentos em lote abaixo de um centavo da Circle não foi testada com carteiras Blockradar.

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 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 amount com 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.
Use metadata e webhooks. Marque os endereços dos agentes com metadata e concilie os webhooks signed.success com a transação on-chain de cada PAYMENT-RESPONSE.
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.

Referência API

Endpoint	Descrição
Sign Typed Data (Master Wallet)	Assinar uma autorização de pagamento a partir de uma carteira principal
Sign Typed Data (Child Address)	Assinar uma autorização de pagamento a partir de um endereço filho
Generate Address	Criar um endereço dedicado para o orçamento de um agente
Update Address	Ativar ou desativar a varredura automática de um endereço

Começar

Carteiras

Receber Pagamentos

Enviar Pagamentos

Converter e Gerenciar

Conformidade e Recuperação

Integrações

Realizar Pagamentos com Agentes

Protocolos Suportados

Pré-requisitos

Dê ao Agente um Orçamento Próprio

Como o x402 Funciona

Pagar com x402

Opção 1: Usar o SDK cliente do x402

Opção 2: Montar o pagamento você mesmo

Passo 1: Ler os requisitos de pagamento

Passo 2: Assinar a autorização

Passo 3: Repetir a requisição com o pagamento

Passo 4: Verificar a liquidação

Regras de assinatura que costumam quebrar integrações

Limitações do x402

Melhores Práticas

Referência API

​Protocolos Suportados

​Pré-requisitos

​Dê ao Agente um Orçamento Próprio

​Como o x402 Funciona

​Pagar com x402

​Opção 1: Usar o SDK cliente do x402

​Opção 2: Montar o pagamento você mesmo

​Passo 1: Ler os requisitos de pagamento

​Passo 2: Assinar a autorização

​Passo 3: Repetir a requisição com o pagamento

​Passo 4: Verificar a liquidação

​Regras de assinatura que costumam quebrar integrações

​Limitações do x402

​Melhores Práticas

​Referência API

Protocolos Suportados

Pré-requisitos

Dê ao Agente um Orçamento Próprio

Como o x402 Funciona

Pagar com x402

Opção 1: Usar o SDK cliente do x402

Opção 2: Montar o pagamento você mesmo

Passo 1: Ler os requisitos de pagamento

Passo 2: Assinar a autorização

Passo 3: Repetir a requisição com o pagamento

Passo 4: Verificar a liquidação

Regras de assinatura que costumam quebrar integrações

Limitações do x402

Melhores Práticas

Referência API