Saltar al contenido principal
Facilitator es el componente de liquidación del lado del servidor en el flujo de X402. El cliente es responsable de firmar, y Gateway o tu servidor es responsable de llamar a /verify y /settle de Facilitator. La dirección de Facilitator de producción de Ace Data Cloud es:
Repositorio de código fuente: https://github.com/AceDataCloud/FacilitatorX402

Convenciones wire de v2

El flujo X402 de Ace Data Cloud ya utiliza completamente el x402 v2 oficial, y ya no acepta el encabezado de solicitud X-Payment de v1. Hay tres puntos a tener en cuenta durante la integración:
  • El encabezado de solicitud es PAYMENT-SIGNATURE, y su valor es un JSON envelope codificado en base64.
  • La capa superior del envelope debe ser x402Version: 2, y se debe usar el objeto accepted para declarar el scheme y network seleccionados esta vez.
  • network utiliza el identificador CAIP-2 (como eip155:8453), y no se pueden escribir abreviaturas como base.
Estructura del envelope:
Además del JSON body, la respuesta 402 también incluirá un encabezado de respuesta PAYMENT-REQUIRED, cuyo valor es la codificación base64 del mismo contenido de desafío, lo que facilita que el cliente lea los requisitos de pago sin analizar el body.

Interfaces principales

GET /supported

Consulta las redes y schemes compatibles:
Ejemplo de respuesta:
Explicación de los resultados:
  • network utiliza el identificador CAIP-2, no abreviaturas como base o solana.
  • /supported indica que Facilitator tiene la capacidad correspondiente de verificación y liquidación.
  • Tanto Base como Solana admiten exact; upto actualmente solo se proporciona en Base.
  • signers son las direcciones que Facilitator utiliza para enviar transacciones de liquidación.
  • Que una API específica permita estas opciones sigue estando sujeto a los accepts 402 de esa API.

POST /verify

Verifica si el PAYMENT-SIGNATURE enviado por el cliente cumple con un payment requirement determinado. Cuerpo de la solicitud:
Los campos de paymentRequirements de v2 son scheme, network, asset, amount, payTo, maxTimeoutSeconds y extra, y el campo de importe es amount. Los accepts[] de la respuesta API 402 también devolverán adicionalmente maxAmountRequired para que el cliente lea el límite superior, pero no pertenece a los campos del cuerpo de solicitud de Facilitator. Respuesta exitosa:
Después de decodificar el encabezado de respuesta PAYMENT-RESPONSE del pago de pedidos de producción, este contiene el resultado de settlement. El resultado de ejecución del programa para el pago de pedidos en Base:
Explicación de los resultados:
  • success=True indica que el settlement de Facilitator fue exitoso.
  • transaction es el hash de la transacción on-chain, y el pay_id del pedido también se escribe con el mismo valor.
  • En el explorer se puede ver la transferencia de 1200000 atomic USDC de Base.
  • errorReason=None indica que este settlement no devolvió un error de negocio.
La verificación fallida también suele devolver HTTP 200, pero isValid es false. El lado de negocio debería leer invalidReason, en lugar de mirar solo el código de estado HTTP.

POST /settle

Liquida on-chain una autorización que ya ha sido verificada. El cuerpo de la solicitud es básicamente igual que /verify. La diferencia de upto es: paymentRequirements.amount se reescribe con el importe real de liquidación durante settle; el límite superior de firma es registrado por Facilitator en la etapa verify, y durante settle se verifica que el importe real no supere ese límite superior. Respuesta exitosa:
Si el importe real de upto es 0, transaction puede ser una cadena vacía, lo que indica que no es necesario enviar una transacción on-chain.

Cómo utiliza Ace Data Cloud Gateway Facilitator

El flujo de Ace Data Cloud API Gateway es el siguiente:
  1. El cliente solicita la API por primera vez, sin Authorization ni PAYMENT-SIGNATURE.
  2. Gateway calcula el precio estimado de la solicitud y devuelve 402 y accepts.
  3. El cliente vuelve a intentarlo con PAYMENT-SIGNATURE después de firmar.
  4. Gateway decodifica PAYMENT-SIGNATURE y selecciona el payment requirement coincidente.
  5. Gateway llama a Facilitator /verify.
  6. Después de que /verify sea exitoso, Gateway permite el paso de la solicitud a la API de destino.
  7. Después de que la API de destino responda, Gateway llama a Facilitator /settle durante la etapa /record.
  8. Gateway escribe el hash de la transacción on-chain en los metadata del registro de uso.
exact liquida el importe firmado en el paso 7; upto escribe amount según el uso real en el paso 7, y luego liquida el importe real.

Cómo integrar tu propia API

Si quieres que tu propia API admita X402, puedes implementarla según esta estructura:
  1. Prepare paymentRequirements for each paid endpoint, including the network, amount, receiving address, asset address, and signature domain.
  2. If the request does not have PAYMENT-SIGNATURE, return HTTP 402 and accepts.
  3. If the request has PAYMENT-SIGNATURE, Base64 decode it to obtain paymentPayload.
  4. Call Facilitator /verify.
  5. Execute the business logic after successful verification.
  6. Call Facilitator /settle after the business operation succeeds.
  7. Save payer, transaction, amount, and network for reconciliation.
The server must use its self-generated paymentRequirements to call /verify and /settle; do not trust the amount, receiving address, or asset address returned by the client.

Replay Protection

Facilitator records nonces. Authorizations with the same nonce cannot be verified and settled repeatedly. This means:
  • The client should sign a new envelope for every request;
  • If /settle has submitted a transaction but has not yet been confirmed, you can retry /settle with the same nonce for idempotent reconciliation;
  • Do not cache the same PAYMENT-SIGNATURE and use it for multiple API calls.

Common Errors