new-x402-listings-feed

全新 x402 列表 Feed

在调用方指定的时间范围内，列出新登记到 402index.io 的 x402/L402 服务。NEXUS 候选项目 #8——手动构建，非 FORGE 生成，采用与候选项目 #3（agent-verification-api）、#4（url-metadata-api）和 #6（document-conversion-api）相同的手动 Cloud Run 资源模式。

• POST /new-x402-listings {"window_hours": 24, "protocol": null, "category": null, "payment_network": null} -- 列出时间范围内登记到 402index.io 的服务（1–168 小时，默认 24 小时）。每次调用 $0.01。
• MCP 工具 get_new_x402_listings，位于 /mcp，参数相同——目前免费，请参阅“已知限制”。
• GET /health、GET /.well-known/agent-card.json、GET /openapi.json（包含 x-payment-info）、 GET /.well-known/402index-verify.txt（402index 声明验证文件）。

切换到主网（2026-09-03）

最初在 Base Sepolia 测试网上构建并测量。现已切换到 Base 主网：x402 结算改用 CDP facilitator（create_facilitator_config()，已对 ws/live-entity-verification/erc8004-agent-liveness/onchain-activity-index/x402-receipt-verifier 应用相同的替换），收款钱包改为 NEXUS_X402_PAYTO_ADDRESS（环境变量缺失时立即失败，不提供占位默认值；原名为 X402_WALLET_ADDRESS）。部署前，必须在 Cloud Run 中设置 CDP_API_KEY_ID/CDP_API_KEY_SECRET 和 NEXUS_X402_PAYTO_ADDRESS。

这是什么（以及不是什么）

这不是独家数据。 此资源使用的登记数据来自 402index.io 自有的免费公开目录（https://402index.io/api-docs，无需身份验证，免费档为每分钟 100 次请求）。任何人都可以免费直接查询。此资源的价值完全在于数据的打包处理：轮询并分页获取约 9.6 万条以上的目录条目，让购买者无需自行处理；合并 402index 自有的近期数据 Feed 以确保时效性；去重；并按调用方指定的时间范围、协议、类别和支付网络筛选。这项披露不只写在本 README 中——产品本身也明确说明了这一点：每条响应都包含一个直白说明此事的 note 字段，Agent 卡片中的 protocol_note 也会重申这一点，因此购买者不必费力查找。

可行性调研（2026-08-23，编写任何代码之前）

任务说明引用了前一会话中 402index.io 上“约 7,595 项服务”的数据。此次会话开始时实际运行 curl https://402index.io/api/v1/services?limit=5，结果显示 "total": 96093——自上次检查以来，目录规模约增长了 12 倍。所有抽样条目都确实包含已填充的 registered_at。我们实时验证了两种上游机制，但各自都有真实限制；任务说明和 402index 自己的文档都未充分说明这些限制：

1. GET /api/v1/services（支持分页，使用 limit/offset，每页最多 200 条）没有按日期排序或按日期范围筛选的功能——sort 只接受 name/price/latency/uptime/reliability（已直接检查 /api-docs）。要查询指定时间范围，只能遍历整个目录并在客户端筛选——没有更省力的服务端处理方式。按当前实际规模，需要约 481 页，而非根据约 7,595 条的数字推算出的约 40 页。
2. GET /feed.xml?type=new 确实存在，采用 RSS 2.0 格式，并且已按近期时间（pubDate）排序——也在 402index 自己记录的免限速列表中。但它的条目数有固定上限：本次会话中的实时请求恰好返回 90 项，涵盖的时间仅约 3 小时，尽管文档将 type=new 描述为“过去 7 天内新增的服务”。按当前登记速度，它本身无法覆盖 7 天（甚至在登记速度峰值时，也无法覆盖 24 小时）的时间范围。

单独使用任一来源，都无法可靠满足产品宣传的时间范围。决定：继续推进，同时使用两者。 两者的组合方式见 main.py 模块文档字符串和下文“架构”部分。这正是 CLAUDE.md 第 3 节要求指出、而非默默绕过的真实数据现状差异——因此我们将它记录在这里，而不只留在聊天记录中。

架构

