> ## 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 Ценовое описание

> Platform API guide - Ace Data Cloud

Этот документ объясняет, как устанавливается цена при вызове Ace Data Cloud API с использованием X402, а также как она соотносится с ценой обычных **Credits** (кредитов) на платформе.

## Основные выводы

X402 не является отдельной ценовой системой. Каждый вызов API изначально имеет стоимость в **Credits**, которая является единственным источником цены для всех способов оплаты (вычет кредитов по API Token, баланс аккаунта, оплата в сети X402). X402 просто конвертирует эту стоимость в Credits по фиксированному курсу в USDC на блокчейне:

> **1 Credit = 0.095215 USDC** (то есть `95215` атомарных USDC, USDC с 6 знаками после запятой)

Это означает:

```text theme={null}
Цена X402 (USDC) = Стоимость Credits за вызов × 0.095215
```

Этот курс не установлен произвольно, он равен **оптимальной цене (большого объема) Credits** на платформе. Таким образом, оплата через X402 ≈ покупка Credits по оптимальной цене и последующее использование, **без наценки X402**, а наоборот, вы получаете самую низкую цену на Credits, без необходимости предварительного пополнения и без API Token.

## Базовые цены

| Параметр | Значение | Описание |
| - | - | - |
| Конверсионный курс | `1 Credit = 0.095215 USDC` | Фиксированный курс, установленный платформой |
| атомарная единица | `1 Credit = 95215 atomic USDC` | USDC с 6 знаками после запятой, `atomic = floor(credits × 0.095215 × 1e6)` |
| Минимальная плата | `1 atomic USDC` (\$0.000001) | Даже при очень низкой стоимости, минимальная сумма 1 atomic |
| Валюта оценки | USDC | Base / SKALE - это ERC-20 USDC, Solana - это SPL USDC |

Конвертация осуществляется платформой, сумма одинакова для всех поддерживаемых сетей (Base, SKALE, Solana); разные сети отличаются только контрактами активов и способами подписи, цена остается одинаковой.

### Связь с обычной ценой Credits

Credits на платформе продаются по ступенчатой системе «чем больше объем, тем ниже цена». При расчете X402 используется оптимальная цена по ступенчатой системе:

| Способ покупки/оплаты | Приблизительная цена Credits | Описание |
| - | - | - |
| Начальный / Небольшой пополнение | Около `$0.13 / Credit` | Розничная цена, цена при покупке небольшого объема Credits |
| Большой / Оптимальный | `$0.095215 / Credit` | Самая низкая цена |
| **X402 по вызову** | **`$0.095215 / Credit`** | **Всегда равна оптимальной цене** |

Другими словами, X402 рассчитывает каждый вызов по оптимальной цене Credits. Пользователи, покупающие Credits по небольшому пополнению, будут платить больше, чем X402; только пользователи, пополняющие на большие суммы, будут иметь такую же цену, как у X402.

## Две ценовые формы: `exact` и `upto`

В ответе 402 X402, `maxAmountRequired` - это сумма, которую вы должны подписать. У него есть две формы:

* **`exact` (фиксированная цена)**: цена может быть определена до обработки запроса (изображения, видео, музыка, поиск, оплата заказов). `maxAmountRequired = Стоимость Credits за вызов × 0.095215`, то есть сумма, подлежащая оплате за этот вызов (соответствует `cost.amount` в успешном ответе).
* **`upto` (после измерения объема)**: интерфейсы, такие как дополнение чата, где «количество токенов становится известно только после завершения ответа». `maxAmountRequired` - это **максимум** (по установленному лимиту для этой модели: лимит Credits × 0.095215), фактическая сумма рассчитывается по реальному объему и не превышает лимит.

