> ## 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 Preço Explicação

> Platform API guide - Ace Data Cloud

Este documento explica como o preço é definido ao chamar a API Ace Data Cloud com o X402, e qual é a relação entre isso e o preço dos **Credits** (créditos) normais da plataforma.

## Conclusão Principal

O X402 não é um sistema de preços independente. Cada chamada de API já tem um custo em **Credits**, que é a única fonte de preço compartilhada por todos os métodos de cobrança (dedução de créditos do Token da API, saldo da conta, pagamento em blockchain com X402). O X402 apenas converte esse custo em Credits para USDC na blockchain a uma taxa fixa:

> **1 Credit = 0.095215 USDC** (ou seja, `95215` atomic USDC, USDC com 6 casas decimais)

Em outras palavras:

```text theme={null}
Preço do X402 (USDC) = Custo em Credits desta chamada × 0.095215
```

Essa taxa não é definida aleatoriamente, ela é igual ao **preço unitário de Credits na melhor faixa (grande volume)** da plataforma. Portanto, pagar com X402 ≈ comprar Credits na melhor faixa de preço e depois consumir, **sem prêmio do X402**, mas sim aproveitando diretamente o preço mais barato dos Credits, sem necessidade de pré-carregamento ou Token da API.

## Base de Cálculo

| Item | Valor | Descrição |
| - | - | - |
| Taxa de Conversão | `1 Credit = 0.095215 USDC` | Taxa fixa definida uniformemente pela plataforma |
| Unidade atomic | `1 Credit = 95215 atomic USDC` | USDC com 6 casas decimais, `atomic = floor(credits × 0.095215 × 1e6)` |
| Custo Mínimo | `1 atomic USDC`（\$0.000001） | Mesmo que o custo seja extremamente baixo, o mínimo a ser liquidado é 1 atomic |
| Moeda de Cálculo | USDC | Base / SKALE é ERC-20 USDC, Solana é SPL USDC |

A conversão é realizada uniformemente pela plataforma, e os valores são consistentes em todas as redes suportadas (Base, SKALE, Solana); as diferentes redes apenas têm contratos de ativos e métodos de assinatura diferentes, mas o preço é o mesmo.

### Relação com o Preço dos Credits Normais

Os Credits da plataforma são vendidos em uma escada de preços onde "quanto maior o uso, menor o preço". O X402, ao cobrar por chamada, utiliza uniformemente o preço da melhor faixa:

| Método de Compra/Pagamento | Preço Aproximado dos Credits | Descrição |
| - | - | - |
| Início / Pequeno Recarregamento | Aproximadamente `$0.13 / Credit` | Preço de tabela, preço por Credits em pequenas compras |
| Grande Volume / Melhor Faixa | `$0.095215 / Credit` | O preço mais barato |
| **X402 Pagamento por Chamada** | **`$0.095215 / Credit`** | **Sempre igual ao preço da melhor faixa** |

Em outras palavras, o X402 liquida cada chamada com o preço dos Credits da melhor faixa. Usuários que compram Credits com pequeno recarregamento terão um preço mais alto do que o do X402; apenas usuários que recarregam em grande volume terão um preço igual ao do X402.

## Duas Formas de Preço: `exact` e `upto`

Na resposta 402 do X402, `maxAmountRequired` é o valor que você precisa assinar. Ele tem duas formas:

* **`exact` (preço fixo)**: O preço pode ser determinado antes do processamento do pedido (imagens, vídeos, música, pesquisa, pagamento de pedidos). `maxAmountRequired = Custo em Credits desta chamada × 0.095215`, ou seja, o valor a ser pago nesta chamada (que é consistente com `cost.amount` na resposta de sucesso).
* **`upto` (medição posterior ao uso)**: Interfaces como a de completamento de chat, onde "só se sabe quanto token foi usado ao final da resposta". `maxAmountRequired` é um **limite** (calculado com base no limite definido por esse modelo: limite de Credits × 0.095215), e o valor real é liquidado com base no uso real, sem exceder o limite.

Para detalhes do protocolo sobre essas duas formas, veja o [esquema de cobrança `exact` e `upto`](https://platform.acedata.cloud/documents/x402-metered-upto). Abaixo, falaremos apenas sobre preços.

## Preço do Chat (completamento de chat)

O completamento de chat é medido como `upto`: a cobrança é feita com base no uso real de tokens de prompt/completação. O preço por milhão (1M) de tokens = `Custo em Credits por 1M tokens deste modelo × 0.095215`, que é completamente consistente com o preço em USD exibido no diretório de modelos da plataforma (`/api/v1/models?with_pricing=true`).

A tabela abaixo mostra os preços reais (extraídos do diretório de modelos, com a taxa do X402), unidade USD / 1M token:

| Modelo | Entrada / 1M | Saída / 1M | Limite `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） |

Observações:

* A tabela mostra o preço por token; o custo de uma solicitação = entrada de tokens × preço de entrada + saída de tokens × preço de saída.
* O limite `upto` é o valor máximo que o modelo permite assinar em uma única solicitação; não é o valor real a ser cobrado, a grande maioria das solicitações fica bem abaixo do limite.
* O limite apenas determina "quanto pode ser cobrado no máximo", a liquidação real é calculada com base no uso de tokens.

### Exemplo: Cotação e Cobrança Consistentes (`exact`)

Abaixo está uma **chamada de pagamento real** feita com o cliente oficial X402Client para `serp/google` (Base `exact`). Ela demonstra a consistência entre os três: cotação 402, valor assinado e o `cost` retornado na resposta de sucesso.

```text theme={null}
# 1) Solicitação não paga -> 402, obtendo a cotação (sem cobrança)
POST /serp/google  ->  402
base/exact maxAmountRequired = 952 atomic = $0.000952 = 0.01 Credit
# 0.01 × 0.095215 = 0.00095215, arredondado para baixo para atomic = 952

# 2) Assinando 952 atomic com a carteira, tentando novamente
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 preço = o custo de Créditos desta chamada × `0.095215`, e a cobrança de Créditos é **o mesmo preço**, apenas liquidado em USDC na blockchain.
* `0.095215`/Crédito é o preço unitário de Créditos na **melhor faixa** (grande quantidade); a compra de Créditos em pequenas quantidades tem um preço unitário mais alto, então X402 automaticamente obtém o melhor preço.
* O valor assinado na interface `exact` (imagem / vídeo / música / pesquisa / pedido) é o valor a ser pago; o valor assinado na interface `upto` (chat) é o limite, liquidado com base no uso real.
* O preço autoritativo é baseado no `maxAmountRequired` retornado por 402: `exact` é o valor a ser pago (consistente com `cost.amount` da resposta de sucesso, já testado); `upto` é o limite, o `cost.amount` da resposta de sucesso é o valor real liquidado com base no uso (≤ limite).

## Documentos Relacionados

| Documento | Link |
| - | - |
| Guia de Integração X402 (Visão Geral) | [Guia de Integração X402](https://platform.acedata.cloud/documents/x402-integration) |
| Começo Rápido | [Começo Rápido X402](https://platform.acedata.cloud/documents/x402-quickstart) |
| Planos de Cobrança `exact` e `upto` | [Descrição dos Planos de Cobrança](https://platform.acedata.cloud/documents/x402-metered-upto) |
| Redes e Métodos de Pagamento | [Redes e Métodos de Pagamento](https://platform.acedata.cloud/documents/x402-networks) |
| Tutorial de Pagamento de Pedidos | [Tutorial de Pagamento de Pedidos](https://platform.acedata.cloud/documents/x402-order-payment) |


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