Verificar la entrada pública
Declaración de capacidades del Facilitator:facilitator, supportedKinds y los endpoints del protocolo, indica que los metadatos de capacidades son normales. El descubrimiento de recursos de API ha sido retirado; llama directamente a la API objetivo y toma como referencia la respuesta 402 en tiempo real.
Capacidades compatibles con Facilitator:
kinds, indica que la entrada del Facilitator funciona correctamente.
Verificar 402 accepts
Envía una solicitud no autenticada que no genere cargos:
accepts devuelto incluye la red que deseas usar. network es un identificador CAIP-2:
eip155:8453+exact(Base)eip155:8453+upto(Base, medición posterior)solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp+exact(Solana)
Ejecutar las herramientas avanzadas de validación de X402Client
El repositorio X402Client proporciona herramientas avanzadas de validación, que pueden utilizarse para confirmar la selección de respuestas 402, la generación de firmas, el paid retry y el settlement on-chain. Requieren una funded wallet, RPC, clave privada y dependencias de desarrollo. Para una integración empresarial normal, se recomienda priorizar el SDK de TypeScript o Python; ejecuta estas herramientas solo cuando necesites localizar problemas de firma o liquidación on-chain. Dirección del repositorio: https://github.com/AceDataCloud/X402Client- La respuesta 402 de la primera solicitud.
- El payment requirement seleccionado.
- El resumen de
PAYMENT-SIGNATUREdespués de firmar. - El estado HTTP y el cuerpo de respuesta después del reintento.
- La transacción de settlement on-chain, o el motivo del error del Facilitator en caso de fallo.
PAYMENT-SIGNATURE completos al sistema de registros ni a los tickets.
Ejemplo de resultados de validación de la API pública:
- Base
exact, Solanaexacty Baseuptocompletaron el paid retry de HTTP 402 a HTTP 200. - La transacción on-chain de Base
exactse puede consultar en BaseScan, y el monto de liquidación es95215atomic USDC. - El límite de firma de Base
uptoes95215atomic USDC, pero el settlement on-chain real es3atomic USDC, lo que indica que la medición posterior cobra según el uso real. - La ruta de Solana confirmó el paid retry y la salida del modelo. El RPC público puede aplicar limitación de tasa; cuando se requiera una conciliación on-chain estricta, utiliza tu propio RPC de Solana o los registros de liquidación de la plataforma para confirmar la firma de la transacción.
SDK smoke test
Las herramientas avanzadas de validación se utilizan para comprobar las firmas y la liquidación on-chain. El lado empresarial también debe ejecutar un SDK smoke test para confirmar que el código de aplicación puede procesar automáticamente 402 mediante el payment handler. A continuación solo se muestran los fragmentos principales; el código completo debe completar la wallet, el provider y los import. TypeScript:exact, y realizan la liquidación por el monto fijo cotizado en 402. Las completaciones de chat pertenecen a escenarios medidos por token; para la integración formal, se recomienda pasar preferScheme: 'upto' (en Python, prefer_scheme="upto"), para liquidar según el uso real.
El objeto devuelto por el SDK de Python es un dict, y se puede usar res["choices"][0]["message"]["content"] para leer el contenido.
E2E de pago de pedidos
El pago de pedidos utiliza la API de plataforma deplatform.acedata.cloud, y requiere un token de cuenta de la plataforma. La cadena completa es: crear un pedido Pending, POST /api/v1/orders/{order_id}/pay/ activa 402 y luego reintentar con PAYMENT-SIGNATURE.
Ejemplo de resultados de validación de pago de pedidos de pequeño importe:
Los siguientes registros de transacciones son muestras históricas de pruebas reales bajo la política anterior; los importes y hashes de transacción se conservan sin cambios. Los nuevos pedidos X402 ya no ofrecen descuentos por método de pago; utiliza el amount de la respuesta 402 actual como base para la firma y el pago.
- Después de crear el pedido, el estado del pedido es
Pending, y el precio es1.26. - La primera solicitud
pay/devuelve HTTP 402, hay Baseexacty Solanaexactenaccepts, y los importes son ambos1200000atomic USDC. - Después de reintentar con Base
PAYMENT-SIGNATURE, devuelve HTTP 200, el estado del pedido cambia aFinished, ypay_wayesX402. - Después de decodificar
PAYMENT-RESPONSE, muestrasuccess=True,network=base, y proporciona el mismo hash de transacción. - En BaseScan, el estado de la transacción es
1, el importe de la transferencia es1200000atomic USDC, es decir,1.2USDC. - El precio de creación
1.26se pagó durante el período de la antigua política de descuentos de pago X402, y el importe final de la firma y liquidación es1.2USDC.
Authorization: Bearer {platform_token}, o el pedido no pertenece a la cuenta actual, fallará en la capa de permisos de la plataforma; esto es diferente de la API X402 sin cuenta que llama directamente a x402.acedata.cloud.
Errores comunes
Lista de verificación de Base upto
upto actualmente solo se proporciona en Base (eip155:8453). Debido a que la firma upto vincula más parámetros de EVM typed data, al integrarla se debe confirmar especialmente que los campos en tiempo real de la respuesta 402 coincidan completamente con la firma del cliente.
upto devuelve invalid_upto_evm_payload_invalid_signature, compruebe primero:
- El
extra.chainId(debe ser8453) en la entradaeip155:8453+uptodevuelta por la API. - El
extra.facilitatorAddressdevuelto por la API. - La dirección del facilitator Base
uptodevuelta porhttps://facilitator.acedata.cloud/supported. - El domain de Permit2, spender, contrato USDC y cuenta de firma.
- Si la billetera ya ha hecho approve Permit2 para Base USDC.
upto vincula simultáneamente el domain de Permit2, chain ID, spender, dirección de recepción, dirección del facilitator y validAfter. Si cualquiera de ellos no coincide, el Facilitator recuperará un signer incorrecto y devolverá invalid signature. Si todos ellos coinciden pero aún devuelve 402, el siguiente paso es comprobar la allowance de Permit2; cuando no está autorizada, devuelve PERMIT2_ALLOWANCE_REQUIRED.
Guardar información de verificación
Una verificación completa debe guardar al menos:- API path y resumen del cuerpo de la solicitud;
- network y scheme seleccionados;
maxAmountRequired;- dirección de la billetera payer;
- estado final HTTP;
- salida del modelo o ID de tarea en la respuesta;
- enlace de la transacción de settlement;
- ID de trace del Gateway o ID de registro de uso de la plataforma.
PAYMENT-SIGNATURE completo, signature EIP-712 completa ni frase mnemotécnica.
Errores de pago estructurados
Los fallos de X402 después de firmar devolveráncode estable, parámetros de interpolación seguros, etapa y marca de reintento en extensions.acedatacloud.paymentError. Priorice el uso de esta estructura para investigar, no analice el error en inglés de nivel superior, ni solicite a los usuarios firmas de billetera o texto original de simulación on-chain.
charged: false: la validación rechazó explícitamente antes del settlement; no se inició ningún cobro esta vez.- Sin
charged: el resultado es desconocido o ya entró en la etapa de settlement; primero consulte el pedido y el estado on-chain, está prohibido repetir directamente el pago. settlement_pending: no repita el pago por ahora; primero actualice el pedido o contacte con soporte.- code no reconocido: trátelo como
payment_failedy conserve el código técnico público para que el servicio de atención al cliente pueda buscarlo.

