Przejdź do głównej treści
Facilitator jest komponentem rozliczeniowym po stronie serwera w łańcuchu X402. Klient odpowiada za podpisywanie, a Gateway lub twój serwer odpowiada za wywoływanie /verify i /settle Facilitatora. Produkcyjny adres Facilitatora Ace Data Cloud to:
Repozytorium źródłowe: https://github.com/AceDataCloud/FacilitatorX402

Konwencje wire v2

Łańcuch X402 Ace Data Cloud w całości używa oficjalnego x402 v2 i nie akceptuje już nagłówka żądania X-Payment z v1. Podczas integracji należy zwrócić uwagę na trzy punkty:
  • Nagłówkiem żądania jest PAYMENT-SIGNATURE, a jego wartością jest envelope JSON zakodowany w base64.
  • Na najwyższym poziomie envelope musi znajdować się x402Version: 2, a wybrane w tym przypadku scheme i network należy zadeklarować za pomocą obiektu accepted.
  • network używa identyfikatora CAIP-2 (np. eip155:8453), nie można zapisywać skrótów takich jak base.
Struktura envelope:
Odpowiedź 402, oprócz JSON body, zawiera również nagłówek odpowiedzi PAYMENT-REQUIRED, którego wartością jest ta sama treść wyzwania zakodowana w base64, co ułatwia klientowi odczytanie wymagań płatności bez parsowania body.

Kluczowe interfejsy

GET /supported

Sprawdź obsługiwane sieci i scheme:
Przykład odpowiedzi:
Opis wyników:
  • network używa identyfikatora CAIP-2, a nie skrótów takich jak base czy solana.
  • /supported oznacza, że Facilitator posiada odpowiednie możliwości weryfikacji i rozliczania.
  • Base i Solana obsługują exact; upto jest obecnie dostępne tylko na Base.
  • signers to adresy używane przez Facilitator do wysyłania transakcji rozliczeniowych.
  • To, czy konkretne API zezwala na te opcje, nadal zależy od accepts w odpowiedzi 402 tego API.

POST /verify

Zweryfikuj, czy PAYMENT-SIGNATURE przesłany przez klienta spełnia określony payment requirement. Body żądania:
Pola paymentRequirements w v2 to scheme, network, asset, amount, payTo, maxTimeoutSeconds i extra, a pole kwoty to amount. W accepts[] odpowiedzi API 402 zwracane jest dodatkowo maxAmountRequired, aby klient mógł odczytać limit, ale nie należy ono do pól body żądania Facilitatora. Pomyślna odpowiedź:
Po zdekodowaniu nagłówka odpowiedzi PAYMENT-RESPONSE dla płatności zamówienia produkcyjnego zawiera on wynik settlement. Wynik działania programu dla płatności zamówienia Base:
Opis wyników:
  • success=True oznacza, że settlement Facilitatora zakończył się sukcesem.
  • transaction jest hashem transakcji on-chain, a pay_id zamówienia jest również zapisywane z tą samą wartością.
  • W explorer można zobaczyć transfer 1200000 atomic USDC Base.
  • errorReason=None oznacza, że ten settlement nie zwrócił błędu biznesowego.
Nieudana weryfikacja zazwyczaj również zwraca HTTP 200, ale isValid ma wartość false. Strona biznesowa powinna odczytać invalidReason, zamiast patrzeć wyłącznie na kod statusu HTTP.

POST /settle

Rozlicz on-chain autoryzację, która została już zweryfikowana. Body żądania jest zasadniczo takie samo jak dla /verify. Różnica dla upto polega na tym, że paymentRequirements.amount jest podczas settle nadpisywane rzeczywistą kwotą rozliczenia; limit podpisu jest rejestrowany przez Facilitator na etapie verify, a podczas settle sprawdzane jest, czy rzeczywista kwota nie przekracza tego limitu. Pomyślna odpowiedź:
Jeśli rzeczywista kwota upto wynosi 0, transaction może być pustym ciągiem znaków, co oznacza, że nie trzeba wysyłać transakcji on-chain.

Jak Ace Data Cloud Gateway używa Facilitatora

Łańcuch API Gateway Ace Data Cloud wygląda następująco:
  1. Klient po raz pierwszy wysyła żądanie API bez Authorization i PAYMENT-SIGNATURE.
  2. Gateway oblicza szacowaną cenę żądania i zwraca 402 oraz accepts.
  3. Po podpisaniu klient ponawia próbę z PAYMENT-SIGNATURE.
  4. Gateway dekoduje PAYMENT-SIGNATURE i wybiera pasujący payment requirement.
  5. Gateway wywołuje /verify Facilitatora.
  6. Po powodzeniu /verify Gateway przepuszcza żądanie do docelowego API.
  7. Po zwróceniu odpowiedzi przez docelowe API Gateway wywołuje /settle Facilitatora na etapie /record.
  8. Gateway zapisuje hash transakcji on-chain w metadata rekordu użycia.
exact rozlicza kwotę podpisaną w kroku 7; upto zapisuje amount według rzeczywistego użycia w kroku 7, a następnie rozlicza rzeczywistą kwotę.

Jak zintegrować własne API

Jeśli chcesz, aby twoje własne API obsługiwało X402, możesz zaimplementować je według tej struktury:
  1. Przygotuj paymentRequirements dla każdego płatnego interfejsu, zawierające sieć, kwotę, adres odbiorcy, adres aktywa i domain podpisu.
  2. Jeśli żądanie nie ma PAYMENT-SIGNATURE, zwróć HTTP 402 i accepts.
  3. Jeśli żądanie ma PAYMENT-SIGNATURE, zdekoduj Base64, aby uzyskać paymentPayload.
  4. Wywołaj Facilitator /verify.
  5. Po pomyślnej weryfikacji wykonaj logikę biznesową.
  6. Po pomyślnym wykonaniu logiki biznesowej wywołaj Facilitator /settle.
  7. Zapisz payer, transaction, amount, network na potrzeby uzgadniania.
Serwer musi używać własnoręcznie wygenerowanych paymentRequirements do wywołania /verify i /settle, nie ufaj kwocie, adresowi odbiorcy ani adresowi aktywa zwróconym przez klienta.

Ochrona przed ponownym odtworzeniem

Facilitator zapisuje nonce. Autoryzacja z tym samym nonce nie może być ponownie weryfikowana i rozliczana. Oznacza to:
  • Klient powinien przy każdym żądaniu podpisywać nowy envelope;
  • Jeśli /settle przesłało już transakcję, ale tymczasowo nie ma potwierdzenia, można ponowić /settle z tym samym nonce, aby wykonać idempotentne uzgodnienie;
  • Nie przechowuj tego samego PAYMENT-SIGNATURE w pamięci podręcznej i nie używaj go do wielu wywołań API.

Częste błędy