402 Payment Required för förfrågningar utan token och bifogar fältet accepts: [...] som listar accepterade kedjor / tillgångar / priser; klienten signerar lokalt en auktorisering (Permit2 / EIP-712 på EVM, SPL token transfer-auktorisering på Solana), lägger det base64-kodade envelopet i PAYMENT-SIGNATURE-huvudet och skickar förfrågan igen. Efter verifiering genomför servern den faktiska avräkningen på kedjan och returnerar sedan affärsresultatet.
Ace Data Clouds X402-klient anropar mål-API:t direkt och använder detBåde402 Payment Requiredochacceptssom returneras i realtid av den förfrågan som grund för pris och signering. Facilitators betalningskapacitet kan verifieras på/.well-known/x402.
@acedatacloud/sdk och acedatacloud exponerar en paymentHandler-hook: när en förfrågan som SDK:t självt skickar får 402, anropas handlern du injicerat för att hämta PAYMENT-SIGNATURE-huvudet, och den ursprungliga förfrågan skickas sedan igen. Kombinera @acedatacloud/x402-client / acedatacloud-x402 med SDK:t, så blir hela flödet helt transparent för affärskoden——du använder bara client.openai.chat.completions.create(...), vilket ser exakt likadant ut som token-läget, men under ytan betalar du per anrop utan att behöva fylla på i förväg.
Denna artikel:
- kopplar ihop hela kedjan med ”ingen token + X402 handler-injektion” på TS-sidan (T12-verifiering)
- listar skillnaderna mellan de två signeringskedjorna EVM / Solana
- ger tre anpassningar:
viem-privatnyckelläge, webbläsarplånboksläge och PythonEVMAccountSigner-läge - förklarar det lättproblematiska fältet
preferScheme/prefer_scheme
I. Protokollöversikt (måste läsas)
Ett lyckat X402-anrop omfattar 3 HTTP RTT:PAYMENT-SIGNATURE-huvudet. Struktur (utdrag):
x402Version: 2, och objektet accepted används för att deklarera den scheme och network (CAIP-2-identifierare) som valts denna gång.
preferScheme / prefer_scheme används för att välja preferens när servern samtidigt erbjuder flera scheme. Om servern endast exponerar exact ignoreras detta fält; om upto anges men servern inte exponerar det, återgår den till den första matchningen.
II. TypeScript: två användningssätt för webbläsarplånbok + viem på servern
Installation
Fullständig signatur för createX402PaymentHandler
(ctx) => Promise<{ headers: Record<string, string> }> som exakt matchar SDK:ts paymentHandler-hook-signatur.
Användning 1: webbläsare (MetaMask / WalletConnect)
MaxUint256, vilket skrivs till kedjan); den andra är EIP-712-signaturen för X402-envelopet (skrivs inte till kedjan, utan endast för facilitators verifiering). Efterföljande anrop behöver bara den andra signaturen, och upplevelsen blir ”klicka en gång för att signera → få resultatet”.
Användning 2: Node-server + viem-privatnyckel (lämpligt för backend / CLI)
@acedatacloud/x402-client accepterar på TS-sidan endast EIP-1193 provider——den hanterar inte privatnycklar direkt. I Node / CLI-scenarier är standardmetoden att använda viem för att paketera privatnyckeln som en WalletClient, och sedan använda @ethereumjs/util eller viems interna EIP-1193-anpassning.
Om du tycker att viems EIP-1193-anpassning inte är tillräckligt stabil kan du också använda den mer lågnivåbaseradesignEVMUptoPayment, och själv koppla ihop vägenaccepts → signed envelope → PAYMENT-SIGNATURE header, för att hoppa över SDK-kroken; men det rekommenderas fortfarande att i första hand väljacreateX402PaymentHandler, så att du slipper underhålla protokolluppgraderingar själv.
Användning 3: Solana
exact scheme, så preferScheme har ingen effekt på Solana.
III. Python: privat nyckel-läge
Pythonsacedatacloud-x402 använder vägen med direkt signering med privat nyckel (utan EIP-1193-abstraktion), vilket passar bättre för servrar / uppgiftskörningar.
Installation
EVM (Base)
Solana
Engångs-approve (endast första gången på EVM)
På EVM Base använder X402 Permit2, vilket kräver att plånboken utför enMaxUint256-approve till Permit2-kontraktet för USDC en gång. acedatacloud-x402 har inbyggd approve_permit2:
IV. Verifiering av faktisk körning
Testmål: TS SDK skickar inte token, injicerar X402 handler och kan normalt konstruera och initiera begäranden (en lättviktsverifiering som inte förbrukar verklig USDC på kedjan).- Ingen
apiTokenskickades, och SDK-konstruktionen ger inget fel, vilket bevisar att X402-läget verkligen är ett giltigt alternativ till token. createX402PaymentHandlerreturnerar en funktion (en hook), som SDK:t först anropar när det tar emot 402.- Ett end-to-end-test där faktisk betalning på kedjan fungerar har inte inkluderats i den här handledningen, eftersom det innebär verkliga USDC-dragningar; du kan hänvisa till e2e-exemplet i X402-integrationsguiden.
Pythonscreate_x402_payment_handlerhar också genomgått samma verifiering —— funktionens returvärde är callable, och konstruktionenAceDataCloud(...)ger inget fel närpayment_handler=...injiceras. Semantiken är anpassad på båda sidor.
V. Jämförelse med ”Bearer token-läget”
VI. Vanliga fallgropar
- chat-klassen måste använda
preferScheme=upto: Om du använderexactkommer facilitator att dra USDC enligtmaxAmountRequired(inte den faktiska användningen). - Skicka inte en rå privat nyckel till
createX402PaymentHandlerpå Node-sidan: TS-paketet accepterar inte{ privateKey }, utan måste kapslas som en EIP-1193-provider (viemWalletClientrekommenderas). - Det första anropet innebär dubbla signaturer: Först signeras Permit2 approve (on-chain, kräver gas), sedan signeras X402 envelope (inte on-chain). Efterföljande anrop har bara den andra signaturen kvar.
- Solana har inget Permit2-koncept: Signera direkt SPL token transfer-auktorisering, ingen approve behövs; men för närvarande stöder Solana-kedjan endast
exact. - Skilj mellan affärsfel och betalningsfel: 402 → handler-fel kastar
X402SignError(den specifika typen varierar beroende på kedja); efterföljande affärsgränssnittsfel efter återförsök (401 / 422 / 5xx) klassificeras fortfarande som vanliga SDK-undantag. - Det mest stabila sättet att anpassa
viem:evmProvider: walletClient as anyförlorar typkontroll men har bäst kompatibilitet; om du vill behålla typer, kapsla viems.transport.requestseparat i ett{ request }-objekt och skicka in det.

