Skip to main content
The Facilitator is the server-side settlement component in the X402 flow. The client is responsible for signing, and the Gateway or your server is responsible for calling the Facilitator’s /verify and /settle. Ace Data Cloud’s production Facilitator address is:
Source repository: https://github.com/AceDataCloud/FacilitatorX402

v2 wire conventions

Ace Data Cloud’s X402 flow fully uses the official x402 v2 and no longer accepts the v1 X-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 the accepted object must be used to declare the scheme and network selected for this request.
  • network uses the CAIP-2 identifier (such as eip155:8453) and cannot use abbreviations such as base.
Envelope structure:
In addition to the JSON body, the 402 response also includes a 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:
Example response:
Result description:
  • network uses the CAIP-2 identifier, not abbreviations such as base or solana.
  • /supported indicates that the Facilitator has the corresponding verification and settlement capabilities.
  • Both Base and Solana support exact; upto is currently available only on Base.
  • signers are 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:
The 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:
After decoding the PAYMENT-RESPONSE response header for a production order payment, it contains the settlement result. The program execution result for a Base order payment:
Result description:
  • success=True indicates that Facilitator settlement was successful.
  • transaction is the on-chain transaction hash, and the order’s pay_id is also written with the same value.
  • The explorer shows a transfer of 1200000 atomic USDC on Base.
  • errorReason=None indicates that this settlement did not return a business error.
Verification failures also usually return HTTP 200, but 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:
If the actual 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:
  1. The client requests the API for the first time, without Authorization or PAYMENT-SIGNATURE.
  2. The Gateway calculates the estimated price of the request and returns 402 and accepts.
  3. The client retries with PAYMENT-SIGNATURE after signing.
  4. The Gateway decodes PAYMENT-SIGNATURE and selects the matching payment requirement.
  5. The Gateway calls Facilitator /verify.
  6. After /verify succeeds, the Gateway allows the request through to the target API.
  7. After the target API returns, the Gateway calls Facilitator /settle during the /record stage.
  8. 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:
  1. Prepare paymentRequirements for each paid endpoint, including the network, amount, recipient 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 own generated 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 /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