## 什么是 Bazaar?

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

## 工作原理

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

```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](https://www.rfc-editor.org/rfc/rfc6648) 弃用。
- **挑战放在哪里**: 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](https://chainagnostic.org/) 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 形式):

```json
{
  "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](https://www.x402.org/) — x402 协议规范(包含 Bazaar)

## 相关

- [OpenAPI](/kb/zh/openapi)
- [A2A](/kb/zh/a2a)