O que é x402.
x402 é um protocolo aberto para pagamentos nativos de HTTP, publicado pela Coinbase no final de 2024. Ele define como um servidor retorna 402 Payment Required com um corpo JSON estruturado - uma lista de requisitos de pagamento aceitáveis (esquema, rede, id da cadeia, endereço do destinatário, valor em unidades base de USDC e um id de solicitação de pagamento) - para que um cliente de máquina possa analisar a resposta, pagar na cadeia e tentar novamente a chamada original com um cabeçalho X-Payment, tudo programaticamente.
HTTP 402 ficou sem uso por trinta anos. x402 fez funcionar.
The 402 Payment Required status code was reserved in the original HTTP spec for "future use" and never received a standardized implementation. For three decades, every actual payment flow on the web was built on top of 200 / 401 / 403: a server returns 401 when authentication is missing, the client signs up via a separate UI flow, gets credentials, and re-authenticates. The signup happens out of band. None of this works for AI agents, which cannot complete signup forms.
x402 fixes this by giving 402 a usable specification. A server can return 402 with structured machine-readable payment instructions; a client can parse those instructions, pay, and retry, all without ever touching a signup form. The protocol is the missing piece between "AI agents can call APIs" and "AI agents can pay for the APIs they call". Before x402, the only practical agent payment paths were pre-paid balance accounts (with manual top-up) or proprietary integrations per API. Both broke at scale.
A importância estratégica do x402 é que ele estabelece um padrão contra o qual o resto do ecossistema pode construir. As carteiras implementam um manipulador x402 uma vez, e cada API compatível com x402 funciona com essa carteira. Frameworks de servidor implementam um middleware x402 uma vez, e cada cliente ciente de x402 pode pagá-los. Facilitadores (serviços que liquidam os pagamentos subjacentes) competem pela qualidade do serviço em vez de pelo lock-in.
Uma resposta, uma nova tentativa, um pagamento.
O ciclo de vida tem três estados: chamada não paga, pagamento, chamada refeito. Abaixo está como a resposta da chamada não paga realmente se parece na rede.
HTTP/1.1 402 Payment Required Content-Type: application/json { "resource": "POST /api/research-query", "accepts": [ { "scheme": "exact-usdc", "network": "mainnet", "chainId": "eip155:8453", "payToAddress": "0xAgent...", "amountWeiUsdc": "50000", "paymentRequestId": "pr_01J9...", "maxAgeSeconds": 60 } ] }
- Status code 402. Distinct from 401 (auth missing) and 403 (auth refused). The presence of 402 signals "payment is the missing input."
- resource + accepts[]. O corpo nomeia o recurso protegido e lista um ou mais requisitos de pagamento aceitáveis. Uma migração pode citar dois requisitos (por exemplo, mainnet e testnet) e deixar o cliente escolher.
- scheme / network / chainId. O esquema de pagamento (exact-usdc), a cadeia (mainnet é Base) e seu id CAIP-2. O cliente corresponde a estes antes de pagar.
- payToAddress / amountWeiUsdc. A carteira do destinatário e o valor exato em unidades base de USDC (50000 = 0.05 USDC, 6 casas decimais). O cliente verifica ambos antes de pagar.
- paymentRequestId + maxAgeSeconds. O id vincula o pagamento a esta cotação; maxAgeSeconds é quão recente o pagamento deve ser. Um pagamento que referencia um id diferente, ou é mais antigo do que a janela, é rejeitado.
- A nova tentativa carrega um cabeçalho X-Payment. O cliente paga na blockchain, então re-emite a solicitação original com um cabeçalho X-Payment provando o pagamento. O servidor verifica e retorna o resultado real. Nenhum cabeçalho de resposta ou página hospedada faz parte do próprio fio x402.
x402 na prática.
Três implementações concretas, ordenadas pela maturidade da adoção em cada camada.
Servidor MCP retornando um desafio 402 para uma chamada de ferramenta não paga
Uma ferramenta MCP paga recebe uma invocação do Claude Desktop e o chamador ainda não está marcado como pago. O servidor constrói um desafio requirePayment - um 402 cujo corpo carrega o preço e um hostedUrl - e o retorna como um erro da ferramenta. O Claude Desktop renderiza o link no chat; o usuário paga $0.05 USDC; a próxima chamada para a mesma ferramenta é bem-sucedida.
Cobrança por chamada em endpoints da API
Uma API de pesquisa cobra $0.50 por chamada atrás do adaptador do servidor x402. Um agente de IA chama o endpoint, recebe um 402 listando o valor e o destinatário, paga na Base de sua carteira e re-emite a solicitação com um cabeçalho X-Payment. O adaptador verifica o cabeçalho e retorna a resposta paga. Todo o loop é concluído em menos de 60 segundos.
Agente pagando programaticamente via carteira ciente de x402
O tempo de execução de um agente é ciente do x402 (ele implementa a especificação). Quando atinge um 402, lê o payToAddress e o valor de accepts[], assina uma transferência de sua carteira pré-autorizada (dentro de sua permissão de gastos), transmite no Base e tenta novamente a chamada original com um cabeçalho X-Payment. Sem envolvimento humano; o loop é concluído em 5-10 segundos.
O que cerca x402 na pilha.
x402 é o protocolo. Esses três termos cobrem os conceitos sobre os quais ele se baseia e os casos de uso que ele possibilita.