Saltar al contenido principal
Además de pagar directamente por solicitudes de API, Ace Data Cloud también admite el uso de X402 para pagar pedidos del panel de control. El protocolo central del pago de pedidos y las llamadas de API es el mismo: la primera solicitud devuelve 402, el cliente firma PAYMENT-SIGNATURE, y luego reintenta con la misma solicitud. La diferencia es que el pago de pedidos pertenece a la API de la plataforma y requiere un token de cuenta; mientras que la llamada directa a la API de IA de x402.acedata.cloud puede usar solo X402, sin requerir API Token.

Preparar el pedido

Ingresa a la consola de Ace Data Cloud, selecciona el pedido que necesitas pagar y registra el ID del pedido. Si todavía no tienes un pedido, puedes crear un pedido pendiente de pago en la página de planes. El precio del pedido prevalece según lo mostrado en la página, y el amount en la respuesta 402 de X402 es la base final para la firma.

Crear un token de cuenta

Las solicitudes de pago de pedidos requieren un token de cuenta. Abre la página de Token de la plataforma, y crea un token con formato platform-v1-.... Para las solicitudes posteriores usa:
El token de cuenta es diferente de un API Token normal. El API Token normal se usa para consumir cuota de API; el token de cuenta se usa para operar recursos de la plataforma en representación de tu cuenta, como el pago de pedidos.

Activar 402

Primero envía una solicitud sin PAYMENT-SIGNATURE:
El estado devuelto es 402, y la respuesta contiene accepts:
El pago de pedidos utiliza el x402 v2 oficial: x402Version es 2, network usa un identificador CAIP-2, y el campo de importe es amount. Resultado de ejecución del programa al crear un pedido de 10 Credits y activar 402:
Los siguientes registros de transacciones son muestras históricas probadas bajo la política anterior; los importes y hashes de transacción se conservan tal como estaban. Los nuevos pedidos X402 ya no ofrecen descuentos por método de pago; usa el amount de la respuesta 402 actual como base para la firma y el pago.
Explicación de los resultados:
  • Después de crear correctamente el pedido, el estado es Pending; en este momento todavía no hay pago en cadena.
  • La primera solicitud a pay/ no lleva PAYMENT-SIGNATURE, por lo que devuelve HTTP 402.
  • accepts proporciona simultáneamente Base exact y Solana exact; este tutorial selecciona Base posteriormente.
  • El precio al crear el pedido era 1.26; al pagar durante la antigua política de descuento de pago X402, el importe real firmado y liquidado fue 1.2 USDC, correspondiente a 1200000 atomic USDC.
Ten en cuenta que resource aquí es un campo devuelto por el servidor y que participa en la firma; el cliente no debe reescribir por sí mismo el protocolo, la ruta ni el ID de pedido incluidos en él.

Firmar y reintentar

El pago de pedidos puede reutilizar @acedatacloud/x402-client o las funciones de firma de bajo nivel de acedatacloud-x402. A continuación hay un ejemplo de TypeScript:
Resultado de ejecución del programa después de firmar y reintentar el mismo pedido con Base exact:
Resultado de confirmación en cadena:
Explicación del resultado:
  • status 200 indica que la interfaz de pago de pedidos de la plataforma aceptó esta PAYMENT-SIGNATURE.
  • has_x_payment_response True indica que el encabezado de respuesta contiene un recibo PAYMENT-RESPONSE codificado en Base64.
  • settle_header.success=True y network=base indican que el Facilitator ha completado el settlement de Base.
  • El estado final del pedido es Finished, pay_way es X402 y pay_id escribe el hash de la transacción en cadena.
  • El evento Transfer en BaseScan muestra que la dirección de pago transfirió 1200000 USDC atomic a la dirección receptora de la plataforma, es decir, 1.2 USDC.

Respuesta exitosa y recibo

Después de que el pago del pedido se realiza correctamente, el cuerpo de respuesta contiene la información del pedido. La plataforma también incluirá en el encabezado de respuesta PAYMENT-RESPONSE una settlement response codificada en Base64, cuyos campos comunes después de decodificar incluyen: Si necesita conciliación, se recomienda guardar simultáneamente el ID del pedido, la dirección de la billetera pagadora, transaction y el estado final del pedido.

Consideraciones

  • El pago del pedido requiere un token de cuenta de la plataforma y no puede completarse únicamente con la firma de la billetera X402.
  • amount usa USDC atomic units; 1200000 representa 1.2 USDC.
  • No construya por su cuenta la dirección receptora ni la dirección del activo; prevalece accepts en la respuesta 402.
  • Si la misma PAYMENT-SIGNATURE se envía repetidamente, el Facilitator aplicará protección contra repetición según el nonce.

Respuesta de fallo de pago

El primer HTTP 402 sin PAYMENT-SIGNATURE es un desafío de pago normal y no representa un fallo de pago. Los fallos de verificación o settlement tras la firma aún conservan el error de cadena estándar como respaldo de compatibilidad, y devuelven una estructura de error estable en extensions.acedatacloud.paymentError:
El cliente debe priorizar la localización según code; los code desconocidos deben recurrir a un fallo de pago genérico. charged es un campo de tres estados: solo devolverá false cuando se rechace explícitamente antes del settlement; la ausencia del campo indica que el estado del cargo es desconocido y no puede interpretarse como “no se ha cobrado”. Una vez que el pedido actual entra en Failed, no puede reintentarse el pedido original; cree un nuevo pedido después de corregir el problema de la billetera. metadata.x402.last_error y metadata.x402.errors de la lista y los detalles de pedidos conservan el mismo conjunto de code, stage, retryable, charged y params; el texto explicativo público se guarda en reason y el momento en que ocurrió se guarda en timestamp. Por ejemplo, insufficient_token_balance indica que el saldo de USDC en la red seleccionada es insuficiente, y invalid_signature indica que la firma de pago no es válida; volver a leer el pedido no los cambiará por el genérico payment_failed. No registre ni envíe la PAYMENT-SIGNATURE completa, firmas de billetera, payload de autorización, diagnósticos originales del Facilitator ni respuestas RPC. Para la investigación de atención al cliente solo se necesitan el ID del pedido y el code de error público.

Recompra y quema de ACE para pagos de Base y Solana

Después de habilitar la estrategia de recompra, el 3% de los importes efectivamente recibidos de Circle USDC de la red principal de Base y USDC de la red principal de Solana que cumplan los requisitos se utiliza para comprar y quemar ACE, sin realizar cargos adicionales a la billetera pagadora. Se provisiona una vez durante la recarga; posteriormente, usar estos Credits para llamar a la API no genera una provisión repetida; los pedidos históricos con descuento y los pedidos con estrategias antiguas no reciben provisiones retroactivas automáticamente. Los pagos de Base conservan el recibo de pago en la cadena Base, mientras que la compra y quema de ACE se ejecutan de forma asíncrona en Solana. Los pagos que cumplen los requisitos provisionan exactamente el 3% según el importe efectivamente recibido, sin un límite fijo por transacción o diario para el monto de recompra; los fondos disponibles, las cotizaciones de mercado y las confirmaciones en cadena aún pueden afectar el tiempo de finalización. El objeto ace_burn en los detalles del pedido proporciona settlement_network, settlement_transaction y execution_network, y proporciona swap_signature y burn_signature después de la finalización. Pending o Processing no indican que ya se haya quemado; solo Completed representa que la prueba final en cadena ha sido verificada. Cuando un pago de Base aún no ha alcanzado la confirmación final, la recompra esperará la confirmación, pero no afectará los Credits ya acreditados.