Skip to main content
El Facilitador es el componente de liquidación del lado del servidor en el enlace X402. El cliente es responsable de la firma, el Gateway o tu servidor es responsable de llamar a los métodos /verify y /settle del Facilitador. La dirección del Facilitador de producción de Ace Data Cloud es:
Repositorio de código fuente: https://github.com/AceDataCloud/FacilitatorX402

​
Convenio v2 wire

El enlace X402 de Ace Data Cloud ha adoptado completamente la versión oficial x402 v2, y ya no acepta el encabezado de solicitud X-Payment de la v1. Al integrarse, se deben tener en cuenta tres puntos:
  • El encabezado de solicitud es PAYMENT-SIGNATURE, y su valor es un envelope JSON codificado en base64.
  • El nivel superior del envelope debe ser x402Version: 2, y debe declarar el scheme y network seleccionados mediante el objeto accepted.
  • network utiliza la identificación CAIP-2 (por ejemplo, eip155:8453), no se pueden usar abreviaturas como base.
Estructura del envelope:
La respuesta 402, además del cuerpo JSON, incluirá un encabezado de respuesta PAYMENT-REQUIRED, cuyo valor es la codificación en base64 del mismo contenido del desafío, facilitando que el cliente lea los requisitos de pago sin necesidad de analizar el cuerpo.

​
Interfaz principal

​
GET /supported

Ver redes y schemes soportados:
Ejemplo de respuesta:
Descripción de los resultados:
  • network utiliza la identificación CAIP-2, no abreviaturas como base, skale.
  • /supported indica que el Facilitador tiene la capacidad de verificación y liquidación correspondiente.
  • Base, SKALE y Solana soportan exact; upto actualmente solo está disponible en Base.
  • signers son las direcciones que el Facilitador utiliza para enviar transacciones de liquidación.
  • Si una API específica permite estas opciones, se regirá por el accepts de esa API 402.

​
POST /verify

Verifica si el PAYMENT-SIGNATURE enviado por el cliente cumple con un requisito de pago determinado. Cuerpo de la solicitud:
El campo paymentRequirements de la v2 incluye scheme, network, asset, amount, payTo, maxTimeoutSeconds y extra, siendo el campo de monto amount. La respuesta API 402 también devolverá maxAmountRequired en accepts[] para que el cliente lea el límite, pero no es un campo del cuerpo de solicitud del Facilitador. Respuesta exitosa:
El encabezado de respuesta PAYMENT-RESPONSE de un pago de orden de producción, al ser decodificado, contiene el resultado de la liquidación. Resultado de la ejecución del pago de orden en Base:
Descripción de los resultados:
  • success=True indica que la liquidación del Facilitador fue exitosa.
  • transaction es el hash de la transacción en la cadena, el pay_id de la orden también se escribe con el mismo valor.
  • En el explorador se puede ver la transferencia de 1200000 atomic USDC de Base USDC.
  • errorReason=None indica que esta liquidación no devolvió errores de negocio.
Las verificaciones fallidas también suelen devolver HTTP 200, pero isValid será false. El lado de negocio debe leer invalidReason, en lugar de solo mirar el código de estado HTTP.

​
POST /settle

Realiza la liquidación en la cadena de autorizaciones que ya han sido verificadas. El cuerpo de la solicitud es básicamente el mismo que el de /verify. La diferencia con upto es que: paymentRequirements.amount se reescribe como el monto real de liquidación; el límite de firma es registrado por el Facilitador en la fase de verificación, y al liquidar se verifica que el monto real no exceda ese límite. Respuesta exitosa:
Si el monto real de upto es 0, transaction puede ser una cadena vacía, lo que indica que no es necesario realizar una transacción en la cadena.

​
Cómo usar el Facilitador en Ace Data Cloud Gateway

El flujo del API Gateway de Ace Data Cloud es el siguiente:
  1. El cliente realiza la primera solicitud al API, sin incluir Authorization y PAYMENT-SIGNATURE.
  2. El Gateway calcula el precio estimado de la solicitud y devuelve 402 y accepts.
  3. El cliente firma y vuelve a intentar con PAYMENT-SIGNATURE.
  4. El Gateway decodifica PAYMENT-SIGNATURE y selecciona el requisito de pago correspondiente.
  5. El Gateway llama al Facilitador /verify.
  6. Una vez que /verify es exitoso, el Gateway permite la solicitud al API objetivo.
  7. Después de que el API objetivo responde, el Gateway llama al Facilitador /settle en la fase de /record.
  8. El Gateway escribe el hash de la transacción en la cadena en los metadatos de uso. exact en el paso 7 liquida el monto de la firma; upto en el paso 7 escribe amount según el uso real, luego liquida el monto real.

​
Cómo integrar tu propia API

Si deseas que tu propia API soporte X402, puedes implementar la siguiente estructura:
  1. Prepara paymentRequirements para cada interfaz de pago, que incluya red, monto, dirección de recepción, dirección de activos y dominio de firma.
  2. Si la solicitud no tiene PAYMENT-SIGNATURE, devuelve HTTP 402 y accepts.
  3. Si la solicitud tiene PAYMENT-SIGNATURE, decodifica en Base64 para obtener paymentPayload.
  4. Llama a Facilitator /verify.
  5. Ejecuta la lógica de negocio después de una verificación exitosa.
  6. Después de que la operación sea exitosa, llama a Facilitator /settle.
  7. Guarda payer, transaction, amount, network para conciliación.
El servidor debe usar su propio paymentRequirements para llamar a /verify y /settle, no confíes en los montos, direcciones de recepción o direcciones de activos devueltas por el cliente.

​
Protección contra reproducción

Facilitator registrará el nonce. La autorización con el mismo nonce no puede ser verificada y liquidada nuevamente. Esto significa:
  • El cliente debe firmar un nuevo envelope en cada solicitud;
  • Si /settle ha enviado la transacción pero aún no ha sido confirmada, se puede reintentar /settle con el mismo nonce para hacer una conciliación idempotente;
  • No caches el mismo PAYMENT-SIGNATURE para usarlo en múltiples llamadas a la API.

​
Errores comunes