Skip to main content
Ace Data Cloud X402 currently uses two types of schemes: exact and upto. They solve different billing problems.

exact

exact means that the price can be determined before this request enters the target API. The amount signed by the client is the final charged amount. Suitable for:
  • Fixed-price image generation;
  • Fixed-price video task creation;
  • Fixed-price search or tool APIs;
  • Order payments.
EVM exact uses USDC EIP-3009 TransferWithAuthorization:
The Facilitator verifies the signature and amount during the /verify stage, and submits this authorization on-chain during the /settle stage.

upto

upto means that the client authorizes a maximum ceiling, and Ace Data Cloud settles according to actual usage after the request is completed. The actual charge cannot exceed the ceiling. Suitable for:
  • Chat completions: the final price depends on prompt tokens and completion tokens;
  • Streaming responses: the actual output length is only known after it ends;
  • Future post-metering APIs.
upto uses Permit2 PermitWitnessTransferFrom. What the client signs is not a fixed transfer, but a ceiling authorization with a witness:
permitted.amount is the ceiling and is not necessarily the final charge. During the /record stage, the Gateway converts actual usage into amount and passes it to the Facilitator. The Facilitator only allows settlement when amount <= permitted.amount. The program execution result for Base upto:
Explanation:
  • The authorization ceiling returned in 402 is 95215 atomic USDC, and the client signs according to this ceiling.
  • Only 3 atomic USDC is settled after the actual model response, and the on-chain transaction can be found on BaseScan.
  • This result demonstrates the key difference of upto: the signed amount is a ceiling, and the on-chain settlement can be less than the ceiling.
  • If actual usage exceeds the ceiling, the Facilitator should reject settlement, and the client needs to authorize again with a higher ceiling.
upto is currently available only on Base. When post-metering is required, please use Base.

Why Permit2 approve is required

upto is ultimately pulled from the payer wallet in USDC by the x402 proxy through Permit2. Before the first use, the payer wallet needs to give Permit2 a one-time ERC-20 allowance. Python CLI:
Programmatic approach:
After authorization is completed, each request still needs to sign a new upto envelope, because the nonce, deadline, witness, and amount ceiling are all different.

Zero-amount settlement

upto supports cases where the actual amount is 0. For example, if the target API does not successfully generate billable usage, the Gateway can pass in amount = "0". The Facilitator will return success but will not send an on-chain transaction. This avoids the issue of “the request was unsuccessful but on-chain fees were still charged.”

Selection recommendations

If you are not sure which one to choose, first use the SDK default behavior; the SDK will select the matching network payment requirement returned by the server.

Base upto Checklist

When integrating or troubleshooting, please confirm that the following parameters come from the same 402 response and remain consistent when signed by the client: Common errors and handling methods: