Перейти до основного вмісту
Facilitator — це серверний компонент розрахунків у ланцюжку X402. Клієнт відповідає за підпис, а Gateway або ваш сервер відповідає за виклик /verify і /settle Facilitator. Адреса production Facilitator Ace Data Cloud:
Репозиторій вихідного коду: https://github.com/AceDataCloud/FacilitatorX402

Домовленості wire v2

Ланцюжок X402 Ace Data Cloud повністю використовує офіційний x402 v2 і більше не приймає заголовок запиту X-Payment v1. Під час інтеграції потрібно звернути увагу на три моменти:
  • Заголовок запиту — PAYMENT-SIGNATURE, а його значенням є JSON envelope, закодований у base64.
  • На верхньому рівні envelope обов’язково має бути x402Version: 2, а вибрані цього разу scheme і network потрібно оголосити за допомогою об’єкта accepted.
  • Для network використовується ідентифікатор CAIP-2 (наприклад, eip155:8453), не можна писати скорочення на кшталт base.
Структура envelope:
Відповідь 402, окрім JSON body, також містить заголовок відповіді PAYMENT-REQUIRED, значенням якого є base64-кодування того самого вмісту challenge, що дає клієнту змогу зчитувати вимоги до платежу без розбору body.

Основні інтерфейси

GET /supported

Перегляд підтримуваних мереж і scheme:
Приклад відповіді:
Пояснення результату:
  • Для network використовується ідентифікатор CAIP-2, а не скорочення на кшталт base, solana.
  • /supported означає, що Facilitator має відповідні можливості верифікації та розрахунків.
  • Base і Solana підтримують exact; upto наразі надається лише в Base.
  • signers — це адреси, які Facilitator використовує для подання транзакцій розрахунку.
  • Чи дозволяє конкретний API ці опції, як і раніше, визначається accepts 402 цього API.

POST /verify

Перевірка, чи відповідає переданий клієнтом PAYMENT-SIGNATURE певній payment requirement. Тіло запиту:
Поля paymentRequirements у v2 — це scheme, network, asset, amount, payTo, maxTimeoutSeconds і extra, а полем суми є amount. У accepts[] відповіді API 402 також додатково повертається maxAmountRequired, щоб клієнт міг зчитати верхню межу, але воно не є полем тіла запиту Facilitator. Успішна відповідь:
Після декодування заголовок відповіді PAYMENT-RESPONSE оплати production-замовлення містить результат settlement. Результат виконання програми для оплати замовлення в Base:
Пояснення результату:
  • success=True означає, що settlement Facilitator завершився успішно.
  • transaction — це хеш ончейн-транзакції, у pay_id замовлення також записується те саме значення.
  • В explorer можна побачити переказ 1200000 atomic USDC у Base.
  • errorReason=None означає, що цей settlement не повернув бізнес-помилку.
Помилка верифікації також зазвичай повертає HTTP 200, але isValid має значення false. Бізнес-сторона повинна зчитувати invalidReason, а не дивитися лише на код статусу HTTP.

POST /settle

Розрахунок ончейн уже верифікованого дозволу. Тіло запиту майже таке саме, як у /verify. Відмінність upto полягає в тому, що paymentRequirements.amount під час settle переписується на фактичну суму розрахунку; ліміт підпису записується Facilitator на етапі verify, а під час settle перевіряється, що фактична сума не перевищує цього ліміту. Успішна відповідь:
Якщо фактична сума upto дорівнює 0, transaction може бути порожнім рядком, що означає відсутність потреби надсилати ончейн-транзакцію.

Як Ace Data Cloud Gateway використовує Facilitator

Ланцюжок Ace Data Cloud API Gateway виглядає так:
  1. Клієнт уперше надсилає запит до API без Authorization і PAYMENT-SIGNATURE.
  2. Gateway обчислює прогнозовану ціну запиту та повертає 402 і accepts.
  3. Після підписання клієнт повторює запит із PAYMENT-SIGNATURE.
  4. Gateway декодує PAYMENT-SIGNATURE і вибирає відповідну payment requirement.
  5. Gateway викликає Facilitator /verify.
  6. Після успішного /verify Gateway пропускає запит до цільового API.
  7. Після повернення цільового API Gateway на етапі /record викликає Facilitator /settle.
  8. Gateway записує хеш ончейн-транзакції до metadata запису використання.
exact виконує розрахунок суми підпису на кроці 7; upto записує amount відповідно до фактичного використання на кроці 7, а потім виконує розрахунок фактичної суми.

Як інтегрувати власний API

Якщо ви хочете, щоб ваш власний API підтримував X402, це можна реалізувати за такою структурою:
  1. Підготуйте paymentRequirements для кожного платного інтерфейсу, включно з мережею, сумою, адресою отримувача, адресою активу та signature domain.
  2. Якщо запит не має PAYMENT-SIGNATURE, поверніть HTTP 402 і accepts.
  3. Якщо запит має PAYMENT-SIGNATURE, виконайте Base64-декодування, щоб отримати paymentPayload.
  4. Викличте Facilitator /verify.
  5. Після успішної перевірки виконайте бізнес-логіку.
  6. Після успішного виконання бізнес-логіки викличте Facilitator /settle.
  7. Збережіть payer, transaction, amount, network для звірки.
Сервер повинен використовувати власноруч згенеровані paymentRequirements для виклику /verify і /settle, не довіряйте сумі, адресі отримувача або адресі активу, повернутим клієнтом.

Захист від повторного відтворення

Facilitator записує nonce. Авторизація з однаковим nonce не може бути повторно перевірена та виконана. Це означає:
  • Клієнт має підписувати новий envelope для кожного запиту;
  • Якщо /settle вже надіслав транзакцію, але тимчасово немає підтвердження, можна повторити /settle з тим самим nonce для ідемпотентної звірки;
  • Не кешуйте той самий PAYMENT-SIGNATURE для використання в кількох API-викликах.

Поширені помилки