## ¿Qué es x402?

x402 convierte el código de estado HTTP 402 `Payment Required` en un protocolo de pago real. Cuando un agente accede a un endpoint pagado, el servidor devuelve una respuesta 402 con un encabezado `Payment-Required` que contiene instrucciones de pago estructuradas. El agente (o su wallet) inspecciona el encabezado, decide si el precio es aceptable, paga en cadena, adjunta el recibo a un reintento y recibe la respuesta.

Conceptualmente, x402 finalmente completa el código de estado HTTP 402 que ha permanecido sin uso en la especificación HTTP desde 1996 — la especificación reservó el código para "Payment Required" pero nunca especificó *cómo* debía pagar un cliente. x402 especifica el mecanismo: USDC en Base, intenciones de pago firmadas, liquidación mediada por facilitador, y un formato de descubrimiento para que los agentes encuentren endpoints pagados antes de llamarlos.

## Por qué importa x402

La monetización tradicional de API está construida para humanos: registrarse, generar una clave de API, gestionar una tarjeta de crédito, recibir una factura mensual. Cada paso requiere una interfaz, una cuenta y una relación fuera de banda entre el proveedor de la API y el desarrollador.

Los agentes autónomos no tienen esas cosas. Un agente que llama a una API pagada por primera vez necesita:

- Descubrir el precio *antes* de comprometerse
- Pagar programáticamente, sin aprobación humana
- Liquidar la transacción en segundos, no en días
- Recibir un recibo que el proveedor de la API pueda verificar

x402 aborda los cuatro con un único mecanismo. El precio está en el encabezado 402. El pago es una transacción firmada en Base. La liquidación es sub-segundo. El recibo es la confirmación en cadena.

Esto hace de x402 la primitiva de pago fundacional para la web agéntica — análogo a lo que fue TLS para la web comercial, o OAuth para la autorización delegada: un protocolo que convierte algo previamente mediado por humanos en algo que las máquinas pueden negociar de extremo a extremo.

## Cómo funciona

1. El agente envía una petición a un endpoint pagado
2. El servidor devuelve **HTTP 402** con un encabezado `Payment-Required` codificado en base64
3. El encabezado contiene: monto, activo (USDC), red (Base), wallet receptor y facilitador
4. El agente paga vía el facilitador (p. ej., Coinbase)
5. El agente reintenta la petición con un encabezado `Payment` que contiene el recibo
6. El servidor verifica el pago a través del facilitador y sirve la respuesta

El flujo completo tarda unos pocos segundos de extremo a extremo. Sin claves de API. Sin suscripciones. Sin humano en el bucle.

## x402 frente a monetización tradicional de API

| Aspecto | Claves de API + suscripción | x402 |
|---|---|---|
| Registro | Cuenta requerida | Ninguno |
| Autenticación | Clave de API por cuenta | Pago por petición |
| Modelo de facturación | Suscripción mensual | Pago por petición |
| Descubrimiento | Fuera de banda (docs, ventas) | En el protocolo (encabezado 402) |
| Liquidación | Ciclo de factura (~30 días) | Sub-segundo (en cadena) |
| Modo de fallo | Cuota excedida → 429 | Pago insuficiente → 402 |
| Compatibilidad con agentes | Difícil (gestión de cuentas) | Nativa |
| Limitaciones geográficas | Comunes (restricciones de Stripe) | Mínimas (en cadena) |

El cambio clave: x402 pone el precio dentro del propio protocolo, donde cualquier agente puede leerlo. Con claves de API, el precio existe sólo en un contrato negociado entre humanos. Con x402, el precio está en la respuesta HTTP, de la misma manera que lo está el código de estado — metadatos de transporte de primera clase, no papeleo.

## Conceptos clave

- **Facilitador**: Un servicio que verifica y liquida pagos. Define `"facilitator": "coinbase"` en tu x402.json para usar el facilitador de Coinbase en Base mainnet.
- **Envelope v2**: El formato de encabezado actual. Añade catálogos de servicios estructurados, descubrimiento Bazaar y opciones de pago más ricas. Usa siempre v2.
- **Red**: Los pagos ocurren en Base (`eip155:8453`) usando USDC. El contrato USDC en Base es `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`.
- **Precio por petición**: Cada llamada de API tiene su propio precio — sin suscripciones, sin niveles, sin claves de API.
- **Servicios descubribles**: Marca servicios con `"discoverable": true` para aparecer en el [x402 Bazaar](/kb/es/bazaar) — un catálogo de endpoints pagados que los agentes navegan.

## Quién usa x402

El ecosistema x402 se ha formado en torno a dos anclas:

- **Coinbase Developer Platform** — el creador del protocolo. Distribuye SDKs oficiales en TypeScript, Go y Python; opera el facilitador canónico en Base mainnet.
- **Tempo [MPP](/kb/es/mpp)** — el proxy de pagos respaldado por Paradigm y Stripe. Tempo opera proxies `*.mpp.tempo.xyz` que traducen entre x402 y los rieles de pago tradicionales para sitios que no han implementado x402 de forma nativa.

Más allá de esas anclas, proveedores individuales de API, runtimes de agentes y operadores de servidores [MCP](/kb/es/mcp) están integrando x402 para facturación por llamada — herramientas MCP pagadas, APIs de datos medidas, endpoints de inferencia de IA y mercados de agentes.

## Cómo añadir x402 a tu servicio

### 1. Instala el SDK

