Przejdź do głównej treści
X402 to protokół płatności on-chain oparty na HTTP 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
Publiczne źródła i adresy pakietów: 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.
Wyjaśnienie:
  • Pakiety npm i PyPI zostały zainstalowane i pomyślnie zaimportowane w czystym środowisku.
  • Żądanie API bez płatności zwraca 402, a accepts zawiera dostępne metody płatności dla Base i Solana.
  • accepts[].network jest 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, Base upto i płatności za zamówienia mają publicznie dostępne adresy explorera.
  • Podpisany limit Base upto wynosi 95215 atomic USDC, a rzeczywiste rozliczenie wynosi 3 atomic USDC, co odzwierciedla cechę rozliczania według rzeczywistego użycia w pomiarze po fakcie.
  • Solana exact zweryfikowano 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[].maxAmountRequired to maksymalna kwota możliwa do podpisania dla bieżącego żądania.
  • accepts[].asset to kontrakt USDC lub mint USDC, którego należy użyć dla tego żądania.
  • accepts[].extra.chainId, accepts[].extra.facilitatorAddress i accepts[].extra.verifyingContract będą uczestniczyć w podpisie EVM typed data.
  • upto wymaga, aby portfel najpierw udzielił Permit2 autoryzacji USDC na docelowym łańcuchu; przy braku autoryzacji zostanie zwrócone PERMIT2_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 Authorization lub PAYMENT-SIGNATURE zwracają 402 Payment Required, a accepts w 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ą accepts zwracanego 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.