Fresh402

npx add-mcp 'https://fresh402.kirilllabs.workers.dev/mcp'

Fresh402

Um oráculo de frescor de baixo custo para agentes de IA, alimentado por x402.

O Fresh402 permite que um agente de IA registre um recurso da web uma única vez e, em seguida, verifique com baixo custo se ele mudou materialmente antes de gastar dinheiro em uma sessão de navegador, raspador, chamada de API ou contexto de LLM.

• Registro de linha de base gratuito
• US$ 0,005 USDC por verificação de frescor
• API REST
• Suporte a MCP
• Pagamentos x402 na rede principal da Base
• IDs de monitoramento persistentes
• Monitoramento de HTML, JSON e texto
• Filtragem de ruído e diffs determinísticos

Por que Fresh402?

Agentes de IA frequentemente precisam responder a uma pergunta simples:

Este recurso mudou desde a última vez que o verifiquei?

Buscar, renderizar, analisar e enviar uma página inteira por um LLM pode custar muito mais do que responder a essa pergunta.

O Fresh402 atua como uma primeira etapa barata:

1. Registre um recurso gratuitamente.
2. Receba um watch_id persistente.
3. Pergunte ao Fresh402 se ele mudou.
4. Execute apenas trabalhos downstream caros quando necessário.

API ao vivo

Produção:

https://fresh402.kirilllabs.workers.dev

Saúde e metadados do serviço:

GET /

Preços

Operação	Preço
Registrar linha de base	Grátis
Verificação de frescor	US$ 0,005 USDC
Rede	Base mainnet
Protocolo de pagamento	x402

Início rápido

1. Registrar uma linha de base

O registro é gratuito.

curl -X POST \
  https://fresh402.kirilllabs.workers.dev/v1/register \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

Exemplo de resposta:

{
  "watch_id": "w_0123456789abcdef0123456789abcdef",
  "url": "https://example.com",
  "created": true,
  "baseline_created": true,
  "content_kind": "html"
}

Registrar o mesmo recurso novamente retorna a linha de base existente sem buscá-lo novamente.

Isso impede que o endpoint de registro gratuito seja usado como uma verificação de frescor repetida e gratuita.

2. Verificar o recurso

curl -X POST \
  https://fresh402.kirilllabs.workers.dev/v1/check \
  -H "Content-Type: application/json" \
  -d '{"watch_id":"w_0123456789abcdef0123456789abcdef","include_diff":true}'

Sem pagamento, o Fresh402 retorna um requisito de pagamento x402.

O preço atual é US$ 0,005 USDC na rede principal da Base (eip155:8453).

Um cliente compatível com x402 pode atender ao requisito de pagamento e tentar a solicitação novamente automaticamente.

API REST

POST /v1/register

Crie ou recupere uma linha de base persistente gratuitamente.

Exemplo com escopo de HTML:

{
  "url": "https://example.com/pricing",
  "selector": "#pricing",
  "ignore_selectors": [
    ".timestamp",
    ".advertisement"
  ]
}

Para recursos JSON:

{
  "url": "https://api.example.com/data",
  "ignore_json_paths": [
    "/generated_at",
    "/items/*/last_seen"
  ]
}

Segmentos de JSON Pointer com curinga * são suportados.

POST /v1/check

Verificação de frescor paga.

{
  "watch_id": "w_0123456789abcdef0123456789abcdef",
  "max_age_seconds": 300,
  "include_diff": true
}

As entradas suportadas incluem:

• watch_id
• url
• previous_hash
• selector
• ignore_selectors
• ignore_json_paths
• max_age_seconds
• include_diff

max_age_seconds permite que agentes reutilizem estado Fresh402 compartilhado suficientemente recente em vez de forçar outra busca upstream.

GET /v1/history

Recupere o histórico de snapshots armazenado usando um watch_id ou URL.

GET /v1/diff

Recupere informações de alteração para um recurso monitorado.

GET /v1/stats

Recupere estatísticas públicas de uso do serviço.

MCP

O Fresh402 expõe um endpoint MCP HTTP transmissível:

https://fresh402.kirilllabs.workers.dev/mcp

Ferramentas disponíveis:

fresh402_register

Grátis.

Cria ou recupera uma linha de base persistente e retorna um watch_id.

fresh402_check

Custa US$ 0,005 USDC.

Verifica se um recurso registrado ou fornecido pelo chamador mudou.

A ferramenta expõe metadados de pagamento x402 para que agentes compatíveis possam descobrir e pagar pela operação programaticamente.

Detecção de alterações

O Fresh402 é projetado para reduzir falsos positivos de ruído irrelevante na página.

Escopo de seletor HTML

Monitore apenas parte de uma página:

{
  "url": "https://example.com/pricing",
  "selector": "#pricing"
}

Filtragem de ruído HTML

Remova elementos voláteis antes da impressão digital:

{
  "ignore_selectors": [
    ".timestamp",
    ".visitor-counter",
    ".advertisement"
  ]
}

JSON canônico

O JSON é canonicalizado antes da hash, para que a ordem das chaves do objeto não cause falsas alterações.

