Przejdź do głównej treści
X402 obejmuje HTTP, SDK, podpisy, Facilitator i transakcje on-chain. Podczas diagnozowania problemów z podpisem lub rozliczeniem zaleca się potwierdzanie warstwa po warstwie w kolejności „publiczny punkt wejścia -> odpowiedź 402 -> SDK payment handler -> settlement on-chain”. Ten samouczek opisuje sposoby sprawdzania każdej warstwy oraz wymienia typowe błędy.

Sprawdź publiczny punkt wejścia

Deklaracja możliwości Facilitatora:
Jeśli zwracane są facilitator, supportedKinds i punkty końcowe protokołu, metadane możliwości są prawidłowe. Wykrywanie zasobów API zostało wycofane; wywołuj bezpośrednio docelowe API i opieraj się na bieżącej odpowiedzi 402. Obsługiwane możliwości Facilitatora:
Jeśli zwracane jest kinds, punkt wejścia Facilitatora działa prawidłowo.

Sprawdź 402 accepts

Wyślij nieuwierzytelnione żądanie, które nie spowoduje opłaty:
Sprawdź, czy zwrócone accepts zawiera sieć, której chcesz użyć. network jest identyfikatorem CAIP-2:
  • eip155:8453 + exact (Base)
  • eip155:8453 + upto (Base, rozliczanie po użyciu)
  • solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp + exact (Solana)
Jeśli docelowa sieć nie jest dostępna, oznacza to, że dane API lub bieżące środowisko nie ma skonfigurowanej odpowiedniej metody płatności X402.

Uruchom zaawansowane narzędzia walidacyjne X402Client

Repozytorium X402Client oferuje zaawansowane narzędzia walidacyjne, których można użyć do potwierdzenia wyboru odpowiedzi 402, generowania podpisu, paid retry i settlement on-chain. Wymagają one funded wallet, RPC, klucza prywatnego oraz zależności deweloperskich. Do standardowej integracji biznesowej zaleca się w pierwszej kolejności użycie SDK TypeScript lub Python; uruchamiaj te narzędzia tylko wtedy, gdy potrzebujesz zlokalizować problemy z podpisem lub rozliczeniem on-chain. Adres repozytorium: https://github.com/AceDataCloud/X402Client
Base:
Solana:
Narzędzia walidacyjne zazwyczaj wyświetlają:
  1. Odpowiedź 402 dla pierwszego żądania.
  2. Wybrane payment requirement.
  3. Skrót podpisanego PAYMENT-SIGNATURE.
  4. Status HTTP i treść odpowiedzi po ponownej próbie.
  5. Transakcję settlement on-chain albo przyczynę błędu Facilitatora w przypadku niepowodzenia.
Nie wysyłaj kluczy prywatnych ani pełnego PAYMENT-SIGNATURE do systemów logowania ani zgłoszeń. Przykład wyników walidacji publicznego API:
Wyjaśnienie:
  • Base exact, Solana exact i Base upto wszystkie ukończyły paid retry z HTTP 402 do HTTP 200.
  • Transakcję on-chain Base exact można sprawdzić w BaseScan, a kwota rozliczenia wynosi 95215 atomic USDC.
  • Limit podpisu dla Base upto wynosi 95215 atomic USDC, ale rzeczywisty settlement on-chain wynosi 3 atomic USDC, co wskazuje, że rozliczanie po użyciu obciąża opłatą według rzeczywistego wykorzystania.
  • Dla ścieżki Solana potwierdzono paid retry i wynik modelu. Publiczne RPC może podlegać limitowaniu; gdy wymagane jest ścisłe uzgadnianie on-chain, użyj własnego Solana RPC lub potwierdź podpis transakcji na podstawie zapisów rozliczeniowych po stronie platformy.

SDK smoke test

Zaawansowane narzędzia walidacyjne służą do sprawdzania podpisów i rozliczeń on-chain. Strona biznesowa powinna także wykonać SDK smoke test, aby potwierdzić, że kod aplikacji może automatycznie obsługiwać 402 przez payment handler. Poniżej pokazano tylko kluczowe fragmenty; pełny kod wymaga uzupełnienia portfela, providera i importów. TypeScript:
Python:
Jeśli model zwróci stały ciąg zgodnie z wymaganiem, oznacza to, że SDK, payment handler, Gateway, Facilitator i docelowe API są połączone. Powyższe dwa smoke testy używają Base exact i rozliczają stałą kwotę podaną w wycenie 402. Uzupełnienia czatu należą do scenariuszy rozliczanych według tokenów; przy integracji produkcyjnej zaleca się przekazanie preferScheme: 'upto' (w Pythonie prefer_scheme="upto"), aby rozliczać według rzeczywistego wykorzystania. Obiekt zwracany przez Python SDK jest dict; można użyć res["choices"][0]["message"]["content"], aby odczytać treść.

E2E płatności za zamówienia

