/verify і /settle Facilitator.
Адреса production Facilitator Ace Data Cloud:
Домовленості 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.
PAYMENT-REQUIRED, значенням якого є base64-кодування того самого вмісту challenge, що дає клієнту змогу зчитувати вимоги до платежу без розбору body.
Основні інтерфейси
GET /supported
Перегляд підтримуваних мереж і scheme:
- Для
networkвикористовується ідентифікатор CAIP-2, а не скорочення на кшталтbase,solana. /supportedозначає, що Facilitator має відповідні можливості верифікації та розрахунків.- Base і Solana підтримують
exact;uptoнаразі надається лише в Base. signers— це адреси, які Facilitator використовує для подання транзакцій розрахунку.- Чи дозволяє конкретний API ці опції, як і раніше, визначається
accepts402 цього 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 можна побачити переказ
1200000atomic USDC у Base. errorReason=Noneозначає, що цей settlement не повернув бізнес-помилку.
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 виглядає так:- Клієнт уперше надсилає запит до API без
AuthorizationіPAYMENT-SIGNATURE. - Gateway обчислює прогнозовану ціну запиту та повертає 402 і
accepts. - Після підписання клієнт повторює запит із
PAYMENT-SIGNATURE. - Gateway декодує
PAYMENT-SIGNATUREі вибирає відповідну payment requirement. - Gateway викликає Facilitator
/verify. - Після успішного
/verifyGateway пропускає запит до цільового API. - Після повернення цільового API Gateway на етапі
/recordвикликає Facilitator/settle. - Gateway записує хеш ончейн-транзакції до metadata запису використання.
exact виконує розрахунок суми підпису на кроці 7; upto записує amount відповідно до фактичного використання на кроці 7, а потім виконує розрахунок фактичної суми.
Як інтегрувати власний API
Якщо ви хочете, щоб ваш власний API підтримував X402, це можна реалізувати за такою структурою:- Підготуйте
paymentRequirementsдля кожного платного інтерфейсу, включно з мережею, сумою, адресою отримувача, адресою активу та signature domain. - Якщо запит не має
PAYMENT-SIGNATURE, поверніть HTTP 402 іaccepts. - Якщо запит має
PAYMENT-SIGNATURE, виконайте Base64-декодування, щоб отриматиpaymentPayload. - Викличте Facilitator
/verify. - Після успішної перевірки виконайте бізнес-логіку.
- Після успішного виконання бізнес-логіки викличте Facilitator
/settle. - Збережіть
payer,transaction,amount,networkдля звірки.
paymentRequirements для виклику /verify і /settle, не довіряйте сумі, адресі отримувача або адресі активу, повернутим клієнтом.
Захист від повторного відтворення
Facilitator записує nonce. Авторизація з однаковим nonce не може бути повторно перевірена та виконана. Це означає:- Клієнт має підписувати новий envelope для кожного запиту;
- Якщо
/settleвже надіслав транзакцію, але тимчасово немає підтвердження, можна повторити/settleз тим самим nonce для ідемпотентної звірки; - Не кешуйте той самий
PAYMENT-SIGNATUREдля використання в кількох API-викликах.

