Saltar al contenido principal
TypeScript es una de las formas más recomendadas para integrar Ace Data Cloud X402. El SDK oficial se encarga de las llamadas API normales, el sondeo de tareas, el manejo de errores y los reintentos automáticos; @acedatacloud/x402-client se encarga de firmar el encabezado de solicitud PAYMENT-SIGNATURE al encontrar 402 Payment Required. Direcciones de código fuente y paquetes:

Instalar dependencias

Si se usa Base, se necesita capacidad de firma EVM:
Si se usa Solana, se necesita un adaptador de wallet de Solana o @solana/web3.js:
Salida de comprobación de instalación e importación de un proyecto npm limpio:
Explicación de los resultados:
  • Tanto @acedatacloud/sdk como @acedatacloud/x402-client se pueden instalar desde npm e importar mediante Node.js.
  • ethers se utiliza para la firma de typed data de EVM, y @solana/web3.js se utiliza para la construcción de transacciones de Solana.

Ejemplo de Base

En el navegador se puede usar directamente window.ethereum. En Node.js se puede envolver ethers.Wallet con un provider de estilo EIP-1193.

Ejemplo de wallet de navegador

Al usar MetaMask, Coinbase Wallet o WalletConnect en una aplicación frontend, normalmente se pasa directamente el provider EIP-1193:
La wallet del navegador mostrará una confirmación de firma. Lo que firma el usuario no es un mensaje arbitrario, sino el requisito de pago devuelto por la API: la dirección de recepción, el contrato USDC, el importe, el período de validez y el nonce están todos incluidos en la firma.

Ejemplo de Solana

Solana utiliza SPL USDC TransferChecked. El wallet adapter pasado debe exponer publicKey y signAndSendTransaction.
Actualmente, la ruta de Solana solo admite exact, no admite upto. Si la API devuelve varios accepts, el handler seleccionará el elemento con network = 'solana'. La ruta de Solana se ha verificado en la misma API pública, donde el reintento de pago puede devolver HTTP 200 y ADC_SOLANA_E2E_OK. Las consultas RPC públicas pueden estar limitadas por tasa, por lo que este artículo no escribe el hash de tx de Solana; cuando se necesite conciliación en cadena, utiliza tu propio RPC de Solana o confirma mediante los registros de la consola.

Elegir exact o upto

El handler actual de TypeScript elegirá el primer payment requirement de la red coincidente devuelto por el servidor. La API de Ace Data Cloud normalmente coloca el exact de la misma red antes de upto, por lo que si explícitamente deseas usar medición posterior, debes pasar preferScheme: 'upto'. Ejemplo:
Si el servidor no devuelve un requirement upto para esa red, el handler volverá automáticamente al primer requirement disponible de esa red, normalmente exact. upto requiere una autorización única de Permit2. Actualmente, upto solo se proporciona en Base, por lo que solo se necesita realizar una autorización para Base USDC:
Base upto ha completado la verificación de API pública: HTTP 402 -> HTTP 200, la tx de settlement posterior es 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036. La salida completa se encuentra en la explicación del esquema de facturación.

Qué hace el SDK

El transport de @acedatacloud/sdk ejecutará una vez el payment handler al recibir 402:
El handler devuelto por @acedatacloud/x402-client hará lo siguiente:
  1. Selecciona el payment requirement de la red objetivo de ctx.accepts.
  2. Construye una firma EVM EIP-712 o una transacción de transferencia Solana según la red.
  3. Serializa el envelope como Base64.
  4. Devuelve { headers: { 'PAYMENT-SIGNATURE': '<base64>' } }.
  5. El SDK reintenta automáticamente con el cuerpo de solicitud original.
Esto significa que el código de negocio solo necesita escribirse como una llamada SDK normal, sin necesidad de manejar manualmente los reintentos 402.