Saltar al contenido principal
X402 es un protocolo de pago on-chain de “facturación por HTTP 402” propuesto por Coinbase: el servidor devuelve 402 Payment Required en solicitudes sin token, adjuntando un campo accepts: [...] que enumera las cadenas / activos / precios aceptables; el cliente firma localmente una autorización (Permit2 / EIP-712 en EVM, autorización de transferencia de token SPL en Solana), coloca el envelope codificado en base64 en el encabezado PAYMENT-SIGNATURE y reenvía la solicitud. Tras la validación, el servidor realiza realmente la liquidación on-chain y luego devuelve el resultado de negocio.
El cliente X402 de Ace Data Cloud llama directamente a la API de destino, y utiliza el 402 Payment Required y accepts devueltos en tiempo real por esa solicitud como base para el precio y la firma. La capacidad de pago del Facilitator puede verificarse en /.well-known/x402.
Tanto @acedatacloud/sdk como acedatacloud exponen un gancho paymentHandler: cuando una solicitud enviada por el propio SDK recibe un 402, llama al handler que inyectaste para obtener el encabezado PAYMENT-SIGNATURE, y después reenvía la solicitud original. Al usar @acedatacloud/x402-client / acedatacloud-x402 junto con el SDK, todo el proceso es completamente transparente para el código de negocio——solo usas client.openai.chat.completions.create(...), y parece idéntico al modo token, pero por debajo se paga por llamada y no se necesita recargar por adelantado. Este artículo:
  • Recorre realmente la cadena de «sin token + inyección de handler X402» del lado de TS (verificación T12)
  • Enumera las diferencias entre las dos cadenas de firma EVM / Solana
  • Proporciona tres adaptaciones: modo de clave privada viem, modo de billetera de navegador y modo Python EVMAccountSigner
  • Explica claramente el campo preferScheme / prefer_scheme, con el que es fácil cometer errores

I. Resumen del protocolo (lectura obligatoria)

Una llamada X402 exitosa involucra 3 RTT HTTP:
El envelope X402 es un fragmento JSON, que se codifica en base64 y se coloca en el encabezado PAYMENT-SIGNATURE. Estructura (extracto):
La capa superior del envelope es x402Version: 2, y utiliza el objeto accepted para declarar el scheme y network seleccionados en esta ocasión (identificador CAIP-2). preferScheme / prefer_scheme se utiliza para elegir la preferencia cuando el servidor proporciona simultáneamente múltiples scheme. Si el servidor solo expone exact, este campo se ignorará; si se establece upto pero el servidor no lo expone, se volverá al primer elemento coincidente.

II. TypeScript: dos usos, billetera de navegador + viem de servidor

Instalación

Versiones probadas:

Firma completa de createX402PaymentHandler

El valor de retorno es un (ctx) => Promise&lt;{ headers: Record<string, string> }>, que coincide exactamente con la firma del gancho paymentHandler del SDK.

Uso 1: navegador (MetaMask / WalletConnect)

En la primera llamada, el navegador mostrará dos avisos de firma: el primero es un approve único de Permit2 para USDC (el importe es MaxUint256, escrito on-chain); el segundo es la firma EIP-712 del envelope X402 (no se envía on-chain, solo sirve para que el facilitator la verifique). Las llamadas posteriores solo necesitan la segunda firma; en términos de experiencia es “hacer clic una vez para firmar → obtener el resultado”.

Uso 2: servidor Node + clave privada viem (adecuado para backend / CLI)

@acedatacloud/x402-client solo acepta proveedores EIP-1193 en el lado TS——no gestiona directamente las claves privadas. En escenarios Node / CLI, la práctica estándar es usar viem para empaquetar la clave privada como WalletClient, y luego usar el adaptador EIP-1193 interno de @ethereumjs/util o viem.
Si consideras que la adaptación EIP-1193 de viem no es lo suficientemente estable, también puedes usar el signEVMUptoPayment de nivel más bajo y conectar por tu cuenta la ruta accepts → signed envelope → PAYMENT-SIGNATURE header, omitiendo el hook del SDK; sin embargo, se recomienda seguir priorizando createX402PaymentHandler, para evitar tener que mantener las actualizaciones del protocolo por tu cuenta.

Uso 3: Solana

Actualmente, en la cadena Solana solo se expone el scheme exact, por lo que preferScheme no tiene efecto en Solana.

III. Python: modo de clave privada

El acedatacloud-x402 de Python sigue la ruta de firmar directamente con la clave privada (sin abstracción EIP-1193), y es más adecuado para servidores / ejecutores de tareas.

Instalación

Versiones verificadas:

EVM (Base)

Solana

Approve único (solo la primera vez en EVM)

En EVM Base, X402 utiliza Permit2, por lo que la wallet debe realizar una vez un approve de MaxUint256 al contrato Permit2 para USDC. acedatacloud-x402 incluye approve_permit2:
Esta transacción solo debe enviarse una vez; posteriormente, todos los pagos X402 de EVM utilizarán esta autorización. Solana no lo necesita.

IV. Verificación de ejecución real

Objetivo de prueba: el SDK de TS no pasa token, inyecta el handler X402 y puede construir e iniciar solicitudes normalmente (verificación ligera sin consumir USDC real en cadena).
Salida:
Los resultados indican:
  • No se pasó apiToken, y la construcción del SDK no produce errores, lo que demuestra que el modo X402 es efectivamente una alternativa válida al token.
  • createX402PaymentHandler devuelve una función (hook), que el SDK solo invocará al recibir un 402.
  • La prueba integral que confirma que el pago real en cadena funciona, dado que implica descuentos reales de USDC, no se ha incluido en este tutorial; puedes consultar el ejemplo e2e en la guía de integración X402.
En Python, create_x402_payment_handler también realizó la misma verificación — el valor de retorno de la función es callable, y la construcción de AceDataCloud(...) no produce errores al inyectar payment_handler=.... La semántica está alineada en ambos lados.

V. Comparación con el «modo Bearer token»

VI. Errores comunes

  1. La clase chat debe usar preferScheme=upto: usar exact hará que el facilitator descuente USDC según maxAmountRequired (no según el uso real).
  2. No pases una clave privada sin envolver a createX402PaymentHandler en Node: el paquete TS no acepta { privateKey }, debe envolverse como un provider EIP-1193 (se recomienda WalletClient de viem).
  3. La primera llamada requiere doble firma: primero se firma el approve de Permit2 (en cadena, con gas), y después se firma el envelope X402 (fuera de cadena). Las llamadas posteriores solo requieren la segunda.
  4. Solana no tiene el concepto de Permit2: se firma directamente la autorización de transferencia de tokens SPL, sin necesidad de approve; pero actualmente en la cadena de Solana solo se admite exact.
  5. Distingue entre errores de negocio y errores de pago: 402 → el fallo del handler lanza X402SignError (el tipo específico varía según la cadena); tras el reenvío, los errores de la interfaz de negocio (401 / 422 / 5xx) siguen clasificándose como excepciones normales del SDK.
  6. La forma más estable de adaptar viem: evmProvider: walletClient as any pierde la comprobación de tipos, pero ofrece la mejor compatibilidad; si quieres conservar los tipos, envuelve por separado .transport.request de viem en un objeto { request } y pásalo.

Más información