Skip to main content
X402 to oparty na HTTP 402 Payment Required protokół płatności na łańcuchu. Dzięki możliwościom X402 w Ace Data Cloud, wywołujący może dokonywać płatności na łańcuchu bez tworzenia tokena API i bez wcześniejszego doładowania salda konta, płacąc bezpośrednio USDC w każdej prośbie API. Zestaw dokumentów jest zorganizowany według rzeczywistej kolejności integracji: najpierw wykonaj minimalne żądanie, następnie zintegrować SDK, a potem zrozumieć sieć, plany taryfowe, płatności za zamówienia i Facilitator. Zaleca się czytanie według poniższej tabeli od góry do dołu.

​
Zalecana ścieżka integracji

Jeśli chcesz tylko wywołać API Ace Data Cloud, najpierw użyj oficjalnego SDK:
  • TypeScript: @acedatacloud/sdk + @acedatacloud/x402-client
  • Python: acedatacloud + acedatacloud-x402
Publiczne źródła i adresy pakietów: SDK automatycznie obsłuży pierwsze żądanie bez uwierzytelnienia, zinterpretuje 402 Payment Required, wywoła handler płatności i powtórzy te kroki z PAYMENT-SIGNATURE. Musisz tylko przygotować portfel z USDC i wybrać sieć, której chcesz użyć. Jeśli chcesz, aby Twoje API również obsługiwało płatności X402, musisz przeczytać dokumentację Facilitator, aby zrozumieć relacje między paymentRequirements, paymentPayload, /verify i /settle.

​
Status wsparcia

Ace Data Cloud X402 został zweryfikowany w publicznym API, oficjalnym SDK, Facilitatorze i ścieżkach rozliczeń na łańcuchu. Poniższa tabela podsumowuje aktualny status według najczęściej używanych wymiarów możliwości przez deweloperów. Poniższe wyjście służy wyłącznie do ilustracji formatu zwrotu zweryfikowanej ścieżki. Podczas rzeczywistej integracji zawsze kieruj się aktualnymi accepts zwracanymi przez API.
Uwagi:
  • Pakiety npm i PyPI zostały zainstalowane i zaimportowane pomyślnie w czystym środowisku.
  • Nieopłacone żądanie API zwraca 402, accepts zawiera dostępne metody płatności dla Base, SKALE i Solana.
  • accepts[].network to identyfikator CAIP-2, przy wyborze sieci przez klienta należy dopasować zgodnie z ciągiem CAIP-2.
  • TypeScript SDK i Python SDK automatycznie obsługują 402 i wykonują ponowną próbę płatności.
  • Base exact, SKALE exact, Base upto oraz płatność za zamówienie mają publicznie dostępne adresy eksploratora.
  • Limit podpisu dla Base upto wynosi 95215 atomic USDC, rzeczywiste rozliczenie wynosi 3 atomic USDC, co odzwierciedla cechę rozliczania na podstawie rzeczywistego zużycia.
  • Solana exact zweryfikowała HTTP 402 -> HTTP 200 oraz wyjście modelu. Ze względu na możliwe ograniczenia zapytań RPC publicznych, w przypadku ścisłego uzgadniania zaleca się korzystanie z własnego RPC Solana lub potwierdzenie podpisu transakcji na zapisach rozliczeniowych platformy.

​
Uwagi dotyczące integracji

Podczas integracji deweloperzy powinni najpierw zwrócić uwagę na aktualne wymagania dotyczące płatności zwracane przez żądanie, a nie kopiować przykładowe kwoty lub adresy z dokumentacji:
  • accepts[].maxAmountRequired to maksymalna kwota, którą można podpisać w bieżącym żądaniu.
  • accepts[].asset to kontrakt USDC lub mint, który ma być użyty w tym żądaniu.
  • accepts[].extra.chainId, accepts[].extra.facilitatorAddress i accepts[].extra.verifyingContract będą uczestniczyć w podpisie danych typu EVM.
  • upto wymaga, aby portfel najpierw autoryzował USDC na docelowej sieci za pomocą Permit2; w przypadku braku autoryzacji zwróci PERMIT2_ALLOWANCE_REQUIRED.
  • Jeśli wyraźnie chcesz użyć rozliczenia na podstawie rzeczywistego zużycia, przekaż w TypeScript SDK preferScheme: 'upto', w przeciwnym razie SDK wybierze pierwszy dostępny wymóg zwrócony przez serwer w danej sieci.

​
Zakres publicznej weryfikacji

Przed integracją można najpierw zweryfikować te publiczne punkty dostępu i zachowanie SDK:
  • Żądania API bez Authorization lub PAYMENT-SIGNATURE zwrócą 402 Payment Required, a accepts w odpowiedzi jest jedyną podstawą podpisu dla tego żądania.
  • TypeScript SDK i Python SDK oferują handler płatności, warstwa transportowa SDK po otrzymaniu 402 wywoła handler i spróbuje ponownie.
  • https://facilitator.acedata.cloud/.well-known/x402: zwraca sieci, schematy i punkty końcowe protokołu wspierane przez Facilitatora; cena API nadal opiera się na 402 zwracanym w czasie rzeczywistym dla docelowego żądania.
  • https://facilitator.acedata.cloud/supported: zwraca sieci i schematy wspierane przez Facilitatora.
  • Repozytorium X402Client zawiera zaawansowane narzędzia do weryfikacji on-chain, które mogą być używane do potwierdzania podpisów, ponownych prób i zachowań rozliczeniowych; wyniki narzędzi nie zastępują zwracanych przez API accepts.
upto należy do rozliczenia na podstawie rzeczywistego zużycia, odpowiedniego dla uzupełniania czatu, wywołań modelu i innych API, gdzie rzeczywiste zużycie jest znane dopiero po odpowiedzi. Obecnie tylko Base oferuje upto; jeśli weryfikacja podpisu nie powiedzie się, sprawdź, czy identyfikator sieci, adres ułatwiający, spender, kontrakt USDC i limit Permit2 są zgodne z odpowiedzią 402.