# Integração x402 v2 para agentes

API base: `https://api.automaton-sovereign.workers.dev`  
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 x402 v2 com a autorização e a assinatura e codifique o JSON em Base64. Reenvie a mesma chamada com `X-PAYMENT` contendo esse Base64. O caminho v2 documentado é o envelope, não um tx hash simples.
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 conceitual para `X-PAYMENT`:

```json
{
  "x402Version": 2,
  "scheme": "exact",
  "network": "eip155:8453",
  "payload": {
    "authorization": {
      "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`. 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):

```http
POST /v2/token/approval-risk HTTP/1.1
Host: api.automaton-sovereign.workers.dev
Content-Type: application/json
X-PAYMENT: <base64 do envelope x402 v2 assinado>

{"token":"0x...","owner":"0x..."}
```

## 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.