Перейти до основного вмісту
X402 — це протокол ончейн-платежів на основі HTTP 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, Base upto та оплата замовлення мають адреси explorer, які можна публічно відкрити.
  • Підписана верхня межа Base upto становить 95215 atomic USDC, а фактичний settlement становить 3 atomic 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-відповіді.