Zum Hauptinhalt springen
X402 ist ein von Coinbase vorgeschlagenes On-Chain-Zahlungsprotokoll für „Abrechnung per HTTP 402“: Der Server gibt bei einer Anfrage ohne Token 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ückgegebene 402 Payment Required und accepts als Grundlage für Preis und Signatur. Die Zahlungsfähigkeit des Facilitators kann unter /.well-known/x402 verifiziert werden.
Sowohl @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:
Der X402-Envelope ist ein JSON-Abschnitt, der nach der Base64-Kodierung in den Header PAYMENT-SIGNATURE eingefügt wird. Struktur (Auszug):
Die oberste Ebene des Envelopes ist 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

Die getesteten Versionsnummern:

Vollständige Signatur von createX402PaymentHandler

Der Rückgabewert ist ein (ctx) => Promise&lt;{ headers: Record<string, string> }>, was genau der Signatur des paymentHandler-Hooks des SDK entspricht.

Verwendung 1: Browser (MetaMask / WalletConnect)

Beim ersten Aufruf zeigt der Browser zwei Signaturaufforderungen an: Die erste ist ein einmaliges Permit2-Approve für USDC (der Betrag ist 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 über signEVMUptoPayment gewählt werden, um die Kette accepts → signed envelope → PAYMENT-SIGNATURE header selbst zu verbinden und den SDK-Hook zu überspringen; empfohlen wird jedoch weiterhin vorrangig createX402PaymentHandler, damit Protokoll-Upgrades nicht selbst gepflegt werden müssen.

Verwendung 3: Solana

In der Solana-Chain wird derzeit nur das 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

Getestete Versionsnummern:

EVM (Base)

Solana

Einmaliges Approve (nur beim ersten EVM-Aufruf)

Bei EVM Base verwendet X402 Permit2, daher muss die Wallet dem Permit2-Vertrag einmal ein MaxUint256-Approve für USDC erteilen. acedatacloud-x402 enthält bereits approve_permit2:
Diese Transaktion muss nur einmal gesendet werden; danach verwenden alle X402-EVM-Zahlungen diese Autorisierung. Solana benötigt dies nicht.

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).
Ausgabe:
Die Ergebnisse zeigen:
  • 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.
  • createX402PaymentHandler gibt 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 wurde create_x402_payment_handler ebenfalls auf die gleiche Weise verifiziert — der Rückgabewert der Funktion ist callable, und die Konstruktion von AceDataCloud(...) erzeugt keinen Fehler, wenn payment_handler=... injiziert wird. Die Semantik beider Seiten ist abgestimmt.

V. Vergleich mit dem „Bearer-Token-Modus“

VI. Häufige Fallstricke

  1. Chat-Typen müssen preferScheme=upto verwenden: Die Verwendung von exact führt dazu, dass der Facilitator USDC gemäß maxAmountRequired (nicht gemäß der tatsächlichen Nutzung) abbucht.
  2. Ü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 viem WalletClient).
  3. 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.
  4. 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 exact unterstützt.
  5. Geschäftsfehler und Zahlungsfehler unterscheiden: 402 → Bei einem Handler-Fehler wird X402SignError ausgelö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.
  6. Die stabilste Schreibweise für die viem-Anpassung: evmProvider: walletClient as any verliert zwar die Typprüfung, bietet aber die beste Kompatibilität; wenn Sie die Typen beibehalten möchten, können Sie viems .transport.request separat in ein { request }-Objekt verpacken und dieses übergeben.

Mehr erfahren