Skip to main content
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-SIGNATURE. Вам лише потрібно підготувати гаманець з USDC та вибрати мережу, яку ви хочете використовувати. Якщо ви хочете, щоб ваш API також підтримував X402 для збору платежів, вам потрібно прочитати документацію Facilitator, щоб зрозуміти зв’язок між paymentRequirements, paymentPayload, /verify та /settle.

​
Статус підтримки

Ace Data Cloud X402 вже пройшов верифікацію в публічному API, офіційному SDK, Facilitator та ланцюгових шляхах розрахунків. У таблиці нижче підсумовано поточний статус за найбільш використовуваними можливостями під час інтеграції розробниками. Наступний вихід призначений лише для ілюстрації формату повернення верифікованих шляхів. Під час фактичної інтеграції завжди орієнтуйтеся на accepts, повернуті поточним API.
说明：
  • npm та PyPI пакети вже успішно встановлені та імпортовані в чистому середовищі.
  • Неплатеж API запит повертає 402, приймає містить доступні способи оплати для Base, SKALE та Solana.
  • приймає[].мережа є CAIP-2 ідентифікатором, клієнт повинен відповідати CAIP-2 рядку при виборі мережі.
  • TypeScript SDK та Python SDK можуть автоматично обробляти 402 та завершувати повторну оплату.
  • Base exact, SKALE exact, Base upto та оплата замовлення мають відкриті адреси експлорера.
  • Ліміт підпису для Base upto становить 95215 атомних USDC, фактичне врегулювання становить 3 атомних USDC, що відображає особливість розрахунку за фактичним використанням.
  • Solana exact підтвердив HTTP 402 -> HTTP 200 та вихід моделі. Оскільки публічні RPC запити можуть бути обмежені, для точного звіряння рекомендується використовувати власний Solana RPC або записи розрахунків платформи для підтвердження підпису транзакції.

​
Уваги при підключенні

Розробники при підключенні повинні спочатку звертати увагу на реальні вимоги до оплати, які повертаються в поточному запиті, а не копіювати приклади сум або адреси з документації:
  • приймає[].maxAmountRequired є максимальною сумою, яку можна підписати в поточному запиті.
  • приймає[].актив є контрактом або mint USDC, який буде використано в цьому запиті.
  • приймає[].extra.chainId, приймає[].extra.facilitatorAddress та приймає[].extra.verifyingContract братимуть участь у підписанні EVM типізованих даних.
  • upto вимагає, щоб гаманець спочатку надав дозвіл Permit2 для USDC цільової мережі; без дозволу буде повернуто PERMIT2_ALLOWANCE_REQUIRED.
  • Якщо ви чітко хочете використовувати розрахунок за фактичним використанням, передайте в TypeScript SDK preferScheme: 'upto', в іншому випадку SDK вибере першу доступну вимогу, повернуту сервером для цієї мережі.

​
Доступні для публічної перевірки області

Перед підключенням можна перевірити ці публічні входи та поведінку SDK:
  • API запити без Authorization або PAYMENT-SIGNATURE повернуть 402 Payment Required, а приймає в відповіді є єдиною підставою для підпису цього запиту.
  • TypeScript SDK та Python SDK обидва надають обробник платежів, рівень передачі SDK після отримання 402 викликає обробник та повторює запит.
  • https://facilitator.acedata.cloud/.well-known/x402: повертає мережі, схеми та кінцеві точки протоколу, підтримувані Facilitator; ціна API все ще базується на 402, що повертається в реальному часі для цільового запиту.
  • https://facilitator.acedata.cloud/supported: повертає мережі та схеми, підтримувані Facilitator.
  • Репозиторій X402Client містить інструменти для верифікації на високому рівні, які можуть бути використані для підтвердження підписів, повторних спроб та поведінки врегулювання; вихід інструменту не замінює приймає, повернуте онлайн API.
upto належить до розрахунку за фактичним використанням, підходить для API, де реальне використання, таке як доповнення чату, виклики моделей тощо, стає відомим лише після відповіді. Наразі лише Base надає upto; якщо перевірка підпису не вдалася, перевірте, чи відповідають chain id, адреса посередника, spender, контракт USDC та дозволи Permit2 відповіді 402.