Płatności za zamówienia używają platformowego API platform.acedata.cloud i wymagają tokenu konta platformy. Pełny przepływ wygląda następująco: utworzenie zamówienia Pending, wywołanie POST /api/v1/orders/{order_id}/pay/ w celu wyzwolenia 402, a następnie ponowienie próby z PAYMENT-SIGNATURE. Przykład wyników walidacji płatności za zamówienie o małej wartości:
Poniższe rekordy transakcji są historycznymi próbkami rzeczywistych testów zgodnie ze starą polityką; kwoty i hashe transakcji zachowano w oryginalnej formie. Nowe zamówienia X402 nie oferują już zniżek zależnych od metody płatności; jako podstawy podpisu i płatności użyj amount z bieżącej odpowiedzi 402.
Wyjaśnienie wyniku:
  • Po utworzeniu zamówienia jego status to Pending, a cena wynosi 1.26.
  • Pierwsze żądanie pay/ zwraca HTTP 402, w accepts znajdują się Base exact i Solana exact, a kwoty w obu przypadkach wynoszą 1200000 atomic USDC.
  • Po ponowieniu próby z Base PAYMENT-SIGNATURE zwracany jest HTTP 200, status zamówienia zmienia się na Finished, a pay_way to X402.
  • Po zdekodowaniu PAYMENT-RESPONSE widoczne są success=True, network=base oraz ten sam hash transakcji.
  • Na BaseScan status transakcji wynosi 1, a kwota transferu to 1200000 atomic USDC, czyli 1.2 USDC.
  • Cena utworzenia 1.26 została opłacona w okresie starej polityki rabatów płatności X402, a końcowa podpisana i rozliczona kwota wynosi 1.2 USDC.
Jeśli płatność za zamówienie nie zawiera Authorization: Bearer {platform_token} albo zamówienie nie należy do bieżącego konta, zakończy się niepowodzeniem na warstwie uprawnień platformy; różni się to od bezkontowego API X402 wywoływanego bezpośrednio w x402.acedata.cloud.

Częste błędy

Lista kontrolna Base upto

upto jest obecnie dostępne tylko w Base (eip155:8453). Ponieważ podpis upto wiąże więcej parametrów EVM typed data, podczas integracji należy szczególnie potwierdzić, że pola czasu rzeczywistego w odpowiedzi 402 są dokładnie zgodne z podpisem klienta.
Jeśli Base upto zwraca invalid_upto_evm_payload_invalid_signature, w pierwszej kolejności sprawdź:
  1. extra.chainId (powinno wynosić 8453) w elemencie eip155:8453 + upto zwróconym przez API.
  2. extra.facilitatorAddress zwrócone przez API.
  3. Adres Base upto facilitator zwrócony przez https://facilitator.acedata.cloud/supported.
  4. Permit2 domain, spender, kontrakt USDC i konto podpisujące.
  5. Czy portfel zatwierdził już Permit2 dla Base USDC.
Digest podpisu upto wiąże jednocześnie Permit2 domain, chain ID, spender, adres odbiorcy, adres facilitator i validAfter. Jeśli którakolwiek pozycja jest niezgodna, Facilitator odzyska nieprawidłowego signer, a następnie zwróci invalid signature. Jeśli wszystkie są zgodne, ale nadal zwracane jest 402, następnym krokiem jest sprawdzenie Permit2 allowance; przy braku autoryzacji zwracane jest PERMIT2_ALLOWANCE_REQUIRED.

Zapisywanie informacji weryfikacyjnych

Pełna weryfikacja powinna zapisać co najmniej:
  • API path oraz skrót treści żądania;
  • wybrane network i scheme;
  • maxAmountRequired;
  • adres portfela payer;
  • końcowy status HTTP;
  • wynik modelu lub ID zadania w odpowiedzi;
  • link do transakcji settlement;
  • Gateway trace ID lub ID rekordu użycia platformy.
Nie zapisuj kluczy prywatnych, pełnego PAYMENT-SIGNATURE, pełnego EIP-712 signature ani frazy odzyskiwania.

Ustrukturyzowane błędy płatności

Niepowodzenia X402 po podpisaniu zwracają stabilne code, bezpieczne parametry interpolacji, etap oraz flagę możliwości ponowienia w extensions.acedatacloud.paymentError. Do diagnostyki w pierwszej kolejności używaj tej struktury; nie analizuj najwyższego poziomu angielskiego error i nie wymagaj od użytkownika podania podpisu portfela ani oryginalnego tekstu symulacji on-chain.
  • charged: false: weryfikacja została wyraźnie odrzucona przed settlement; w tym przypadku nie zainicjowano obciążenia.
  • Brak charged: wynik jest nieznany lub wszedł już w etap settlement; najpierw sprawdź zamówienie i status on-chain, nie wolno bezpośrednio powtarzać płatności.
  • settlement_pending: nie powtarzaj jeszcze płatności; najpierw odśwież zamówienie lub skontaktuj się ze wsparciem.
  • Nierozpoznany code: traktuj jako payment_failed i zachowaj publiczny kod techniczny do wyszukania przez obsługę klienta.