API Reference
x402-paysdk 的公开入口、运行时边界、金额规则、返回证据和失败行为。
所有 TypeScript 公共 API 都随同一个 x402-paysdk 版本发布。
Shellnpm install x402-paysdk
公开入口
| 导入 | 运行时 | Reference |
|---|---|---|
x402-paysdk/pay | 浏览器、应用、钱包宿主 | 付款 API |
x402-paysdk/receive | 收款应用或受信工具 | 收款 API |
x402-paysdk/merchant | 仅限后端 | 商户 API |
包根不提供 catch-all export。显式子路径能让信任边界错误在 import 和 code review 中直接可见。
共同约定
金额
金额是 token 原子单位的正整数字符串。USDC 有六位精度，1000000 表示 1 USDC。不要传 JavaScript 浮点 token 值。
网关 origin
生产网关必须是没有 credential、path、query 和 fragment 的规范 HTTPS origin。HTTP 只允许 localhost 开发。
标识符
refId、paymentId、invoiceId、orderId 和 cursor 都是有界公开标识符，不能包含 PII、secret 或任意长文本。
错误
输入和协议失败会 reject Error。HTTP 错误在可用时包含网关 code，例如 invalid_request、unauthorized、ref_expired、ref_revoked、payment_verification_failed、settlement_failed、receipt_invalid、rpc_unavailable 和 rate_limited。
终局性
pay() 返回 status: "settled" 表示网关返回了成功结算交易。商户履约仍应通过 verifyReceipt() 或 getTxStatus() 执行明确的确认数策略。
SDK 方法对应网关 HTTP surface。路由、认证、header 和恢复行为见网关 HTTP API。