x402 Bazaar Listing Monitor

x402 Bazaar 列表监控器

面向 x402 卖家的定时监控程序：定期轮询 Coinbase CDP 的公开 Bazaar 发现目录，检查你注册的资源，并在资源消失或重新出现时发出提醒——不用等到几天后收入下滑才发现问题。

通过 x402 真实收款的卖家，没有可靠的方式确认自己的资源是否仍能在 CDP 的 Bazaar 目录中被发现。发现 API 存在一类反复出现且公开报告过的错误：即使收款已确认，资源仍会悄然从目录中消失。目前卖家只能自行安排时间，手动重新运行 GET /discovery/merchant?payTo=<address> 来发现这一问题。

本服务会自动执行这项检查：注册你的 payTo 地址和所提供的资源 URL，定时轮询会将它们与实时发现目录进行比对。状态变更会连同时间戳一并记录，因此如果需要向 CDP 支持团队升级反馈，你可以提供持久的历史记录作为依据。

MCP 服务

端点： https://x402-listing-monitor.acjlabs.com/mcp（可流式传输的 HTTP）

提供一个工具——无需注册，无需 API 密钥：

check_listing_health

检查卖家的 x402 Bazaar 资源当前是否列在公开发现目录中 payTo 地址对应的条目下。可按需针对任意 payTo/资源组合运行与定时轮询相同的卖家级比对，无论是否已在此处注册。

参数	类型	说明
payTo	string	以 0x 开头的 40 位十六进制字符
resources	string[]	1–200 个 http(s) URL

以 JSON 格式返回每个资源，并标记其状态为已列出或缺失。

HTTP API

基础 URL：https://x402-listing-monitor.acjlabs.com

方法	路径	用途
GET	/health	存活状态检查
POST	/register	注册卖家以进行定时轮询
GET	/status	查看你自己的当前状态和近期提醒
POST	/poll	立即运行一次轮询（仅统计数量，见下文）

POST /register

{
  "sellerId": "your-slug",
  "payTo": "0x0000000000000000000000000000000000000000",
  "resources": ["https://api.example.com/your-resource"],
  "alertWebhookUrl": "https://example.com/hook"
}

• sellerId — 2–64 个字符：字母、数字、-、_
• payTo — 以 0x 开头的 40 位十六进制字符
• resources — 1–200 个 http(s) URL，不得重复
• alertWebhookUrl — 可选。公开的 https URL；你的套餐所支持的提醒会通过 POST 发送到此 URL。拒绝 IP 字面量、环回地址、.internal/.local 主机以及包含凭据的 URL。
• alertEmail — 可选，且仅存储，尚未使用：尚未启用邮件投递（见“状态”）。

两个联系字段均为可选，不填写也能成功注册。若两者都不提供，我们不会主动向你发送任何内容——请使用下方的 GET /status 自行检查列表状态。

资源采用自行声明的方式进行监控：你指定检查哪些内容，服务就会检查哪些内容。若 sellerId 已存在，注册将被拒绝，不会覆盖现有记录。

GET /status

GET /status?sellerId=your-slug&payTo=0x0000000000000000000000000000000000000000

返回你自己的记录：你注册的每个资源及其当前状态（listed、missing、payTo-mismatch；如果尚未轮询到该资源，则为 null）、连续未命中次数和上次检查时间戳，以及最近的提醒和每条提醒的投递状态。

sellerId 和 payTo 均为必填项，且必须与注册信息匹配；否则将返回 404。此接口用于了解状态，并非身份验证——返回的数据只是与公开目录比对所得的结果。不会回显你的 alertEmail 和 alertWebhookUrl，只会报告是否已设置。

POST /poll

立即为每位已注册卖家运行与每六小时一次的 cron 相同的轮询。不需要请求正文， 且仅返回计数：

{ "polled": 2, "ok": 2, "failed": 0 }

它不会报告任何单个卖家的信息。此端点无需身份验证，因此返回的任何内容都会是公开的——请改用 GET /status 读取你自己的状态。

同一时间只会运行一次轮询。如果已有轮询正在进行——无论是由其他人触发，还是由每六小时一次的 cron 触发——此端点都会返回 409，且不会执行任何操作：

{ "status": "already_running" }

这不是需要重试的错误：你请求的轮询已经在进行，重试不会让提醒更早送达，也不会让提醒重复送达——锁的作用就是防止两个并发轮询向你发送相同的提醒。这是防止重复的保障，而非送达保障：提醒总是在发送前记录；如果发送未成功，它会保留为已记录但未送达，而不会重试。请稍后读取 GET /status，查看每条近期提醒及其是否已送达。

/register、/status、/poll 和 MCP 工具调用均受每 IP 速率限制。

Webhook 负载

{
  "service": "x402-listing-monitor",
  "sellerId": "your-slug",
  "checkedAt": "2026-08-07T00:00:00.000Z",
  "alerts": [
    {
      "type": "listing-dropped",
      "resource": "https://api.example.com/your-resource",
      "detail": "was listed, now missing from discovery",
      "message": "⚠️ Listing dropped: https://api.example.com/your-resource — was listed, now missing from discovery"
    }
  ]
}

checkedAt 是此次轮询的时间戳，与 GET /status 中相同提醒的 created_at 一致。任何 2xx 状态码都视为已送达。不会跟随重定向——3xx 会被视为发送失败，因此请注册最终 URL。发送失败不会重试；提醒会保留在你的历史记录中，并标记为未送达。

轮询和提醒

计划轮询每 6 小时运行一次。每次运行都会将你注册的资源与实时发现目录进行比对，并记录带时间戳的状态变化——这是一段历史记录，而非仅反映某个时间点的结果。

提醒类型	层级
资源已从目录中移除	免费
索引延迟宽限期后仍未找到	免费
资源已恢复	免费
目录条目中缺少已注册的 payTo	付费
目录质量／排名下降	付费

“仍未找到”提醒每段缺失期只触发一次，从资源连续缺失三次或以上的首次轮询开始——这段时间足以排除索引延迟。只要资源仍然缺失，它就不会每六小时重复触发；当前状态始终可通过 GET /status 查看。

连续缺失三次是它最早可以触发的时间点，而非唯一触发时间点。某资源如果已经连续缺失超过三次，且该段缺失期尚未触发提醒，则会在下一次轮询时触发一次提醒。如果资源恢复后又再次消失，这就构成一段新的缺失期，并会再次触发提醒。

付费层级还会缩短轮询间隔。

状态

早期版本。服务已上线并正在轮询，记录的提醒历史是其已观察到情况的权威记录。

• Webhook 发送已启用。 注册一个 https alertWebhookUrl；当检查产生提醒时，你套餐中包含的提醒会通过 POST 发送到该 URL。
• 电子邮件提醒尚未启用。 alertEmail 会与您的注册信息一同存储，但不会向其发送任何内容。
• 无需提供联系方式。 你可以随时通过 GET /status 获取相同的信息。

源码可用性与支持

此仓库托管托管服务的文档。服务实现并非开源。欢迎在此仓库的 Issues 中提交 Bug 报告和功能请求；你也可以通过 [email protected] 联系我们。

源码可用性与支持

此仓库托管托管服务的文档。服务实现并非开源。欢迎在此仓库的 Issues 中提交 Bug 报告和功能请求；你也可以通过 [email protected] 联系我们。