PAYMENT-SIGNATURE, a następnie ponawia to samo żądanie.
Różnica polega na tym, że płatność za zamówienie należy do API platformy i wymaga tokenu konta; natomiast bezpośrednie wywoływanie AI API x402.acedata.cloud może korzystać wyłącznie z X402, bez potrzeby używania API Token.
Przygotowanie zamówienia
Wejdź do konsoli Ace Data Cloud, wybierz zamówienie, za które chcesz zapłacić, i zanotuj ID zamówienia. Jeśli nie masz jeszcze zamówienia, możesz utworzyć oczekujące na płatność zamówienie na stronie pakietów. Cena zamówienia jest zgodna z ceną wyświetlaną na stronie, aamount w odpowiedzi X402 402 jest ostateczną podstawą podpisu.
Tworzenie tokenu konta
Żądania płatności za zamówienia wymagają tokenu konta. Otwórz stronę Token platformy, utwórz token w formacieplatform-v1-....
W kolejnych żądaniach używaj:
Wywołanie 402
Najpierw wyślij żądanie bezPAYMENT-SIGNATURE:
accepts:
x402Version wynosi 2, network używa identyfikatora CAIP-2, a pole kwoty to amount.
Wynik działania programu tworzącego zamówienie na 10 Credits i wywołującego 402:
Poniższe rekordy transakcji są historycznymi, rzeczywistymi przykładami z okresu obowiązywania starej polityki, a kwoty i hashe transakcji zachowano w oryginalnej formie. Nowe zamówienia X402 nie otrzymują już rabatów zależnych od metody płatności; jako podstawę podpisu i płatności należy przyjąć amount z bieżącej odpowiedzi 402.
- Po pomyślnym utworzeniu zamówienia jego status to
Pending, a płatność on-chain nie została jeszcze wykonana. - Pierwsze żądanie
pay/nie zawieraPAYMENT-SIGNATURE, dlatego zwraca HTTP 402. acceptsjednocześnie podaje Baseexacti Solanaexact, a w dalszej części tego samouczka wybrano Base.- Cena przy utworzeniu zamówienia wynosiła
1.26; w trakcie obowiązywania starej polityki rabatów za płatności X402 rzeczywista kwota podpisu i rozliczenia wynosiła1.2USDC, czyli1200000atomic USDC.
resource jest polem zwracanym przez serwer i uczestniczącym w podpisie, dlatego klient nie powinien samodzielnie zmieniać znajdującego się w nim protokołu, ścieżki ani ID zamówienia.
Podpisanie i ponowienie
Płatność za zamówienie może ponownie wykorzystać niskopoziomowe funkcje podpisu z@acedatacloud/x402-client lub acedatacloud-x402. Poniżej znajduje się przykład TypeScript:
exact i ponowieniu dla tego samego zamówienia:
status 200oznacza, że interfejs płatności zamówienia platformy zaakceptował tenPAYMENT-SIGNATURE.has_x_payment_response Trueoznacza, że nagłówek odpowiedzi zawiera zakodowany w Base64 paragonPAYMENT-RESPONSE.settle_header.success=Trueoraznetwork=baseoznaczają, że Facilitator zakończył settlement w Base.- Końcowy status zamówienia to
Finished,pay_waytoX402, apay_idzapisuje hash transakcji on-chain. - Zdarzenie
Transferna BaseScan pokazuje, że adres płatnika przelał na adres odbiorcy platformy1200000atomic USDC, czyli1.2USDC.
Pomyślna odpowiedź i paragon
Po pomyślnej płatności zamówienia treść odpowiedzi zawiera informacje o zamówieniu. Platforma przenosi również w nagłówku odpowiedziPAYMENT-RESPONSE zakodowaną w Base64 odpowiedź settlement, której typowe pola po zdekodowaniu obejmują:
Jeśli potrzebujesz uzgodnienia, zaleca się jednoczesne zapisanie ID zamówienia, adresu portfela płatnika,
transaction oraz końcowego statusu zamówienia.
Uwagi
- Płatność zamówienia wymaga tokena konta platformy i nie może zostać zrealizowana wyłącznie za pomocą podpisu portfela X402.
amountużywa USDC atomic units,1200000oznacza1.2USDC.- Nie składaj samodzielnie adresu odbiorcy ani adresu aktywa; kieruj się
acceptsw odpowiedzi 402. - Jeśli ten sam
PAYMENT-SIGNATUREzostanie przesłany ponownie, Facilitator zastosuje ochronę przed ponownym odtworzeniem na podstawie nonce.
Odpowiedź w przypadku niepowodzenia płatności
Pierwszy HTTP 402 bezPAYMENT-SIGNATURE jest normalnym wyzwaniem płatności i nie oznacza niepowodzenia płatności. Niepowodzenie weryfikacji lub settlement po podpisaniu nadal zachowuje standardowy tekstowy error jako kompatybilne zabezpieczenie awaryjne i zwraca stabilną strukturę błędu w extensions.acedatacloud.paymentError:
code, a w przypadku nieznanego code przejść do ogólnego niepowodzenia płatności. charged jest polem trójstanowym: false zostanie zwrócone tylko wtedy, gdy płatność zostanie wyraźnie odrzucona przed settlement; brak pola oznacza, że status obciążenia jest nieznany i nie może być interpretowany jako „nie pobrano opłaty”. Po przejściu bieżącego zamówienia do Failed nie można ponowić próby dla tego samego zamówienia; po naprawieniu problemu z portfelem utwórz nowe zamówienie.
metadata.x402.last_error oraz metadata.x402.errors na liście i w szczegółach zamówienia zachowują ten sam zestaw code, stage, retryable, charged oraz params; publiczny tekst wyjaśniający jest przechowywany w reason, a czas wystąpienia w timestamp. Na przykład insufficient_token_balance oznacza niewystarczające saldo USDC w wybranej sieci, a invalid_signature oznacza nieprawidłowy podpis płatności; ponowne odczytanie zamówienia nie zmieni ich na ogólne payment_failed.
Nie zapisuj ani nie przesyłaj pełnego PAYMENT-SIGNATURE, podpisów portfela, payloadu autoryzacji, surowej diagnostyki Facilitatora ani odpowiedzi RPC. Do analizy przez obsługę klienta wystarczą ID zamówienia oraz publiczny code błędu.
Wykup i spalanie ACE dla płatności Base i Solana
Po włączeniu strategii wykupu, 3% faktycznie otrzymanej kwoty kwalifikujących się płatności Circle USDC w sieci głównej Base i USDC w sieci głównej Solana jest używane do zakupu i spalenia ACE, bez dodatkowego obciążania portfela płatnika. Odpis jest naliczany jednorazowo podczas doładowania, a późniejsze użycie tych Credits do wywoływania API nie powoduje ponownego naliczenia; historyczne zamówienia rabatowe i zamówienia ze starą strategią nie są automatycznie rozliczane wstecznie. Płatności Base zachowują paragon płatności w łańcuchu Base, a zakup i spalanie ACE są wykonywane asynchronicznie w Solana. Kwalifikujące się płatności są naliczane dokładnie w wysokości 3% faktycznie otrzymanej kwoty, bez ustalonego limitu kwoty wykupu na pojedynczą transakcję lub na dzień; dostępne środki, ceny rynkowe i potwierdzenia on-chain nadal mogą wpływać na czas realizacji. Obiektace_burn w szczegółach zamówienia udostępnia settlement_network, settlement_transaction oraz execution_network, a po ukończeniu udostępnia swap_signature i burn_signature. Pending lub Processing nie oznacza, że spalanie zostało wykonane; tylko Completed oznacza, że ostateczny dowód on-chain został zweryfikowany. Gdy płatność Base nie osiągnęła jeszcze ostatecznego potwierdzenia, wykup oczekuje na potwierdzenie, ale nie wpływa to na Credits, które już wpłynęły.
