Перейти к основному содержанию
Ace Data Cloud X402 в настоящее время использует два типа схем: 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: подписанная сумма является верхним пределом, а 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 вернёт успех, но не будет отправлять транзакцию в блокчейн. Это позволяет избежать проблемы «запрос не был успешным, но комиссия в блокчейне всё равно списана».

Рекомендации по выбору

Если вы не уверены, что выбрать, сначала используйте поведение SDK по умолчанию; SDK выберет соответствующее требование к оплате сети, возвращённое сервером.

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

При интеграции или устранении неполадок убедитесь, что следующие параметры получены из одного и того же ответа 402 и остаются согласованными при подписании клиентом: Распространённые ошибки и способы обработки: