Bazaar — 服务发现

什么是 Bazaar?

Bazaar 是 x402 的发现层。它回答 "这里能买什么,多少钱?" 这个问题。智能体在 /.well-known/x402.json 浏览结构化的服务、价格和输入/输出 schema 目录。

工作原理

发布 /.well-known/x402.json:

{
  "x402Version": 2,
  "name": "Your Service",
  "description": "What your service does",
  "network": "base",
  "facilitator": "coinbase",
  "payTo": "0xYourWallet",
  "services": [
    {
      "method": "POST",
      "path": "/api/generate",
      "description": "Generate content",
      "amount": "100000",
      "discoverable": true,
      "outputSchema": {
        "input": {
          "type": "http",
          "method": "POST",
          "bodyFields": {
            "prompt": { "type": "string", "required": true }
          }
        },
        "output": {
          "type": "json",
          "schema": { "result": { "type": "string" } }
        }
      }
    }
  ]
}

必填字段

x402Version — 规范版本(使用 2;扫描器也接受 1 — 见下文)
name — 提供方名称
network — 区块链(例如 base,或 v2 下的 CAIP 形式 eip155:8453)
facilitator — 结算提供方(例如 coinbase)
payTo — 接收付款的钱包地址
services[] — 带有 method 和 path 的付费端点数组

v1 vs v2

x402 v2 于 2025 年 12 月发布,是当前的规范,但 v1 服务器在现网中仍很常见。AgentGrade 同时接受两者。下面是协议层面的所有差异:

请求头名称: v1 使用带 X- 前缀的头(重试请求上的 X-PAYMENT、成功时的 X-PAYMENT-RESPONSE)。v2 去掉了 X- 前缀(PAYMENT-SIGNATURE、PAYMENT-RESPONSE)— X- 约定早在 2012 年就被 RFC 6648 弃用。
挑战放在哪里: v1 把支付挑战放在 402 响应的 JSON 正文里。v2 把它移到 PAYMENT-REQUIRED 响应头中(base64 编码的 JSON),让正文可以用作人类可读的付费墙页面。
amount 字段重命名: v1 的 accepts[] 条目用 maxAmountRequired 表示价格。v2 重命名为 amount。
resource 形状: v1 把 resource(作为字符串 URL)、description 和 mimeType 放在每个 accepts[] 条目里。v2 把它们提升为顶层的 resource 对象,包含 url、description、mimeType 字段 — 整个 402 响应只声明一次,不必在每个 accepts 条目中重复。
链标识: v1 在 network 字段中用 "base" 这样的自由字符串。v2 标准化为 CAIP ID(例如 eip155:8453),让同一字段适用于非 EVM 链和链下轨道。
动态的 payTo: v1 在发现目录中为每个服务声明一个静态收款方。v2 允许服务器为每次请求动态计算 payTo — 适用于把付款分发给各个卖家的市集场景。
会话: v1 要求每次调用都走完整的支付流程。v2 增加了钱包控制的会话(Sign In With X402)— 签名一次,服务器签发会话,后续调用跳过握手。

如果你在新建服务,直接用 v2。如果你在审查现有的 v1 服务器,扫描器不会因为你还在用 v1 而扣分 — 但 v2 的差异是实实在在的效率提升。

live 402 头中的 extensions.bazaar

当智能体在没有付款的情况下调用付费端点时,你的服务器会返回 HTTP 402,并附带一个 base64 编码的 Payment-Required 头。该头的 JSON 负载应声明 extensions.bazaar,这样智能体就能知道该端点属于一个可发现的目录。base64 编码之前的 JSON 负载(v2 形式):

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "amount": "100000",
      "asset": "0xUSDC...",
      "payTo": "0xYourWallet",
      "maxTimeoutSeconds": 60
    }
  ],
  "extensions": {
    "bazaar": { "discoverable": true }
  }
}

如果没有 extensions.bazaar,收到 402 的智能体就完全没有线索得知该端点也已编入 /.well-known/x402.json 目录 — 它们可能会把它当成一次性付费端点,而不是可浏览服务的一部分。

规范成熟度

x402 v2 的一部分。 Bazaar 发现机制定义在 x402 规范内。

了解更多

x402.org — x402 协议规范(包含 Bazaar)