# 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
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`):

```json
{
  "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:

```http
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

- Leia preço, ativo, rede e destinatário de cada 402; preços de referência constam em `routes.md` e no desafio recebido.
- Nunca reutilize `nonce`; preserve `validAfter` e `validBefore` recebidos/gerados para a autorização.
- O agente deve pedir aprovação local de orçamento antes de assinar; este guia não habilita gasto nem realiza chamadas.
- Um erro de rota, timeout, `402`, `4xx` ou falha de liquidação não deve ser descrito como chamada paga bem-sucedida.
- As análises são informativas e somente leitura. Não constituem garantia de segurança, recomendação de investimento nem execução de swap.