X402 `exact` и `upto` схемы тарификации

Ace Data Cloud X402 в настоящее время использует два типа схем: exact и upto. Они решают разные проблемы тарификации.

`exact`

exact означает, что цена запроса может быть определена до его отправки в целевой API. Сумма, подписанная клиентом, является окончательной суммой списания. Подходит для:

Генерации изображений с фиксированной ценой;
Создания видео задач с фиксированной ценой;
Поисковых или инструментальных API с фиксированной ценой;
Оплаты заказов.

EVM exact использует USDC EIP-3009 TransferWithAuthorization:

{
  "x402Version": 2,
  "accepted": {
    "scheme": "exact",
    "network": "eip155:8453"
  },
  "payload": {
    "authorization": {
      "from": "0x...",
      "to": "0x...",
      "value": "95215",
      "validAfter": "1780237345",
      "validBefore": "1780240945",
      "nonce": "0x..."
    },
    "signature": "0x..."
  }
}

Facilitator на этапе /verify проверяет подпись и сумму, на этапе /settle отправляет эту авторизацию в блокчейн.

`upto`

upto означает, что клиент авторизует максимальный лимит, Ace Data Cloud рассчитывает по фактическому использованию после завершения запроса, фактическое списание не может превышать лимит. Подходит для:

Дополнения чата: окончательная цена зависит от токенов prompt и completion;
Потоковых ответов: реальная длина вывода известна только после завершения;
Будущих API с постфактумным измерением.

upto использует Permit2 PermitWitnessTransferFrom. Подписанная клиентом сумма не является фиксированной передачей, а представляет собой авторизацию с лимитом и свидетелем:

{
  "x402Version": 2,
  "accepted": {
    "scheme": "upto",
    "network": "eip155:8453"
  },
  "payload": {
    "permit2Authorization": {
      "from": "0x...",
      "spender": "0x4020A4f3b7b90ccA423B9fabCc0CE57C6C240002",
      "nonce": "123456789",
      "deadline": "1780240945",
      "permitted": {
        "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "amount": "95215"
      },
      "witness": {
        "to": "0x...",
        "facilitator": "0x...",
        "validAfter": "1780237345"
      }
    },
    "signature": "0x..."
  }
}

permitted.amount является лимитом, не обязательно равным окончательному списанию. Gateway на этапе /record преобразует фактическое использование в amount и передает Facilitator. Facilitator разрешает расчет только при amount <= permitted.amount. Результат выполнения программы Base upto:

payer 0x5d4f08D5c2bb60703284bc06671Eb680fA41B105
elapsed_ms 5104
content ADC_BASE_UPTO_OK
id chatcmpl-DlcbyS4IT8kUAMo4Ri97HiIHc9T8V
tx 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
block 46726437
explorer https://basescan.org/tx/0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
signed ceiling 95215 atomic USDC
transfer value 3 atomic USDC

Объяснение:

Возвращенный лимит авторизации в 402 составляет 95215 atomic USDC, клиент подписывает на этот лимит.
После фактического ответа модели списывается только 3 atomic USDC, транзакция в блокчейне доступна для проверки на BaseScan.
Этот результат подчеркивает ключевую разницу upto: подписанная сумма является лимитом, расчет в блокчейне может быть меньше лимита.
Если фактическое использование превышает лимит, Facilitator должен отклонить расчет, клиенту необходимо повторно авторизовать на более высокий лимит.

upto в настоящее время доступен только на Base. SKALE предлагает только exact, если вам нужно постфактумное измерение, используйте Base.

Почему требуется Permit2 approve

upto в конечном итоге управляется прокси x402 через Permit2 для получения USDC из кошелька для платежей. Перед первым использованием кошелек для платежей должен предоставить Permit2 одно разрешение ERC-20. Python CLI:

pip install 'acedatacloud-x402[cli]'
X402_PRIVATE_KEY=0x... acedatacloud-x402 approve-permit2 --network base

Программный способ:

from acedatacloud_x402 import EVMAccountSigner, approve_permit2

approve_permit2(
    rpc_url="https://mainnet.base.org",
    signer=EVMAccountSigner.from_private_key("0x..."),
    token_address="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
)

После завершения авторизации каждый запрос все равно требует подписания нового upto envelope, так как nonce, deadline, witness и лимит суммы различаются.

Нулевая сумма расчета

upto поддерживает ситуацию, когда фактическая сумма равна 0. Например, если целевой API не смог успешно сгенерировать подлежащую оплате сумму, Gateway может передать amount = "0". Facilitator вернет успешный ответ, но не выполнит транзакцию в блокчейне. Это позволяет избежать проблемы “запрос не удался, но все равно списание в блокчейне”.

Сцена	Рекомендация
API с фиксированной ценой	Используйте `exact`, логика проста.
Оплата заказа	Используйте `exact`.
Дополнение чата, тарификация по токенам	Используйте Base `upto`.
Еще не сделали Permit2 approve	Сначала используйте `exact`, затем переключитесь на `upto`.
Необходимость постфактумного измерения на SKALE	В настоящее время не поддерживается, SKALE предлагает только `exact`.

Проверочный список Base `upto`

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

Параметр	Проверочный пункт
`network`	Должен быть `eip155:8453`.
`scheme`	Должен быть `upto`.
`extra.chainId`	Идентификатор цепи Base равен `8453`.
`asset`	Используйте адрес контракта Base USDC из ответа 402.
`extra.facilitatorAddress`	Должен участвовать в свидетелях и соответствовать Facilitator `/supported`.
Permit2 allowance	Кошелек для платежей должен сначала авторизовать Permit2 для Base USDC.

Распространенные ошибки и способы их устранения:

Ошибка	Способ устранения
`invalid_upto_evm_payload_invalid_signature`	Проверьте идентификатор цепи, адрес facilitator, домен Permit2, spender, подписанный аккаунт и свидетеля на соответствие ответу 402.
`PERMIT2_ALLOWANCE_REQUIRED`	Выполните Permit2 approve для USDC целевой цепи и повторно отправьте запрос.
`amount exceeds permitted amount`	Фактическое использование превышает подписанный лимит, необходимо повторно подписать на более высокий лимит.

Начало работы

AI Чат

AI Изображение

AI Видео

AI Аудио

Веб и данные

CAPTCHA

Идентичность

Coding

Другие руководства

X402 `exact` и `upto` схемы тарификации

`exact`

`upto`

Почему требуется Permit2 approve

Нулевая сумма расчета

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

Проверочный список Base `upto`

​exact

​upto

​Почему требуется Permit2 approve

​Нулевая сумма расчета

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

​Проверочный список Base upto

`exact`

`upto`

Почему требуется Permit2 approve

Нулевая сумма расчета

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

Проверочный список Base `upto`