> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# X402 `exact` та `upto` платіжні схеми

> Platform API guide - Ace Data Cloud

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

## `exact`

`exact` означає, що ціну запиту можна визначити ще до того, як він надійде до цільового API. Сума, підписана клієнтом, є остаточною сумою для списання.

Підходить для:

* Генерації зображень за фіксованою ціною;
* Створення відеозавдань за фіксованою ціною;
* Фіксованої ціни для API пошуку або інструментів;
* Оплати замовлень.

EVM `exact` використовує USDC EIP-3009 `TransferWithAuthorization`:

```json theme={null}
{
  "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`. Клієнт підписує не фіксований переказ, а авторизацію з лімітом, що містить свідка:

```json theme={null}
{
  "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`:

```text theme={null}
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:

```bash theme={null}
pip install 'acedatacloud-x402[cli]'
X402_PRIVATE_KEY=0x... acedatacloud-x402 approve-permit2 --network base
```

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

```python theme={null}
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`. |

Якщо ви не впевнені, що вибрати, спочатку використовуйте стандартну поведінку SDK; SDK вибере вимогу оплати, що відповідає мережі, повернутій сервером.

## Перевірочний список 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` | Фактичне використання перевищує підписаний ліміт, потрібно повторно підписати за вищим лімітом. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.