Skip to main content
X402 es un protocolo de pago en cadena basado en HTTP 402 Payment Required. A través de las capacidades X402 de Ace Data Cloud, el llamador puede realizar pagos en cadena directamente con USDC en cada solicitud API sin necesidad de crear un token API o recargar el saldo de la cuenta. Este conjunto de documentos está organizado en el orden de integración real: primero ejecutar una solicitud mínima, luego integrar el SDK, y después entender la red, los planes de facturación, el pago de pedidos y el Facilitador. Se recomienda leer la tabla a continuación de arriba hacia abajo.

​
Ruta de integración recomendada

Si solo deseas llamar a la API de Ace Data Cloud, utiliza primero el SDK oficial:
  • TypeScript: @acedatacloud/sdk + @acedatacloud/x402-client
  • Python: acedatacloud + acedatacloud-x402
Direcciones de código abierto y paquetes: El SDK completará automáticamente la primera solicitud sin autenticación, analizará 402 Payment Required, llamará al manejador de pagos y reintentará estos pasos con PAYMENT-SIGNATURE. Solo necesitas preparar una billetera con USDC y elegir la red que deseas utilizar. Si deseas que tu API también soporte pagos X402, necesitarás leer la documentación del Facilitador y entender la relación entre paymentRequirements, paymentPayload, /verify y /settle.

​
Estado de soporte

Ace Data Cloud X402 ha completado la validación en la API pública, el SDK oficial, el Facilitador y la ruta de liquidación en cadena. La siguiente tabla resume el estado actual según las capacidades más utilizadas por los desarrolladores al integrarse. La siguiente salida es solo para ilustrar la forma de retorno de las rutas validadas. Al integrarse, siempre consulta el accepts devuelto por la API actual.
Instrucciones:
  • Los paquetes de npm y PyPI se han instalado e importado correctamente en un entorno limpio.
  • La solicitud de API no pagada devuelve 402, accepts incluye los métodos de pago disponibles para Base, SKALE y Solana.
  • accepts[].network es la identificación CAIP-2, el cliente debe coincidir con la cadena CAIP-2 al seleccionar la red.
  • Tanto el SDK de TypeScript como el SDK de Python pueden manejar automáticamente el 402 y completar el reintento pagado.
  • Base exact, SKALE exact, Base upto y el pago del pedido tienen direcciones de explorador que se pueden abrir públicamente.
  • El límite de firma de Base upto es de 95215 USDC atómicos, el asentamiento real es de 3 USDC atómicos, lo que refleja la característica de liquidación por medición posterior según el uso real.
  • Solana exact ha verificado HTTP 402 -> HTTP 200 y la salida del modelo. Dado que la consulta RPC pública puede estar limitada, se recomienda utilizar RPC de Solana propio o registros de liquidación del lado de la plataforma para confirmar la firma de la transacción.

​
Consideraciones para la integración

Al integrar, los desarrolladores deben centrarse en los requisitos de pago en tiempo real devueltos por la solicitud actual, en lugar de copiar los montos o direcciones de ejemplo en la documentación:
  • accepts[].maxAmountRequired es el monto máximo que se puede firmar en la solicitud actual.
  • accepts[].asset es el contrato o mint de USDC que se utilizará en esta solicitud.
  • accepts[].extra.chainId, accepts[].extra.facilitatorAddress y accepts[].extra.verifyingContract participarán en la firma de datos tipados de EVM.
  • upto requiere que la billetera autorice primero el USDC de la cadena objetivo con Permit2; si no está autorizado, devolverá PERMIT2_ALLOWANCE_REQUIRED.
  • Si se desea explícitamente utilizar la medición posterior, se debe pasar preferScheme: 'upto' en el SDK de TypeScript; de lo contrario, el SDK elegirá el primer requisito disponible devuelto por el servidor en esa red.

​
Rango de verificación pública

Antes de la integración, se pueden verificar estos puntos de entrada públicos y el comportamiento del SDK:
  • Las solicitudes de API sin Authorization o PAYMENT-SIGNATURE devolverán 402 Payment Required, y accepts en la respuesta es la única base de firma para esta solicitud.
  • Tanto el SDK de TypeScript como el SDK de Python proporcionan un controlador de pago; la capa de transporte del SDK llamará al controlador y reintentará una vez al recibir 402.
  • https://facilitator.acedata.cloud/.well-known/x402: devuelve las redes, esquemas y puntos finales de protocolo admitidos por el Facilitador; el precio de la API seguirá siendo el 402 devuelto en tiempo real por la solicitud objetivo.
  • https://facilitator.acedata.cloud/supported: devuelve las redes y esquemas admitidos por el Facilitador.
  • El repositorio de X402Client incluye herramientas avanzadas de verificación en cadena que se pueden utilizar para confirmar firmas, reintentos y comportamientos de liquidación; la salida de la herramienta no reemplaza la accepts devuelta por la API en línea.
upto pertenece a la liquidación por medición posterior, adecuada para API donde el uso real, como la finalización de chat o la llamada de modelo, solo se conoce después de la respuesta. Actualmente, solo Base ofrece upto; si la verificación de la firma falla, verifique si el id de la cadena, la dirección del facilitador, el gastador, el contrato de USDC y la asignación de Permit2 coinciden con la respuesta 402.