Перейти до основного вмісту
Ace Data Cloud X402 наразі використовує два типи scheme: exact та upto. Вони вирішують різні проблеми виставлення рахунків.

exact

exact означає, що ціну цього запиту можна визначити ще до його надходження до цільового API. Сума, підписана клієнтом, є остаточною сумою списання. Підходить для:
  • Генерації зображень із фіксованою ціною;
  • Створення відеозавдань із фіксованою ціною;
  • API пошуку або інструментів із фіксованою ціною;
  • Оплати замовлень.
EVM exact використовує USDC EIP-3009 TransferWithAuthorization:
Facilitator перевіряє підпис і суму на етапі /verify, а на етапі /settle надсилає цю авторизацію в блокчейн.

upto

upto означає, що клієнт авторизує максимальний ліміт, а Ace Data Cloud здійснює розрахунок за фактичним використанням після завершення запиту; фактичне списання не може перевищувати ліміт. Підходить для:
  • Чат-доповнень: остаточна ціна залежить від prompt tokens і completion tokens;
  • Потокових відповідей: фактична довжина виводу стає відомою лише після завершення;
  • Майбутніх API із післяплатним обліком.
upto використовує Permit2 PermitWitnessTransferFrom. Клієнт підписує не фіксований переказ, а авторизацію ліміту з witness:
permitted.amount є лімітом, а не обов’язково остаточною сумою списання. Gateway на етапі /record перетворює фактичне використання на amount і передає його Facilitator. Facilitator дозволяє розрахунок лише за умови amount <= permitted.amount. Результат виконання програми Base upto:
Пояснення:
  • Ліміт авторизації, повернений у 402, становить 95215 atomic USDC, клієнт підписує цей ліміт.
  • Після фактичної відповіді моделі розраховується лише 3 atomic USDC, а транзакцію в блокчейні вже можна перевірити в BaseScan.
  • Цей результат демонструє ключову відмінність upto: підписана сума є лімітом, а on-chain settlement може бути меншим за ліміт.
  • Якщо фактичне використання перевищує ліміт, Facilitator має відхилити settlement, і клієнту потрібно повторно авторизувати вищий ліміт.
upto наразі доступний лише в Base. Якщо потрібен післяплатний облік, використовуйте Base.

Чому потрібен Permit2 approve

Зрештою upto дозволяє x402 proxy стягувати USDC із платіжного гаманця через Permit2. Перед першим використанням платіжний гаманець повинен надати Permit2 одноразовий ERC-20 allowance. Python CLI:
Програмним способом:
Після завершення авторизації для кожного запиту все одно потрібно підписувати новий upto envelope, оскільки nonce, deadline, witness і ліміт суми щоразу відрізняються.

Розрахунок із нульовою сумою

upto підтримує ситуації, коли фактична сума дорівнює 0. Наприклад, якщо цільовий API не зміг успішно створити використання, що підлягає оплаті, Gateway може передати amount = "0". Facilitator поверне успіх, але не надсилатиме транзакцію в блокчейн. Це дає змогу уникнути проблеми «запит не був успішним, але все одно стягується on-chain комісія».

Рекомендації щодо вибору

Якщо ви не впевнені, що вибрати, спочатку використовуйте поведінку SDK за замовчуванням; SDK вибере payment requirement відповідної мережі, повернутий сервером.

Контрольний список Base upto

Під час інтеграції або діагностики переконайтеся, що наведені нижче параметри походять з однієї й тієї самої відповіді 402 і залишаються однаковими під час підписання клієнтом: Поширені помилки та способи їх усунення: