402 Payment Required for requests without a token, with an accepts: [...] field listing acceptable chains / assets / prices; the client signs an authorization locally (Permit2 / EIP-712 on EVM, SPL token transfer authorization on Solana), puts the base64-encoded envelope into the PAYMENT-SIGNATURE header and resends. After verification, the server actually settles on-chain, then returns the business result.
Ace Data Cloud’s X402 client directly calls the target API, and uses theBoth402 Payment Requiredandacceptsreturned in real time by that request as the basis for pricing and signing. The Facilitator’s payment capabilities can be verified at/.well-known/x402.
@acedatacloud/sdk and acedatacloud expose a paymentHandler hook: when a request sent by the SDK itself receives 402, it calls the handler you inject to obtain the PAYMENT-SIGNATURE header, then resends the original request. Combining @acedatacloud/x402-client / acedatacloud-x402 with the SDK, the entire process is completely transparent to business code—you only use client.openai.chat.completions.create(...), which looks exactly the same as token mode, but the underlying mechanism is pay-per-call and requires no advance top-up.
This article:
- Actually runs through the TS-side “no token + X402 handler injection” flow (T12 verification)
- Lists the differences between the EVM / Solana signing flows
- Provides three adaptations:
viemprivate-key mode, browser-wallet mode, and PythonEVMAccountSignermode - Clearly explains the easily confusing
preferScheme/prefer_schemefield
I. Protocol Overview (Must Read)
One successful X402 call involves 3 HTTP RTTs:PAYMENT-SIGNATURE header. Structure (excerpt):
x402Version: 2, and uses the accepted object to declare the scheme and network selected for this transaction (CAIP-2 identifier).
preferScheme / prefer_scheme is used to select a preference when the server simultaneously provides multiple schemes. If the server only exposes exact, this field is ignored; if upto is set but not exposed by the server, it falls back to the first matching option.
II. TypeScript: Two Approaches for Browser Wallets + Server-Side viem
Installation
Full Signature of createX402PaymentHandler
(ctx) => Promise<{ headers: Record<string, string> }> that exactly matches the SDK’s paymentHandler hook signature.
Approach 1: Browser (MetaMask / WalletConnect)
MaxUint256, written on-chain); the second is the EIP-712 signature for the X402 envelope (not on-chain, only for facilitator verification). Subsequent calls only require the second signature; in terms of experience, it is “click one signature → get the result”.
Approach 2: Node Server-Side + viem Private Key (Suitable for Backend / CLI)
@acedatacloud/x402-client only accepts an EIP-1193 provider on the TS side—it does not directly handle private keys. In Node / CLI scenarios, the standard approach is to use viem to wrap the private key as a WalletClient, then use @ethereumjs/util or viem’s internal EIP-1193 adapter.
If you feel that viem’s EIP-1193 compatibility is not stable enough, you can also use the lower-levelsignEVMUptoPayment, and wire together theaccepts → signed envelope → PAYMENT-SIGNATURE headerpath yourself, bypassing the SDK hook; however,createX402PaymentHandleris still recommended as the first choice, so that you do not need to maintain protocol upgrades yourself.
Usage 3: Solana
exact scheme is currently exposed, so preferScheme does not take effect on Solana.
3. Python: Private Key Mode
Python’sacedatacloud-x402 uses the path of signing directly with a private key (without an EIP-1193 abstraction), which is more suitable for servers / task runners.
Installation
EVM (Base)
Solana
One-Time Approve (EVM First Time Only)
X402 on EVM Base uses Permit2, requiring the wallet to perform a one-timeMaxUint256 approve of USDC for the Permit2 contract. acedatacloud-x402 has approve_permit2 built in:
4. Real Runtime Verification
Test objective: The TS SDK does not receive a token, injects an X402 handler, and can normally construct and initiate requests (a lightweight verification that does not consume real on-chain USDC).- Without passing
apiToken, SDK construction does not throw an error, proving that X402 mode is indeed a valid substitute for tokens. createX402PaymentHandlerreturns a function (hook), which the SDK invokes only after receiving a 402 response.- The end-to-end test for actual on-chain payments was not included in this tutorial because it involves real USDC deductions; you can refer to the e2e examples in the X402 Integration Guide.
Python’screate_x402_payment_handleralso performs the same verification — the function return value is callable, andAceDataCloud(...)construction does not throw an error when injectingpayment_handler=.... The semantics are aligned on both sides.
5. Comparison with “Bearer Token Mode”
6. Common Pitfalls
- Chat-type requests must use
preferScheme=upto: Usingexactwill cause the facilitator to deduct USDC based onmaxAmountRequired(not actual usage). - Do not pass a raw private key to
createX402PaymentHandleron the Node side: The TS package does not accept{ privateKey }; it must be wrapped as an EIP-1193 provider (viemWalletClientis recommended). - The first call requires two signatures: The first signs a Permit2 approve (on-chain, requires gas), and the second signs an X402 envelope (off-chain). Subsequent calls only require the second one.
- Solana does not have the Permit2 concept: It directly signs SPL token transfer authorization, with no approve required; however, only
exactis currently supported on the Solana chain. - Distinguish business errors from payment errors: 402 → handler failure throws
X402SignError(the specific type varies by chain); after retrying, errors from the business API (401 / 422 / 5xx) are still classified as regular SDK exceptions. - The most stable way to adapt
viem:evmProvider: walletClient as anyloses type checking but offers the best compatibility; if you want to preserve types, separately wrap viem’s.transport.requestin a{ request }object and pass it in.

