x402: como uma IA paga uma API sem ter conta

Toda API da internet é vendida através de um formulário.

Você chega numa página de preços, digita um e-mail, confirma na caixa de entrada, cola um cartão, copia uma chave e guarda numa variável de ambiente. São quatro minutos e funciona muito bem — porque você é humano, e humanos têm caixa de entrada, cartão e paciência.

Agora imagine um agente de IA no meio de um ciclo de pesquisa. Ele precisa de uma página web convertida em Markdown, agora, para terminar a tarefa que recebeu. Não pode receber e-mail de confirmação. Não tem cartão. Não pode esperar um humano acordar e colar uma chave.

Então ele faz a única coisa que resta: desiste e usa outra coisa.

É exatamente essa lacuna que o x402 fecha — e a partir de hoje a API do Minibase responde a ela em produção.

O HTTP já tinha um plano para isso em 1997

O código de status 402 Payment Required está na especificação HTTP desde o início, marcado como “reservado para uso futuro”. Por quase trinta anos foi a piada da RFC: o código que ninguém conseguia implementar, porque a web não tinha como mover pequenas quantias dentro de uma requisição.

x402 é o protocolo que finalmente o usa. O formato cabe em três passos:

1. Um cliente chama seu endpoint sem nenhuma credencial.
2. Em vez de um 401 Unauthorized, o servidor responde 402 Payment Required e anexa condições de pagamento legíveis por máquina: quanto, em qual ativo, em qual rede, para qual endereço.
3. O cliente paga e repete a requisição com a prova de pagamento anexada. O servidor verifica, liquida e serve a resposta.

Sem conta. Sem chave. Sem painel. Toda a negociação acontece em duas idas e voltas HTTP, num formato que outro programa sabe ler.

Como isso aparece num endpoint real

Chame nosso endpoint de conversão sem nada:

curl -i -X POST https://api.minibase.md/v1/convert \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/article"}'

Você recebe um 402, e as condições voltam codificadas em base64 num cabeçalho payment-required:

{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "10000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0xfb8157a583e3050440301f418f5e890190222a5c",
    "maxTimeoutSeconds": 300
  }]
}

Tudo o que um cliente autônomo precisa está ali. network é um identificador CAIP-2 — eip155:8453 é a Base mainnet. asset é o contrato do USDC. amount vem em unidades atômicas: USDC tem seis casas decimais, então 10000 é um centavo. payTo é para onde o dinheiro vai.

O cliente assina uma transferência de USDC, repete a requisição com o pagamento anexado e recebe seu Markdown. Envolvimento humano: zero.

A parte que ninguém menciona: você não precisa guardar cripto

A objeção óbvia a qualquer discurso de “aceite stablecoins” é que agora você opera uma carteira. Chaves privadas. Custódia. Um saldo denominado em algo que seu contador nunca viu, avaliado a uma cotação que se mexeu enquanto você dormia.

Nós não fazemos nada disso, e você também não precisa. O endereço de depósito do payload acima foi emitido pela Stripe. Os pagamentos são liquidados on-chain para esse endereço, a Stripe registra cada um como um PaymentIntent comum e paga em euros no calendário normal.

Na prática, o dinheiro aparece no mesmo painel de qualquer pagamento com cartão, no mesmo repasse, nos mesmos livros. Não há carteira para proteger, nem valoração cambial recibo a recibo, nem livro paralelo para conciliar no fechamento. A parte stablecoin é real e, ao mesmo tempo, completamente invisível do lado contábil.

Duas coisas que nos custaram tempo

Se você for implementar por conta própria, estas são as duas armadilhas que pagamos.

O handshake com o facilitador não é opcional. Um resource server precisa perguntar ao facilitador quais pares de esquema e rede ele realmente liquida antes de conseguir cotar qualquer coisa. Pule esse passo e absolutamente toda chamada morre com Facilitator does not support exact on eip155:8453 — uma mensagem que parece erro de configuração e é, na verdade, uma ida e volta faltando. Na mainnet, esse facilitador é o da Coinbase; o público de testnet não liquida dinheiro de verdade.

Preço abaixo de um centavo quebra sua contabilidade em silêncio. Nosso custo gira em torno de US$ 0,002 por página, então cobrar US$ 0,002 na porta x402 parecia óbvio. Não é: PaymentIntents são denominados em centavos inteiros, então qualquer valor abaixo de um centavo é liquidado on-chain e depois não pode ser registrado de jeito nenhum. O dinheiro chega e não entra em livro nenhum. Por isso a porta sem chave custa US$ 0,01 por chamada — cinco vezes nossa tarifa por volume, o que um pagamento por chamada sem conta e sem compromisso sustenta com folga.

Vale a pena adicionar?

Sejamos honestos quanto ao tamanho: x402 não vai substituir sua receita de assinaturas neste trimestre. Pagamentos iniciados por agentes são recentes, o ferramental do lado cliente é jovem, e a maioria dos seus clientes continua sendo humana e com cartão.

Mas a assimetria é incomum. Montar a porta nos custou algumas centenas de linhas e ela só dispara para quem não apresenta credencial nenhuma — qualquer detentor de chave cai direto no caminho que já tinha, com a mesma cota e o mesmo plano. Nada do que você já vende fica em risco.

E o modo de falha de não ter isso é invisível. Um chamador sem chave que bate num 401 não deixa rastro: nenhum cadastro, nenhum ticket de suporte, nem uma linha nas suas métricas. Você nunca fica sabendo que ele esteve ali. Agora medimos isso especificamente — toda chamada sem credencial é registrada, junto com a informação de se o chamador já fala o protocolo — porque “tem alguém batendo na porta?” é a única pergunta que decide se algo disso valeu a pena.

Se os agentes vão comprar coisas na web aberta, eles precisam de um jeito de pagar que não passe por um formulário de cadastro. Esse jeito já existe, está na especificação HTTP desde 1997, e se conecta numa tarde.

---

Teste: chame POST https://api.minibase.md/v1/convert sem credenciais e leia o cabeçalho payment-required. Prefere uma chave? O plano gratuito dá 1.000 páginas por mês, sem cartão. Especificação completa para agentes: minibase.md/api.md.