> ## 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 и completion;
* Потоковых ответов: реальная длина вывода известна только после завершения;
* Будущих 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`.

Результат выполнения программы Base `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 через Permit2 для получения USDC из кошелька для платежей. Перед первым использованием кошелек для платежей должен предоставить Permit2 одно разрешение ERC-20.

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 равен `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` | Фактическое использование превышает подписанный лимит, необходимо повторно подписать на более высокий лимит. |


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