x402 Spec V2 Deep-Dive: Decodificando las Cabeceras Base64 Payment-Required

--- ## 1. De V1 a V2: Razones de la Reingeniería de Cabeceras En la versión 1 de x402, los requerimientos de pago se transmitían frecuentemente en el cuerpo (body) de la respuesta HTTP 402 o mediante múltiples cabeceras personalizadas (`X-Payment-Address`, `X-Payment-Amount`, `X-Payment-Network`). Esta arquitectura generaba tres problemas críticos de infraestructura: **Incompatibilidad con Métodos HTTP GET y HEAD:** Las respuestas a peticiones `HEAD` o peticiones que pasan por capas de almacenamiento en caché intermedias (como Varnish o Cloudflare) descartaban o alteraban los cuerpos de respuesta no estándar. **Fragmentación de Metadatos:** Los proxies empresariales a menudo filtran cabeceras personalizadas que inician con `X-`, impidiendo que los clientes reciban los parámetros de pago. **Falta de Tipado Polimórfico:** La V1 no permitía declarar múltiples esquemas de liquidación (e.g. aceptar USDC en Base y simultáneamente en Solana o Polygon) en una sola respuesta atómica. La especificación V2 resolvió estas fricciones unificando todos los parámetros transaccionales en un objeto JSON único, fuertemente tipado y serializado en Base64 bajo la cabecera estándar `PAYMENT-REQUIRED`. EVOLUCIÓN ARQUITECTÓNICA DE CABECERAS x402 x402 Versión 1 (Heredada): ├── X-Payment-Address: 0x742d35... ├── X-Payment-Amount: 0.01 ├── X-Payment-Token: USDC └── X-Payment-Network: base-mainnet (Fragmentado y propenso a filtrado) x402 Versión 2 (Estandarizada): └── PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6MiwiYWNjZXB0cyI6W... (JSON Base64 Unificado) --- ## 2. Decodificación y Estructura de la Cabecera `PAYMENT-REQUIRED` Cuando un servidor devuelve un código `402 Payment Required`, la cabecera `PAYMENT-REQUIRED` encapsula un objeto con la siguiente estructura formal: { "x402Version": 2, "scheme": "exact", "accepts": [ { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "10000", "payTo": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "validUntil": 1787400000, "resource": "https://api.m2mcent.com/v1/solidity-audit", "description": "Auditoría estática de bytecode Solidity por llamada" }, { "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "amount": "10000", "payTo": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU", "validUntil": 1787400000, "resource": "https://api.m2mcent.com/v1/solidity-audit", "description": "Auditoría estática de bytecode Solidity por llamada" } ], "extensions": { "bazaar": { "name": "Solidity Bytecode Auditor", "category": "Cybersecurity & DevSecOps", "slaLatencyMs": 150 } } } Campos Críticos Explicados: `x402Version`: Entero que declara la versión del protocolo (obligatoriamente `2`). `network`: Cadena formateada bajo el estándar **CAIP-2 (Chain Agnostic Identifier Protocol)**. Por ejemplo, `eip155:8453` identifica inequívocamente a Base Mainnet (`8453` es el EIP-155 Chain ID). `asset`: Dirección del contrato inteligente del token ERC-20 (o mint address en Solana). `amount`: Valor en unidades mínimas indivisibles (en USDC, con 6 decimales, `10000` representa $0.01 USDC). `validUntil`: Timestamp UNIX tras el cual el desafío expira y la firma debe ser regenerada. `extensions`: Espacio de nombres reservado para metadatos semánticos requeridos por catálogos de agentes (como Smithery o el registro M2MCent). --- ## 3. La Cabecera `PAYMENT-SIGNATURE`: El Reintento del Cliente El cliente decodifica el Base64, selecciona la red de su preferencia (por ejemplo, Base L2), firma la autorización criptográfica y reenvía la petición adjuntando la cabecera `PAYMENT-SIGNATURE`: // Objeto que se serializa a Base64 en PAYMENT-SIGNATURE interface PaymentSignaturePayload { x402Version: 2; selectedNetwork: "eip155:8453"; scheme: "exact"; authorization: { from: string; // Dirección de billetera del agente to: string; // Dirección del proveedor o Bóveda Escrow value: string; // Monto autorizado validAfter: number; // Timestamp inicial validBefore: number; // Timestamp límite nonce: string; // Hexadecimal de 32 bytes v: number; // Parámetro v de ECDSA r: string; // Parámetro r de ECDSA s: string; // Parámetro s de ECDSA }; } --- ## 4. La Cabecera `PAYMENT-RESPONSE`: El Recibo de Liquidación Cuando el servidor valida y procesa el cobro a través del Facilitador, responde con código `200 OK` y emite la cabecera `PAYMENT-RESPONSE`, que contiene la prueba criptográfica de liquidación on-chain: { "x402Version": 2, "status": "settled", "network": "eip155:8453", "txHash": "0x4a8f9c1e7d2b3a0f5e6d8c9b1a2f3e4d5c6b7a8f9e0d1c2b3a4f5e6d7c8b9a0f", "blockNumber": 18945201, "gasUsedUsdc": "0.0002", "timestamp": 1787399500 } Este recibo permite que el agente almacene el hash de la transacción para conciliaciones contables internas o para presentar pruebas de pago ante disputas entre enjambres. --- ## 5. Implementación en TypeScript: Parser y Serializador de Cabeceras ```typescript export class X402HeaderCodec { /** * Codifica un objeto de desafío a cabecera PAYMENT-REQUIRED */ static encodeChallenge(challenge: object): string { const jsonStr = JSON.stringify(challenge); return Buffer.from(jsonStr, 'utf-8').toString('base64'); } /** * Decodifica una cabecera PAYMENT-REQUIRED recibida del servidor */ static decodeChallenge(headerValue: string): any { const jsonStr = Buffer.from(headerValue, 'base64').toString('utf-8'); const parsed = JSON.parse(jsonStr); if (parsed.x402Version !== 2) { throw new Error(`Versión x402 no soportada: ${parsed.x402Version}`); } return parsed; } /** * Codifica la firma del agente para PAYMENT-SIGNATURE */ static encodeSignature(signaturePayload: PaymentSignaturePayload): string { return Buffer.from(JSON.stringify(signaturePayload), 'utf-8').toString('base64'); } } ``` --- ## 6. Buenas Prácticas y Manejo de Casos Límite **Validación de Padding en Base64:** Asegúrate de que tu parser maneje tanto codificación estándar con padding (`=`) como URL-safe Base64 sin padding. **Tolerancia al Sesgo Temporal (Clock Skew):** Configura el validador del servidor con un margen de tolerancia de ±30 segundos en `validAfter` y `validBefore` para compensar discrepancias de reloj entre servidores distribuidos. **Codificación UTF-8 Estricta:** Las descripciones en lenguaje natural dentro del objeto de desafío deben codificarse en UTF-8 antes de la conversión a Base64 para evitar corrupción de caracteres especiales. --- ### Conclusión y Llamada a la Acción (CTA) La especificación x402 V2 transforma el código HTTP 402 en un canal de negociación financiera robusto, polimórfico e interoperable con cualquier infraestructura web moderna. Al estandarizar la codificación Base64 y los identificadores CAIP-2, garantiza que los agentes de IA puedan comerciar de manera determinista a escala global. ¿Quieres construir herramientas compatibles con el estándar oficial? Consulta la referencia completa de la especificación V2 y prueba los endpoints en vivo en [M2MCent Documentation](https://m2mcent.com).