> ## 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 X402 是基于 HTTP `402 Payment Required` 的链上支付协议。通过 Ace Data Cloud 的 X402 能力，调用方可以不创建 API Token、不预充值账户余额，而是在每一次 API 请求中直接用 USDC 完成链上支付。 这组文档按真实接入顺序组织：先跑通一次最小请求，再接入 SDK，之后理解网络、计费方案、订单支付和 Facilitator。建议按下表从上到下阅读。 | 教程 | 适用场景 | 链接 | | - | - | - | | 快速开始 | 先用一个最小请求理解 402、`accepts` 和 `PAYMENT-SIGNATURE` 流程 | [X402 快速开始](https://platform.acedata.cloud/documents/x402-quickstart) | | TypeScript SDK | 在浏览器、Node.js 或前端应用中调用 Ace Data Cloud API | [TypeScript SDK 接入](https://platform.acedata.cloud/documents/x402-typescript-sdk) | | Python SDK | 在 Python 服务、脚本、Agent 或数据流水线中调用 API | [Python SDK 接入](https://platform.acedata.cloud/documents/x402-python-sdk) | | 订单支付 | 用 X402 支付 Ace Data Cloud 控制台订单 | [订单支付教程](https://platform.acedata.cloud/documents/x402-order-payment) | | 网络与支付方式 | 了解 Base、SKALE、Solana 的资产、签名和适用场景 | [网络与支付方式](https://platform.acedata.cloud/documents/x402-networks) | | `exact` 与 `upto` | 区分固定价格 API 和用量后置结算 API | [计费方案说明](https://platform.acedata.cloud/documents/x402-metered-upto) | | 价格说明 | 了解 X402 价格与 Credits 单价的关系，及各服务真实价格 | [X402 价格说明](https://platform.acedata.cloud/documents/x402-pricing) | | Facilitator | 理解 `verify`、`settle` 和自建收款 API 的服务端链路 | [Facilitator 集成](https://platform.acedata.cloud/documents/x402-facilitator) | | E2E 与故障排查 | 检查公开入口、运行高级验证工具，定位常见 402、签名和结算问题 | [E2E 验证与故障排查](https://platform.acedata.cloud/documents/x402-e2e-troubleshooting) | ## 推荐接入路径 如果你只是想调用 Ace Data Cloud API，优先使用官方 SDK： * TypeScript：`@acedatacloud/sdk` + `@acedatacloud/x402-client` * Python：`acedatacloud` + `acedatacloud-x402` 公开源码与包地址： | 项目 | 地址 | | - | - | | Ace Data Cloud SDK | [https://github.com/AceDataCloud/SDK](https://github.com/AceDataCloud/SDK) | | X402 Client | [https://github.com/AceDataCloud/X402Client](https://github.com/AceDataCloud/X402Client) | | X402 Facilitator | [https://github.com/AceDataCloud/FacilitatorX402](https://github.com/AceDataCloud/FacilitatorX402) | | npm SDK | [https://www.npmjs.com/package/@acedatacloud/sdk](https://www.npmjs.com/package/@acedatacloud/sdk) | | npm X402 Client | [https://www.npmjs.com/package/@acedatacloud/x402-client](https://www.npmjs.com/package/@acedatacloud/x402-client) | | PyPI SDK | [https://pypi.org/project/acedatacloud/](https://pypi.org/project/acedatacloud/) | | PyPI X402 Client | [https://pypi.org/project/acedatacloud-x402/](https://pypi.org/project/acedatacloud-x402/) | SDK 会自动完成第一次无认证请求、解析 `402 Payment Required`、调用 payment handler、携带 `PAYMENT-SIGNATURE` 重试这些步骤。你只需要准备一个有 USDC 的钱包，并选择希望使用的网络。 如果你要让自己的 API 也支持 X402 收款，则需要阅读 Facilitator 文档，理解 `paymentRequirements`、`paymentPayload`、`/verify` 和 `/settle` 的关系。 ## 支持状态 Ace Data Cloud X402 已在公开 API、官方 SDK、Facilitator 和链上结算路径完成验证。下表按开发者接入时最常用的能力维度汇总当前状态。 | 能力 | 状态 | 说明 | | - | - | - | | Facilitator capabilities | 可用 | `https://facilitator.acedata.cloud/.well-known/x402` 返回支付网络与协议端点。 | | API 402 `accepts` | 可用 | 未支付请求会返回 Base、SKALE 和 Solana 的可用 payment requirement。 | | TypeScript SDK | 可用 | `@acedatacloud/sdk` 与 `@acedatacloud/x402-client` 可自动处理 402、签名和重试。 | | Python SDK | 可用 | `acedatacloud` 与 `acedatacloud-x402` 可自动处理 402、签名和重试。 | | Base `exact` | 已链上验证 | 适合固定金额 API 和订单支付。 | | Base `upto` | 已链上验证 | 适合聊天补全等后置计量 API，当前唯一提供 `upto` 的网络。 | | SKALE `exact` | 已链上验证 | 适合低 gas 成本的 EVM 支付场景。 | | Solana `exact` | HTTP paid retry 已验证 | 已验证 API paid retry 与模型响应；链上签名确认建议使用自有 Solana RPC 对账。 | | 订单支付 | 已链上验证 | Base `exact` 订单支付已完成链上结算并更新订单状态。 | 以下输出仅用于说明已验证路径的返回形态。实际接入时，请始终以当前 API 返回的 `accepts` 为准。 ```text theme={null} packages @acedatacloud/sdk@2026.504.2 import ok @acedatacloud/x402-client@2026.531.3 import ok acedatacloud==2026.4.26.1 import ok acedatacloud-x402==2026.5.31.3 import ok API 402 status 402 accepts eip155:8453/exact, eip155:8453/upto, solana:5eykt4.../exact, eip155:1187947933/exact TypeScript SDK content ADC_TS_SDK_X402_OK Python SDK content ADC_PY_SDK_X402_OK Base exact content ADC_BASE_E2E_OK tx 0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3 explorer https://basescan.org/tx/0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3 SKALE exact content ADC_SKALE_E2E_OK tx 0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f explorer https://skale-base-explorer.skalenodes.com/tx/0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f Base upto content ADC_BASE_UPTO_OK tx 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036 explorer https://basescan.org/tx/0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036 signed ceiling 95215 atomic USDC transfer value 3 atomic USDC Solana exact HTTP 402 -> HTTP 200 content ADC_SOLANA_E2E_OK chain signature not confirmed in this run Order payment order 78481793-304e-47f7-bc0c-8231aec9cc1e state Finished pay_way X402 tx 0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151 explorer https://basescan.org/tx/0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151 ``` 说明： * npm 和 PyPI 包都已在干净环境安装并导入成功。 * 未支付 API 请求返回 402，`accepts` 中包含 Base、SKALE 和 Solana 的可用支付方式。 * `accepts[].network` 是 CAIP-2 标识，客户端选网时必须按 CAIP-2 字符串匹配。 * TypeScript SDK 与 Python SDK 都能自动处理 402 并完成 paid retry。 * Base `exact`、SKALE `exact`、Base `upto` 和订单支付都有可公开打开的 explorer 地址。 * Base `upto` 的签名上限为 `95215` atomic USDC，实际 settlement 为 `3` atomic USDC，体现了后置计量按真实用量结算的特性。 * Solana `exact` 已验证 HTTP 402 -> HTTP 200 和模型输出。由于公开 RPC 查询可能限流，严格对账时建议使用自有 Solana RPC 或平台侧结算记录确认交易签名。 ## 接入注意事项 开发者接入时，请优先关注当前请求返回的实时支付要求，而不是复制文档中的示例金额或地址： * `accepts[].maxAmountRequired` 是当前请求可签名的最大金额。 * `accepts[].asset` 是本次请求要使用的 USDC 合约或 mint。 * `accepts[].extra.chainId`、`accepts[].extra.facilitatorAddress` 和 `accepts[].extra.verifyingContract` 会参与 EVM typed data 签名。 * `upto` 需要钱包先对目标链 USDC 授权 Permit2；未授权时会返回 `PERMIT2_ALLOWANCE_REQUIRED`。 * 如果明确希望使用后置计量，请在 TypeScript SDK 中传入 `preferScheme: 'upto'`，否则 SDK 会选择该网络下服务器返回的第一个可用 requirement。 ## 可以公开核验的范围 接入前可以先核验这些公开入口和 SDK 行为： * 未带 `Authorization` 或 `PAYMENT-SIGNATURE` 的 API 请求会返回 `402 Payment Required`，响应中的 `accepts` 是本次请求的唯一签名依据。 * TypeScript SDK 和 Python SDK 都提供 payment handler，SDK 传输层在收到 402 后会调用 handler 并重试一次。 * `https://facilitator.acedata.cloud/.well-known/x402`：返回 Facilitator 支持的网络、scheme 与协议端点；API 价格仍以目标请求实时返回的 402 为准。 * `https://facilitator.acedata.cloud/supported`：返回 Facilitator 支持的网络与 scheme。 * X402Client 仓库包含高级链上验证工具，可用于确认签名、重试和 settlement 行为；工具输出不替代线上 API 返回的 `accepts`。 `upto` 属于后置计量结算，适合聊天补全、模型调用等真实用量在响应后才知道的 API。当前只有 Base 提供 `upto`；如果签名验证失败，请检查 chain id、facilitator 地址、spender、USDC 合约和 Permit2 allowance 是否与 402 响应一致。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.