/verify and /settle.
Ace Data Cloud’s production Facilitator address is:
v2 wire conventions
Ace Data Cloud’s X402 flow fully uses the official x402 v2 and no longer accepts the v1X-Payment request header. There are three points to note during integration:
- The request header is
PAYMENT-SIGNATURE, and its value is a base64-encoded JSON envelope. - The top level of the envelope must be
x402Version: 2, and theacceptedobject must be used to declare theschemeandnetworkselected for this request. networkuses the CAIP-2 identifier (such aseip155:8453) and cannot use abbreviations such asbase.
PAYMENT-REQUIRED response header. Its value is a base64 encoding of the same challenge content, allowing clients to read payment requirements without parsing the body.
Core interfaces
GET /supported
View supported networks and schemes:
networkuses the CAIP-2 identifier, not abbreviations such asbaseorsolana./supportedindicates that the Facilitator has the corresponding verification and settlement capabilities.- Both Base and Solana support
exact;uptois currently available only on Base. signersare the addresses used by the Facilitator to submit settlement transactions.- Whether a specific API allows these options is still subject to that API’s 402
accepts.
POST /verify
Verify whether the PAYMENT-SIGNATURE sent by the client satisfies a payment requirement.
Request body:
paymentRequirements fields in v2 are scheme, network, asset, amount, payTo, maxTimeoutSeconds, and extra, and the amount field is amount. The API 402 response’s accepts[] also additionally returns maxAmountRequired for the client to read the maximum limit, but it is not a field in the Facilitator request body.
Successful response:
PAYMENT-RESPONSE response header for a production order payment, it contains the settlement result. The program execution result for a Base order payment:
success=Trueindicates that Facilitator settlement was successful.transactionis the on-chain transaction hash, and the order’spay_idis also written with the same value.- The explorer shows a transfer of
1200000atomic USDC on Base. errorReason=Noneindicates that this settlement did not return a business error.
isValid is false. The business side should read invalidReason, rather than only looking at the HTTP status code.
POST /settle
Settle already verified authorization on-chain.
The request body is basically the same as /verify. The difference for upto is: paymentRequirements.amount is rewritten to the actual settlement amount during settlement; the signature limit is recorded by the Facilitator during the verify stage, and during settlement it validates that the actual amount does not exceed that limit.
Successful response:
upto amount is 0, transaction may be an empty string, indicating that there is no need to send an on-chain transaction.
How the Ace Data Cloud Gateway uses Facilitator
The flow of the Ace Data Cloud API Gateway is as follows:- The client requests the API for the first time, without
AuthorizationorPAYMENT-SIGNATURE. - The Gateway calculates the estimated price of the request and returns 402 and
accepts. - The client retries with
PAYMENT-SIGNATUREafter signing. - The Gateway decodes
PAYMENT-SIGNATUREand selects the matching payment requirement. - The Gateway calls Facilitator
/verify. - After
/verifysucceeds, the Gateway allows the request through to the target API. - After the target API returns, the Gateway calls Facilitator
/settleduring the/recordstage. - The Gateway writes the on-chain transaction hash into the usage record metadata.
exact settles the signed amount in step 7; upto writes amount based on actual usage in step 7, then settles the actual amount.
How to integrate your own API
If you want your own API to support X402, you can implement it according to this structure:- Prepare
paymentRequirementsfor each paid endpoint, including the network, amount, recipient 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, recipient 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 each 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.

