Integração x402 v2 para agentes

API base: https://api.automatonsvrn.xyz

Rede: Base Mainnet (eip155:8453)

Ativo de pagamento: USDC

Destinatário informado pelo operador: 0x71DEAc098914A009E3720524642A6bE6F65EE528

Fluxo de chamada paga

1. Envie a chamada HTTP à rota e método documentados em routes.md. Para POST, envie JSON conforme o schema da rota. Não anexe pagamento antecipadamente.

2. Quando receber HTTP 402 Payment Required, leia o header PAYMENT-REQUIRED. Seu valor é Base64 de um JSON de desafio x402 v2. Decodifique-o para JSON. O corpo 402 também pode conter accepts; trate os termos do desafio como fonte de verdade para aquela requisição.

3. Selecione em accepts o termo de USDC na rede Base e confira o scheme, amount/maxAmountRequired, asset, payTo/recipient, resource.url e network. Não substitua nem infira termos ausentes.

4. Com a carteira pagadora, assine EIP-712 TransferWithAuthorization de USDC usando os campos do desafio/autorização: from, to, value, validAfter, validBefore e nonce. Use domínio USDC (name: "USD Coin", version: "2", chainId: 8453, verifyingContract: contrato USDC da Base indicado no desafio). A assinatura autoriza a transferência; não transmite uma transação pelo agente.

5. Monte o envelope FLAT: os seis campos from, to, value, validAfter, validBefore, nonce planos dentro de payload e a signature no topo do envelope. Codifique o JSON em Base64 e reenvie a mesma chamada com o header X-PAYMENT-AUTH contendo esse Base64. X-PAYMENT pode levar o mesmo envelope junto, por retrocompatibilidade. O caminho documentado é o envelope assinado, não um tx hash simples: o envelope com authorization aninhada dentro de payload é recusado pela origem (missing_from).

6. Confirme a resposta HTTP e os metadados de liquidação retornados. Só considere o serviço concluído se a chamada retornar sucesso; desafios 402, assinatura local ou autorização sem liquidação não provam execução paga.

Exemplo esquemático do desafio (os valores variam por rota; use os valores recebidos, sem copiar placeholders):

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <base64(JSON do desafio x402 v2)>
X-402-Version: 2

Após decodificar, o desafio contém x402Version, resource e accepts[]; cada termo de accepts informa scheme, rede, ativo, valor e destinatário, entre outros campos de pagamento. O header é Base64 do JSON inteiro, não só de accepts.

Envelope FLAT para X-PAYMENT-AUTH (o mesmo Base64 pode ir também em X-PAYMENT):

{
  "x402Version": 2,
  "scheme": "exact",
  "network": "eip155:8453",
  "payload": {
    "from": "<carteira pagadora>",
    "to": "<payTo do desafio>",
    "value": "<amount do desafio>",
    "validAfter": "<timestamp em segundos>",
    "validBefore": "<timestamp em segundos>",
    "nonce": "<bytes32 único>"
  },
  "signature": "<assinatura EIP-712 0x...>"
}

Codifique o JSON do envelope acima em Base64 e envie o resultado como valor do header X-PAYMENT-AUTH. Não envie esse JSON literal como header. A carteira do agente precisa ter USDC suficiente e conseguir assinar EIP-712; ela não precisa de ETH para gas. O operador mediu uma liquidação de US$ 0,002 USDC com carteira pagadora sem ETH: a transação foi enviada pelo relayer do CDP, e o saldo de gas da tesouraria permaneceu inalterado ao wei. Essa evidência não substitui a validação do desafio de cada chamada.

Exemplo HTTP genérico (não executado aqui), no Pre-Flight AI Firewall — POST /v2/firewall/simulate-tx, US$ 0,02 (20000 unidades de USDC) por chamada:

POST /v2/firewall/simulate-tx HTTP/1.1
Host: api.automatonsvrn.xyz
Content-Type: application/json
X-PAYMENT-AUTH: <base64 do envelope FLAT assinado>
X-PAYMENT: <o mesmo base64>

{"targetContract":"0x...","calldata":"0x..."}

Em vez de montar o envelope à mão, o SDK @celorodrigues/agentkit-firewall@1.0.1 responde ao 402, recusa valor acima do teto maxAmountUnits, rede, ativo ou payTo estranhos antes de assinar, e envia os dois headers.

Regras do cliente

Automaton-Sovereign (ERC-8004 #95791 on Base L2) · Durable x402 edge · Zero gas needed by buyers.