/verify y /settle de Facilitator.
La dirección de Facilitator de producción de Ace Data Cloud es:
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 solicitudX-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 objetoacceptedpara declarar elschemeynetworkseleccionados esta vez. networkutiliza el identificador CAIP-2 (comoeip155:8453), y no se pueden escribir abreviaturas comobase.
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:
networkutiliza el identificador CAIP-2, no abreviaturas comobaseosolana./supportedindica que Facilitator tiene la capacidad correspondiente de verificación y liquidación.- Tanto Base como Solana admiten
exact;uptoactualmente solo se proporciona en Base. signersson las direcciones que Facilitator utiliza para enviar transacciones de liquidación.- Que una API específica permita estas opciones sigue estando sujeto a los
accepts402 de esa API.
POST /verify
Verifica si el PAYMENT-SIGNATURE enviado por el cliente cumple con un payment requirement determinado.
Cuerpo de la solicitud:
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:
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:
success=Trueindica que el settlement de Facilitator fue exitoso.transactiones el hash de la transacción on-chain, y elpay_iddel pedido también se escribe con el mismo valor.- En el explorer se puede ver la transferencia de
1200000atomic USDC de Base. errorReason=Noneindica que este settlement no devolvió un error de negocio.
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:
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:- El cliente solicita la API por primera vez, sin
AuthorizationniPAYMENT-SIGNATURE. - Gateway calcula el precio estimado de la solicitud y devuelve 402 y
accepts. - El cliente vuelve a intentarlo con
PAYMENT-SIGNATUREdespués de firmar. - Gateway decodifica
PAYMENT-SIGNATUREy selecciona el payment requirement coincidente. - Gateway llama a Facilitator
/verify. - Después de que
/verifysea exitoso, Gateway permite el paso de la solicitud a la API de destino. - Después de que la API de destino responda, Gateway llama a Facilitator
/settledurante la etapa/record. - 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:- Prepare
paymentRequirementsfor each paid endpoint, including the network, amount, receiving address, asset address, and signature domain. - If the request does not have
PAYMENT-SIGNATURE, return HTTP 402 andaccepts. - If the request has
PAYMENT-SIGNATURE, Base64 decode it to obtainpaymentPayload. - Call Facilitator
/verify. - Execute the business logic after successful verification.
- Call Facilitator
/settleafter the business operation succeeds. - Save
payer,transaction,amount, andnetworkfor reconciliation.
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
/settlehas submitted a transaction but has not yet been confirmed, you can retry/settlewith the same nonce for idempotent reconciliation; - Do not cache the same
PAYMENT-SIGNATUREand use it for multiple API calls.

