402 Payment Required dla żądań bez tokena, dołączając pole accepts: [...] z listą akceptowanych łańcuchów / aktywów / cen; klient lokalnie podpisuje autoryzację (na EVM jest to Permit2 / EIP-712, na Solana jest to autoryzacja transferu tokenu SPL), umieszcza envelope po base64 w nagłówku PAYMENT-SIGNATURE i ponownie wysyła żądanie. Po weryfikacji serwer faktycznie rozlicza płatność on-chain, a następnie zwraca wynik biznesowy.
Klient X402 Ace Data Cloud bezpośrednio wywołuje docelowe API i używa zwracanego w czasie rzeczywistym przez to żądanieZarówno402 Payment Requiredorazacceptsjako podstawy ceny i podpisu. Możliwość płatności Facilitatora można zweryfikować pod/.well-known/x402.
@acedatacloud/sdk, jak i acedatacloud udostępniają hook paymentHandler: gdy żądanie wysłane przez sam SDK otrzyma 402, wywołuje on wstrzyknięty przez Ciebie handler, aby uzyskać nagłówek PAYMENT-SIGNATURE, a następnie ponownie wysyła pierwotne żądanie. Łącząc @acedatacloud/x402-client / acedatacloud-x402 z SDK, cały proces jest całkowicie transparentny dla kodu biznesowego — używasz tylko client.openai.chat.completions.create(...), wygląda to dokładnie tak samo jak tryb tokenowy, lecz pod spodem jest płatność za wywołanie bez potrzeby wcześniejszego doładowania.
Ten artykuł:
- faktycznie przeprowadza łańcuch „bez tokena + wstrzyknięcie handlera X402” po stronie TS (weryfikacja T12)
- wymienia różnice między dwoma łańcuchami podpisów EVM / Solana
- przedstawia trzy adaptacje: tryb klucza prywatnego
viem, tryb portfela przeglądarkowego oraz tryb PythonEVMAccountSigner - wyjaśnia pole
preferScheme/prefer_scheme, na którym łatwo się potknąć
I. Przegląd protokołu (koniecznie przeczytaj)
Jedno udane wywołanie X402 obejmuje 3 HTTP RTT:PAYMENT-SIGNATURE. Struktura (fragment):
x402Version: 2, a obiekt accepted deklaruje scheme i network (identyfikator CAIP-2) wybrane dla tej płatności.
preferScheme / prefer_scheme służy do wyboru preferencji, gdy serwer jednocześnie udostępnia wiele scheme. Jeśli serwer udostępnia tylko exact, to pole zostanie zignorowane; jeśli ustawisz upto, ale serwer go nie udostępnia, nastąpi powrót do pierwszej pasującej pozycji.
II. TypeScript: dwie metody użycia — portfel przeglądarkowy + serwerowe viem
Instalacja
Pełna sygnatura createX402PaymentHandler
(ctx) => Promise<{ headers: Record<string, string> }>, co dokładnie odpowiada sygnaturze hooka SDK paymentHandler.
Użycie 1: przeglądarka (MetaMask / WalletConnect)
MaxUint256, zapisywana on-chain); drugi to podpis EIP-712 dla envelope X402 (nie jest zapisywany on-chain, służy tylko do weryfikacji przez facilitator). Kolejne wywołania wymagają tylko drugiego podpisu, więc z perspektywy użytkownika jest to „kliknij raz, aby podpisać → uzyskaj wynik”.
Użycie 2: serwer Node + klucz prywatny viem (odpowiednie dla backendu / CLI)
@acedatacloud/x402-client po stronie TS akceptuje wyłącznie providera EIP-1193 — nie zarządza bezpośrednio kluczami prywatnymi. W scenariuszach Node / CLI standardowym sposobem jest opakowanie klucza prywatnego jako WalletClient za pomocą viem, a następnie użycie adaptacji EIP-1193 przez @ethereumjs/util lub wewnętrznej adaptacji viem.
Jeśli uważasz, że adaptacja EIP-1193 w viem nie jest wystarczająco stabilna, możesz również skorzystać z bardziej niskopoziomowegosignEVMUptoPayment, samodzielnie łącząc ścieżkęaccepts → signed envelope → PAYMENT-SIGNATURE headeri pomijając hook SDK; jednak nadal zalecane jest przede wszystkim użyciecreateX402PaymentHandler, aby nie musieć samodzielnie utrzymywać aktualizacji protokołu.
Sposób użycia 3: Solana
exact, więc preferScheme nie działa w Solanie.
III. Python: tryb klucza prywatnego
acedatacloud-x402 w Pythonie korzysta ze ścieżki bezpośredniego podpisywania kluczem prywatnym (bez abstrakcji EIP-1193), co lepiej nadaje się do serwerów / executorów zadań.
Instalacja
EVM (Base)
Solana
Jednorazowe approve (tylko przy pierwszym użyciu EVM)
X402 na EVM Base korzysta z Permit2, co wymaga, aby portfel jednorazowo wykonał approveMaxUint256 dla USDC na rzecz kontraktu Permit2. acedatacloud-x402 ma wbudowane approve_permit2:
IV. Weryfikacja rzeczywistego uruchomienia
Cel testu: SDK TS nie przekazuje tokena, wstrzykuje handler X402 i może poprawnie skonstruować oraz zainicjować żądanie (lekka weryfikacja bez wydawania prawdziwego USDC w sieci).- Nie przekazano
apiToken, a konstrukcja SDK nie zgłasza błędu, co dowodzi, że tryb X402 rzeczywiście jest prawidłowym zamiennikiem tokena. createX402PaymentHandlerzwraca funkcję (hook), którą SDK wywoła dopiero po otrzymaniu 402.- Kompleksowy test end-to-end faktycznej płatności w sieci nie został umieszczony w tym poradniku, ponieważ wiąże się z rzeczywistym pobraniem USDC; możesz zapoznać się z przykładem e2e w przewodniku integracji X402.
Pythonowecreate_x402_payment_handlerrównież przeszło taką samą weryfikację — wartość zwracana przez funkcję jest callable, a konstrukcjaAceDataCloud(...)nie zgłasza błędu przy wstrzyknięciupayment_handler=.... Semantyka po obu stronach jest zgodna.
V. Porównanie z „trybem tokena Bearer”
VI. Częste pułapki
- Klasa chat musi mieć
preferScheme=upto: użycieexactsprawi, że facilitator pobierze USDC zgodnie zmaxAmountRequired(a nie rzeczywistym użyciem). - Po stronie Node nie przekazuj surowego klucza prywatnego do
createX402PaymentHandler: pakiet TS nie akceptuje{ privateKey }, należy opakować go jako provider EIP-1193 (zalecany viemWalletClient). - Pierwsze wywołanie wymaga podwójnego podpisu: pierwszy podpis zatwierdza Permit2 approve (on-chain, z gas), drugi podpisuje X402 envelope (nie on-chain). Kolejne wywołania wymagają już tylko drugiego.
- Solana nie ma koncepcji Permit2: bezpośrednio podpisuje autoryzację transferu tokenów SPL, bez potrzeby approve; ale obecnie on-chain Solana obsługuje tylko
exact. - Rozróżniaj błędy biznesowe i błędy płatności: 402 → niepowodzenie handlera rzuca
X402SignError(konkretny typ zależy od łańcucha); błędy interfejsu biznesowego po ponownym wysłaniu (401 / 422 / 5xx) są nadal klasyfikowane jako zwykłe wyjątki SDK. - Najstabilniejszy sposób adaptacji
viem:evmProvider: walletClient as anytraci sprawdzanie typów, ale zapewnia najlepszą kompatybilność; jeśli chcesz zachować typy, opakuj osobno.transport.requestz viem w obiekt{ request }i przekaż go dalej.

