Payer API

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

This entry point is safe for payer-facing runtimes. It never receives a private key; it calls the host's WalletSigner only after validating payment requirements and signed offer context.

Core payment functions

Function	Signature	Purpose
getPaymentRequired	(refUrl: string, amount?: string) => Promise<PaymentRequired>	Resolve a ref and validate the 402 Payment Required response without signing
pay	(options: PayOptions) => Promise<PayResult>	Negotiate, verify offer, sign EIP-3009, submit, and return settlement evidence
prepareEip3009TypedData	(required: PaymentRequired, payer: string) => Eip712TypedData	Build bounded TransferWithAuthorization typed data
toReceiveUrl	(refUrl: string) => URL	Convert x402pay:// transport form into the gateway receive URL
decodePaymentRequired	(encoded: string) => PaymentRequired	Decode a payment-required header value

pay(options)

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

Option	Required	Behavior
refUrl	Yes	x402pay:// reference or supported receive URL
wallet	Yes	Host adapter with address and signTypedData
paymentId	No	Idempotency id; defaults to invoice id or a random public id
amount	For open refs	Atomic amount applied to the receive URL
trustedOfferSigners	No	Explicit gateway signer allowlist; otherwise same-origin DID discovery is used
requireSignedOffer	No	Defaults to true; disable only in controlled development
fetch	No	Custom bounded/test transport implementation

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

The returned signature must be a 65-byte EVM signature. The SDK builds the nonce and valid time window; wallet code should not mutate the typed data.

Return value

TypeScript
1interface PayResult {2  txHash: string;3  payTo: string;4  amount: string;5  network: string;6  payer: string;7  receiptStatus: string;8  signedPaymentReceipt?: string;9  receipt?: PaymentReceipt;10  status: 'settled';11}

The signed receipt and receipt JSON form a pair. Archive both without modifying fields.

Offer trust and gateway DID

Function	Purpose
verifySignedOffer(required, options)	Verify signed offer presence, context, signature, signer trust, payment id, and expiry
fetchGatewayDidDocument(gateway, options?)	Load and validate /.well-known/did.json with a 16 KiB default limit
discoverGatewayDidSigners(gateway, options?)	Return trusted assertion signers from the same-origin DID document
gatewayDidSigners(document, gateway, options?)	Validate an already loaded DID document
didWebIdFromGateway(gateway)	Derive the expected did:web identifier from an origin

VerifySignedOfferResult exposes present, verified, trusted, signer, kid, and the parsed offer. Verification fails closed when an expected origin, payment id, signer, or context differs.

Receipt APIs

Function	Network call	Purpose
verifySignedPaymentReceipt(options)	No	Verify envelope signature, content hash, expected fields, and optional signer allowlist
verifyReceipt(options)	Yes	Call /verify-receipt and verify chain status plus expected amount/payTo
paymentReceiptContentHash(receipt)	No	Produce the canonical sha256: payment receipt reference
verifySignedRefundReceipt(options)	No	Verify a refund receipt signature and expected refund context
verifyRefundReceipt(options)	Yes	Verify refund receipt and reverse transfer on-chain
refundReceiptContentHash(receipt)	No	Produce the canonical refund receipt hash

TypeScript
1const result = await verifyReceipt({2  gateway: 'https://pay.example.com',3  signedReceipt,4  receipt,5  expectedPayTo,6  expectedAmount,7  minConfirmations: 38});

The result separates valid from confirmed. A valid signed receipt can still be below the required confirmation policy.

Recovery and chain queries

Function	Signature	Notes
recoverSettlement	(options: RecoverSettlementOptions) => Promise<RecoverSettlementResult>	Reconstruct a known settlement without calling settle again
getTxStatus	(gateway: string, txHash: string) => Promise<TxStatus>	Validate tx hash and query bounded chain status
getPaymentHistory	(gateway: string, options: PaymentHistoryOptions) => Promise<PaymentHistoryResult>	Query bounded USDC Transfer logs

getPaymentHistory requires payTo, from, or a cursor. Options include asset, fromBlock, limit, and cursor.

Exported types

The entry point exports payment and receipt models including PaymentRequired, PaymentOffer, PaymentPayload, PaymentReceipt, RefundReceipt, Eip712TypedData, PayOptions, PayResult, WalletSigner, TxStatus, PaymentHistoryOptions, and the verification/recovery option and result types.