X402 TypeScript SDK 接入教程
内容提要
本文介绍Ace Data Cloud X402的TypeScript SDK接入教程。该SDK处理API调用、轮询、错误重试，并在遇到402错误时自动签出X-Payment请求头。文章涵盖安装依赖、Base/SKALE及Solana网络配置示例、浏览器钱包集成，以及exact和upto支付方案的选择，强调业务代码无需手动处理402重试。
延伸解读
SDK 自动处理 402 重试
SDK 在收到 402 错误时，会自动调用 payment handler 生成 X-Payment 头，并使用原请求体重试。业务代码无需手动处理 402 重试，只需像普通 SDK 调用一样编写代码。这简化了支付流程，但开发者需确保正确配置钱包或私钥，否则重试可能失败。
网络选择：Base 与 SKALE 的权衡
Base 和 SKALE 均支持 EVM 签名，但各有优劣：SKALE 链上交易 gas 成本低，适合高频小额支付；Base 的 USDC 流动性和钱包支持更成熟，适合依赖现有生态的场景。开发者应根据应用需求选择网络，并注意 Solana 路径目前仅支持 exact 方案。
exact 与 upto 支付方案的选择
exact 方案预先支付固定金额，upto 方案通过 Permit2 一次性授权，后置计量。默认选择 exact，若需 upto 需显式传入 preferScheme: 'upto'。注意 upto 需要额外授权步骤，且服务端可能未返回 upto 要求，此时会自动回退到 exact。
Q&A
如何安装 X402 TypeScript SDK？
使用 npm 安装 @acedatacloud/sdk 和 @acedatacloud/x402-client。如果使用 Base 或 SKALE，还需要安装 ethers；如果使用 Solana，需要安装 @solana/web3.js。
X402 SDK 在遇到 402 错误时如何处理？
SDK 的 transport 在收到 402 错误时，会调用 payment handler 生成 X-Payment 请求头，然后自动使用原请求体重试，业务代码无需手动处理。
如何在 Base 网络上使用 X402 SDK？
在 Node.js 中，可以使用 ethers.Wallet 包装一个 EIP-1193 风格的 provider，然后创建 AceDataCloud 客户端时传入 paymentHandler，并设置 network 为 'base'。
如何在浏览器中集成 X402 SDK？
在浏览器中，可以直接使用 window.ethereum 作为 EIP-1193 provider，传入 createX402PaymentHandler，并设置 network 为 'base'。用户会看到签名确认，签名内容包含支付要求。
X402 SDK 支持哪些网络？
支持 Base、SKALE 和 Solana。Base 的优势是 USDC 流动性和钱包支持更成熟，SKALE 的优势是 gas 成本低，Solana 目前只支持 exact 支付方案。
exact 和 upto 支付方案有什么区别？如何选择？
exact 是固定金额支付，upto 是后置计量支付。SDK 默认选择 exact，如果需要 upto，需要传入 preferScheme: 'upto'。如果服务端没有返回 upto，会自动回退到 exact。
Solana 网络使用 X402 SDK 有什么限制？
Solana 路径目前只支持 exact 支付方案，不支持 upto。如果 API 返回多个 accepts，handler 会选择 network 为 'solana' 的那一项。
