Przejdź do głównej treści
X402 to zaproponowany przez Coinbase protokół płatności on-chain „rozliczany przez HTTP 402”: serwer zwraca 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 żądanie 402 Payment Required oraz accepts jako podstawy ceny i podpisu. Możliwość płatności Facilitatora można zweryfikować pod /.well-known/x402.
Zarówno @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 Python EVMAccountSigner
  • 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:
Envelope X402 to fragment JSON, który po zakodowaniu base64 jest umieszczany w nagłówku PAYMENT-SIGNATURE. Struktura (fragment):
Na najwyższym poziomie envelope znajduje się 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

Przetestowane numery wersji:

Pełna sygnatura createX402PaymentHandler

Wartością zwracaną jest (ctx) => Promise&lt;{ headers: Record<string, string> }>, co dokładnie odpowiada sygnaturze hooka SDK paymentHandler.

Użycie 1: przeglądarka (MetaMask / WalletConnect)

Przy pierwszym wywołaniu przeglądarka wyświetli dwa monity o podpis: pierwszy to jednorazowe approve Permit2 dla USDC (kwota to 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 niskopoziomowego signEVMUptoPayment, samodzielnie łącząc ścieżkę accepts → signed envelope → PAYMENT-SIGNATURE header i pomijając hook SDK; jednak nadal zalecane jest przede wszystkim użycie createX402PaymentHandler, aby nie musieć samodzielnie utrzymywać aktualizacji protokołu.

Sposób użycia 3: Solana

W sieci Solana obecnie udostępniany jest tylko scheme 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

Przetestowane wersje:

EVM (Base)

Solana

Jednorazowe approve (tylko przy pierwszym użyciu EVM)

X402 na EVM Base korzysta z Permit2, co wymaga, aby portfel jednorazowo wykonał approve MaxUint256 dla USDC na rzecz kontraktu Permit2. acedatacloud-x402 ma wbudowane approve_permit2:
Tę transakcję wystarczy wysłać raz, a później wszystkie płatności X402 EVM będą korzystać z tego upoważnienia. Solana tego nie wymaga.

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).
Wynik:
Wynik oznacza:
  • Nie przekazano apiToken, a konstrukcja SDK nie zgłasza błędu, co dowodzi, że tryb X402 rzeczywiście jest prawidłowym zamiennikiem tokena.
  • createX402PaymentHandler zwraca 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.
Pythonowe create_x402_payment_handler również przeszło taką samą weryfikację — wartość zwracana przez funkcję jest callable, a konstrukcja AceDataCloud(...) nie zgłasza błędu przy wstrzyknięciu payment_handler=.... Semantyka po obu stronach jest zgodna.

V. Porównanie z „trybem tokena Bearer”

VI. Częste pułapki

  1. Klasa chat musi mieć preferScheme=upto: użycie exact sprawi, że facilitator pobierze USDC zgodnie z maxAmountRequired (a nie rzeczywistym użyciem).
  2. Po stronie Node nie przekazuj surowego klucza prywatnego do createX402PaymentHandler: pakiet TS nie akceptuje { privateKey }, należy opakować go jako provider EIP-1193 (zalecany viem WalletClient).
  3. 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.
  4. 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.
  5. 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.
  6. Najstabilniejszy sposób adaptacji viem: evmProvider: walletClient as any traci sprawdzanie typów, ale zapewnia najlepszą kompatybilność; jeśli chcesz zachować typy, opakuj osobno .transport.request z viem w obiekt { request } i przekaż go dalej.

Dowiedz się więcej