• 一个后台 asyncio 任务（在 FastAPI 的 lifespan 中启动，不会阻塞启动过程）会遍历完整的 /api/v1/services 目录，每隔 NEXUS_CATALOG_REFRESH_SECONDS（默认 600s/10min）执行一次；请求间隔为 0.65s（持续约 92 req/min，低于 402index 免费层 100 req/min 上限，并留有安全余量）。结果 会缓存在内存中（_catalog_cache），以服务 ID 为键。按当前目录规模，完整遍历约需 481 页 / 5.2 分钟——这完全是后台任务的开销，绝不会发生在买家的请求中。
• 此外，每个买家请求都会实时获取 /feed.xml?type=new（不受速率限制，约 1 个请求，开销很小）， 并将其与后台遍历已缓存的内容合并，以捕获上次遍历完成后注册的内容。ID 冲突时优先使用缓存条目（字段更丰富）；Feed 条目仅用于补充缺失内容。
• 对合并结果进行筛选、去重和排序（最新内容在前），最多返回 500 条。

为什么不用字面意义上的 TTL 缓存（偏离任务说明建议的设计）

任务说明建议使用“短时内存缓存（5-10 min TTL）”。实际采用的是：持续运行的后台循环每 10 分钟重新遍历并替换缓存，买家请求始终读取当前缓存（不会自行触发遍历）。若采用过期后按需更新的字面意义上的 TTL，那么过期后恰好到来的买家请求就要支付 $0.01，然后阻塞至多约 5 分钟，等待完成全新的 481 页遍历——设计阶段就发现这对买家体验不可接受，而非事后才发现。后台循环的设计同样能实现“不要频繁请求 402index.io”的目标，同时绝不会让付费调用方等待遍历完成。

冷启动（Cloud Run 缩容至零）

min-instances=0 意味着新容器启动时缓存为空。每次容器处于非活动状态后收到的第一个（或几个）请求都会得到 catalog_walk.status: "cold_fallback_feed_only"——结果仅限于 /feed.xml?type=new 当前包含的内容（最近观察到的范围仅有几小时），而非完整的请求时间范围。响应自身的 note 字段会说明这一情况，不会隐瞒。容器启动约 5 分钟后，后台任务完成首次遍历；之后的请求会得到 status: "warm"，覆盖完整的目录遍历结果。这只是切实缓解，并未彻底解决——参见“已知限制”。

定价：$0.01/次（低阶档）

这是由产品负责人明确指定的利基推测性产品（并非基于数据得出的结论）——与 url-metadata-api/document-conversion-api 的 $0.01-$0.02 一样，属于低阶档，而非 agent-verification-api 的 $0.35 信号档。无需支付第三方 API 费用，纯 CPU/内存开销，每次调用只需获取一次免费的上游数据。

部署前质量门禁（2026-08-23，基于设计，而非事后补做）

首次部署前，从 4 个角度进行了审查，并在每一步都针对真实运行中的 402index.io API（而非模拟 API）进行测试。实际发现的问题及修复如下：

• 安全性：调用方输入（window_hours/protocol/category/payment_network）绝不会被插入上游 402index.io 请求中——目录遍历和 Feed 获取仅使用固定的硬编码查询参数（分别为 limit/offset/sort/order 和 type=new）；调用方筛选条件仅应用于已获取并标准化的内存结果。已确认不会盲目信任上游 JSON/XML：每个字段都通过带类型检查的 .get() 读取（_normalize_catalog_item 遇到格式错误的条目时会返回 None，而不是抛出异常）；/feed.xml 中格式错误的 XML 会由 ET.ParseError 捕获，不会导致请求崩溃；Feed 中单个格式错误的 <item> 不会丢弃其余内容。此会话期间通过真实的错误输入测试（None、缺少 id、类型错误、无效时间戳、截断的 XML）逐一确认，而非仅通过阅读代码判断正确性。
• 功能正确性（发现真实缺陷，现已修复）：初始设计在内部缓存了 complete: bool，但从未在响应中返回该值——调用方无法区分因达到 _WALK_MAX_WALL_SECONDS 墙钟时间上限而提前退出、返回部分结果的后台遍历，与正常完成的遍历，尽管两者都报告 status: "warm"。现已修复：在响应中加入 catalog_walk.walk_complete。分页本身（偏移量递增、达到总数时停止、超时上限时提前退出）已通过真实运行中的 API 进行有界测试验证（实际遍历 8 页，偏移量递增正确，并记录了正常提前退出）——没有静默截断，也没有无限循环。
• 代码质量：审查未发现死代码或未使用的导入；结构与手动移植的同类资源（Supabase 遥测辅助工具、x402 接线、发现路由）一致，也符合构建 document-conversion-api/url-metadata-api 的方式。
• 购买者体验（“其他地方可以免费获取原始数据”的披露角度）：已确认在 3 处明确说明 402index.io 的数据本身免费，而不只是在 README 中：Agent 卡片的 protocol_note，以及——更直接地说，这样购买者无需获取 Agent 卡片——每个 API 响应自身的 note 字段。同一 note 字段还会说明冷缓存下的覆盖降级情况（cold_fallback_feed_only），并用通俗语言解释这对请求时间窗口意味着什么，而不只是返回一个调用方必须预先知道如何解读的状态枚举。

