Skip to main content
In addition to paying directly per API request, Ace Data Cloud also supports paying console orders with X402. Order payment and API calls use the same core protocol: the first request returns 402, the client signs 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 the amount 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 the platform-v1-... format. Use the following for subsequent requests:
An account token is different from a regular API Token. A regular API Token is used to consume API credits; an account token is used to operate platform resources on behalf of your account, such as order payments.

Trigger 402

First send a request without PAYMENT-SIGNATURE:
The returned status is 402, and the response contains accepts:
Order payment uses the official x402 v2: 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.
Result explanation:
  • After the order is created successfully, its status is Pending, and there is no on-chain payment yet.
  • The first pay/ request does not include PAYMENT-SIGNATURE, so it returns HTTP 402.
  • accepts provides both Base exact and Solana exact; 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 was 1.2 USDC, corresponding to 1200000 atomic USDC.
Note that 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:
Program output after signing and retrying the same order with Base exact:
On-chain confirmation result:
Result description:
  • status 200 indicates that the platform order payment API accepted this PAYMENT-SIGNATURE.
  • has_x_payment_response True indicates that the response header contains a Base64-encoded PAYMENT-RESPONSE receipt.
  • settle_header.success=True and network=base indicate that the Facilitator has completed Base settlement.
  • The final order status is Finished, pay_way is X402, and pay_id is written with the on-chain transaction hash.
  • The Transfer event on BaseScan shows that the payment address transferred 1200000 atomic USDC, that is, 1.2 USDC, 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 the PAYMENT-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.
  • amount uses USDC atomic units; 1200000 represents 1.2 USDC.
  • Do not construct the receiving address or asset address yourself; use the accepts in the 402 response as the source of truth.
  • If the same PAYMENT-SIGNATURE is submitted repeatedly, the Facilitator performs replay protection based on the nonce.

Payment Failure Response

The first HTTP 402 without PAYMENT-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:
Clients should prioritize localizing based on 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. The ace_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.