Walidacja i rozwiązywanie problemów X402 E2E

X402 obejmuje HTTP, SDK, podpisy, Facilitator i transakcje on-chain. Podczas rozwiązywania problemów z podpisami lub rozliczeniami zaleca się potwierdzanie warstwa po warstwie w kolejności „publiczny punkt wejścia -> odpowiedź 402 -> SDK payment handler -> on-chain settlement”. Ten samouczek wyjaśnia metody sprawdzania każdej warstwy oraz wymienia typowe błędy.

Sprawdź publiczny punkt wejścia

Deklaracja możliwości Facilitator:

curl https://facilitator.acedata.cloud/.well-known/x402

Jeśli zwracane są facilitator, supportedKinds i punkty końcowe protokołu, oznacza to, że metadane możliwości są prawidłowe. Wykrywanie zasobów API zostało wycofane; wywołuj bezpośrednio docelowe API i kieruj się odpowiedzią 402 w czasie rzeczywistym. Obsługiwane możliwości Facilitator:

curl https://facilitator.acedata.cloud/supported

Jeśli zwracane jest kinds, oznacza to, że punkt wejścia Facilitator działa prawidłowo.

Sprawdź 402 `accepts`

Wyślij nieuwierzytelnione żądanie, które nie spowoduje opłaty:

curl -sS -X POST https://x402.acedata.cloud/openai/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "hi"}],
    "max_tokens": 1
  }'

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 postpaid）
eip155:1187947933 + exact（SKALE）
solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp + exact（Solana）

Jeśli docelowa sieć nie jest obecna, oznacza to, że to API lub bieżące środowisko nie ma skonfigurowanej odpowiedniej metody pobierania płatności X402.

Uruchom zaawansowane narzędzia weryfikacyjne X402Client

Repozytorium X402Client udostępnia zaawansowane narzędzia weryfikacyjne, które można wykorzystać do potwierdzenia wyboru odpowiedzi 402, generowania podpisów, paid retry i on-chain settlement. Wymagają one funded wallet, RPC, klucza prywatnego oraz zależności deweloperskich. W przypadku zwykłej integracji biznesowej zaleca się preferowanie SDK TypeScript lub Python; uruchamiaj te narzędzia tylko wtedy, gdy konieczne jest zlokalizowanie problemów z podpisem lub rozliczeniem on-chain. Adres repozytorium：https://github.com/AceDataCloud/X402Client

git clone https://github.com/AceDataCloud/X402Client.git
cd X402Client/typescript
npm install
npm install --no-save ethers @solana/spl-token bs58 tsx

Base:

export X402B_BASE_PAYER_PRIVATE_KEY=0x...
TEST_API_PATH='/openai/chat/completions' \
TEST_BODY='{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hi"}],"max_tokens":10}' \
npx tsx scripts/test-real-e2e.ts

SKALE:

export SKALE_BASE_PRIVATE_KEY=0x...
TEST_API_PATH='/openai/chat/completions' \
TEST_BODY='{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hi"}],"max_tokens":10}' \
npx tsx scripts/test-skale-e2e.ts

Solana:

export X402B_SOLANA_PAYER_PRIVATE_KEY=...
npx tsx scripts/test-solana-e2e.ts

Narzędzia weryfikacyjne zazwyczaj wypisują:

Odpowiedź 402 pierwszego żądania.
Wybrane payment requirement.
Skrót podpisanego PAYMENT-SIGNATURE.
Status HTTP i treść odpowiedzi po ponowieniu próby.
Transakcję on-chain settlement lub przyczynę błędu Facilitator w przypadku niepowodzenia.

Nie wysyłaj kluczy prywatnych ani pełnego PAYMENT-SIGNATURE do systemu logów ani w zgłoszeniach. Przykład wyników weryfikacji publicznego API:

SKALE exact
HTTP 402 -> HTTP 200
content ADC_SKALE_E2E_OK
tx 0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f
block 1969317
explorer https://skale-base-explorer.skalenodes.com/tx/0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f
paid 0.095215 USDC

