Saltar al contenido principal
X402 involucra HTTP, SDK, firmas, Facilitator y transacciones on-chain. Al solucionar problemas de firma o liquidación, se recomienda confirmar capa por capa en el orden de “entrada pública -> respuesta 402 -> SDK payment handler -> settlement on-chain”. Este tutorial explica cómo verificar cada capa y enumera errores comunes.

Verificar la entrada pública

Declaración de capacidades del Facilitator:
Si devuelve 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:
Si devuelve kinds, indica que la entrada del Facilitator funciona correctamente.

Verificar 402 accepts

Envía una solicitud no autenticada que no genere cargos:
Verifica si el 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)
Si no está la red objetivo, indica que esa API o el entorno actual no tiene configurado el método de cobro X402 correspondiente.

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
Base:
Solana:
Las herramientas de validación normalmente imprimen:
  1. La respuesta 402 de la primera solicitud.
  2. El payment requirement seleccionado.
  3. El resumen de PAYMENT-SIGNATURE después de firmar.
  4. El estado HTTP y el cuerpo de respuesta después del reintento.
  5. La transacción de settlement on-chain, o el motivo del error del Facilitator en caso de fallo.
No envíes claves privadas ni PAYMENT-SIGNATURE completos al sistema de registros ni a los tickets. Ejemplo de resultados de validación de la API pública:
Explicación:
  • Base exact, Solana exact y Base upto completaron el paid retry de HTTP 402 a HTTP 200.
  • La transacción on-chain de Base exact se puede consultar en BaseScan, y el monto de liquidación es 95215 atomic USDC.
  • El límite de firma de Base upto es 95215 atomic USDC, pero el settlement on-chain real es 3 atomic 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:
Python:
Si el modelo devuelve la cadena fija según lo solicitado, indica que el SDK, el payment handler, el Gateway, el Facilitator y la API objetivo están conectados. Los dos smoke test anteriores usan Base 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 de platform.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.
Explicación de los resultados:
  • Después de crear el pedido, el estado del pedido es Pending, y el precio es 1.26.
  • La primera solicitud pay/ devuelve HTTP 402, hay Base exact y Solana exact en accepts, y los importes son ambos 1200000 atomic USDC.
  • Después de reintentar con Base PAYMENT-SIGNATURE, devuelve HTTP 200, el estado del pedido cambia a Finished, y pay_way es X402.
  • Después de decodificar PAYMENT-RESPONSE, muestra success=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 es 1200000 atomic USDC, es decir, 1.2 USDC.
  • El precio de creación 1.26 se 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 es 1.2 USDC.
Si el pago del pedido no tiene 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.
Si Base upto devuelve invalid_upto_evm_payload_invalid_signature, compruebe primero:
  1. El extra.chainId (debe ser 8453) en la entrada eip155:8453 + upto devuelta por la API.
  2. El extra.facilitatorAddress devuelto por la API.
  3. La dirección del facilitator Base upto devuelta por https://facilitator.acedata.cloud/supported.
  4. El domain de Permit2, spender, contrato USDC y cuenta de firma.
  5. Si la billetera ya ha hecho approve Permit2 para Base USDC.
El digest de firma de 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.
No guarde claves privadas, PAYMENT-SIGNATURE completo, signature EIP-712 completa ni frase mnemotécnica.

Errores de pago estructurados

Los fallos de X402 después de firmar devolverán code 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_failed y conserve el código técnico público para que el servicio de atención al cliente pueda buscarlo.