跳到正文

快速开始

用最短路径从支付引用完成一次链上结算。

x402 PaySDK 把支付请求表达成可移植的 PaymentRef。同一个引用可以通过二维码、链接、应用深链或 API 响应传递，而不需要改变支付协议。

选择接入方式

你的角色使用职责
钱包或付款应用x402-paysdk/pay解析引用、验证 offer、请求钱包签名并提交支付。
收款工具x402-paysdk/receive创建、读取、列出和撤销支付引用。
商户后端x402-paysdk/merchant注册商户、管理引用和订单、验证收据、处理通知并对账。
网关运营方Rust gateway crates运行原生服务或 Cloudflare Worker，且不托管用户资金。

安装付款 SDK

Shell
npm install x402-paysdk

提供一个能够签署 EIP-712 typed data 的钱包适配器。SDK 负责准备 EIP-3009 授权，但不会接触私钥。

TypeScript
import { pay } from 'x402-paysdk/pay';const result = await pay({  refUrl: paymentRef,  paymentId: crypto.randomUUID(),  wallet: {    address: account.address,    signTypedData: (typedData) => walletClient.signTypedData(typedData)  }});console.log(result.status, result.txHash);

默认情况下，pay() 会要求 signed offer，发现网关身份、验证支付上下文、请求钱包签名、提交 PAYMENT-SIGNATURE，并返回结算结果和 signed receipt。

一次成功支付

  1. 收款方创建 PaymentRef。
  2. 付款方请求 /receive/:payTo，收到 402 Payment Required。
  3. 付款 SDK 验证 signed offer 和完整支付上下文。
  4. 钱包为 USDC 签署 EIP-3009 授权。
  5. 网关请求 facilitator 验证并结算。
  6. USDC 在链上从付款方直接转给收款方。
  7. 网关返回交易哈希，以及配置完成时的 signed receipt。

网关不持有付款方私钥或资金。涉及财务终局性时，应验证链上交易，不能只依赖 webhook。

下一步