API reference
Exact public entry points, runtime boundaries, amount conventions, return evidence, and failure behavior for x402-paysdk.
All public TypeScript APIs ship in one x402-paysdk release.
Shellnpm install x402-paysdk
Entry points
| Import | Runtime | Reference |
|---|---|---|
x402-paysdk/pay | Browser, app, wallet host | Payer API |
x402-paysdk/receive | Receiver app or trusted tool | Receiver API |
x402-paysdk/merchant | Backend only | Merchant API |
The package has no catch-all root export. Explicit subpaths make trust-boundary mistakes visible in imports and code review.
Shared conventions
Amounts
Amounts are positive decimal strings in the token's atomic unit. USDC uses six decimals: 1000000 is 1 USDC. Never pass JavaScript floating-point token values.
Gateway origins
Production gateways must use canonical HTTPS origins without credentials, path, query, or fragment. Local HTTP is accepted only for localhost development.
Identifiers
refId, paymentId, invoiceId, orderId, and cursors are bounded public identifiers. Do not put PII, secrets, or unbounded text in them.
Errors
Input and protocol failures reject with Error. HTTP error messages include the gateway error code when available, including invalid_request, unauthorized, ref_expired, ref_revoked, payment_verification_failed, settlement_failed, receipt_invalid, rpc_unavailable, and rate_limited.
Finality
pay() returning status: "settled" means the gateway returned a successful settlement transaction. Merchant fulfillment should still use verifyReceipt() or getTxStatus() with an explicit confirmation policy.
HTTP API
SDK methods map to the gateway's versioned HTTP surface. See the Gateway HTTP API for routes, auth, x402 headers, query bounds, and recovery behavior.