Concepts

This SDK is browser only. Do not create a client or call SDK methods on the server (Node.js, SSR, RSC). createSwappedConnectClient throws BROWSER_REQUIRED if it is initialized outside the browser. Create a sessionId on your backend, then run this package in the browser. Strict Content-Security-Policy setups must allow the hidden gateway iframe (when wallets or coinbase is enabled) and API WebSocket - see Browser requirements.

Term	Meaning
Session	A Swapped Connect run identified by sessionId. Holds merchant config and payment state.
Payment method	A wallet or exchange option available for the session.
Wallets	Self-custodial connect + deposit (type: wallet). Extension, WalletConnect, or open-in-wallet-app; then direct / swap / bridge. Not Coinbase OAuth.
Available wallet	A payment-method wallet this device can connect. Not yet a connection.
Connection	One approved wallet instance (walletId). The same brand can appear more than once.
Transfer plan	How a connected token reaches the session deposit (direct / swap / bridge / unavailable).
Exchange Pay	Deposit through an exchange app (Binance Pay, etc.) via exchange_pay order + QR/checkout. Not Coinbase OAuth.
Cash App	Deposit with Cash App (type: cash_app) via order + Cash App URL / Lightning invoice. Not Exchange Pay.
Order expiry	Per-order deadline (expiresAt) for Exchange Pay and Cash App checkout. After it fires, create a new order.
Coinbase	Separate OAuth flow (exchange_oauth): connect Coinbase, then withdraw crypto to complete payment. Not Exchange Pay and not Coinbase Wallet.
Wallet verification	Standalone product (@swapped/connect-sdk/wallet-verification). Prove the user controls an address (wallet signature or Coinbase login). Not a Connect session.
Submission cooldown	Fixed SDK client-side wait (30s) after Coinbase startWithdrawal before another start is allowed. Does not block 2FA confirm.
Lifecycle event	Callbacks such as session:loaded, order updates, or errors.

Session lifecycle

1. Create a client with a sessionId.
2. loadSession().
3. Branch UI on session view (active, completed, expired, …) - see Session (React) or Session (Core).
4. Run a payment flow only while the view is active (payment methods → Wallets, Exchange Pay, Cash App, or Coinbase).
5. When the session is completed (or otherwise terminal), call restartSession() before another payment.
6. Call destroy() when tearing down.

Core vs React

Same package, two tracks:

• Core - createSwappedConnectClient and modules (Client)
• React - provider + hooks on top of a core client (Client)
• Formatters - display helpers from @swapped/connect-sdk/format (same APIs in both tracks)

Use the sidebar toggle (or top nav) to switch tracks.