PAYMENT-SIGNATURE, and then retries with the same request.
The difference is that order payment is a platform API and requires an account token; while directly calling the AI API at x402.acedata.cloud can use only X402 and does not require an API Token.
Prepare an Order
Go to the Ace Data Cloud Console, select the order you need to pay for, and note down the order ID. If you do not yet have an order, you can create a pending-payment order on the plan page. The order price is subject to what is displayed on the page, and theamount in the X402 402 response is the final basis for signing.
Create an Account Token
Order payment requests require an account token. Open the Platform Token page and create a token in theplatform-v1-... format.
Use the following for subsequent requests:
Trigger 402
First send a request withoutPAYMENT-SIGNATURE:
accepts:
x402Version is 2, network uses the CAIP-2 identifier, and the amount field is amount.
Program output from creating a 10 Credits order and triggering 402:
The following transaction records are historical real-test samples under the old policy, and the amounts and transaction hashes are retained as-is. New X402 orders no longer have payment method discounts; please use the amount in this 402 response as the basis for signing and payment.
- After the order is created successfully, its status is
Pending, and there is no on-chain payment yet. - The first
pay/request does not includePAYMENT-SIGNATURE, so it returns HTTP 402. acceptsprovides both Baseexactand Solanaexact; this tutorial chooses Base in the following steps.- The price when the order was created was
1.26; when paid during the old X402 payment discount policy period, the actual signed and settled amount was1.2USDC, corresponding to1200000atomic USDC.
resource here is a field returned by the server and participates in signing. The client must not rewrite the protocol, path, or order ID in it by itself.
Sign and Retry
Order payment can reuse the low-level signing functions of@acedatacloud/x402-client or acedatacloud-x402. Below is a TypeScript example:
exact:
status 200indicates that the platform order payment API accepted thisPAYMENT-SIGNATURE.has_x_payment_response Trueindicates that the response header contains a Base64-encodedPAYMENT-RESPONSEreceipt.settle_header.success=Trueandnetwork=baseindicate that the Facilitator has completed Base settlement.- The final order status is
Finished,pay_wayisX402, andpay_idis written with the on-chain transaction hash. - The
Transferevent on BaseScan shows that the payment address transferred1200000atomic USDC, that is,1.2USDC, to the platform receiving address.
Successful Response and Receipt
After the order payment succeeds, the response body contains order information. The platform also carries a Base64-encoded settlement response in thePAYMENT-RESPONSE response header. After decoding, common fields include:
If you need reconciliation, it is recommended to save the order ID, payment wallet address,
transaction, and final order status at the same time.
Notes
- Order payment requires a platform account token and cannot be completed using only an X402 wallet signature.
amountuses USDC atomic units;1200000represents1.2USDC.- Do not construct the receiving address or asset address yourself; use the
acceptsin the 402 response as the source of truth. - If the same
PAYMENT-SIGNATUREis submitted repeatedly, the Facilitator performs replay protection based on the nonce.
Payment Failure Response
The first HTTP 402 withoutPAYMENT-SIGNATURE is a normal payment challenge and does not indicate a payment failure. Verification or settlement failures after signing still retain the standard string error as a compatibility fallback, and return a stable error structure in extensions.acedatacloud.paymentError:
code; unknown codes should fall back to a generic payment failure. charged is a three-state field: false is returned only when the payment is explicitly rejected before settlement; a missing field indicates that the charge status is unknown and cannot be interpreted as “not charged.” Once the current order enters Failed, it cannot be retried using the original order. Please create a new order after fixing the wallet issue.
metadata.x402.last_error and metadata.x402.errors in the order list and details retain the same set of code, stage, retryable, charged, and params; the public description text is stored in reason, and the occurrence time is stored in timestamp. For example, insufficient_token_balance indicates insufficient USDC balance on the selected network, while invalid_signature indicates an invalid payment signature; rereading the order will not change them to the generic payment_failed.
Do not record or submit the complete PAYMENT-SIGNATURE, wallet signature, authorization payload, Facilitator raw diagnostics, or RPC responses. Customer support troubleshooting requires only the order ID and the public error code.
ACE Buyback and Burn for Base and Solana Payments
After the buyback policy is enabled, 3% of the received amount from eligible Base mainnet Circle USDC and Solana mainnet USDC is used to purchase and burn ACE, with no additional charge to the payment wallet. It is accrued once during recharge, and subsequent use of these Credits to call APIs does not result in repeated accrual; historical discounted orders and orders under old policies are not automatically accrued retroactively. Base payments retain the payment receipt on the Base chain, while ACE purchase and burning are performed asynchronously on Solana. Eligible payments accrue exactly 3% based on the received amount, with no fixed per-transaction or daily buyback amount cap; available funds, market quotes, and on-chain confirmations may still affect completion time. Theace_burn object in the order details provides settlement_network, settlement_transaction, and execution_network, and provides swap_signature and burn_signature after completion. Pending or Processing does not mean it has been burned; only Completed represents that the final on-chain proof has been verified. When a Base payment has not yet reached final confirmation, the buyback waits for confirmation, but this does not affect the Credits already received.
