Pular para o conteúdo
jsonW Paper GitHub

Protocolos de comércio com agentes

x402: o pagamento por chamada, o que o protocolo registra e o que a Wortic não aceita

O x402 cobra cada chamada de API com uma prova de pagamento no cabeçalho. Ele tem um formato próprio de preço e de recibo. A Wortic ainda não aceita esse meio, então nada é gravado em jsonW para ele. Veja os campos do protocolo e o estado atual.

· jsonW 1.3.11

O protocolo

O x402 é um protocolo aberto criado pela Coinbase. Ele usa o código HTTP 402, de pagamento necessário. Quando o cliente pede um recurso pago, o servidor responde com as condições: o valor, a moeda, a rede e o endereço de recebimento.

O cliente paga e repete o pedido com uma prova de pagamento num cabeçalho. Em versões do protocolo, esse cabeçalho aparece com nomes como PAYMENT-SIGNATURE ou X-PAYMENT. O servidor confere a prova e entrega o recurso.

Os campos que importam

Para um registro de cobrança, três campos são essenciais: o valor, a rede e a referência da transação. O valor vem em uma unidade pequena, porque a cobrança é de frações de centavo. A rede diz onde o pagamento foi liquidado. A referência liga a prova ao pedido.

[valor, moeda, rede, endereço de recebimento, referência da transação]

Esses campos são o que um registro precisaria guardar. Hoje a Wortic não guarda nenhum deles, porque não aceita o protocolo.

O que o jsonW guardaria

Se a casa aceitasse x402, o registro de cada chamada paga seria um dado de dinheiro. Ele iria ao registro de pagamentos, e não ao jsonW de descrição. O jsonW serve bem para o histórico de tarefas e de negociações. Para cobrança, é preciso um registro com conferência de valor, e isso ainda não está desenhado.

Por que a Wortic não aceita agora

Aceitar x402 exige um endereço de recebimento numa rede compatível e uma forma de conferir cada prova antes de entregar o dado. Hoje a Wortic não tem esse destino definido. Sem ele, a API entregaria sem receber, ou cobraria sem entregar.

Quando o assunto volta

O protocolo pode entrar no plano da casa quando houver um destino de recebimento e um motivo de negócio. Até lá, as APIs seguem com limite de pedidos por IP. Se a decisão mudar, esta publicação deve ser atualizada.

Como conferir o formato

Para entender o formato, leia a documentação oficial e teste com uma API de demonstração. Não use uma chave de produção para isso. A especificação muda, e a versão da documentação precisa bater com a do seu servidor.

A documentação oficial está em x402.org, e o código, em github.com/coinbase/x402.

Versões e cabeçalhos

O x402 mudou nomes de cabeçalho entre versões. Por isso, o registro deve guardar a versão do protocolo junto com a prova, e não só o valor pago. Sem a versão, uma prova antiga pode ser confundida com uma prova válida de hoje.

Regras de conferência

Antes de guardar um pagamento, o sistema deve conferir três coisas: a rede, o valor e o destino. Se qualquer um deles não bater com a oferta, a prova não entra no registro, e a resposta recusa o recurso.

Site oficial do x402 →