Ignorar JSON Pointer

Campos JSON voláteis conhecidos podem ser removidos antes da impressão digital.

{
  "ignore_json_paths": [
    "/generated_at",
    "/items/*/last_seen"
  ]
}

Revalidação HTTP condicional

O Fresh402 pode usar metadados upstream ETag e Last-Modified quando disponíveis.

Diff determinístico

Quando conteúdo anterior comparável existe, include_diff: true pode retornar um resumo de alteração determinístico e compacto.

Monitoramentos persistentes

O Fresh402 v1.1 introduziu monitoramentos persistentes de agentes.

Um recurso registrado recebe um identificador estável:

w_0123456789abcdef0123456789abcdef

O Fresh402 armazena o estado do monitoramento e o histórico limitado de snapshots no Cloudflare D1.

O registro gratuito repetido não atualiza um monitoramento existente. Uma verificação paga é necessária para buscar estado upstream novo.

Arquitetura

O Fresh402 atualmente usa:

• Cloudflare Workers
• Cloudflare D1
• Infraestrutura x402 da Coinbase / CDP
• Base mainnet
• USDC
• Model Context Protocol (MCP)
• TypeScript

O objetivo é manter as verificações de frescor baratas o suficiente para que agentes possam usar o Fresh402 antes de trabalhos mais caros de navegação, raspagem ou raciocínio.

Segurança

O Fresh402 valida alvos de saída e inclui proteções destinadas a reduzir o risco de SSRF.

Credenciais de pagamento e segredos de implantação são fornecidos por meio da configuração de ambiente em tempo de execução e não são armazenados neste repositório.

Limites de recursos

• Novos registros gratuitos (REST e MCP combinados) são limitados a 10 tentativas por hostname de destino e 60 tentativas no total por 60 segundos, em cada localização do Cloudflare. Caminhos, consultas, portas e variantes de regras de seletor/ignorar compartilham o limite do hostname. Tentativas upstream com falha também consomem cota. Monitoramentos existentes são retornados sem busca ou cobrança de cota; verificações pagas não usam esses limites.
• REST retorna 429 registration_rate_limited com Retry-After: 60 quando um limite é atingido. Ligações de limite de taxa ausentes ou indisponíveis retornam 503 registration_unavailable para novos registros. MCP relata isso pelo caminho de erro de ferramenta existente.
• Todo corpo de POST recebido é limitado a 65.536 bytes antes do parsing JSON, manipulação de pagamento, despacho MCP ou clonagem (413 request_too_large). A leitura de um corpo recebido tem um prazo de 10 segundos (408 request_timeout).
• Corpos de resposta upstream são transmitidos com um limite de 5.000.000 bytes (413 content_too_large), inclusive quando Content-Length está ausente ou enganoso. Um único prazo de 10 segundos cobre redirecionamentos, cabeçalhos e leitura do corpo (504 upstream_timeout). Fluxos não utilizados e rejeitados são cancelados.
• A criação concorrente do mesmo monitoramento salva apenas uma linha de base e um snapshot inicial. Um registro gratuito perdedor retorna a linha de base armazenada; solicitações iniciais sobrepostas ainda podem realizar buscas upstream separadas, sujeitas aos limites de registro.

As duas ligações de limite de taxa e seus limites são declarados em wrangler.jsonc; mantenha os IDs de namespace exclusivos dentro da conta do Cloudflare. Esses limites do Cloudflare são locais para cada localização e eventualmente consistentes. Eles mitigam picos, mas não são uma cota mundial estrita ou um limite de armazenamento/faturamento. Usuários legítimos que compartilham um hostname de destino também compartilham sua cota. O sinalizador de compatibilidade global_fetch_strictly_public permanece habilitado para proteger contra endereços privados alcançados por DNS.

Verificação local

Use Node.js 24 e execute:

npm ci
npx tsc --noEmit
npx tsc --noEmit -p test/tsconfig.json
npm test -- --run

Os testes usam um runtime local do Workers, dados D1 isolados e solicitações upstream simuladas. Eles não exigem credenciais de pagamento nem acessam produção. O GitHub Actions executa essas mesmas verificações em pull requests e pushes para main; o fluxo de trabalho não tem etapa de implantação.

Versão atual

v1.1.1

Destaques:

• watch_id persistente
• Registro de linha de base gratuito
• Comportamento anti-atualização gratuita
• Escopo de seletor HTML
• Seletores de ignorar HTML
• Monitoramento JSON canônico
• Caminhos de ignorar JSON Pointer com curinga
• Cache de frescor compartilhado
• previous_hash fornecido pelo chamador
• Diff inline determinístico
• Revalidação ETag / Last-Modified
• Retenção limitada de snapshots
• Suporte REST e MCP

Status

O Fresh402 está ativo e utilizável hoje.

O projeto ainda é inicial e a API pode evoluir à medida que padrões reais de uso por agentes se tornarem mais claros.

Autor

Construído e mantido por Kirill Radchenko.

Problemas, integrações, feedback e casos de uso de agentes de IA são bem-vindos.