Hoppa till huvudinnehåll
X402 är ett betalningsprotokoll på kedjan för ”debitering via HTTP 402” som föreslagits av Coinbase: servern returnerar 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 det 402 Payment Required och accepts som returneras i realtid av den förfrågan som grund för pris och signering. Facilitators betalningskapacitet kan verifieras på /.well-known/x402.
Både @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 Python EVMAccountSigner-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:
X402-envelopet är en JSON-sträng som base64-kodas och placeras i PAYMENT-SIGNATURE-huvudet. Struktur (utdrag):
Envelopets toppnivå är 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

Testade versionsnummer:

Fullständig signatur för createX402PaymentHandler

Returvärdet är en (ctx) => Promise&lt;{ headers: Record<string, string> }> som exakt matchar SDK:ts paymentHandler-hook-signatur.

Användning 1: webbläsare (MetaMask / WalletConnect)

Vid första anropet visar webbläsaren två signeringsuppmaningar: den första är ett engångsgodkännande av Permit2 för USDC (beloppet är 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åbaserade signEVMUptoPayment, och själv koppla ihop vägen accepts → signed envelope → PAYMENT-SIGNATURE header, för att hoppa över SDK-kroken; men det rekommenderas fortfarande att i första hand välja createX402PaymentHandler, så att du slipper underhålla protokolluppgraderingar själv.

Användning 3: Solana

På Solana-kedjan exponeras för närvarande endast exact scheme, så preferScheme har ingen effekt på Solana.

III. Python: privat nyckel-läge

Pythons acedatacloud-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

Testade versionsnummer:

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 en MaxUint256-approve till Permit2-kontraktet för USDC en gång. acedatacloud-x402 har inbyggd approve_permit2:
Den här transaktionen behöver bara skickas en gång, och därefter använder alla X402 EVM-betalningar denna auktorisering. Solana behöver inte det.

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).
Utdata:
Resultatet visar:
  • Ingen apiToken skickades, och SDK-konstruktionen ger inget fel, vilket bevisar att X402-läget verkligen är ett giltigt alternativ till token.
  • createX402PaymentHandler returnerar 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.
Pythons create_x402_payment_handler har också genomgått samma verifiering —— funktionens returvärde är callable, och konstruktionen AceDataCloud(...) ger inget fel när payment_handler=... injiceras. Semantiken är anpassad på båda sidor.

V. Jämförelse med ”Bearer token-läget”

VI. Vanliga fallgropar

  1. chat-klassen måste använda preferScheme=upto: Om du använder exact kommer facilitator att dra USDC enligt maxAmountRequired (inte den faktiska användningen).
  2. Skicka inte en rå privat nyckel till createX402PaymentHandler på Node-sidan: TS-paketet accepterar inte { privateKey }, utan måste kapslas som en EIP-1193-provider (viem WalletClient rekommenderas).
  3. 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.
  4. 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.
  5. 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.
  6. Det mest stabila sättet att anpassa viem: evmProvider: walletClient as any förlorar typkontroll men har bäst kompatibilitet; om du vill behålla typer, kapsla viems .transport.request separat i ett { request }-objekt och skicka in det.

Läs mer