Saltar al contenido principal
X402 es un protocolo de pagos en cadena basado en HTTP 402 Payment Required. Mediante la capacidad X402 de Ace Data Cloud, los solicitantes pueden completar pagos en cadena directamente con USDC en cada solicitud de API, sin crear un API Token ni recargar previamente el saldo de la cuenta. Este conjunto de documentos está organizado según el orden real de integración: primero complete una solicitud mínima, luego integre el SDK y después comprenda las redes, los esquemas de facturación, el pago de pedidos y el Facilitator. Se recomienda leer de arriba abajo según la siguiente tabla.

Ruta de integración recomendada

Si solo desea llamar a la API de Ace Data Cloud, priorice el uso del SDK oficial:
  • TypeScript:@acedatacloud/sdk + @acedatacloud/x402-client
  • Python:acedatacloud + acedatacloud-x402
Código fuente público y direcciones de paquetes: El SDK completará automáticamente los pasos de la primera solicitud sin autenticación, el análisis de 402 Payment Required, la llamada al payment handler y el reintento con PAYMENT-SIGNATURE. Solo necesita preparar una billetera con USDC y seleccionar la red que desea utilizar. Si desea que su propia API también admita cobros con X402, deberá leer la documentación de Facilitator para comprender la relación entre paymentRequirements, paymentPayload, /verify y /settle.

Estado de soporte

Ace Data Cloud X402 ha completado la validación en las rutas de API pública, SDK oficial, Facilitator y liquidación en cadena. La siguiente tabla resume el estado actual según las dimensiones de capacidad más utilizadas durante la integración de desarrolladores. La siguiente salida solo se utiliza para ilustrar la forma de respuesta de las rutas validadas. Durante la integración real, tome siempre como referencia los accepts devueltos por la API actual.
Descripción:
  • Los paquetes npm y PyPI se instalaron e importaron correctamente en un entorno limpio.
  • Las solicitudes de API no pagadas devuelven 402, y accepts contiene métodos de pago disponibles para Base y Solana.
  • accepts[].network es un identificador CAIP-2; los clientes deben coincidir con la cadena mediante la cadena CAIP-2 al seleccionar una red.
  • Tanto el SDK de TypeScript como el SDK de Python pueden gestionar automáticamente 402 y completar el reintento pagado.
  • Base exact, Base upto y los pagos de pedidos tienen direcciones de explorador que se pueden abrir públicamente.
  • El límite máximo firmado de Base upto es 95215 USDC atómicos, y el settlement real es de 3 USDC atómicos, lo que refleja la característica de settlement por uso real de la medición posterior.
  • Solana exact ha verificado HTTP 402 -> HTTP 200 y la salida del modelo. Dado que las consultas RPC públicas pueden estar limitadas, se recomienda utilizar tu propio RPC de Solana o los registros de settlement de la plataforma para confirmar la firma de la transacción durante una conciliación estricta.

Consideraciones de integración

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

Alcance que se puede verificar públicamente

Antes de la integración, se pueden verificar primero estos puntos de acceso públicos y comportamientos del SDK:
  • Las solicitudes de API sin Authorization ni PAYMENT-SIGNATURE devolverán 402 Payment Required, y el accepts de la respuesta es la única base de firma para esta solicitud.
  • Tanto el SDK de TypeScript como el SDK de Python proporcionan un payment handler; la capa de transporte del SDK llamará al handler y volverá a intentarlo una vez después de recibir un 402.
  • https://facilitator.acedata.cloud/.well-known/x402: devuelve las redes, schemes y puntos de acceso de protocolo compatibles con el Facilitator; el precio de la API sigue estando sujeto al 402 devuelto en tiempo real por la solicitud de destino.
  • https://facilitator.acedata.cloud/supported: devuelve las redes y schemes compatibles con el Facilitator.
  • El repositorio X402Client incluye herramientas avanzadas de verificación en cadena, que pueden utilizarse para confirmar firmas, reintentos y comportamientos de settlement; la salida de las herramientas no sustituye al accepts devuelto por la API en línea.
upto pertenece al settlement de medición posterior y es adecuado para API cuyo uso real solo se conoce después de la respuesta, como completados de chat y llamadas a modelos. Actualmente, solo Base ofrece upto; si falla la verificación de la firma, comprueba que el chain id, la dirección del facilitator, el spender, el contrato USDC y el allowance de Permit2 coincidan con la respuesta 402.