402 Payment Required zurück und führt über das Feld accepts: [...] akzeptierte Chains / Assets / Preise auf; der Client signiert lokal eine Autorisierung (auf EVM Permit2 / EIP-712, auf Solana eine SPL-Token-Transfer-Autorisierung), legt den base64-kodierten Envelope in den Header PAYMENT-SIGNATURE und sendet erneut. Nach der Verifizierung wickelt der Server die Zahlung tatsächlich on-chain ab und gibt dann das Geschäftsergebnis zurück.
Der X402-Client von Ace Data Cloud ruft die Ziel-API direkt auf und verwendet das in dieser Anfrage in Echtzeit zurückgegebeneSowohl402 Payment Requiredundacceptsals Grundlage für Preis und Signatur. Die Zahlungsfähigkeit des Facilitators kann unter/.well-known/x402verifiziert werden.
@acedatacloud/sdk als auch acedatacloud stellen einen paymentHandler-Hook bereit: Wenn eine vom SDK selbst gesendete Anfrage 402 erhält, wird dein injizierter Handler aufgerufen, um den Header PAYMENT-SIGNATURE zu erhalten, und die ursprüngliche Anfrage wird erneut gesendet. Wenn du @acedatacloud/x402-client / acedatacloud-x402 zusammen mit dem SDK verwendest, ist der gesamte Ablauf für den Geschäftscode vollständig transparent — du verwendest nur client.openai.chat.completions.create(...); es sieht genauso aus wie der Token-Modus, aber darunter wird pro Aufruf bezahlt, ohne vorher aufladen zu müssen.
Dieser Artikel:
- führt die TS-Kette „ohne Token + X402-Handler-Injektion“ tatsächlich vollständig durch (T12-Verifizierung)
- listet die Unterschiede zwischen den zwei Signaturketten EVM / Solana auf
- bietet drei Anpassungen:
viem-Privatschlüsselmodus, Browser-Wallet-Modus und Python-EVMAccountSigner-Modus - erklärt das leicht fehleranfällige Feld
preferScheme/prefer_scheme
Eins, Protokollübersicht (unbedingt lesen)
Ein erfolgreicher X402-Aufruf umfasst 3 HTTP-RTTs:PAYMENT-SIGNATURE eingefügt wird. Struktur (Auszug):
x402Version: 2 und deklariert mit dem Objekt accepted das für dieses Mal gewählte scheme und network (CAIP-2-Kennung).
preferScheme / prefer_scheme wird verwendet, um eine Präferenz auszuwählen, wenn der Server gleichzeitig mehrere Schemes bereitstellt. Wenn der Server nur exact bereitstellt, wird dieses Feld ignoriert; wenn upto gesetzt ist, der Server es aber nicht bereitstellt, wird auf den ersten passenden Eintrag zurückgefallen.
Zwei, TypeScript: zwei Verwendungsweisen für Browser-Wallet + serverseitiges viem
Installation
Vollständige Signatur von createX402PaymentHandler
(ctx) => Promise<{ headers: Record<string, string> }>, was genau der Signatur des paymentHandler-Hooks des SDK entspricht.
Verwendung 1: Browser (MetaMask / WalletConnect)
MaxUint256, wird on-chain geschrieben); die zweite ist die EIP-712-Signatur des X402-Envelopes (geht nicht on-chain, sondern dient nur der Verifizierung durch den Facilitator). Bei nachfolgenden Aufrufen ist nur die zweite Signatur erforderlich; vom Erlebnis her ist es „einmal auf Signieren klicken → Ergebnis erhalten“.
Verwendung 2: Node-Server + viem-Privatschlüssel (geeignet für Backend / CLI)
@acedatacloud/x402-client akzeptiert auf der TS-Seite nur EIP-1193-Provider — es verwaltet keine Privatschlüssel direkt. Im Node- / CLI-Szenario besteht die Standardvorgehensweise darin, den Privatschlüssel mit viem in einen WalletClient zu verpacken und dann über @ethereumjs/util oder viems interne EIP-1193-Anpassung zu arbeiten.
Wenn die EIP-1193-Anpassung von viem nicht stabil genug erscheint, kann auch der niedrigschwelligere Weg übersignEVMUptoPaymentgewählt werden, um die Ketteaccepts → signed envelope → PAYMENT-SIGNATURE headerselbst zu verbinden und den SDK-Hook zu überspringen; empfohlen wird jedoch weiterhin vorrangigcreateX402PaymentHandler, damit Protokoll-Upgrades nicht selbst gepflegt werden müssen.
Verwendung 3: Solana
exact-Scheme bereitgestellt, daher hat preferScheme auf Solana keine Wirkung.
III. Python: Modus mit privatem Schlüssel
acedatacloud-x402 für Python verwendet den Weg der direkten Signierung mit dem privaten Schlüssel (ohne EIP-1193-Abstraktion) und eignet sich besser für Server / Task-Executors.
Installation
EVM (Base)
Solana
Einmaliges Approve (nur beim ersten EVM-Aufruf)
Bei EVM Base verwendet X402 Permit2, daher muss die Wallet dem Permit2-Vertrag einmal einMaxUint256-Approve für USDC erteilen. acedatacloud-x402 enthält bereits approve_permit2:
IV. Verifizierung durch echten Lauf
Testziel: Das TS SDK übergibt kein Token, injiziert einen X402-Handler und kann Anfragen normal konstruieren und initiieren (leichte Verifizierung ohne Verbrauch von echtem On-Chain-USDC).- Es wurde kein
apiTokenübergeben, und die SDK-Konstruktion erzeugt keinen Fehler, was beweist, dass der X402-Modus tatsächlich ein gültiger Ersatz für ein Token ist. createX402PaymentHandlergibt eine Funktion (einen Hook) zurück, die vom SDK erst bei Empfang eines 402 aufgerufen wird.- Der End-to-End-Test für erfolgreich durchgeführte tatsächliche On-Chain-Zahlungen ist wegen des Abzugs von echtem USDC nicht in diesem Tutorial enthalten; siehe die e2e-Beispiele im X402-Integrationsleitfaden.
Auf Python-Seite wurdecreate_x402_payment_handlerebenfalls auf die gleiche Weise verifiziert — der Rückgabewert der Funktion ist callable, und die Konstruktion vonAceDataCloud(...)erzeugt keinen Fehler, wennpayment_handler=...injiziert wird. Die Semantik beider Seiten ist abgestimmt.
V. Vergleich mit dem „Bearer-Token-Modus“
VI. Häufige Fallstricke
- Chat-Typen müssen
preferScheme=uptoverwenden: Die Verwendung vonexactführt dazu, dass der Facilitator USDC gemäßmaxAmountRequired(nicht gemäß der tatsächlichen Nutzung) abbucht. - Übergeben Sie im Node-Ende keinen nackten privaten Schlüssel an
createX402PaymentHandler: Das TS-Paket akzeptiert kein{ privateKey }; es muss in einen EIP-1193-Provider verpackt werden (empfohlen wird viemWalletClient). - Der erste Aufruf umfasst zwei Signaturen: Zuerst wird Permit2 approve signiert (on-chain, mit Gas), danach wird das X402-Envelope signiert (nicht on-chain). Bei nachfolgenden Aufrufen bleibt nur die zweite Signatur übrig.
- Solana kennt kein Permit2-Konzept: Die SPL-Token-Transferautorisierung wird direkt signiert, ein Approve ist nicht erforderlich; derzeit wird auf der Solana-Chain jedoch nur
exactunterstützt. - Geschäftsfehler und Zahlungsfehler unterscheiden: 402 → Bei einem Handler-Fehler wird
X402SignErrorausgelöst (der konkrete Typ variiert je nach Chain); Fehler der Geschäftsschnittstelle nach einem erneuten Senden (401 / 422 / 5xx) werden weiterhin als gewöhnliche SDK-Ausnahmen klassifiziert. - Die stabilste Schreibweise für die
viem-Anpassung:evmProvider: walletClient as anyverliert zwar die Typprüfung, bietet aber die beste Kompatibilität; wenn Sie die Typen beibehalten möchten, können Sie viems.transport.requestseparat in ein{ request }-Objekt verpacken und dieses übergeben.

