Concepts

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.
Order expiry	Per-order deadline (expiresAt) for Exchange Pay 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.
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, 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
• React — provider + hooks on top of a core client
• Formatters — display helpers from @swapped/connect-sdk/format (same APIs in both tracks)

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