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 tokens та completion tokens;
Потокових відповідей: реальна довжина виходу стає відомою лише після завершення;
Майбутніх 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. Результат виконання програми базового 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 proxy через Permit2 для отримання USDC з платіжного гаманця. Перед першим використанням платіжний гаманець повинен надати Permit2 одноразово ERC-20 allowance. 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 chain id дорівнює `8453`.
`asset`	Використовуйте адресу контракту Base USDC з відповіді 402.
`extra.facilitatorAddress`	Повинен брати участь у свідченні та відповідати Facilitator `/supported`.
Permit2 allowance	Платіжний гаманець повинен спочатку авторизувати Permit2 для Base USDC.

Поширені помилки та способи їх усунення:

Помилка	Спосіб усунення
`invalid_upto_evm_payload_invalid_signature`	Перевірте chain id, адресу facilitator, домен Permit2, spender, підписаний акаунт та свідка на відповідність відповіді 402.
`PERMIT2_ALLOWANCE_REQUIRED`	Виконайте Permit2 approve для USDC цільової мережі, а потім повторно надішліть запит.
`amount exceeds permitted amount`	Фактичне використання перевищує підписаний ліміт, потрібно повторно підписати за вищим лімітом.

Getting Started

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`