> ## 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 Opis cenowy

> Platform API guide - Ace Data Cloud

Ten dokument wyjaśnia, jak ustalana jest cena przy wywołaniu Ace Data Cloud API za pomocą X402 oraz jak ma się ona do ceny zwykłych **Credits** (kredytów) na platformie.

## Kluczowe wnioski

X402 nie jest niezależnym systemem cenowym. Każde wywołanie API ma koszt wyrażony w **Credits**, który jest jedynym źródłem cen dla wszystkich metod rozliczeń (odjęcie kredytów z tokena API, saldo konta, płatność na łańcuchu X402). X402 po prostu przelicza ten koszt kredytów na USDC na łańcuchu według stałego kursu:

> **1 Credit = 0.095215 USDC** (czyli `95215` atomic USDC, USDC ma 6 miejsc po przecinku)

Oznacza to, że:

```text theme={null}
Cena X402 (USDC) = Koszt kredytów za to wywołanie × 0.095215
```

Ten kurs nie jest ustalany przypadkowo, jest równy **najlepszej stawce (dużych) kredytów** na platformie. Dlatego płacenie za pomocą X402 ≈ kupowanie kredytów po najlepszej stawce, **bez dodatkowych opłat X402**, a wręcz korzystanie z najtańszej stawki kredytów, bez potrzeby wcześniejszego doładowania, bez potrzeby tokena API.

## Podstawa wyceny

| Element | Wartość | Opis |
| - | - | - |
| Kurs wymiany | `1 Credit = 0.095215 USDC` | Ustalony przez platformę stały kurs |
| jednostka atomic | `1 Credit = 95215 atomic USDC` | USDC 6 miejsc po przecinku, `atomic = floor(credits × 0.095215 × 1e6)` |
| Minimalna opłata | `1 atomic USDC` (\$0.000001) | Nawet przy bardzo niskim koszcie, rozliczenie wynosi co najmniej 1 atomic |
| Waluta wyceny | USDC | Base / SKALE to ERC-20 USDC, Solana to SPL USDC |

Przeliczenie jest realizowane przez platformę, kwoty są takie same dla wszystkich wspieranych sieci (Base, SKALE, Solana); różne sieci różnią się jedynie kontraktami aktywów i metodami podpisu, cena jest taka sama.

### Związek z ceną zwykłych kredytów

Kredyty na platformie są sprzedawane w systemie „im większe zużycie, tym niższa cena”. X402 przy rozliczaniu wywołań zawsze korzysta z najlepszej stawki:

| Metoda zakupu/płatności | Przybliżona cena kredytów | Opis |
| - | - | - |
| Wstęp / Małe doładowanie | Około `$0.13 / Credit` | Cena katalogowa, cena przy zakupie małych kredytów |
| Duże / Najlepsza stawka | `$0.095215 / Credit` | Najtańsza cena |
| **X402 płatność za wywołanie** | **`$0.095215 / Credit`** | **Zawsze równa najlepszej stawce** |

Innymi słowy, X402 rozlicza każde wywołanie według najlepszej stawki kredytów. Użytkownicy kupujący kredyty w małych doładowaniach będą mieli wyższą cenę niż X402; tylko użytkownicy z dużymi doładowaniami będą mieli cenę równą X402.

## Dwa rodzaje cen: `exact` i `upto`

W odpowiedzi 402 X402, `maxAmountRequired` to kwota, którą musisz podpisać. Ma ona dwa kształty:

* **`exact` (stała cena)**: Cena jest znana przed przetworzeniem żądania (obrazy, wideo, muzyka, wyszukiwanie, płatności zamówień). `maxAmountRequired = Koszt kredytów za to wywołanie × 0.095215`, czyli kwota do zapłaty za to wywołanie (zgodna z `cost.amount` w udanej odpowiedzi).
* **`upto` (pomiar po zużyciu)**: Interfejsy takie jak uzupełnianie czatu, gdzie „dopiero po zakończeniu odpowiedzi wiadomo, ile tokenów zostało użytych”. `maxAmountRequired` to **górny limit** (przeliczony według ustalonego modelu limitu: limit kredytów × 0.095215), rzeczywiste rozliczenie odbywa się według rzeczywistego zużycia, nie przekraczając górnego limitu.

Szczegóły protokołu dotyczącego tych dwóch schematów można znaleźć w [schemacie rozliczeń `exact` i `upto`](https://platform.acedata.cloud/documents/x402-metered-upto). Poniżej omawiamy tylko ceny.

## Ceny czatu (uzupełnianie czatu)

Uzupełnianie czatu jest rozliczane w systemie `upto`: według rzeczywistego zużycia tokenów prompt / completion. Cena za milion (1M) tokenów = `Koszt kredytów za 1M tokenów w tym modelu × 0.095215`, całkowicie zgodna z publicznym katalogiem modeli platformy (`/api/v1/models?with_pricing=true`).

Poniższa tabela przedstawia rzeczywiste ceny (pochodzące z katalogu modeli, według kursu X402), jednostka USD / 1M tokenów:

| Model | Wejście / 1M | Wyjście / 1M | Górny limit `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) |

Wyjaśnienie:

* W tabeli przedstawiono ceny jednostkowe według tokenów; koszt jednego żądania = wejście tokenów × cena jednostkowa wejścia + wyjście tokenów × cena jednostkowa wyjścia.
* Górny limit `upto` to maksymalna kwota, którą można podpisać w jednym żądaniu dla tego modelu; nie jest to rzeczywista kwota do zapłaty, większość żądań jest znacznie poniżej górnego limitu.
* Górny limit decyduje tylko o „maksymalnej możliwej kwocie do odjęcia”, rzeczywiste rozliczenie odbywa się według zużycia tokenów.

### Przykład: Cena i opłata są zgodne (`exact`)

Poniżej znajduje się rzeczywiste wywołanie płatności za pomocą oficjalnego X402Client dla `serp/google` (Base `exact`). Demonstruje ono zgodność trzech elementów: wyceny 402, kwoty podpisanej oraz `cost` zwróconej w udanej odpowiedzi.

```text theme={null}
# 1) Żądanie bez płatności -> 402, uzyskanie wyceny (bez opłaty)
POST /serp/google  ->  402
base/exact maxAmountRequired = 952 atomic = $0.000952 = 0.01 Credit
# 0.01 × 0.095215 = 0.00095215, zaokrąglone w dół do atomic = 952

# 2) Podpisanie 952 atomic PAYMENT-SIGNATURE z portfela, ponowne próby
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 cena = koszt Credits za to wywołanie × `0.095215`, i jest to **ta sama cena** co w przypadku zwykłych Credits, tylko rozliczane w USDC na łańcuchu.
* `0.095215`/Credit to **najlepsza stawka** (duże) Credits; przy małych doładowaniach cena Credits jest wyższa, więc X402 automatycznie uzyskuje najlepszą stawkę.
* Kwota podpisana w interfejsie `exact` (zdjęcia / wideo / muzyka / wyszukiwanie / zamówienia) to kwota do zapłaty; w interfejsie `upto` (czat) podpisana jest górna granica, rozliczane według rzeczywistego zużycia.
* Autorytatywna cena opiera się na `maxAmountRequired` zwróconym przez 402: `exact` to kwota do zapłaty (zgodna z `cost.amount` w odpowiedzi sukcesu, potwierdzone); `upto` to górna granica, a `cost.amount` w odpowiedzi sukcesu to rzeczywista kwota rozliczana według zużycia (≤ górna granica).

## Powiązane dokumenty

| Dokument | Link |
| - | - |
| Przewodnik integracji X402 (przegląd) | [Przewodnik integracji X402](https://platform.acedata.cloud/documents/x402-integration) |
| Szybki start | [Szybki start X402](https://platform.acedata.cloud/documents/x402-quickstart) |
| Plany rozliczeniowe `exact` i `upto` | [Opis planów rozliczeniowych](https://platform.acedata.cloud/documents/x402-metered-upto) |
| Sieci i metody płatności | [Sieci i metody płatności](https://platform.acedata.cloud/documents/x402-networks) |
| Samouczek dotyczący płatności za zamówienia | [Samouczek dotyczący płatności za zamówienia](https://platform.acedata.cloud/documents/x402-order-payment) |


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