Подробности об этих двух схемах см. в [схеме тарификации `exact` и `upto`](https://platform.acedata.cloud/documents/x402-metered-upto). Здесь мы говорим только о ценах.

## Цены на Chat (дополнение чата)

Дополнение чата рассчитывается по модели `upto`: оплата производится по фактическому объему токенов prompt / completion. Цена за миллион (1M) токенов = `Стоимость Credits за 1M токенов для этой модели × 0.095215`, полностью соответствует цене в USD, представленной в открытом каталоге моделей платформы (`/api/v1/models?with_pricing=true`).

Ниже приведена таблица с реальными ценами (взята из каталога моделей, по курсу X402), единица USD / 1M токенов:

| Модель | Вход / 1M | Выход / 1M | `upto` лимит |
| - | - | - | - |
| gpt-4o-mini | \$0.0796 | \$0.3183 | 1 Credit (\$0.095215) |
| gemini-2.5-flash | \$0.1591 | \$1.3262 | 5 Credits (\$0.476074) |
| gpt-5 / gpt-5.1 | \$0.6631 | \$5.3050 | 20 Credits (\$1.904299) |
| gemini-2.5-pro | \$0.6631 | \$5.3050 | 50 Credits (\$4.760750) |
| gpt-4.1 | \$1.0610 | \$4.2440 | 20 Credits (\$1.904299) |
| claude-sonnet-4-5 | \$0.6006 | \$3.0028 | 50 Credits (\$4.760750) |
| grok-4 | \$1.5915 | \$7.9574 | 10 Credits (\$0.952149) |
| claude-opus-4-1 | \$3.0028 | \$15.0140 | 50 Credits (\$4.760750) |

Примечания:

* В таблице указана цена за токен; стоимость одного запроса = входные токены × цена за вход + выходные токены × цена за выход.
* Лимит `upto` - это максимальная сумма, которую разрешено подписывать за один запрос для этой модели; это не фактический вычет, большинство запросов значительно ниже лимита.
* Лимит определяет только «максимально возможную сумму», фактический расчет производится по объему токенов.

### Пример: цена и вычет совпадают (`exact`)

Ниже приведен пример **реального платного вызова** с использованием официального X402Client к `serp/google` (Base `exact`). Он демонстрирует согласованность трех элементов: цена 402, подписанная сумма и `cost`, возвращаемый в успешном ответе.

```text theme={null}
# 1) Запрос без оплаты -> 402, получение цены (без вычета)
POST /serp/google  ->  402
base/exact maxAmountRequired = 952 atomic = $0.000952 = 0.01 Credit
# 0.01 × 0.095215 = 0.00095215, округлено до atomic = 952

# 2) Подписание 952 atomic с помощью кошелька PAYMENT-SIGNATURE, повторная попытка
POST /serp/google (PAYMENT-SIGNATURE) -> 200
body.cost = {"amount": 0.000952, "currency": "usdc", "settlement": "authorized"}
```

响应返回的 `cost.amount`（0.000952 USDC）与 402 报价、与 `Credits × 0.095215` 完全一致。`settlement` 字段是该笔支付的结算状态（`authorized` = 已授权）；链上结算由平台处理，机制见 [`exact` 与 `upto` 计费方案](https://platform.acedata.cloud/documents/x402-metered-upto)。

### `upto` 报价计算（聊天）

聊天按 token 计量。某次请求的报价（不是上限）按下式计算（以 gpt-4o-mini 为例）：

```text theme={null}
Credits = 1e-6 × (0.835733 × prompt_tokens + 3.342933 × completion_tokens)
USDC    = Credits × 0.095215
```

一次 500 prompt + 200 completion token 的请求：

```text theme={null}
Credits = 1e-6 × (0.835733 × 500 + 3.342933 × 200) ≈ 0.001086 Credits
报价 USDC ≈ 0.001086 × 0.095215 ≈ $0.0001034
```

客户端按 `upto` 上限（gpt-4o-mini 为 1 Credit = `95215` atomic）签名，这只是**最多可能扣多少**；该次请求的真实报价（上例约 \$0.0001）远低于上限，按 token 用量结算。`upto` 的链上结算机制见 [`exact` 与 `upto` 计费方案](https://platform.acedata.cloud/documents/x402-metered-upto)。

## 其他服务价格（固定价 `exact`）

图片、视频、音乐、搜索这类接口在请求时价格即可确定，使用 `exact`。下表为真实价格，取自线上接口对未支付请求返回的 402 `maxAmountRequired`（查询报价不会产生扣费）：

| 服务 | 示例模型 / 参数 | Credits | USDC | atomic |
| - | - | - | - | - |
| 网页搜索 | serp/google，≤10 条结果 | 0.01 | \$0.000952 | 952 |
| 图片 | nano-banana | 0.14 | \$0.013330 | 13330 |
| 图片 | gpt-image-1，1024×1024 | 0.20 | \$0.019043 | 19043 |
| 图片 | flux-dev | 0.24 | \$0.022851 | 22851 |
| 图片 | midjourney imagine | 0.27 | \$0.025708 | 25708 |
| 图片 | seedream-4 | 0.32 | \$0.030468 | 30468 |
| 音乐 | suno generate | 0.55 | \$0.052368 | 52368 |
| 音乐 | producer generate | 0.68 | \$0.064746 | 64746 |
| 视频 | luma | 1.19 | \$0.113305 | 113305 |
| 视频 | hailuo（minimax-hailuo-2-3） | 1.72 | \$0.163769 | 163769 |
| 视频 | kling-v2-6 std | 2.10 | \$0.199951 | 199951 |
| 视频 | kling-v3 std | 4.20 | \$0.399903 | 399903 |
| 视频 | veo-3 text→video | 5.00 | \$0.476074 | 476074 |
| 视频 | seedance-1-0-pro，1080p / 5s | 5.60 | \$0.533204 | 533204 |
| 视频 | wan2.6-t2v | 13.50 | \$1.285402 | 1285402 |

说明：

* 同一服务的价格随**模型、分辨率、时长、动作**变化（尤其是视频）。上表是某一组参数下的真实取值，仅供量级参考。
* 这类固定价（`exact`）接口，该请求 402 响应里的 `maxAmountRequired` 即该次应付金额（与成功响应的 `cost.amount` 一致，上节已实测）。
* 每个价格都由 `Credits × 0.095215` 向下取整到 atomic 单位得到（见上文计价基准），与聊天用的是同一套换算。因浮点表示与取整，个别值可能与朴素乘积相差 1 atomic（\$0.000001），一律以 402 返回值为准。

## 订单支付价格

用 X402 支付控制台订单（购买套餐 / 充值 Credits）时，价格以订单页面显示为准，402 的 `amount` 为最终签名依据。订单支付走平台 API、需要账户令牌，详见 [订单支付教程](https://platform.acedata.cloud/documents/x402-order-payment)。

订单支付教程中的一个真实例子（购买 10 Credits）：

```text theme={null}
description Ace Data Cloud Credits x 10.0
created price 1.26          # 订单创建价（USD）
settled    1.20 USDC        # 最终签名/结算金额（= 402 amount）
            = 1200000 atomic USDC
```

注意：**按调用付费**（上文 Chat / 其他服务）和**订单支付**是两条不同路径。按调用付费统一用 `0.095215`/Credit 的最优档单价；订单支付按套餐定价，其创建价与最终结算金额的差异以 [订单支付教程](https://platform.acedata.cloud/documents/x402-order-payment) 为准。

## 如何实时获取价格

价格随模型和参数变化，请用程序实时获取，不要硬编码：

* **按调用价格**：对目标 API 发一次**不带** `PAYMENT-SIGNATURE`（也不带 `Authorization`）的请求，读取返回的 402 `accepts[].maxAmountRequired`。这一步不会扣费。对 `exact` 接口它是最终价格；对 `upto` 接口（聊天）它是上限，实际按用量结算。
* **聊天每 token 单价**：`GET https://platform.acedata.cloud/api/v1/models?with_pricing=true&type=chat`，读取每个模型的 `pricing.input_usd` / `pricing.output_usd`（已按 `credit_usd_rate` 计算）。
* **换算校验**：`atomic = floor(Credits × 0.095215 × 1e6)`，`USDC = atomic / 1e6`（即 `USDC ≈ Credits × 0.095215`）。

获取价格的最小请求示例：

```bash theme={null}
curl -sS -X POST https://x402.acedata.cloud/midjourney/imagine \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "a cat"}'
# 返回 402，accepts[].maxAmountRequired 即为该次（exact）调用价格
```

## 小结

* X402 цена = стоимость Credits за этот вызов × `0.095215`, и обычная стоимость Credits **та же самая**, просто расчет производится в цепочном USDC.
* `0.095215`/Credit — это **оптимальная ставка** (крупные) Credits; при небольших пополнениях цена за Credits выше, поэтому X402 автоматически получает оптимальную цену.
* Сумма подписи интерфейса `exact` (изображение / видео / музыка / поиск / заказ) — это сумма к оплате; сумма подписи интерфейса `upto` (чат) — это верхний предел, расчет производится по фактическому использованию.
* Авторитетная цена определяется по `maxAmountRequired`, возвращаемому 402: `exact` — это сумма к оплате (соответствует `cost.amount` успешного ответа, уже протестировано); `upto` — это верхний предел, `cost.amount` успешного ответа — это реальная сумма, рассчитанная по использованию (≤ верхнего предела).

## Связанные документы

| Документ | Ссылка |
| - | - |
| Руководство по интеграции X402 (обзор) | [Руководство по интеграции X402](https://platform.acedata.cloud/documents/x402-integration) |
| Быстрый старт | [Быстрый старт X402](https://platform.acedata.cloud/documents/x402-quickstart) |
| Планы тарификации `exact` и `upto` | [Описание тарифных планов](https://platform.acedata.cloud/documents/x402-metered-upto) |
| Сети и способы оплаты | [Сети и способы оплаты](https://platform.acedata.cloud/documents/x402-networks) |
| Учебник по оплате заказов | [Учебник по оплате заказов](https://platform.acedata.cloud/documents/x402-order-payment) |


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