Wallets (Core)

Connect self-custodial wallets and deposit with client.wallets and client.wallets.transfer.

Wallets is a separate flow from Exchange Pay, Cash App, and Coinbase OAuth. Route to it when the payment method has type: wallet (see Payment methods).

Prerequisites

1. Create a client with a Swapped Connect sessionId (from your backend).
2. Call loadSession() and confirm the session is active.
3. List available wallets before connecting.

import { createSwappedConnectClient } from '@swapped/connect-sdk'

const client = createSwappedConnectClient({
  sessionId: 'your-session-id',
})

await client.loadSession()

const available = await client.wallets.getAvailable()

createSwappedConnectClient accepts optional wallets.balancesCacheTtlMs (default 10 minutes). A manual refresh always loads fresh balances.

Available wallet → connect → walletId → transfer plan → submit

Flow overview

Step	What happens	Docs
1. Availability	Pair payment methods with transports on this device	Availability
2. Connect	Extension, WalletConnect, or open-in-wallet-app	Connect wallet
3. Connections	Read connected instances (walletId)	Connected wallets
4. Balances	Load tokens (crypto + fiat) for a walletId	Balances
5. Transfer plan	How this token reaches the session (direct / swap / bridge / unavailable)	Transfer plan
6. Amount + quote	Min, validation, crypto/fiat, quote	Amount & quote
7. Submit	User confirms in the wallet; status stream	Submit
8. Done	Summary; restartSession() for another payment	Summary

The session must stay active before transfer.submit. After a completed payment, call restartSession() before starting another one. Connected wallets persist across restartSession().

Every Core action that touches a wallet takes a walletId - the connection instance, not the provider brand. In React, WalletsProvider tracks the active wallet.

Term	Meaning
Available wallet	A payment-method wallet this device can connect. Availability
Connection	One approved instance (walletId). Connected wallets
Transfer plan	How a token reaches the session (direct / swap / bridge / unavailable). Transfer plan

Step-by-step walkthrough: Example.

Methods by topic

Topic	Methods
Availability	getAvailable, watchAvailability, requiresDeepLink, supportsWalletConnect
Connect wallet	connect, cancelPairing, getDeepLinkUrl, openDeepLink
Connected wallets	getConnections, getConnection, getConnectionsByProvider, isConnected, getAddresses, getConnectionState, subscribe, disconnect, disconnectProvider, disconnectAll, reconnect
Balances	getBalances, getWalletBalance, getCachedBalances
Transfer plan	transfer.getPlanSync, transfer.getPlan, transfer.prefetchTransferCurrencies
Amount & quote	transfer.getMinAmount, transfer.validateAmount, transfer.getQuote
Submit	transfer.submit, transfer.retry
Summary	transfer.getCompletedTransactionSummary, ensureCompletedTransactionFees, ensureCompletedTransactionRates
Events	wallets:connected, wallets:pairingUri, wallets:transferStatus, …
Errors	How failures surface

Advanced wallet APIs

Not part of the deposit flow - prefer transfer.submit for sending.

Method	Purpose
signMessage({ walletId, message, namespace? })	Sign a message
sendTransaction({ walletId, chainId, to, amount, tokenAddress?, … })	Low-level send (human-readable amount)
switchChain(walletId, chainId)	Switch the active EVM chain for a connection