Saltar al contenido principal
Ace Data Cloud X402 actualmente utiliza dos tipos de scheme: exact y upto. Resuelven diferentes problemas de facturación.

exact

exact significa que el precio puede determinarse antes de que esta solicitud entre en la API objetivo. El importe firmado por el cliente es el importe final cobrado. Adecuado para:
  • Generación de imágenes con precio fijo;
  • Creación de tareas de video con precio fijo;
  • APIs de búsqueda o herramientas con precio fijo;
  • Pago de pedidos.
EVM exact utiliza USDC EIP-3009 TransferWithAuthorization:
El Facilitator verifica la firma y el importe durante la fase /verify, y envía esta autorización a la cadena durante la fase /settle.

upto

upto significa que el cliente autoriza un límite máximo, y Ace Data Cloud liquida según el uso real después de que se complete la solicitud; el cargo real no puede superar el límite. Adecuado para:
  • Completado de chat: el precio final depende de los prompt tokens y los completion tokens;
  • Respuestas en streaming: solo se conoce después de que termina la longitud real de salida;
  • Futuras APIs de medición posterior.
upto utiliza Permit2 PermitWitnessTransferFrom. Lo que firma el cliente no es una transferencia fija, sino una autorización de límite con witness:
permitted.amount es el límite máximo, no necesariamente el cargo final. El Gateway convertirá el uso real en amount y lo pasará al Facilitator durante la fase /record. El Facilitator solo permite liquidar amount <= permitted.amount. Resultado de ejecución del programa Base upto:
Explicación:
  • El límite de autorización devuelto en 402 es 95215 atomic USDC, y el cliente firma según este límite.
  • Después de la respuesta real del modelo, solo se liquidan 3 atomic USDC, y la transacción en cadena ya se puede consultar en BaseScan.
  • Este resultado puede demostrar la diferencia clave de upto: el importe firmado es el límite máximo, y el settlement en cadena puede ser menor que el límite máximo.
  • Si el uso real supera el límite máximo, el Facilitator debe rechazar el settlement, y el cliente necesita autorizar nuevamente según un límite máximo más alto.
upto actualmente solo se proporciona en Base. Cuando se requiera medición posterior, utilice Base.

Por qué se necesita Permit2 approve

upto finalmente permite que el proxy x402 retire USDC de la cartera pagadora mediante Permit2. Antes del primer uso, la cartera pagadora debe otorgar a Permit2 una ERC-20 allowance. Python CLI:
De forma programática:
Después de completar la autorización, cada solicitud aún necesita firmar un nuevo envelope upto, porque nonce, deadline, witness y el límite de importe son todos diferentes.

Liquidación de importe cero

upto admite casos donde el importe real es 0. Por ejemplo, si la API objetivo no produjo exitosamente un uso facturable, el Gateway puede pasar amount = "0". El Facilitator devolverá éxito, pero no enviará una transacción en cadena. Esto puede evitar el problema de “la solicitud no tuvo éxito pero aún se cobran tarifas en cadena”.

Recomendaciones de selección

Si no está seguro de cuál elegir, primero use el comportamiento predeterminado del SDK; el SDK seleccionará el payment requirement de red coincidente devuelto por el servidor.

Lista de comprobación de Base upto

Al integrar o solucionar problemas, confirme que los siguientes parámetros provengan de la misma respuesta 402 y se mantengan consistentes al firmar en el cliente: Errores comunes y formas de manejarlos: