> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Walidacja i rozwiązywanie problemów X402 E2E > Platform API guide - Ace Data Cloud 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: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} 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](https://github.com/AceDataCloud/X402Client) ```bash theme={null} git clone https://github.com/AceDataCloud/X402Client.git cd X402Client/typescript npm install npm install --no-save ethers @solana/spl-token bs58 tsx ``` Base: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} export X402B_SOLANA_PAYER_PRIVATE_KEY=... npx tsx scripts/test-solana-e2e.ts ``` Narzędzia weryfikacyjne zazwyczaj wypisują: 1. Odpowiedź 402 pierwszego żądania. 2. Wybrane payment requirement. 3. Skrót podpisanego `PAYMENT-SIGNATURE`. 4. Status HTTP i treść odpowiedzi po ponowieniu próby. 5. 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: ```text theme={null} 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: ```ts theme={null} 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: ```python theme={null} 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: ```text theme={null} 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. ```text theme={null} 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. ```text theme={null} 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ź: 1. `extra.chainId` (powinno wynosić `8453`) w elemencie `eip155:8453` + `upto` zwróconym przez API. 2. `extra.facilitatorAddress` zwrócone przez API. 3. Adres facilitatora Base `upto` zwrócony przez `https://facilitator.acedata.cloud/supported`. 4. Permit2 domain, spender, kontrakt USDC i konto podpisujące. 5. 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.