付款 API

x402-paysdk/pay 的支付、钱包、offer、收据、恢复、DID 与交易 API。

TypeScript
1import { pay } from 'x402-paysdk/pay';

该入口可以运行在付款客户端。它不接收私钥，只在验证 payment requirements 和 signed offer 后调用宿主 WalletSigner。

核心函数

函数	签名	用途
`getPaymentRequired`	`(refUrl: string, amount?: string) => Promise<PaymentRequired>`	解析 ref 并校验 402，不请求签名
`pay`	`(options: PayOptions) => Promise<PayResult>`	协商、验证 offer、签署 EIP-3009、提交并返回证据
`prepareEip3009TypedData`	`(required, payer) => Eip712TypedData`	构造有时间边界的 `TransferWithAuthorization`
`toReceiveUrl`	`(refUrl: string) => URL`	把 `x402pay://` 转为 receive URL
`decodePaymentRequired`	`(encoded: string) => PaymentRequired`	解码 payment-required header

`pay(options)`

TypeScript
1interface PayOptions {2  refUrl: string;3  wallet: WalletSigner;4  paymentId?: string;5  amount?: string;6  trustedOfferSigners?: string[];7  requireSignedOffer?: boolean;8  fetch?: typeof fetch;9}

参数	必填	行为
`refUrl`	是	`x402pay://` 引用或受支持 receive URL
`wallet`	是	提供 address 与 `signTypedData` 的宿主适配器
`paymentId`	否	幂等 id；默认使用 invoice id 或随机公开 id
`amount`	开放金额 ref 必填	原子单位金额
`trustedOfferSigners`	否	网关 signer allowlist；未提供时使用同源 DID 发现
`requireSignedOffer`	否	默认 `true`，只应在受控开发环境关闭
`fetch`	否	自定义测试或有界 transport

TypeScript
1interface WalletSigner {2  address: string;3  signTypedData(params: Eip712TypedData): Promise<string>;4}

返回签名必须是 65-byte EVM signature。Nonce 和有效时间窗由 SDK 生成，钱包适配器不应修改 typed data。

返回值

PayResult 包含 txHash、payTo、amount、network、payer、receiptStatus 和 status: "settled"，以及可选的 signedPaymentReceipt 与 receipt。签名 envelope 和 receipt JSON 必须成对归档，不能修改字段。

Offer 与 DID

函数	用途
`verifySignedOffer`	验证 offer 存在性、上下文、签名、signer trust、payment id 和 expiry
`fetchGatewayDidDocument`	加载并校验 `/.well-known/did.json`，默认最大 16 KiB
`discoverGatewayDidSigners`	返回同源 DID assertion signer
`gatewayDidSigners`	校验已经加载的 DID document
`didWebIdFromGateway`	从网关 origin 推导 `did:web` id

收据 API

函数	网络请求	用途
`verifySignedPaymentReceipt`	否	验证 envelope、content hash、预期字段和 signer allowlist
`verifyReceipt`	是	调用 `/verify-receipt` 验证链状态、金额和 payTo
`paymentReceiptContentHash`	否	生成规范 `sha256:` payment receipt ref
`verifySignedRefundReceipt`	否	本地验证退款收据
`verifyRefundReceipt`	是	验证退款收据与反向链转账
`refundReceiptContentHash`	否	生成规范退款 receipt hash

verifyReceipt 的结果会分开返回 valid 和 confirmed。签名有效的收据仍可能没有达到要求的确认数。

恢复和链查询

函数	签名	说明
`recoverSettlement`	`(options) => Promise<RecoverSettlementResult>`	恢复已知结算，不会再次 settle
`getTxStatus`	`(gateway, txHash) => Promise<TxStatus>`	校验 hash 并查询有界状态
`getPaymentHistory`	`(gateway, options) => Promise<PaymentHistoryResult>`	查询有界 USDC Transfer log

getPaymentHistory 必须提供 payTo、from 或 cursor，还支持 asset、fromBlock 和 limit。

该入口同时导出 PaymentRequired、PaymentOffer、PaymentPayload、PaymentReceipt、RefundReceipt、Eip712TypedData、PayOptions、PayResult、WalletSigner、TxStatus 以及验证和恢复相关类型。