402 Payment Required. Dzięki możliwościom X402 Ace Data Cloud wywołujący nie musi tworzyć API Token ani doładowywać salda konta z wyprzedzeniem, lecz może bezpośrednio realizować płatności on-chain w USDC przy każdym żądaniu API.
Ten zestaw dokumentów jest zorganizowany według rzeczywistej kolejności integracji: najpierw wykonaj minimalne żądanie, następnie zintegruj SDK, a potem zapoznaj się z sieciami, planami rozliczeń, płatnościami za zamówienia i Facilitator. Zaleca się czytanie od góry do dołu zgodnie z poniższą tabelą.
Zalecana ścieżka integracji
Jeśli chcesz jedynie wywoływać Ace Data Cloud API, w pierwszej kolejności użyj oficjalnego SDK:- TypeScript:
@acedatacloud/sdk+@acedatacloud/x402-client - Python:
acedatacloud+acedatacloud-x402
SDK automatycznie wykona kroki pierwszego żądania bez uwierzytelnienia, przeanalizuje
402 Payment Required, wywoła payment handler oraz ponowi próbę z PAYMENT-SIGNATURE. Wystarczy przygotować portfel z USDC i wybrać sieć, z której chcesz korzystać.
Jeśli chcesz, aby Twoje własne API również obsługiwało przyjmowanie płatności X402, musisz przeczytać dokumentację Facilitator, aby zrozumieć relację między paymentRequirements, paymentPayload, /verify i /settle.
Status wsparcia
Ace Data Cloud X402 został zweryfikowany w publicznym API, oficjalnym SDK, Facilitator i ścieżce rozliczeń on-chain. Poniższa tabela podsumowuje bieżący status według wymiarów możliwości najczęściej używanych przez deweloperów podczas integracji.
Poniższe dane wyjściowe służą wyłącznie do przedstawienia formatu odpowiedzi zweryfikowanych ścieżek. Podczas rzeczywistej integracji zawsze kieruj się
accepts zwróconym przez bieżące API.
- Pakiety npm i PyPI zostały zainstalowane i pomyślnie zaimportowane w czystym środowisku.
- Żądanie API bez płatności zwraca 402, a
acceptszawiera dostępne metody płatności dla Base i Solana. accepts[].networkjest identyfikatorem CAIP-2; klient musi dopasować sieć według ciągu CAIP-2 podczas jej wyboru.- Zarówno TypeScript SDK, jak i Python SDK mogą automatycznie obsłużyć 402 i wykonać płatną ponowną próbę.
- Base
exact, Baseuptoi płatności za zamówienia mają publicznie dostępne adresy explorera. - Podpisany limit Base
uptowynosi95215atomic USDC, a rzeczywiste rozliczenie wynosi3atomic USDC, co odzwierciedla cechę rozliczania według rzeczywistego użycia w pomiarze po fakcie. - Solana
exactzweryfikowano pod kątem HTTP 402 -> HTTP 200 oraz wyjścia modelu. Ponieważ publiczne zapytania RPC mogą podlegać ograniczaniu liczby żądań, przy ścisłym uzgadnianiu zaleca się użycie własnego Solana RPC lub potwierdzenie podpisu transakcji w zapisach rozliczeniowych po stronie platformy.
Uwagi dotyczące integracji
Podczas integracji deweloperzy powinni przede wszystkim zwracać uwagę na wymagania płatnicze zwracane w czasie rzeczywistym przez bieżące żądanie, zamiast kopiować przykładowe kwoty lub adresy z dokumentacji:accepts[].maxAmountRequiredto maksymalna kwota możliwa do podpisania dla bieżącego żądania.accepts[].assetto kontrakt USDC lub mint USDC, którego należy użyć dla tego żądania.accepts[].extra.chainId,accepts[].extra.facilitatorAddressiaccepts[].extra.verifyingContractbędą uczestniczyć w podpisie EVM typed data.uptowymaga, aby portfel najpierw udzielił Permit2 autoryzacji USDC na docelowym łańcuchu; przy braku autoryzacji zostanie zwróconePERMIT2_ALLOWANCE_REQUIRED.- Jeśli wyraźnie chcesz użyć pomiaru po fakcie, przekaż
preferScheme: 'upto'w TypeScript SDK; w przeciwnym razie SDK wybierze pierwsze dostępne requirement zwrócone przez serwer dla tej sieci.
Zakres możliwy do publicznej weryfikacji
Przed integracją można najpierw zweryfikować te publiczne punkty wejścia i zachowanie SDK:- Żądania API bez
AuthorizationlubPAYMENT-SIGNATUREzwracają402 Payment Required, aacceptsw odpowiedzi jest jedyną podstawą podpisu dla bieżącego żądania. - Zarówno TypeScript SDK, jak i Python SDK zapewniają payment handler; warstwa transportowa SDK po otrzymaniu 402 wywoła handler i ponowi próbę jeden raz.
https://facilitator.acedata.cloud/.well-known/x402: zwraca sieci, scheme i punkty końcowe protokołu obsługiwane przez Facilitator; ceny API nadal opierają się na 402 zwracanym w czasie rzeczywistym przez docelowe żądanie.https://facilitator.acedata.cloud/supported: zwraca sieci i scheme obsługiwane przez Facilitator.- Repozytorium X402Client zawiera zaawansowane narzędzia weryfikacji on-chain, które mogą być używane do potwierdzania podpisów, ponownych prób i zachowania settlement; dane wyjściowe narzędzi nie zastępują
acceptszwracanego przez API online.
upto należy do rozliczania z pomiarem po fakcie i jest odpowiednie dla API, takich jak uzupełnianie czatu i wywołania modelu, gdzie rzeczywiste użycie jest znane dopiero po odpowiedzi. Obecnie tylko Base udostępnia upto; jeśli weryfikacja podpisu się nie powiedzie, sprawdź, czy chain id, adres facilitatora, spender, kontrakt USDC i Permit2 allowance są zgodne z odpowiedzią 402.
