Nuevo feed de listados x402

Feed de servicios x402/L402 recién listados en 402index.io dentro de una ventana de recencia especificada por el llamante. Candidato NEXUS #8 -- compilación manual, no generada por FORGE, mismo patrón de activo manual de Cloud Run que los candidatos #3 (agent-verification-api), #4 (url-metadata-api) y #6 (document-conversion-api).

• POST /new-x402-listings {"window_hours": 24, "protocol": null, "category": null, "payment_network": null} -- servicios registrados en 402index.io dentro de la ventana (1-168h, por defecto 24). $0.01/llamada.

• Herramienta MCP get_new_x402_listings en /mcp, mismos parámetros -- actualmente gratis, ver "Limitaciones conocidas".

• GET /health, GET /.well-known/agent-card.json, GET /openapi.json (tiene x-payment-info), GET /.well-known/402index-verify.txt (archivo de verificación de reclamación de 402index).

Qué es esto (y qué no es)

Esto no son datos exclusivos. Los datos de registro subyacentes a este activo son el propio directorio gratuito y público de 402index.io (https://402index.io/api-docs, sin necesidad de autenticación, 100 req/min en el nivel gratuito). Cualquiera puede consultarlo directamente sin coste. El valor de este activo reside enteramente en el empaquetado: sondear y paginar el catálogo de ~96k+ entradas para que un comprador no tenga que hacerlo, fusionar el propio feed de recencia de 402index para la frescura, deduplicar y filtrar según la ventana/protocolo/categoría/red de pago del llamante. Esta divulgación no está solo en este README -- está integrada en el propio producto: cada respuesta incluye un campo note que lo indica claramente, y el protocol_note de la agent-card lo repite, de modo que un comprador nunca tenga que buscarlo.

Related MCP server: x402-discovery

Investigación de viabilidad (2026-08-23, antes de escribir código)

La premisa del brief de la tarea citaba una cifra de una sesión anterior de "~7,595 servicios totales" en 402index.io. Un curl https://402index.io/api/v1/services?limit=5 real al inicio de esta sesión mostró "total": 96093 -- el catálogo creció aproximadamente 12 veces desde esa comprobación. registered_at es real y está poblado en cada entrada muestreada. Se verificaron en vivo dos mecanismos ascendentes, cada uno con una limitación real que ni el brief de la tarea ni la propia documentación de 402index revelaron por completo:

1. GET /api/v1/services (paginado, limit/offset, máx. 200/página) NO tiene filtro de ordenación por fecha ni de rango de fechas -- sort solo acepta name/price/latency/uptime/reliability (comprobado directamente en /api-docs). Una consulta por ventana solo puede responderse recorriendo el catálogo completo y filtrando en el lado del cliente -- no hay una ruta más barata en el lado del servidor. Con el tamaño real actual, eso son ~481 páginas, no las ~40 páginas que la cifra de ~7,595 habría implicado.

2. GET /feed.xml?type=new es real, RSS 2.0, y YA está ordenado por recencia (pubDate) -- y está en la propia lista documentada de exentos de límite de velocidad de 402index. Pero está limitado a un número fijo de elementos: una búsqueda en vivo durante esta sesión devolvió exactamente 90 elementos que abarcaban solo ~3 horas, a pesar de que la documentación describe type=new como "servicios añadidos en los últimos 7 días". Con la velocidad de registro actual, no cubre por sí solo una ventana de 7 días (ni siquiera de 24 horas, en velocidad máxima).

Ninguna fuente por sí sola satisface honestamente el rango de ventana anunciado del producto. Decisión: proceder, usando ambas. Ver el docstring del módulo main.py y "Arquitectura" a continuación para saber cómo se combinan. Este es el tipo de discrepancia real y actual de datos que CLAUDE.md SS3 pide sacar a la luz en lugar de construir pasando por alto en silencio -- por eso se registra aquí y no solo en una transcripción de chat.

Arquitectura

• Una tarea asyncio en segundo plano (iniciada en el lifespan de FastAPI, sin bloquear el arranque) recorre el catálogo completo de /api/v1/services cada NEXUS_CATALOG_REFRESH_SECONDS (por defecto 600s/10min), con un ritmo de 0.65s/solicitud (~92 req/min sostenidos, margen de seguridad por debajo del límite de 100 req/min del nivel gratuito de 402index). Los resultados se almacenan en caché en memoria (_catalog_cache), con clave por id de servicio. Un recorrido completo con el tamaño actual del catálogo es de ~481 páginas / ~5.2 minutos -- es un coste totalmente de la tarea en segundo plano, nunca en línea dentro de la solicitud de un comprador.

• Cada solicitud de comprador además obtiene /feed.xml?type=new en vivo (exento de límite de velocidad, ~1 solicitud, barato) y lo fusiona con lo que la caminata en segundo plano haya almacenado en caché, capturando cualquier cosa registrada después de la última caminata completada. Las entradas de caché ganan en conflicto de id (campos más ricos); las entradas del feed solo rellenan huecos.

• La respuesta se filtra/deduplica/ordena (más recientes primero) a partir de esa fusión, con un límite de 500 resultados.

Por qué no una caché TTL literal (desviación de la forma sugerida en el brief de la tarea)

El brief sugería "una caché corta en memoria (TTL de 5-10 min)". En su lugar se implementó: un bucle en segundo plano que se ejecuta continuamente, re-recorre cada 10 minutos y reemplaza la caché, y las solicitudes de los compradores siempre leen lo que esté actualmente en caché (nunca desencadenan un recorrido por sí mismas). Un TTL literal bajo demanda cuando está obsoleto significaría que la solicitud de cualquier comprador que llegue justo después de la expiración pague $0.01 y luego se bloquee hasta ~5 minutos esperando un recorrido fresco de 481 páginas -- una experiencia de comprador inaceptable encontrada durante el diseño, no retroactivamente. La forma de bucle en segundo plano logra el mismo objetivo de "no golpear 402index.io" sin hacer que un llamante de pago espere nunca por el recorrido.

Arranque en frío (escala a cero de Cloud Run)

min-instances=0 significa que un contenedor nuevo arranca con una caché vacía. Las primeras solicitudes después de cualquier período de inactividad obtienen catalog_walk.status: "cold_fallback_feed_only" -- los resultados se limitan a lo que /feed.xml?type=new contenga actualmente (observado recientemente que abarca solo unas pocas horas), no la ventana completa solicitada. Esto se divulga en el propio campo note de la respuesta, no se oculta. Una vez que la primera caminata de la tarea en segundo plano se completa (~5 minutos después del arranque del contenedor), las solicitudes posteriores obtienen status: "warm" con cobertura completa del recorrido del catálogo. Mitigado de verdad, no resuelto -- ver "Limitaciones conocidas".

Precio: $0.01/llamada (nivel bajo)

Nicho especulativo según el propietario del producto (dirección explícita, no una conclusión basada en datos) -- mismo nivel bajo que los $0.01-$0.02 de url-metadata-api/document-conversion-api, no el nivel de señal de $0.35 de agent-verification-api. Sin coste de API de terceros de pago, solo CPU/memoria + una búsqueda ascendente gratuita por llamada.

Puerta de calidad previa al despliegue (2026-08-23, desde el diseño, no retroactivo)

Revisado a través de 4 lentes antes del primer despliegue, probado contra la API real en vivo de 402index.io (no simulada) en cada paso. Hallazgos y correcciones reales:

• Seguridad: la entrada del llamante (window_hours/protocol/category/payment_network) nunca se interpola en la solicitud ascendente a 402index.io -- el recorrido del catálogo y la búsqueda del feed usan solo parámetros de consulta fijos y codificados (limit/offset/sort/order y type=new respectivamente); los filtros del llamante se aplican exclusivamente al resultado ya obtenido y normalizado en memoria. Se verificó que el JSON/XML ascendente nunca se confía a ciegas: cada campo se lee mediante .get() con comprobaciones de tipo (_normalize_catalog_item devuelve None en una entrada malformada en lugar de lanzar una excepción), el XML malformado de /feed.xml se captura (ET.ParseError) en lugar de hacer fallar la solicitud, y un solo <item> malformado en el feed no descarta el resto. Todo confirmado con pruebas reales de entrada malformada (None, id faltante, tipos incorrectos, marca de tiempo basura, XML truncado) durante esta sesión, no solo leído como correcto.

• Corrección funcional (brecha real, corregida): el diseño inicial almacenaba en caché complete: bool internamente pero nunca lo exponía en la respuesta -- un llamante no tenía forma de distinguir una caminata en segundo plano que alcanzó el límite de tiempo de pared _WALK_MAX_WALL_SECONDS (saliendo con un resultado parcial) de una que terminó limpiamente, aunque ambas reportaran status: "warm". Corregido: se añadió catalog_walk.walk_complete a la respuesta. La paginación en sí (avance de offset, parada en total, salida por límite de pared) se verificó contra la API real en vivo con una caminata de prueba acotada (8 páginas reales, offset avanzando correctamente, salida elegante registrada) -- sin truncamiento silencioso, sin bucle infinito.

• Calidad del código: no se encontró código muerto ni importaciones sin usar en la revisión; coincide con la estructura de los activos hermanos (helpers de telemetría de Supabase, cableado x402, rutas de descubrimiento) portados a mano, coherente con cómo se construyen document-conversion-api/url-metadata-api.

• Experiencia del comprador (la lente de divulgación de "los datos brutos son gratis en otro lugar"): el hecho de que los datos de 402index.io sean en sí mismos gratuitos se verificó presente en 3 lugares, no solo en el README: el protocol_note de la agent-card, y -- más directamente, para que ningún comprador tenga que obtener la agent-card -- el propio campo note de cada respuesta de API. La cobertura degradada de caché fría (cold_fallback_feed_only) también se divulga en ese mismo campo note con lenguaje claro sobre lo que significa para la ventana solicitada, no solo un enum de estado que un llamante ya tiene que saber interpretar.

Limitaciones conocidas (dejadas como compensaciones documentadas, no en silencio)

• Las llamadas a herramientas MCP no se cobran. Mismo patrón de llamada en proceso que los activos manuales hermanos.

• Sin límite de velocidad por llamante. Aceptable para una ventana de medición desechable de 7 días.

• La subcobertura de la ventana de caché fría está mitigada, no resuelta. Una solicitud que llegue en los primeros ~5 minutos después de un arranque en frío de Cloud Run obtiene cobertura solo de feed (observado recientemente ~3h de alcance para un feed de 90 elementos a la velocidad actual de 402index), no la ventana completa solicitada, aunque se cobre el mismo $0.01. Esto se divulga en vivo en la respuesta, pero un comprador que llame una vez, justo después de un arranque en frío, y no lea catalog_walk.status/note podría leer razonablemente una lista de resultados corta como "nada nuevo" en lugar de "la caché aún se está calentando". Una corrección futura podría mantener min-instances=1 para eliminar los arranques en frío por completo, a un coste real de Cloud Run siempre activo -- no hecho para un candidato de prueba de 7 días.

• Se asume que registered_at está en UTC. /api/v1/services de 402index devuelve marcas de tiempo sin zona horaria ("2026-08-22 22:13:15", sin offset) -- tratadas como UTC basándose en la coherencia con los valores last_checked observados en vivo durante esta sesión, no una garantía documentada de 402index.io en sí.

• El ritmo del recorrido del catálogo completo asume el tamaño actual del catálogo. Con ~96k entradas, un recorrido completo es de ~481 páginas/~5.2min, dentro del intervalo de actualización de 10 minutos de forma segura. Si el catálogo de 402index sigue creciendo al ritmo de ~12x desde la última comprobación observado en esta sesión, un recorrido futuro podría acercarse o superar el intervalo de actualización de 10 minutos (entonces solo tardaría más entre las actualizaciones visibles de "last_full_walk_at", no se rompería -- _WALK_MAX_WALL_SECONDS saca un ciclo individual a los 900s y walk_complete lo reporta honestamente) -- no se re-ingeniería preventivamente según CLAUDE.md SS3 (sin puerta sin evidencia de que se necesite aún).

NEXUS_X402_FREE_MODE

Por defecto false (cobra desde el día 1, sin ventana freemium) -- misma convención que document-conversion-api. Establecer true localmente para pruebas sin un viaje de ida y vuelta real con el facilitador.

Destino de despliegue: Cloud Run, no Railway

Mismo pipeline que los candidatos #3/#4/#6 -- ver skills/infra-deploy-ops. No hay análisis de PDF/Office aquí, por lo que se usa el 512Mi por defecto del script compartido (no se aumenta a 1Gi como en document-conversion-api).

# 1. First deploy -- PUBLIC_DOMAIN not known yet, every real request 421s until step 2.
./scripts/deploy_cloud_run.sh new-x402-listings-feed manual_assets/new-x402-listings-feed \
    manual_assets/new-x402-listings-feed/env-vars.deploy.yaml

# 2. Grab the printed *.run.app URL, then:
gcloud run services update new-x402-listings-feed --region us-central1 --project nexus-505016 \
    --update-env-vars PUBLIC_DOMAIN=<the-real-domain>

Medición (candidato #8, ventana de 7 días)

Ventana de 7 días desde el primer despliegue real (2026-08-23 -> punto de decisión 2026-08-30). Fuente de verdad: tablas traffic_events/revenue_events/mcp_call_events (asset_name = 'new-x402-listings-feed'), no registros de Cloud Run. Día 7: si no hay tráfico real (filtrando rastreadores), pausar/eliminar el servicio de Cloud Run, misma regla de decisión que los candidatos #3/#4/#6. Este es explícitamente el más especulativo de los 4 candidatos manuales (el propio marco del propietario del producto) -- un feed de descubrimiento de nicho para un ecosistema x402 aún incipiente, no una forma de demanda recurrente probada como la conversión de documentos o las vistas previas de enlaces.