Base exact
HTTP 402 -> HTTP 200
content ADC_BASE_E2E_OK
tx 0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3
block 46726299
explorer https://basescan.org/tx/0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3
transfer value 95215 atomic USDC

Solana exact
HTTP 402 -> HTTP 200
content ADC_SOLANA_E2E_OK
chain signature not confirmed in this run because public RPC lookup hit 429

Base upto
HTTP 402 -> HTTP 200
content ADC_BASE_UPTO_OK
tx 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
block 46726437
explorer https://basescan.org/tx/0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
signed ceiling 95215 atomic USDC
transfer value 3 atomic USDC

Wyjaśnienie:

SKALE exact, Base exact, Solana exact i Base upto wszystkie zakończyły paid retry z HTTP 402 do HTTP 200.
Transakcję on-chain dla SKALE exact można sprawdzić w SKALE explorer, a kwota rozliczenia wynosi 0.095215 USDC.
Transakcję on-chain dla Base exact można sprawdzić w BaseScan, a kwota rozliczenia wynosi 95215 atomic USDC.
Limit podpisu Base upto wynosi 95215 atomic USDC, ale rzeczywisty on-chain settlement to 3 atomic USDC, co oznacza, że rozliczanie postpaid pobiera opłatę według rzeczywistego użycia.
Ścieżka Solana potwierdziła paid retry i wynik modelu. Publiczne RPC może podlegać ograniczeniu szybkości; gdy wymagane jest ścisłe uzgodnienie on-chain, użyj własnego Solana RPC lub potwierdź podpis transakcji na podstawie rekordów rozliczeniowych po stronie platformy.

SDK smoke test

Zaawansowane narzędzia weryfikacyjne służą do sprawdzania podpisów i rozliczeń on-chain. Strona biznesowa powinna również wykonać SDK smoke test, aby potwierdzić, że kod aplikacji potrafi automatycznie obsłużyć 402 przez payment handler. Poniżej pokazano tylko kluczowe fragmenty; pełny kod wymaga uzupełnienia wallet, provider i import. TypeScript:

const client = new AceDataCloud({
  paymentHandler: createX402PaymentHandler({
    network: 'skale',
    evmProvider,
    evmAddress: wallet.address
  })
});

const res = await client.openai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Reply with exactly ADC_SDK_X402_OK' }],
  max_tokens: 8
});

Python:

client = AceDataCloud(
    payment_handler=create_x402_payment_handler(
        network="skale",
        evm_signer=signer,
    )
)

res = client.openai.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Reply with exactly ADC_PY_X402_OK"}],
    max_tokens=8,
)

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ą SKALE exact. SKALE obecnie udostępnia tylko exact, rozliczane według stałej kwoty wycenionej przez 402 i nieobniżane wraz z rzeczywistym zużyciem tokenów. Uzupełnianie czatu należy do scenariuszy rozliczanych według tokenów; przy wdrożeniu produkcyjnym zaleca się przejście na Base i przekazywanie preferScheme: 'upto', aby rozliczać się według rzeczywistego użycia. Wyniki uruchomienia programu smoke test SDK:

TypeScript SDK
payer 0xd0479FA9FD8C678303d477433d24C15e3723CC1C
elapsed_ms 6782
content ADC_TS_SDK_X402_OK
id chatcmpl-DlcVLO4PQWvmjPDQpy9yQw2QdLGAT

Python SDK
payer 0xd0479FA9FD8C678303d477433d24C15e3723CC1C
elapsed_ms 4786
content ADC_PY_SDK_X402_OK
id chatcmpl-DlcWajqAHOop3iebmO19XRfT5bTPz

Opis wyników:

TypeScript SDK automatycznie obsługuje 402, podpisywanie i ponawianie przez createX402PaymentHandler, ostatecznie uzyskując ADC_TS_SDK_X402_OK.
Python SDK realizuje ten sam przepływ przez create_x402_payment_handler, ostatecznie uzyskując ADC_PY_SDK_X402_OK.
Oba smoke testy używają payera SKALE 0xd0479FA9FD8C678303d477433d24C15e3723CC1C.
Obiekt zwracany przez Python SDK jest typu dict; w przykładzie można użyć res["choices"][0]["message"]["content"], aby odczytać treść.