已知限制（作为已记录的权衡保留，不做隐瞒）

• MCP 工具调用不收费。 与同类手动资产采用相同的进程内调用模式。
• 不按调用方限流。 对于为期 7 天的一次性测量窗口而言足够。
• 冷缓存窗口覆盖不足的问题有所缓解，但尚未解决。 在 Cloud Run 冷启动后的前约 5 分钟内到达的请求，只能获得 Feed 覆盖（按照当前 402index 的增长速度，近期观察到，90 条目的 Feed 覆盖约 3 小时），而非完整的请求窗口，却仍收取相同的 0.01 美元。响应中会实时说明这一点，但买家如果在冷启动后立即只调用一次，且不查看 catalog_walk.status/note，可能会合理地把较短的结果列表理解为“没有新内容”，而不是“缓存仍在预热”。未来可以通过将 min-instances=1 设为 1 来彻底消除冷启动，但这会产生 Cloud Run 持续运行的实际成本；对于为期 7 天的试运行候选项目，目前不采用此方案。
• 假定 registered_at 为 UTC。 402index 的 /api/v1/services 返回不带时区信息的时间戳（"2026-08-22 22:13:15"）——根据本次会话期间实时观察到的 last_checked 值保持一致这一点，将其视为 UTC；但 402index.io 本身并未对此作出文档保证。
• 全目录遍历的节奏假定目录大小与当前相同。 当前约有 96k 个条目，全目录遍历约需 481 页／5.2 分钟，可安全地在 10 分钟刷新间隔内完成。如果 402index 的目录继续以本次会话观察到的、较上次检查约 12 倍的速度增长，未来的遍历可能接近或超过 10 分钟刷新间隔（届时只会延长可见的 last_full_walk_at 更新间隔，不会导致故障——_WALK_MAX_WALL_SECONDS 会在 900 秒时中止单次循环，且 walk_complete 会如实报告），因此不会按照 CLAUDE.md SS3 提前重构（尚无证据表明有此必要，不设置门槛）。

NEXUS_X402_FREE_MODE

默认值为 false（从第 1 天起收费，没有免费增值窗口）——与 document-conversion-api 采用相同约定。 本地设为 true 可在不实际往返调用 Facilitator 的情况下进行测试。

部署目标：Cloud Run，而非 Railway

采用与候选项目 #3/#4/#6 相同的流水线——参见 skills/infra-deploy-ops。此处不涉及 PDF/Office 解析，因此使用共享脚本默认的 512Mi（不像 document-conversion-api 那样提高到 1Gi）。

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

测量（候选项目 #8，为期 7 天）

为期 7 天的窗口从首次实际部署开始（2026-08-23 -> 决策日期 2026-08-30）。数据的唯一可信来源为 traffic_events/revenue_events/mcp_call_events 表（asset_name = 'new-x402-listings-feed'），而非 Cloud Run 日志。第 7 天：如果没有真实流量（过滤爬虫后），则暂停／删除 Cloud Run 服务，决策规则与候选项目 #3/#4/#6 相同。明确来说，这是 4 个手动候选项目中最具推测性的一个（产品负责人的原话）——面向仍处于萌芽阶段的 x402 生态系统的细分发现 Feed，并非像文档转换或链接预览那样已验证有持续需求。