Sprawdź publiczny punkt wejścia
Deklaracja możliwości Facilitatora: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:
kinds, punkt wejścia Facilitatora działa prawidłowo.
Sprawdź 402 accepts
Wyślij nieuwierzytelnione żądanie, które nie spowoduje opłaty:
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)
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- Odpowiedź 402 dla pierwszego żądania.
- Wybrane payment requirement.
- Skrót podpisanego
PAYMENT-SIGNATURE. - Status HTTP i treść odpowiedzi po ponownej próbie.
- Transakcję settlement on-chain albo przyczynę błędu Facilitatora w przypadku niepowodzenia.
PAYMENT-SIGNATURE do systemów logowania ani zgłoszeń.
Przykład wyników walidacji publicznego API:
- Base
exact, Solanaexacti Baseuptowszystkie ukończyły paid retry z HTTP 402 do HTTP 200. - Transakcję on-chain Base
exactmożna sprawdzić w BaseScan, a kwota rozliczenia wynosi95215atomic USDC. - Limit podpisu dla Base
uptowynosi95215atomic USDC, ale rzeczywisty settlement on-chain wynosi3atomic 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: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 APIplatform.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.
- Po utworzeniu zamówienia jego status to
Pending, a cena wynosi1.26. - Pierwsze żądanie
pay/zwraca HTTP 402, wacceptsznajdują się Baseexacti Solanaexact, a kwoty w obu przypadkach wynoszą1200000atomic USDC. - Po ponowieniu próby z Base
PAYMENT-SIGNATUREzwracany jest HTTP 200, status zamówienia zmienia się naFinished, apay_waytoX402. - Po zdekodowaniu
PAYMENT-RESPONSEwidoczne sąsuccess=True,network=baseoraz ten sam hash transakcji. - Na BaseScan status transakcji wynosi
1, a kwota transferu to1200000atomic USDC, czyli1.2USDC. - Cena utworzenia
1.26została opłacona w okresie starej polityki rabatów płatności X402, a końcowa podpisana i rozliczona kwota wynosi1.2USDC.
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.
upto zwraca invalid_upto_evm_payload_invalid_signature, w pierwszej kolejności sprawdź:
extra.chainId(powinno wynosić8453) w elemencieeip155:8453+uptozwróconym przez API.extra.facilitatorAddresszwrócone przez API.- Adres Base
uptofacilitator zwrócony przezhttps://facilitator.acedata.cloud/supported. - Permit2 domain, spender, kontrakt USDC i konto podpisujące.
- Czy portfel zatwierdził już Permit2 dla Base USDC.
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.
PAYMENT-SIGNATURE, pełnego EIP-712 signature ani frazy odzyskiwania.
Ustrukturyzowane błędy płatności
Niepowodzenia X402 po podpisaniu zwracają stabilnecode, 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_failedi zachowaj publiczny kod techniczny do wyszukania przez obsługę klienta.

