# Rotas pagas de análise na Base

API base: `https://api.automaton-sovereign.workers.dev`  
Rede de serviço: Base Mainnet. Todas as chamadas usam o fluxo x402 v2 documentado em `integration-guide.md`.

A tabela abaixo lista **todos os endpoints pagos**, com o preço cobrado por rota, e as seis rotas do briefing
recebem detalhamento próprio nas seções seguintes. O mesmo conteúdo existe em forma de máquina em
`/.well-known/x402` (gerado do `PRICING` que o servidor efetivamente cobra) e `/.well-known/x402-bazaar.json`; um
teste de paridade (`services/test/catalog-parity.test.js`) exige que as três superfícies citem as mesmas rotas com
os mesmos preços.

O briefing diz que são cinco rotas, mas lista seis paths. Para não omitir nenhum path informado, esta página
detalha os seis; `sentinel/latest` e `sentinel/stream` estão agrupados no mesmo produto Sentinel.

| Produto / path | Método | Preço por chamada | Entrada | Saída principal |
|---|---:|---:|---|---|
| `/v2/security/scan` | GET | US$ 0,001 | Query `address` (endereço do contrato/token) | `address`, `network`, `chainId`, `isContract`, `isHoneypot`, `riskScore`, `verdict`, `summary`, flags/checks, timestamp e envelope de verificação/assinatura. |
| `/v2/sentinel/latest` | GET | US$ 0,001 | Query opcional: `limit` (1–500, padrão 50), `maxRisk`/`minRisk` (0–100), `dex`, `since` (data ISO) | `ok`, `updatedAt`, `lastBlock`, `count`, `pools`. |
| `/v2/sentinel/stream` | GET | US$ 0,01 | Sem parâmetros de entrada | SSE; evento `hello` com `expiresAt` e `lastBlock`, eventos `pool` com dados da pool e evento `expired` ao fim da janela de 15 minutos. |
| `/v2/token/approval-risk` | POST | US$ 0,01 | JSON `{token, owner, spenders?}`; endereços EVM; `spenders` opcional, até 20 endereços | `ok`, rede/chain, token/owner, saldo/metadados, `approvals[]`, `overallRisk`, `coverage`, `readOnly`, timestamp. Cada approval inclui allowance, estado ilimitado, tipo/verificação do spender, valor potencialmente drenável e risco/razão. |
| `/v2/token/simulate` | POST | US$ 0,01 | JSON `{token, wallet, side, amount}`; `side` é `buy` ou `sell`; `amount` é decimal string, ETH para compra ou unidades de token para venda | `ok`, token/metadata, `wallet`, `side`, rota, objeto `buy` ou `sell`, `verdict`, `limitations`, `readOnly`, timestamp. |
| `/v2/token/liquidity-risk` | POST | US$ 0,01 | JSON `{token, pair?}`; `pair` é endereço opcional para filtrar a pool | `ok`, token/metadata, bloco, `ethUsd`, `pools`, `summary`, `coverage`, `readOnly`, timestamp. `summary` inclui pools encontradas/analisadas, estimativa USD para mover preço 2% (compra/venda) e veredito. |
| `/v1/hash` | GET | US$ 0,001 | Query `input` (string) | `sha256` hex do texto. |
| `/v1/echo` | GET | US$ 0,001 | Query `msg` (string) | `msg` de volta com o timestamp do servidor. |
| `/v1/uuid` | GET | US$ 0,001 | Sem parâmetros | Um UUID v4. |
| `/v1/random` | GET | US$ 0,001 | Query `min`, `max` (inteiros) | Um inteiro uniforme no intervalo. |
| `/v2/attest` | GET/POST | US$ 0,05 | Query/JSON `data` (string) | Entrada assinada no registro encadeado por hash (`seq`, hash, assinatura) — prova de existência, não de veracidade. |
| `/v2/batch` | POST | US$ 0,05 | JSON `{items}` com até 1000 itens | **Um** root de Merkle assinado comprometendo todos os itens. |
| `/v2/oracle/base` | GET | US$ 0,001 | Sem parâmetros | Leitura de gas/preço da Base assinada em ECDSA P-256. |
| `/v2/merkle/prove` | POST | US$ 0,001 | JSON `{items, target}` | Prova de inclusão de um item, com o root assinado. |
| `/v2/sentiment` | GET | US$ 0,001 | Query `asset` (ex.: `ETH`, `AERO`) | Índice composto de risco, liquidez e sentimento para um ativo, com veredito assinado. |
| `/v2/simulate` | GET/POST | US$ 0,001 | Query/JSON `to` (obrigatório), `data`, `value`, `from` | Dry-run na Base Mainnet: `willRevert`, razão do revert decodificada, `estimatedGas`, `returnData`. |

## Quando chamar e o que não cobre

### `/v2/security/scan`

Use para triagem de bytecode de um contrato/token Base. **Não cobre:** auditoria formal, prova de ausência de exploit, estado de todas as dependências externas nem comportamento futuro do contrato. Um score/veredito não é garantia de segurança.

### Sentinel — `/v2/sentinel/latest` e `/v2/sentinel/stream`

