Bazaar — Descubrimiento de Servicios

¿Qué es Bazaar?

Bazaar es la capa de descubrimiento de x402. Responde a la pregunta: "¿Qué puedo comprar aquí y cuánto cuesta?" Los agentes navegan un catálogo estructurado de servicios, precios y esquemas de entrada/salida en /.well-known/x402.json.

Cómo funciona

Publica /.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" } }
        }
      }
    }
  ]
}

Campos requeridos

x402Version — Versión de la especificación (usa 2; el escáner también acepta 1 — ver más abajo)
name — Nombre del proveedor
network — Blockchain (por ejemplo, base, o la forma CAIP eip155:8453 bajo v2)
facilitator — Proveedor de liquidación (por ejemplo, coinbase)
payTo — Dirección de billetera que recibe los pagos
services[] — Array de endpoints de pago con method y path

v1 vs v2

x402 v2 se lanzó en diciembre de 2025 y es la especificación actual, pero los servidores v1 siguen siendo comunes. AgentGrade acepta ambos. Cada diferencia a nivel de protocolo:

Nombres de encabezados: v1 usaba encabezados con prefijo X- (X-PAYMENT en la solicitud de reintento, X-PAYMENT-RESPONSE en éxito). v2 elimina el prefijo X- (PAYMENT-SIGNATURE, PAYMENT-RESPONSE) — el convenio X- quedó obsoleto por la RFC 6648 en 2012.
Dónde vive el desafío: v1 ponía el desafío de pago en el cuerpo JSON de la respuesta 402. v2 lo mueve al encabezado de respuesta PAYMENT-REQUIRED (JSON codificado en base64), liberando el cuerpo para una página de paywall legible por humanos.
Renombrado del campo amount: las entradas de accepts[] en v1 usaban maxAmountRequired para el precio. v2 lo renombra a amount.
Forma del campo resource: v1 ponía resource (como cadena URL), description y mimeType dentro de cada entrada de accepts[]. v2 los eleva a un objeto resource de nivel superior con campos url, description y mimeType — declarados una sola vez para toda la respuesta 402 en lugar de duplicarse por cada entrada accepts.
Identificación de cadena: v1 usaba cadenas libres como "base" para el campo network. v2 estandariza en IDs CAIP como eip155:8453, para que el mismo campo funcione en cadenas no-EVM y rieles off-chain.
payTo dinámico: v1 declaraba un único destinatario estático por servicio en el catálogo de descubrimiento. v2 permite que el servidor calcule payTo por solicitud — útil para marketplaces que enrutan pagos a vendedores individuales.
Sesiones: v1 requería el flujo completo de pago en cada llamada. v2 añade sesiones controladas por wallet (Sign In With X402) — firmas una vez, el servidor emite una sesión y las llamadas siguientes saltan el handshake.

Si vas a construir algo nuevo, hazlo en v2. Si auditas un servidor v1 existente, el escáner no te penalizará por estar en v1 — pero las diferencias de v2 son ganancias reales de eficiencia.

extensions.bazaar en el encabezado live 402

Cuando un agente llama a un endpoint de pago sin haber pagado, tu servidor devuelve HTTP 402 con un encabezado Payment-Required codificado en base64. El payload JSON de ese encabezado debe declarar extensions.bazaar para que los agentes sepan que el endpoint forma parte de un catálogo descubrible. El payload JSON antes de la codificación base64 (forma v2):

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

Sin extensions.bazaar, los agentes que reciben un 402 no tienen señal alguna de que el endpoint también está catalogado en /.well-known/x402.json — pueden tratarlo como un endpoint de pago aislado en lugar de parte de un servicio explorable.

Madurez de la especificación

Parte de x402 v2. El descubrimiento Bazaar está definido dentro de la especificación de x402.

Más información

x402.org — Especificación del protocolo x402 (incluye Bazaar)

Relacionado

OpenAPI
A2A