Painel
PT
Comece grátis

Como um agente de IA paga cada busca na web com x402

Sem conta e sem chave de API: o desafio 402 real que o FastAF devolve, o cliente Node que paga em USDC na Base e como limitar o que o agente gasta por chamada.

Um agente que precisa de uma única busca no Google não deveria precisar de formulário de cadastro, de uma chave de API guardada num gerenciador de segredos e de um saldo pré-pago. Com x402 ele envia a requisição, recebe um preço de volta, paga com a própria wallet e recebe os dados. Aqui está o ciclo completo contra o FastAF, com o desafio real e o código real do cliente.

O que é x402?

O x402 ressuscita o status HTTP 402 Payment Required, que ficou sem uso na especificação por décadas. O servidor responde a uma requisição não paga com 402 e um preço legível por máquina; o cliente paga e repete a mesma requisição. Na versão 2 do protocolo isso trafega em três headers, cada um com JSON codificado em base64: PAYMENT-REQUIRED (do servidor para o cliente, o preço), PAYMENT-SIGNATURE (do cliente para o servidor, o pagamento assinado) e PAYMENT-RESPONSE (do servidor para o cliente, o resultado da liquidação), como descrito em docs.x402.org, verificado em 19 de outubro de 2026.

O pagamento em si é uma transferência de stablecoin, na prática USDC na Base. O cliente assina uma autorização; um facilitator confere essa autorização com os requisitos do servidor e a envia on-chain. A documentação do facilitator é explícita ao dizer que ele “does not hold funds or act as a custodian”, ou seja, não guarda fundos nem atua como custodiante. O protocolo foi incubado na Coinbase e doado à x402 Foundation, sob a Linux Foundation, num anúncio de 2 de abril de 2026, e tem licença Apache-2.0.

Como é o desafio 402?

Todo endpoint do FastAF está disponível em https://api.fastaf.co/x402/v1/{endpoint}, com os mesmos parâmetros da API com chave. A primeira requisição não custa nada:

curl -i "https://api.fastaf.co/x402/v1/serp?query=x402+payment+protocol"

Em 19 de outubro de 2026 isso voltou como HTTP/2 402 em 0,24 segundo. Decodificando o header payment-required você obtém (resumido):

{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "5000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x05B75e13f071A09A26B50a18Ce5BD02a0755d76F",
    "maxTimeoutSeconds": 300,
    "extra": { "name": "USD Coin", "version": "2" }
  }]
}

Campo por campo:

  • scheme: "exact": pague exatamente esse valor, nem um centavo a mais.
  • network: "eip155:8453": Base mainnet, em notação CAIP-2.
  • amount: "5000": unidades atômicas. O USDC tem 6 casas decimais, então 5000 é US$ 0,005, o preço de uma busca.
  • asset: o contrato do USDC na Base. A própria tabela de ativos padrão do SDK lista o mesmo endereço como USDC.
  • payTo: o endereço que recebe o pagamento.
  • maxTimeoutSeconds: 300: a autorização assinada vale por cinco minutos.
  • extra.name e extra.version: o domínio EIP-712 do token, de que o cliente precisa para assinar uma autorização de transferência válida.

Um detalhe que vale conhecer: os parâmetros são validados antes de qualquer preço ser cotado. A mesma URL sem q devolveu 400 invalid_parameters, não um 402, então um agente nunca é cobrado por uma requisição malformada.

Como o agente paga em Node?

Os pacotes oficiais cuidam do parsing, da assinatura e do retry. As versões abaixo são as atuais no npm (@x402/fetch 2.28.0, com @x402/core e @x402/evm na mesma versão):

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const client = new x402Client();
registerExactEvmScheme(client, {
  signer: privateKeyToAccount(process.env.AGENT_WALLET_KEY),
  networks: ["eip155:8453"],
});

// Recusa qualquer pagamento individual acima de um centavo.
client.setSpendControls({ maxAmountPerPayment: "$0.01" });

// Para de pagar quando esta execução tiver gastado $0.05 (unidades atômicas de USDC).
let spent = 0n;
client.onBeforePaymentCreation(async ({ selectedRequirements }) => {
  const amount = BigInt(selectedRequirements.amount);
  if (spent + amount > 50_000n) return { abort: true, reason: "run budget exhausted" };
  spent += amount;
});