E2E płatności za zamówienie

Płatności za zamówienia używają platformowego API platform.acedata.cloud i wymagają tokena konta platformy. Pełny przepływ jest następujący: utworzenie zamówienia Pending, wywołanie 402 przez POST /api/v1/orders/{order_id}/pay/, a następnie ponowienie z PAYMENT-SIGNATURE. Przykład wyników weryfikacji płatności za zamówienie o małej wartości:

Poniższe rekordy transakcji są historycznymi próbkami rzeczywistych testów w ramach starej polityki; kwoty i hashe transakcji zachowano w oryginalnej postaci. Nowe zamówienia X402 nie mają już zniżek zależnych od metody płatności; jako podstawy podpisu i płatności należy używać amount z bieżącej odpowiedzi 402.

created order 78481793-304e-47f7-bc0c-8231aec9cc1e
created state Pending
created price 1.26

http_status=402
x402Version 2
accepts [('eip155:8453', 'exact', '1200000'), ('solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp', 'exact', '1200000')]

status 200
order state Finished
pay_way X402
pay_id 0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
settle_header {'success': True, 'network': 'base', 'transaction': '0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151'}

Base tx status 1
block 46726704
explorer https://basescan.org/tx/0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
transfer value 1200000 atomic USDC

Opis wyników:

Po utworzeniu zamówienia jego stan to Pending, a cena to 1.26.
Pierwsze żądanie pay/ zwraca HTTP 402; w accepts znajdują się Base exact i Solana exact, a obie kwoty wynoszą 1200000 atomic USDC.
Po ponowieniu z Base PAYMENT-SIGNATURE zwracany jest HTTP 200, stan zamówienia zmienia się na Finished, a pay_way to X402.
Po zdekodowaniu PAYMENT-RESPONSE wyświetlane są success=True, network=base oraz ten sam hash transakcji.
Na BaseScan stan transakcji to 1, a kwota transferu wynosi 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 kwota podpisu i rozliczenia wynosi 1.2 USDC.

Jeśli płatność za zamówienie nie zawiera Authorization: Bearer {platform_token} lub 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 przez x402.acedata.cloud.

Częste błędy

Objaw	Kierunek diagnostyki
Pierwsze żądanie nie jest 402	Sprawdź, czy omyłkowo przekazano `Authorization`, lub czy to API nadal nie ma X402 pricing.
`No payment requirement for network`	Sieć docelowa nie znajduje się w `accepts`; zmień sieć lub sprawdź konfigurację Gateway.
`invalid_402`	Odpowiedź 402 nie jest prawidłowym JSON; sprawdź proxy, gateway lub stronę błędu.
`Authorization nonce already processed`	Ten sam `PAYMENT-SIGNATURE` został użyty ponownie; podpisz ponownie.
`invalid_upto_evm_payload_invalid_signature`	Sprawdź, czy chainId `upto`, Permit2 domain, adres facilitator i konto podpisujące są zgodne.
`PERMIT2_ALLOWANCE_REQUIRED`	Wykonaj `approve-permit2` dla USDC w sieci docelowej.
`Payer has insufficient USDC balance`	Portfel płatnika ma niewystarczającą ilość USDC.
HTTP 200, ale bez tx hash	Rzeczywista kwota `upto` może wynosić 0 lub rekord settlement jest nadal zapisywany asynchronicznie.
Solana `Missing transaction payload`	W envelope `PAYMENT-SIGNATURE` nie ma serializowanej transakcji ani signature; sprawdź wallet adapter.

Lista kontrolna Base `upto`

upto jest obecnie dostępne tylko na Base (eip155:8453). SKALE udostępnia tylko exact. 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ą w pełni zgodne z podpisem klienta.

SKALE exact
HTTP 402 -> HTTP 200
content ADC_SKALE_E2E_OK
tx 0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f

Base upto
HTTP 402 -> HTTP 200
content ADC_BASE_UPTO_OK
tx 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
explorer https://basescan.org/tx/0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
signed ceiling 95215 atomic USDC
transfer value 3 atomic USDC

