新 x402 列表订阅源

x402/L402 服务在 402index.io 上新近列出的订阅源（feed），限定在调用者指定的最近时间窗口内。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} -- 返回在窗口（1-168 小时，默认 24 小时）内注册到 402index.io 的服务。$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 声明验证文件）。

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

这不是独家数据。 这个资产底下的注册数据来自 402index.io 自己的免费、公共目录（https://402index.io/api-docs，无需认证，免费额度 100 次请求/分钟）。任何人都可以直接免费查询。这个资产的价值完全在于包装：轮询并对约 ~96k+ 条目目录做翻页，买家无需自己做；并入 402index 自己的新近 feed 以保持时效；去重；再按调用者的窗口/协议/类别/支付网络过滤。这个披露不止写在 README 里，它已经融入了产品本身：每一个响应都带一个 note 字段，直接说明这一点；agent-card 的 protocol_note 也重复同样表述，所以买家永远不用自己去挖。

Related MCP server: x402-discovery

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

任务简报的前提引用了此前一次会话的"约 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 的模块 docstring 以及下方"架构"一节。这正是 CLAUDE.md SS3 要求主动暴露而非默默绕过的那类真实、当前数据偏差——所以记录在这里，而不是只存在于对话记录中。

架构

• 一个后台 asyncio 任务（在 FastAPI 的 lifespan 中启动，不阻塞启动）每 NEXUS_CATALOG_REFRESH_SECONDS（默认 600 秒/10 分钟）遍历一次完整的 /api/v1/services 目录，节奏为 0.65 秒/请求（约持续 92 req/min，安全地低于 402index 100 req/min 免费层上限）。结果缓存在内存中（_catalog_cache），以服务 id 作为键。按当前目录规模，一次完整遍历约 ~481 页 / ~5.2 分钟——这完全是后台任务代价，绝不内联在买家的请求路径中。

• 每一次买家请求还会实时拉取 /feed.xml?type=new（限流豁免，约 1 次请求，很便宜），并把它合并进后台遍历已缓存的内容，以捕获最后一遍遍历完成之后新注册的数据。id 冲突时缓存条目胜出（字段更丰富）；feed 条目只负责补缺口。

• 响应在合并后做过滤/去重/排序（最新在前），上限 500 条结果。

为什么不用字面意义上的 TTL 缓存（对任务简报建议形态的偏离）

简报建议"一个短内存缓存（5-10 分钟 TTL）"。实际实现是：一个持续运行的后台循环，每 10 分钟重新遍历并替换缓存，而买家请求始终读当前缓存（自己绝不会触发一次遍历）。如果采用字面意义的"过期按需刷新 TTL"，那么正好在过期后到达的那个买家请求会花 $0.01 付费，然后阻塞最多约 5 分钟等待一轮全新的 481 页遍历——这是设计过程中发现、而不是追溯得到的不可接受买家体验。后台循环的形态同样达成了"不要打爆 402index"的目标，却永远不会让付费调用者等待遍历。

冷启动（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.92 相同；不同于 agent-verification-api 的 $0.35 信号档。无第三方付费 API 成本，只是纯 CPU / 内存 + 每次调用有一个免费上行请求。

预部署质量门禁（2026-08-23，从设计而非回顾中得来）

在首次部署前用 4 个视角审视，每一步都对着真实在线的 402index.io API（不是 mock）测试。真实发现与修正：

• 安全：调用方输入（window_hours/protocol/category/payment_network）永远不会拼接进上游 402 请求——目录遍历和 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。分页本身（offset 正确推进、总数停止、走时上限兜底）也已用有限测试遍历（8 个真实页，offset 正常增长，优雅退出被记录下来）对着真实在线 API 验证过——没有静默截断，也没有死循环。

• 代码质量：评审未发现死代码或用不到的 import；与同级资产的结构（Supabase 遥测辅助、x402 接线、路由发现）一致，手工迁移，同 document-conversion-api/url-metadata-api 的构建方式一致。

• 买家体验（"原始数据在其他平台本就是免费"披露的视角）：402index.io 自身数据免费这一事实，已经验证存在于 3 个地方，不只在 README：agent-card 的 protocol_note，以及——更直接地，让买家完全不用去拿 agent-card——每个 API 响应自带 的 note 字段。冷缓存降级（cold_fallback_feed_only）也在同一个 note 字段里用对买家请求的窗口意味着什么的白话披露了，而不只是一个通话必须知道如何读取的状态枚举。

已知限制（作为已文档化的取舍，而不是默默留着）

• MCP 工具调用不收费。 与同行手工资产相同的进程内调用模式。

• 没有按调用方做限流。 对于 7 天的一次性测量窗口，这是够用的。

• 冷缓存窗口覆盖不足，缓解了，但没根治。 一个落地到 Cloud Run 冷启动后约 5 分钟窗口内的请求，只能拿到仅 feed 的覆盖范围（当前数据显示 90 条 feed 约 3 小时左右），而不是请求的完整窗口，但同样扣 $0.01。这个会以响应中实时披露，但一个恰好只调用一次、冷启动之后、且不去读 catalog_walk.status 也不会读 note 的买家，可能把短结果列表合理理解为"没有新的内容"，而不是"缓存正在预热"。未来可以把 min-instances=1 固定，从而彻底消除冷启动；但同时会产生真实的常驻 Cloud Run 费用——对一个 7 天试用候选来说，先不做。

• registered_at 理解为 UTC（假设）。 402alert的服务──（http://api/v1/services）返回的是无时区的时间戳（`"2026-08-22 22:13:15"，没有偏移）——仅依据与本次会话中实测到 last_checked` 值的一致性把它当作 UTC 处理；并不是 4028 官方文档保证。

• 全量目录遍历的节奏基于今天的目录体量。 在约 ~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 生态里的发现订阅源，而不是像转换转换/链接预览那样验证过的持续性需求形态。