Przejdź do głównej treści
Ten samouczek przedstawia kompletny proces Ace Data Cloud X402 za pomocą minimalnego żądania API. Celem nie jest najpierw pisanie złożonego kodu, lecz najpierw zrozumienie: dlaczego pierwsze żądanie zwraca 402, co znajduje się w accepts oraz w jaki sposób PAYMENT-SIGNATURE zmienia to samo żądanie API w opłacone żądanie.

Przygotowanie

Musisz przygotować: Podczas wywoływania Ace Data Cloud API przez X402 nie jest wymagany API Token. Pierwsze żądanie SDK nie zawiera Authorization, Gateway zwróci 402 Payment Required oraz wymagania płatności; po podpisaniu SDK automatycznie ponowi próbę.

Instalacja SDK

Adresy źródeł i pakietów: TypeScript:
Python:
Jeśli chcesz używać Solana, musisz również zainstalować odpowiednie zależności:
Zależność Solana signer dla wersji Python jest już zawarta w acedatacloud-x402. Wynik instalacji i sprawdzenia importów w czystym środowisku tymczasowym:
Wyjaśnienie wyników:
  • Zarówno pakiety npm, jak i PyPI są rzeczywiście opublikowanymi pakietami, a nie nazwami zastępczymi w dokumentacji.
  • acedatacloud-x402[cli] zainstaluje CLI, a podkomenda approve-permit2 może być używana do autoryzacji Permit2 w scenariuszu upto.

Pierwsze żądanie zwróci 402

Możesz najpierw użyć curl, aby zobaczyć, co zwraca nieopłacone żądanie. Poniższy przykład nie spowoduje obciążenia, ponieważ nie zawiera PAYMENT-SIGNATURE:
Treść odpowiedzi będzie zawierać tablicę accepts, której typowa struktura jest następująca:
Ta sama treść wyzwania jest również umieszczana w formacie base64 w nagłówku odpowiedzi PAYMENT-REQUIRED, aby klient mógł odczytać wymagania płatności bez parsowania body. Podsumowanie wyjścia programu dla nieopłaconego żądania produkcyjnego API jest następujące:
Wyjaśnienie wyników:
  • Pierwsze żądanie nie zawiera Authorization ani PAYMENT-SIGNATURE, dlatego zwraca HTTP 402 i nie powoduje obciążenia.
  • accepts jest jedyną wiarygodną podstawą podpisu dla tego żądania i zawiera dostępne sieci, scheme, limit kwoty, adres odbiorcy oraz adres aktywa.
  • network jest identyfikatorem CAIP-2; podczas wyboru sieci klient musi dopasować ciąg CAIP-2.
  • Limit kwoty dla tego minimalnego żądania czatu gpt-4o-mini wynosi 95215 atomic USDC, czyli 0.095215 USDC.
  • Dla każdego żądania należy odczytać bieżącą odpowiedź 402; nie należy na stałe kodować przykładowej kwoty w kodzie biznesowym.
Znaczenie pól:

Ukończenie ponownej próby płatności za pomocą SDK

Poniżej znajduje się minimalny przykład TypeScript. Określa on network: 'base', a handler wybierze wymaganie płatności Base z bieżącej odpowiedzi 402; rzeczywista kwota i adres odbiorcy nadal są określane przez accepts:
Za tą częścią kodu stoją cztery kroki:
  1. SDK wysyła zwykłe żądanie API bez Authorization.
  2. Gateway zwraca 402 Payment Required oraz accepts.
  3. createX402PaymentHandler wybiera payment requirement dla network = 'base' i podpisuje PAYMENT-SIGNATURE.
  4. SDK ponawia żądanie z tym samym body, a Gateway wywołuje Facilitator w celu weryfikacji i rozliczenia, po czym przepuszcza je do docelowego API.

Sprawdzanie obsługiwanych możliwości Facilitator

X402 API nie zależy od katalogu zasobów. Klient bezpośrednio wywołuje znane API i wykorzystuje zwrócone w czasie rzeczywistym przez to żądanie 402 Payment Required oraz accepts jako jedyną podstawę ceny i podpisu. Deklaracja możliwości Facilitator znajduje się pod adresem:
Opisuje ona tylko /supported, /verify, /settle oraz aktualnie włączone sieci płatności, nie wymienia zasobów API. Adres produkcyjnego Facilitator Ace Data Cloud to:
Można sprawdzić, jakie sieci i scheme obsługuje:
Zwrócone kinds wyświetlą sieci i scheme obsługiwane przez Facilitator. Podczas rzeczywistych wywołań nadal należy kierować się accepts zwróconym przez API. Wynik /supported Facilitator:
Wynik oznacza:
  • /supported wskazuje, że Facilitator ma możliwości weryfikacji i rozliczania dla tych sieci i scheme.
  • Zarówno Base, jak i Solana obsługują exact; upto jest obecnie dostępne tylko w Base.
  • To, czy konkretne API zezwala na daną sieć, nadal zależy od 402 accepts tego API.