> ## 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 集成指南 - Ace Data Cloud

Ace Data Cloud X402 当前围绕 USDC 结算，支持 EVM 和 Solana 两类链。不同网络的签名方式、资产地址、gas 行为和适用场景不同，接入前需要先选好网络。

## 网络标识使用 CAIP-2

x402 v2 的 `accepts[].network` 是 CAIP-2 标识，不是 `base`、`skale` 这类简称。客户端匹配网络时必须按 CAIP-2 字符串比较：

| 网络 | CAIP-2 标识 |
| - | - |
| Base | `eip155:8453` |
| SKALE Base | `eip155:1187947933` |
| Solana mainnet | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` |

## 支持矩阵

| 网络 | scheme | 资产 | 签名方式 | 适用场景 |
| - | - | - | - | - |
| Base | `exact` | Base USDC | EIP-3009 `TransferWithAuthorization` | 默认推荐，钱包和流动性支持成熟。 |
| Base | `upto` | Base USDC + Permit2 | Permit2 `PermitWitnessTransferFrom` | 聊天、模型等后置计量 API。 |
| SKALE | `exact` | SKALE bridged USDC | EIP-3009 `TransferWithAuthorization` | 低 gas 成本，适合 EVM 支付验证和低成本调用。 |
| Solana | `exact` | Solana USDC | SPL `TransferChecked` | Solana 钱包、Agent 或链上应用场景。 |

`upto` 目前只在 Base 上提供。实际可用项以 API 返回的 `accepts` 为准。你也可以查看 Facilitator：

```bash theme={null}
curl https://facilitator.acedata.cloud/supported
```

Facilitator `/supported` 的返回：

```json theme={null}
{
  "kinds": [
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "eip155:8453"
    },
    {
      "x402Version": 2,
      "scheme": "upto",
      "network": "eip155:8453",
      "extra": {
        "facilitatorAddress": "0xd019238EAA8a9Ca13C5792Ca10B4029D6ce25708"
      }
    },
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "eip155:1187947933"
    },
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "extra": {
        "feePayer": "3SPm6qbgsDkj24MuR8Ss4sH97fziqyCiqFKDyeVU2igq"
      }
    }
  ]
}
```

结果说明：

* Base、SKALE 和 Solana 的 `exact` 是固定金额支付路径。
* 只有 Base 提供 `upto` 后置计量路径，依赖 Permit2 approve。
* `upto` 条目里的 `extra.facilitatorAddress` 是客户端签名时要写入 witness 的地址，必须和服务端返回值一致。

## Base

Base 使用官方 USDC 合约：

```text theme={null}
0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
```

`exact` 方案中，客户端签署 EIP-712 `TransferWithAuthorization`。签名内容包括：

* `from`：付款钱包地址
* `to`：Ace Data Cloud 收款地址
* `value`：本次支付金额
* `validAfter` / `validBefore`：签名有效时间窗口
* `nonce`：32 字节随机 nonce

Facilitator 验证签名后，会在链上调用 USDC 的 `transferWithAuthorization` 完成转账。

Base 是最推荐的正式接入网络，尤其适合 `upto` 后置计量，因为 Permit2、USDC 和钱包生态都更成熟。

Base `exact` 验证结果示例：

```text theme={null}
payer 0x5d4f08D5c2bb60703284bc06671Eb680fA41B105
content ADC_BASE_E2E_OK
tx 0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3
block 46726299
explorer https://basescan.org/tx/0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3
transfer value 95215 atomic USDC
```

结果说明：

* API paid retry 返回模型内容 `ADC_BASE_E2E_OK`。
* 链上交易已在 BaseScan 可查，区块号是 `46726299`。
* `95215` atomic USDC 对应 `0.095215` USDC，是这次 API 调用的实际结算金额。

订单支付 Base `exact` 的程序运行结果：

```text theme={null}
order 78481793-304e-47f7-bc0c-8231aec9cc1e
state Finished
tx 0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
block 46726704
explorer https://basescan.org/tx/0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
transfer value 1200000 atomic USDC
```

结果说明：

* 平台订单最终状态是 `Finished`。
* 订单 `pay_id` 写入同一个 Base 交易哈希。
* `1200000` atomic USDC 对应 `1.2` USDC，是旧政策下该笔 10 Credits 订单的历史实付金额；新订单不再额外享受 X402 支付方式折扣，具体签名金额以本次 402 响应为准。

## SKALE

SKALE 使用 bridged USDC，签名方式与 Base 类似，也是 EIP-3009。它适合低 gas 成本的 EVM 支付场景；实际调用仍以 API 返回的 `accepts` 为准。

SKALE 的典型 402 `accepts` 中会包含：

```json theme={null}
{
  "network": "eip155:1187947933",
  "scheme": "exact",
  "extra": {
    "name": "Bridged USDC (SKALE Bridge)",
    "version": "2",
    "chainId": 1187947933,
    "verifyingContract": "0x85889c8c714505E0c94b30fcfcF64fE3Ac8FCb20"
  }
}
```

SKALE 当前只提供 `exact`。如果你需要后置计量，请使用 Base `upto`。

SKALE `exact` 验证结果示例：

```text theme={null}
content ADC_SKALE_E2E_OK
tx 0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f
block 1969317
explorer https://skale-base-explorer.skalenodes.com/tx/0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f
paid 0.095215 USDC
```

结果说明：

* API paid retry 返回模型内容 `ADC_SKALE_E2E_OK`。
* 交易已在 SKALE explorer 可查，区块号是 `1969317`。
* 这次 `exact` 支付的结算金额是 `0.095215` USDC。

## Solana

Solana 使用 SPL USDC `TransferChecked`。客户端会构造一笔转账交易，签名并提交，之后把交易签名或序列化交易放入 `PAYMENT-SIGNATURE` envelope。

Solana 的特点：

* 使用 Solana wallet adapter 或 base58 secret key；
* 资产是 Solana USDC mint；
* 当前只支持 `exact`；
* Facilitator 会校验 transfer instruction 的 mint、destination、authority 和 amount。

如果使用钱包 fee payer 模式，钱包会直接提交交易，Facilitator 负责确认交易并返回 settlement 结果。

Solana `exact` 验证结果示例：

```text theme={null}
payer AY2RmGm2zPxB1uKvvF4dKyYdr2VySyL3wcD1MKJZoLRd
HTTP 402 -> HTTP 200
content ADC_SOLANA_E2E_OK
chain signature not confirmed in this run
```

结果说明：

* paid retry 已经返回 HTTP 200，并且模型输出 `ADC_SOLANA_E2E_OK`。
* 公开 RPC 查询链上 signature 时可能遇到限流。
* 因为公开 RPC 查询可能限流，这里不写 Solana explorer。需要严格对账时，请使用自有 Solana RPC 或平台侧结算记录确认交易签名。

## 如何选择

| 你要做什么 | 推荐网络 |
| - | - |
| 快速跑通最小链路 | SKALE `exact` 或 Base `exact` |
| 面向普通 Web3 用户 | Base |
| 做聊天补全等后置计量 | Base `upto` |
| Solana 生态应用 | Solana `exact` |
| 低成本 EVM 支付验证 | SKALE `exact` |

无论选择哪条链，都不要在客户端硬编码价格。价格由服务器返回的 `accepts[].maxAmountRequired` 决定。


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