Saltar al contenido principal
Este tutorial utiliza una solicitud mínima de API para explicar el flujo completo de Ace Data Cloud X402. El objetivo no es escribir primero código complejo, sino entender primero: por qué la primera solicitud devuelve 402, qué contiene accepts y cómo PAYMENT-SIGNATURE convierte la misma solicitud de API en una solicitud pagada.

Preparativos

Necesitas preparar: No se necesita un API Token al llamar a Ace Data Cloud API mediante X402. La primera solicitud del SDK no incluye Authorization, Gateway devolverá 402 Payment Required y los requisitos de pago; el SDK vuelve a intentarlo automáticamente después de firmar.

Instalar el SDK

Código fuente y direcciones de los paquetes: TypeScript:
Python:
Si deseas utilizar Solana, también necesitas instalar las dependencias correspondientes:
La dependencia de signer de Solana para la versión de Python ya está incluida en acedatacloud-x402. La salida de la comprobación de instalación e importación en un entorno temporal limpio:
Resultados:
  • Tanto los paquetes npm como los paquetes PyPI son paquetes publicados reales, no nombres de marcador de posición en la documentación.
  • acedatacloud-x402[cli] instala la CLI, y el subcomando approve-permit2 puede utilizarse para la autorización Permit2 en escenarios upto.

La primera solicitud devolverá 402

Primero puedes usar curl para ver qué devuelve una solicitud sin pagar. El siguiente ejemplo no generará ningún cargo, porque no incluye PAYMENT-SIGNATURE:
El cuerpo de la respuesta incluirá un array accepts, cuya estructura habitual es la siguiente:
El mismo contenido del desafío también se coloca en formato base64 en el encabezado de respuesta PAYMENT-REQUIRED, lo que permite al cliente leer los requisitos de pago sin analizar el body. El resumen de salida del programa para solicitudes no pagadas de la API de producción es el siguiente:
Resultados:
  • La primera solicitud no incluye Authorization ni PAYMENT-SIGNATURE, por lo que devuelve HTTP 402 y no genera ningún cargo.
  • accepts es la única base de firma fiable para esta solicitud, e incluye las redes opcionales, el scheme, el límite de importe, la dirección de cobro y la dirección del activo.
  • network es un identificador CAIP-2, y el cliente debe coincidir con la cadena CAIP-2 al seleccionar la red.
  • El importe máximo para esta solicitud mínima de chat de gpt-4o-mini es 95215 atomic USDC, es decir, 0.095215 USDC.
  • Cada solicitud debe leer la respuesta 402 de esa ocasión; no codifiques de forma rígida el importe de ejemplo en el código de negocio.
Significado de los campos:

Completar el reintento de pago con el SDK

A continuación se muestra un ejemplo mínimo de TypeScript. Especifica network: 'base'; el handler seleccionará el payment requirement de Base de la respuesta 402 de esta solicitud; el importe real y la dirección de cobro siguen estando sujetos a accepts:
Detrás de este código ocurren cuatro pasos:
  1. El SDK envía una solicitud de API normal, sin Authorization.
  2. El Gateway devuelve 402 Payment Required y accepts.
  3. createX402PaymentHandler selecciona el requisito de pago de network = 'base' y firma PAYMENT-SIGNATURE.
  4. El SDK vuelve a intentar con el mismo cuerpo de solicitud, y el Gateway llama al Facilitator para verificar y liquidar antes de permitir el acceso a la API de destino.

Consultar las capacidades compatibles del Facilitator

La API X402 no depende de un directorio de recursos. El cliente llama directamente a la API conocida y utiliza el 402 Payment Required y accepts devueltos en tiempo real por esa solicitud como la única base para el precio y la firma. La declaración de capacidades del Facilitator se encuentra en:
Solo describe /supported, /verify, /settle y las redes de pago actualmente habilitadas, sin enumerar los recursos de la API. La dirección del Facilitator de producción de Ace Data Cloud es:
Puedes consultar qué redes y schemes admite:
El kinds devuelto enumerará las redes y schemes admitidos por el Facilitator. En las llamadas reales, se seguirá tomando como referencia el accepts devuelto por la API. Salida de Facilitator /supported:
Los resultados indican:
  • /supported indica que el Facilitator tiene capacidades de verificación y liquidación para estas redes y schemes.
  • Tanto Base como Solana admiten exact; upto actualmente solo se proporciona en Base.
  • Si una API específica permite una red determinada sigue dependiendo del accepts de 402 de esa API.