Jeśli Base upto zwraca invalid_upto_evm_payload_invalid_signature, w pierwszej kolejności sprawdź:

extra.chainId (powinno wynosić 8453) w elemencie eip155:8453 + upto zwróconym przez API.
extra.facilitatorAddress zwrócone przez API.
Adres facilitatora Base upto zwrócony przez https://facilitator.acedata.cloud/supported.
Permit2 domain, spender, kontrakt USDC i konto podpisujące.
Czy portfel wykonał już approve Permit2 dla Base USDC.

Digest podpisu upto jednocześnie wiąże Permit2 domain, chain ID, spender, adres odbiorcy, adres facilitatora i validAfter. Jeśli dowolna pozycja jest niezgodna, Facilitator odzyska nieprawidłowego signera, a następnie zwróci invalid signature. Jeśli wszystkie są zgodne, ale nadal zwracane jest 402, w kolejnym kroku sprawdź Permit2 allowance; przy braku autoryzacji zwracane jest PERMIT2_ALLOWANCE_REQUIRED.

Zapisywanie informacji weryfikacyjnych

Co najmniej w ramach jednej pełnej weryfikacji zapisz:

ścieżkę API i podsumowanie treści żądania;
wybrane network i scheme;
maxAmountRequired;
adres portfela płatnika;
końcowy status HTTP;
wynik modelu lub identyfikator zadania w odpowiedzi;
link do transakcji rozliczeniowej;
identyfikator śledzenia Gateway lub identyfikator rekordu użycia platformy.

Nie zapisuj kluczy prywatnych, pełnego PAYMENT-SIGNATURE, pełnego podpisu EIP-712 ani frazy seed.

Ustrukturyzowane błędy płatności

Błędy X402 po podpisaniu zwracają w extensions.acedatacloud.paymentError stabilny code, bezpieczne parametry interpolacji, etap i flagę ponawiania. Przy rozwiązywaniu problemów preferuj tę strukturę, nie analizuj angielskiego error najwyższego poziomu i nie wymagaj od użytkowników podawania podpisu portfela ani oryginalnego tekstu symulacji on-chain.

charged: false: weryfikacja została wyraźnie odrzucona przed rozliczeniem, w tym przypadku nie zainicjowano obciążenia.
Brak charged: wynik jest nieznany lub proces wszedł już w etap rozliczenia; najpierw sprawdź zamówienie i status on-chain, bezpośrednie ponawianie płatności jest zabronione.
settlement_pending: na razie nie ponawiaj płatności; najpierw odśwież zamówienie lub skontaktuj się ze wsparciem.
Nierozpoznany code: traktuj jako payment_failed i zachowaj publiczny kod techniczny na potrzeby wyszukiwania przez obsługę klienta.

Getting Started

Czat AI

Obraz AI

Wideo AI

Audio AI

Sieć i dane

CAPTCHA

Tożsamość

Coding

Więcej przewodników

Walidacja i rozwiązywanie problemów X402 E2E

Sprawdź publiczny punkt wejścia

Sprawdź 402 `accepts`

Uruchom zaawansowane narzędzia weryfikacyjne X402Client

SDK smoke test

E2E płatności za zamówienie

Częste błędy

Lista kontrolna Base `upto`

Zapisywanie informacji weryfikacyjnych

Ustrukturyzowane błędy płatności

​Sprawdź publiczny punkt wejścia

​Sprawdź 402 accepts

​Uruchom zaawansowane narzędzia weryfikacyjne X402Client

​SDK smoke test

​E2E płatności za zamówienie

​Częste błędy

​Lista kontrolna Base upto

​Zapisywanie informacji weryfikacyjnych

​Ustrukturyzowane błędy płatności

Sprawdź publiczny punkt wejścia

Sprawdź 402 `accepts`

Uruchom zaawansowane narzędzia weryfikacyjne X402Client

SDK smoke test

E2E płatności za zamówienie

Częste błędy

Lista kontrolna Base `upto`

Zapisywanie informacji weryfikacyjnych

Ustrukturyzowane błędy płatności