先决条件

在使用此技能之前，请确保：

Python 3.10+ 已安装
x402-avm 带有扩展：pip install "x402-avm[extensions,avm]"
熟悉 x402 资源服务器 和 Facilitator 概念
Web 框架 已安装：pip install "x402-avm[extensions,avm,fastapi]" 或 [...,flask]

Bazaar Discovery 功能

Bazaar 是内置于 x402 的资源发现协议。它允许支付受限的 API 宣传：

它们接受的输入 – GET/HEAD/DELETE 的查询参数，或 POST/PUT/PATCH 的请求正文模式
它们返回的输出 – 响应数据的形状、类型和示例

此元数据使 Facilitator 能够自动编目和索引 x402 启用的资源，因此客户端可以通过它们的功能而不是仅通过 URL 发现 API。它是付费 API 的机器可读菜单。

资源服务器（声明）         Facilitator（编目）        客户端（发现）
+---------------------------+      +----------------------+      +-------------------+
| RouteConfig + extensions: |      | extract_discovery_   |      | with_bazaar()     |
|   **declare_discovery_    | ---> |   info()             | ---> |   .list_resources()|
|     extension(...)        |      | validate_discovery_  |      |                   |
+---------------------------+      |   extension()        |      +-------------------+
                                   +----------------------+

如何进行

第 1 步：安装依赖项

# 扩展 + Algorand + FastAPI
pip install "x402-avm[extensions,avm,fastapi]"

# 扩展 + Algorand + Flask
pip install "x402-avm[extensions,avm,flask]"

extensions 额外安装 jsonschema>=4.0.0 用于模式验证。

第 2 步：在路由上声明发现扩展

使用 declare_discovery_extension() 在您的路由配置上描述每个端点接受和返回的内容。

对于 GET 端点（查询参数）：

from x402.extensions.bazaar import declare_discovery_extension, OutputConfig

discovery = declare_discovery_extension(
    input={"city": "San Francisco"},
    input_schema={
        "properties": {
            "city": {"type": "string", "description": "城市名称"},
        },
        "required": ["city"],
    },
    output=OutputConfig(
        example={"weather": "sunny", "temperature": 70},
        schema={
            "properties": {
                "weather": {"type": "string"},
                "temperature": {"type": "number"},
            },
            "required": ["weather", "temperature"],
        },
    ),
)

对于 POST 端点（JSON 正文）：

discovery = declare_discovery_extension(
    input={"prompt": "告诉我关于 Algorand 的信息", "max_tokens": 100},
    input_schema={
        "properties": {
            "prompt": {"type": "string"},
            "max_tokens": {"type": "integer"},
        },
        "required": ["prompt"],
    },
    body_type="json",
    output=OutputConfig(
        example={"text": "Algorand 是...", "tokens_used": 42},
    ),
)

第 3 步：将扩展添加到路由配置

将发现字典展开到您的路由的 extensions 字段：

from x402.http import PaymentOption
from x402.http.types import RouteConfig
from x402.schemas import Network

AVM_NETWORK: Network = "algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="

routes = {
    "GET /weather": RouteConfig(
        accepts=[
            PaymentOption(
                scheme="exact",
                pay_to=AVM_ADDRESS,
                price="$0.001",
                network=AVM_NETWORK,
            ),
        ],
        description="天气报告",
        mime_type="application/json",
        extensions={
            **declare_discovery_extension(
                input={"city": "San Francisco"},
                input_schema={
                    "properties": {"city": {"type": "string"}},
                    "required": ["city"],
                },
                output=OutputConfig(
                    example={"weather": "sunny", "temperature": 70},
                ),
            )
        },
    ),
}

第 4 步：在服务器上注册 Bazaar 扩展

from x402.server import x402ResourceServer
from x402.http import FacilitatorConfig, HTTPFacilitatorClient
from x402.extensions.bazaar import bazaar_resource_server_extension
from x402.mechanisms.avm.exact import ExactAvmServerScheme

facilitator = HTTPFacilitatorClient(FacilitatorConfig(url="https://x402.org/facilitator"))
server = x402ResourceServer(facilitator)
server.register(AVM_NETWORK, ExactAvmServerScheme())
server.register_extension(bazaar_resource_server_extension)

第 5 步：在 Facilitator 方面提取和验证

from x402.extensions.bazaar import extract_discovery_info, validate_discovery_extension

# 从支付请求中提取发现信息
discovered = extract_discovery_info(
    payment_payload=payment_payload,
    payment_requirements=payment_requirements,
    validate=True,
)

if discovered:
    print(f"URL: {discovered.resource_url}")
    print(f"Method: {discovered.method}")
    print(f"Description: {discovered.description}")

第 6 步：应用支付中间件

FastAPI：

from fastapi import FastAPI
from x402.http.middleware.fastapi import PaymentMiddlewareASGI

app = FastAPI()
app.add_middleware(PaymentMiddlewareASGI, routes=routes, server=server)

Flask：

from flask import Flask
from x402.http.middleware.flask import payment_middleware

app = Flask(__name__)
payment_middleware(app, routes=routes, server=server)

重要规则 / 指南

发现是链无关的 – 相同的 Bazaar 元数据适用于客户端使用哪种支付网络（AVM、EVM、SVM）。
扩展展开到路由 – 使用 **declare_discovery_extension(...) 将 {"bazaar": {...}} 字典合并到路由的 extensions 字典中。
body_type 确定输入类型 – None（默认）创建查询扩展（GET/HEAD/DELETE）。"json" 创建正文扩展（POST/PUT/PATCH）。
服务器扩展是必需的 – 在服务器上注册 bazaar_resource_server_extension 以在运行时用 HTTP 方法丰富声明。
验证使用 jsonschema – [extensions] 额外安装 jsonschema。验证检查 info 数据是否符合其 schema。

常见错误 / 故障排除

错误	原因	解决方案
`ImportError: jsonschema`	缺少 `[extensions]` 额外	安装 `pip install "x402-avm[extensions]"`
`KeyError: 'bazaar'`	路由上未声明扩展	将 `**declare_discovery_extension(...)` 添加到路由配置 `extensions`
`ValidationResult.valid is False`	扩展信息与模式不匹配	检查示例数据是否符合声明的输入/输出模式
`discovered is None`	支付请求中没有 Bazaar 扩展	确保服务器端声明和扩展注册都已就绪
`body_type not set for POST`	POST 路由被视为查询扩展	将 `body_type="json"` 添加到 `declare_discovery_extension()`

参考资料 / 进一步阅读

REFERENCE.md – Bazaar 扩展的详细 API 参考
EXAMPLES.md – 完整的代码示例
Extensions Examples
x402-avm AVM Documentation