const fetchWithPayment = wrapFetchWithPayment(fetch, client);
const res = await fetchWithPayment("https://api.fastaf.co/x402/v1/serp?query=x402+payment+protocol");
console.log(res.status, res.headers.get("X-FastAF-Credits-Used"));

Sem setSpendControls, o @x402/core já limita cada pagamento a DEFAULT_MAX_AMOUNT_PER_PAYMENT, que é "$1" no código-fonte instalado. Para uma API de busca isso é generoso demais; ajuste para o custo da sua chamada mais cara.

Rodamos esse script em 19 de outubro de 2026 com uma wallet recém-gerada, sem USDC nenhum, então nenhuma chamada paga foi concluída: a resposta 200 com o recibo em PAYMENT-RESPONSE é o que o SDK faz com uma wallet que tem saldo. O que de fato aconteceu: com o limite em $0.002, o SDK recusou localmente em 91 ms, antes de assinar qualquer coisa (“rejected by spendControls.maxAmountPerPayment”). Com o limite em $0.01, ele fez o parsing do 402, assinou, repetiu a requisição, e o servidor respondeu 402 de novo com invalid_exact_evm_insufficient_balance. Nenhuma busca rodou e nada foi liquidado.

Por que “liquidado só em caso de sucesso” importa para agentes?

Agentes erram muitas chamadas: uma consulta ruim, uma página que estoura o timeout, um alvo que não é permitido. No FastAF o pagamento assinado só é liquidado depois que a requisição upstream dá certo. Se a chamada falha, a autorização nunca é enviada e expira depois de maxTimeoutSeconds, então a wallet fica com o dinheiro. A API com chave segue a mesma regra: requisições que falham nunca são cobradas.

Os preços são o custo em créditos da API com chave a US$ 0,001 por crédito. Estes valores foram lidos de desafios reais em 19 de outubro de 2026:

Requisição Créditos Valor x402 Preço
/scrape, página estática 1 1000 US$ 0,001
/serp, busca no Google 5 5000 US$ 0,005
/shopping 10 10000 US$ 0,01
/linkedin, perfil 60 60000 US$ 0,06

Quando os créditos pré-pagos são a melhor escolha?

O x402 é o encaixe certo para um agente que faz chamadas ocasionais, roda num lugar onde você não consegue provisionar uma chave, ou deve pagar com o próprio orçamento. Os créditos pré-pagos ganham em três casos:

  • Volume. Um pacote Starter de US$ 10 tem 20.000 créditos, então 1.000 buscas custam US$ 2,50 em vez de US$ 5,00 via x402, e US$ 1,50 no pacote Pro. Os créditos valem por 12 meses, sem assinatura.
  • MCP. O servidor MCP hospedado em https://api.fastaf.co/mcp autentica com uma chave Bearer; ele não aceita pagamentos x402.
  • Um teto rígido na conta. Um saldo esgotado devolve 402 insufficient_credits e para, decida o agente o que decidir. O post sobre teto de gastos mostra como combinar isso com um orçamento por execução.

Como manter a wallet do agente segura?

A chave privada fica no ambiente do agente e assina sem perguntar a ninguém, então trate essa wallet como uma hot wallet:

  • Use uma wallet dedicada por agente, nunca uma que guarde qualquer outra coisa.
  • Coloque pouco dinheiro nela e recarregue de forma deliberada; o saldo é o seu pior cenário.
  • Defina maxAmountPerPayment com o preço da sua chamada mais cara, mais um orçamento por execução no hook.
  • Fixe networks em eip155:8453 para que o cliente nunca pague numa chain que você não planejou.

Resumindo

O x402 transforma uma resposta 402 numa etiqueta de preço: decodifique PAYMENT-REQUIRED, assine a autorização em USDC, repita a requisição com PAYMENT-SIGNATURE. No FastAF uma busca custa US$ 0,005, liquidada só se der certo, e os controles de gasto do SDK limitam cada pagamento antes de qualquer assinatura. O fluxo completo está na seção x402 e todos os preços estão em preços. Para volume ou MCP, crie uma conta grátis e comece com 500 créditos, sem cartão.