```bash
npm install @coinbase/x402-express
```

### 2. Añade middleware a tu app Express

```javascript
import { paymentMiddleware } from '@coinbase/x402-express';

app.use('/api/paid-endpoint', paymentMiddleware({
  payTo: '0xYourWalletAddress',
  amount: '100000', // 0.10 USDC (unidad mínima)
  network: 'base',
  facilitator: 'coinbase',
}));
```

### 3. Publica el archivo de descubrimiento

Sirve `/.well-known/x402.json` para que los agentes encuentren tus endpoints pagados:

```json
{
  "x402Version": 2,
  "name": "Tu Servicio",
  "network": "base",
  "facilitator": "coinbase",
  "payTo": "0xYourWalletAddress",
  "services": [{
    "method": "POST",
    "path": "/api/paid-endpoint",
    "amount": "100000",
    "discoverable": true
  }]
}
```

### 4. Prueba el flujo

```bash
curl -i https://your-domain.com/api/paid-endpoint
# Espera: HTTP/1.1 402 Payment Required
# Espera: Payment-Required: <instrucciones de pago en base64>
```

Decodifica el encabezado `Payment-Required` (base64 → JSON) y confirma que el monto, activo, receptor y facilitador coinciden con la configuración del middleware.

## Errores comunes y depuración

- **402 sin encabezado Payment-Required**: Middleware no configurado. Confirma que `payTo` y `amount` están establecidos.
- **Encabezado Payment rechazado**: El recibo es por el monto incorrecto, activo incorrecto o ha expirado. La mayoría de los facilitadores rechazan recibos de más de unos pocos minutos.
- **Discrepancia de dirección de wallet**: `payTo` en el middleware no coincide con el receptor del recibo. Debe coincidir exactamente.
- **Discrepancia de red**: El recibo está en una cadena diferente a la declarada. Confirma que `network` es `base` en middleware y x402.json.
- **Facilitador inalcanzable**: El servicio facilitador está caído. Usa un facilitador de respaldo o falla abierto durante interrupciones.

El escáner de agentgrade prueba estos directamente — su comprobación x402 verifica que las respuestas 402 en vivo se parsean limpiamente y que el archivo de descubrimiento coincide con lo que devuelven los endpoints.

## Preguntas frecuentes

### ¿Es x402 un protocolo de blockchain o un protocolo HTTP?

Ambos. El transporte es HTTP (un estado 402 con encabezados estructurados). La liquidación es en cadena (USDC en Base). x402 es el puente — el protocolo que permite a servidores HTTP y clientes HTTP negociar un pago que se liquida en una blockchain.

### ¿Necesito una wallet de cripto para aceptar pagos x402?

Sí. Necesitas una wallet de Base para recibir USDC. El CDP de Coinbase lo hace manejable para equipos no nativos en cripto — puedes aprovisionar una wallet custodiada vía API sin tocar claves.

### ¿Cuál es la diferencia entre x402 y Stripe?

Stripe es el riel tradicional dominante: claves de API por cuenta, suscripciones mensuales, detección de fraude entrenada con compradores humanos. x402 es por petición, nativo para agentes, y se liquida en cadena. Son complementarios — Stripe para checkout humano, x402 para acceso medido por agentes. Tempo MPP hace de puente entre ambos.

### ¿Está x402 listo para producción?

Sí. x402 v2 es soportado por Coinbase con SDKs oficiales en TypeScript, Go y Python. El facilitador canónico opera en producción y el ecosistema de servicios pagados está creciendo.

### ¿Pueden los agentes pagarse entre sí con x402, no sólo a proveedores de API?

Sí. A x402 no le importa si el "servidor" es una API operada por humanos, un agente o una herramienta MCP. Cualquier respondedor HTTP puede devolver un 402 y cualquier solicitante HTTP puede pagar. El trabajo medido entre agentes es uno de los casos de uso más activos.

### ¿Por qué USDC y no ETH?

Estable. Precio predecible. La mayoría de proveedores de API fijan precios en dólares y quieren un activo estable en dólares para liquidación; los activos volátiles crean fricción contable que anula el modelo por petición.

### ¿Qué pasa si el agente no tiene fondos?

La wallet devuelve fondos insuficientes y la llamada falla. No hay un flujo de reintento-comprar-créditos en el protocolo en sí — financiar es asunto de la wallet, no de la API.

### ¿Qué tan descubribles son los endpoints x402?

Los endpoints marcados como `"discoverable": true` en tu x402.json aparecen en el x402 Bazaar — el catálogo público de servicios pagados. Los agentes navegan el Bazaar igual que los desarrolladores navegan npm.

## Madurez de la especificación

**Listo para producción.** x402 v2 es el envelope actual, soportado por Coinbase con SDKs oficiales en TypeScript, Go y Python. El protocolo es estable, el facilitador canónico opera en producción, y el ecosistema se expande por proveedores de herramientas MCP, APIs de datos y mercados de agentes.

## Más información

- [x402.org](https://www.x402.org/) — Especificación del protocolo
- [Documentación de Coinbase x402](https://docs.cdp.coinbase.com/x402/docs/welcome) — Guía de SDK e integración
- [Paquete npm x402](https://www.npmjs.com/package/@coinbase/x402-express) — Middleware de Express
- [Preparación para Agentes](/agent-readiness) — Cómo encaja x402 en el panorama más amplio de preparación para agentes

## Relacionado

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