Use `latest` para consultar o conjunto recente com filtros; use `stream` para receber eventos SSE novos durante a janela paga. A saída depende da coleta Sentinel disponível no momento. **Não cobre:** todos os DEXes, todos os pools da Base ou eventos fora da fonte e da janela de coleta; stream expira após 15 minutos. Verifique a atualidade/cobertura da resposta.

### `/v2/token/approval-risk`

Use para revisar permissões ERC-20 entre token, owner e spenders. **Não cobre:** histórico ilimitado de approvals; logs anteriores à janela são encontrados apenas para spenders conhecidos ou fornecidos em `spenders`. `coverage.logWindow.gaps` registra lacunas. Não revoga allowance.

### `/v2/token/simulate`

Use antes de considerar uma compra/venda simulada. A leitura simula swaps via pool Uniswap V2/WETH com `eth_call`. Compra aceita até 10 ETH como valor de simulação; venda depende do saldo e allowance reais da carteira consultada. **Não cobre:** Uniswap V3/V4, Aerodrome ou outras rotas; não envia transação; é um snapshot e o comportamento do token pode mudar depois.

### `/v2/token/liquidity-risk`

Use para estimar profundidade/impacto nas pools analisadas. O snapshot é fixado em um bloco e informa lacunas. **Não cobre:** Uniswap V4, Uniswap V2, pares com ativos de cotação fora WETH/USDC; lock de posições concentradas NFT não é enumerável por esta análise. Estimativas de pool não garantem execução nem preço realizável.

## Demais rotas: o que não cobrem

- **`/v1/hash`, `/v1/echo`, `/v1/uuid`, `/v1/random`** — utilitários sem estado: o resultado é calculado por chamada e nada é guardado. Não são fonte de aleatoriedade criptográfica para chaves e não substituem um gerador auditado.
- **`/v2/attest`** — grava uma entrada assinada no registro encadeado por hash. Atesta que um dado existia naquele momento; **não** atesta que o conteúdo é verdadeiro, nem que o autor é quem diz ser. Leitura do registro é gratuita em `/v2/ledger`.
- **`/v2/batch`** — compromete até 1000 itens sob um root. O servidor guarda o root, não a sua lista: **guarde os itens**, porque a prova de inclusão (`/v2/merkle/prove`) é gerada a partir da lista que o chamador fornecer.
- **`/v2/oracle/base`** — leitura de gas/preço da Base em um bloco, assinada. É snapshot, não feed contínuo nem garantia de preço futuro.
- **`/v2/simulate`** — dry-run de calldata arbitrária. Diz se a chamada reverte e quanto gas consumiria; **não** conhece intenção, não envia transação e não garante o resultado de uma execução posterior. O mesmo trabalho existe **grátis** na ferramenta MCP local `simulate_base_transaction` (ver a seção seguinte).
- **`/v2/sentiment`** — índice composto de uma leitura por ativo, com veredito assinado. Não é recomendação de investimento e não garante desempenho; a cobertura depende dos dados disponíveis no momento da chamada.

## Três coisas chamadas "simular", e qual usar

Existem três operações distintas sob o mesmo nome. Confundi-las custa dinheiro ou tempo:

| O quê | Onde | Preço | O que faz |
|---|---|---:|---|
| `simulate_base_transaction` | ferramenta MCP (`local`) | **grátis** | `eth_call` + `eth_estimateGas` na Base com calldata arbitrária que **você** fornece (`{to, data, value, from}`). Não conhece pool, token nem intenção: diz se a chamada reverte, o gas que consumiria e a razão do revert (decodifica `Error(string)`). É a ferramenta para "minha transação passa?". |
| `/v2/simulate` | HTTP nesta API | US$ 0,001 | **O mesmo trabalho** do anterior (V2 do enunciado: `to` obrigatório, `data`/`value`/`from` opcionais), servido no servidor em vez de localmente. |
| `/v2/token/simulate` | HTTP nesta API | US$ 0,01 | Simula **compra ou venda** de um token contra a pool Uniswap V2/WETH (`{token, wallet, side, amount}`): taxas, impacto na pool, veredito de honeypot e limitações. É a ferramenta para "vale a pena comprar/vender este token?". |

As três são **somente leitura e nenhuma envia transação**. A divisão de preço é deliberada: o dry-run de calldata é barato de servir (uma chamada de RPC, sem interpretação) e por isso existe de graça na ferramenta MCP local; a simulação de compra/venda é um produto analítico com custo de RPC e de interpretação, e por isso é cobrada.

Uma inconsistência permanece declarada, não escondida: a ferramenta MCP gratuita e o `/v2/simulate` pago fazem **o mesmo trabalho**, então o mesmo produto tem dois preços dependendo de onde roda. A escolha documentada acima é manter a distinção e a ferramenta local gratuita; cobrar por ela no HTTP continua sendo uma decisão do operador.

## Limites das afirmações comerciais

Os preços por rota vêm da tabela `ROUTE_PRICES` do servidor (a mesma que o paywall aplica) e são verificados contra o catálogo público por teste. O status de validação 26/26 foi informado pelo operador para as rotas deste kit; o briefing declara cinco rotas, mas enumera seis paths. Não há compra de serviço confirmada nem número de clientes/usuários a declarar. A validação 26/26 não significa que cada agente encontrou, pagou ou usou as rotas. Os rascunhos e exemplos não foram publicados nem executados como compra.