> ## 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.