Перейти до основного вмісту
Цей посібник пояснює повний процес Ace Data Cloud X402 за допомогою мінімального API-запиту. Мета полягає не в тому, щоб спочатку писати складний код, а в тому, щоб спершу зрозуміти: чому перший запит повертає 402, що міститься в accepts і як PAYMENT-SIGNATURE перетворює той самий API-запит на оплачений запит.

Підготовка

Вам потрібно підготувати: Для виклику Ace Data Cloud API через X402 не потрібен API Token. Перший запит SDK не містить Authorization, Gateway повертає 402 Payment Required і вимоги до оплати; після підпису SDK автоматично повторює запит.

Встановлення SDK

Вихідний код і адреси пакетів: TypeScript:
Python:
Якщо потрібно використовувати Solana, також потрібно встановити відповідні залежності:
Залежності Solana signer для версії Python уже включено до acedatacloud-x402. Вивід перевірки встановлення та імпорту в чистому тимчасовому середовищі:
Пояснення результату:
  • Пакети npm і PyPI є справді опублікованими пакетами, а не назвами-заповнювачами в документації.
  • acedatacloud-x402[cli] встановлює CLI, а підкоманда approve-permit2 може використовуватися для авторизації Permit2 у сценарії upto.

Перший запит поверне 402

Ви можете спочатку скористатися curl, щоб побачити, що повертає неоплачений запит. Наведений нижче приклад не призведе до списання коштів, оскільки він не містить PAYMENT-SIGNATURE:
Тіло відповіді міститиме масив accepts, типова структура така:
Такий самий вміст запиту також у форматі base64 розміщується у заголовку відповіді PAYMENT-REQUIRED, щоб клієнт міг зчитувати вимоги до оплати без аналізу body. Нижче наведено підсумок програмного виводу неоплаченого запиту до production API:
Пояснення результату:
  • Перший запит не містить Authorization або PAYMENT-SIGNATURE, тому повертає HTTP 402 і не призведе до списання коштів.
  • accepts є єдиною надійною основою для підпису цього запиту та містить доступні мережі, scheme, ліміт суми, адресу одержувача та адресу активу.
  • network є ідентифікатором CAIP-2, і клієнт під час вибору мережі повинен зіставляти його за рядком CAIP-2.
  • Максимальна сума для цього мінімального запиту чату gpt-4o-mini становить 95215 atomic USDC, тобто 0.095215 USDC.
  • Для кожного запиту слід зчитувати відповідь 402 саме цього запиту; не слід жорстко кодувати приклад суми в бізнес-коді.
Значення полів:

Виконання повторного запиту з оплатою через SDK

Нижче наведено мінімальний приклад TypeScript. Він задає network: 'base', handler вибере payment requirement Base із відповіді 402 цього запиту; фактична сума та адреса одержувача все одно визначаються accepts:
За цим кодом відбуваються чотири кроки:
  1. SDK надсилає звичайний API-запит без Authorization.
  2. Gateway повертає 402 Payment Required і accepts.
  3. createX402PaymentHandler вибирає payment requirement для network = 'base' і підписує PAYMENT-SIGNATURE.
  4. SDK повторює спробу з тим самим тілом запиту, Gateway викликає Facilitator для перевірки й розрахунку, після чого пропускає запит до цільового API.

Перегляд можливостей Facilitator

X402 API не залежить від каталогу ресурсів. Клієнт безпосередньо викликає відомий API та використовує 402 Payment Required і accepts, що повертаються цим запитом у реальному часі, як єдину основу для ціни й підпису. Оголошення можливостей Facilitator знаходиться за адресою:
Воно описує лише /supported, /verify, /settle і поточно ввімкнені платіжні мережі, не перелічуючи ресурси API. Адреса виробничого Facilitator Ace Data Cloud:
Можна переглянути, які мережі та scheme він підтримує:
Повернене kinds перелічує мережі та scheme, які підтримує Facilitator. Під час фактичних викликів усе одно слід орієнтуватися на accepts, що повертається API. Вивід Facilitator /supported:
Результат означає:
  • /supported означає, що Facilitator має можливості перевірки й розрахунку для цих мереж і scheme.
  • Base і Solana обидві підтримують exact; upto наразі доступний лише в Base.
  • Чи дозволяє конкретний API певну мережу, усе одно визначається його 402 accepts.