402 Payment Required. Завдяки можливостям X402 від Ace Data Cloud викликаюча сторона може не створювати API Token і не поповнювати баланс облікового запису заздалегідь, а натомість безпосередньо здійснювати ончейн-платіж у USDC в кожному API-запиті.
Цей набір документів організований за реальним порядком інтеграції: спочатку виконайте мінімальний запит, потім підключіть SDK, а далі розберіться з мережами, схемами тарифікації, оплатою замовлень і Facilitator. Рекомендується читати зверху вниз відповідно до таблиці нижче.
Рекомендований шлях інтеграції
Якщо ви лише хочете викликати Ace Data Cloud API, пріоритетно використовуйте офіційний SDK:- TypeScript:
@acedatacloud/sdk+@acedatacloud/x402-client - Python:
acedatacloud+acedatacloud-x402
SDK автоматично виконає перший неавтентифікований запит, розбере
402 Payment Required, викличе payment handler і повторить запит із PAYMENT-SIGNATURE. Вам потрібно лише підготувати гаманець із USDC та вибрати мережу, яку ви хочете використовувати.
Якщо ви хочете, щоб ваш власний API також підтримував приймання платежів X402, вам потрібно прочитати документацію Facilitator, щоб зрозуміти взаємозв’язок між paymentRequirements, paymentPayload, /verify і /settle.
Статус підтримки
Ace Data Cloud X402 пройшов валідацію на публічному API, офіційному SDK, Facilitator і в ончейн-шляху розрахунків. Таблиця нижче узагальнює поточний статус за вимірами можливостей, які найчастіше використовують розробники під час інтеграції.
Наведений нижче вивід призначений лише для пояснення форми відповідей валідованих шляхів. Під час фактичної інтеграції завжди орієнтуйтеся на
accepts, повернутий поточним API.
- Пакети npm і PyPI успішно встановлені та імпортовані в чистому середовищі.
- Неоплачений API-запит повертає 402, а
acceptsмістить доступні способи оплати для Base і Solana. accepts[].networkє ідентифікатором CAIP-2; клієнт повинен зіставляти мережу за рядком CAIP-2.- Як TypeScript SDK, так і Python SDK можуть автоматично обробити 402 і виконати paid retry.
- Base
exact, Baseuptoта оплата замовлення мають адреси explorer, які можна публічно відкрити. - Підписана верхня межа Base
uptoстановить95215atomic USDC, а фактичний settlement становить3atomic USDC, що відображає властивість postpaid metering — розрахунок за фактичним використанням. - Для Solana
exactперевірено HTTP 402 -> HTTP 200 і вивід моделі. Оскільки публічні RPC-запити можуть бути обмежені за швидкістю, для суворої звірки рекомендується використовувати власний Solana RPC або записи про розрахунки на стороні платформи для підтвердження підпису транзакції.
Примітки щодо інтеграції
Під час інтеграції розробникам слід насамперед звертати увагу на вимоги до оплати в реальному часі, які повертає поточний запит, а не копіювати приклади сум або адрес із документації:accepts[].maxAmountRequired— це максимальна сума, яку можна підписати для поточного запиту.accepts[].asset— це USDC-контракт або mint, який слід використати для цього запиту.accepts[].extra.chainId,accepts[].extra.facilitatorAddressіaccepts[].extra.verifyingContractберуть участь у підписі EVM typed data.uptoвимагає, щоб гаманець заздалегідь надав Permit2 дозвіл на USDC цільової мережі; за відсутності дозволу повертаєтьсяPERMIT2_ALLOWANCE_REQUIRED.- Якщо ви явно бажаєте використовувати postpaid metering, передайте
preferScheme: 'upto'у TypeScript SDK; інакше SDK вибере перший доступний requirement, повернений сервером для цієї мережі.
Межі, які можна публічно перевірити
Перед інтеграцією можна спочатку перевірити ці публічні точки доступу та поведінку SDK:- API-запит без
AuthorizationабоPAYMENT-SIGNATUREповертає402 Payment Required, аacceptsу відповіді є єдиною підставою для підпису цього запиту. - TypeScript SDK і Python SDK обидва надають payment handler; транспортний рівень SDK після отримання 402 викликає handler і повторює запит один раз.
https://facilitator.acedata.cloud/.well-known/x402: повертає мережі, scheme та протокольні endpoints, які підтримує Facilitator; ціна API все одно визначається 402, що в реальному часі повертається цільовим запитом.https://facilitator.acedata.cloud/supported: повертає мережі та scheme, які підтримує Facilitator.- Репозиторій X402Client містить розширені інструменти ончейн-перевірки, які можна використовувати для підтвердження підписів, повторних спроб і поведінки settlement; вивід інструментів не замінює
accepts, повернений онлайн API.
upto належить до postpaid metering settlement і підходить для API, у яких фактичне використання, наприклад для чат-доповнень і викликів моделей, стає відомим лише після відповіді. Наразі лише Base надає upto; якщо перевірка підпису не вдається, перевірте, чи chain id, адреса facilitator, spender, USDC-контракт і Permit2 allowance відповідають 402-відповіді.
