Connected wallets

A connection is one approved wallet instance after the user has connected — not a row in the availability list. Opening a wallet is Connect wallet (connect). This page is the list that remains afterward.

The SDK holds any number of connections at once, keyed by walletId. Core methods take walletId on each call (getWalletBalance, transfer.getPlan, disconnect, …). In React, WalletsProvider tracks the active wallet for UI.

walletId identifies one connect action (one injected instance, or one WalletConnect session). The same provider can appear more than once (extension + a WalletConnect pairing, or two WalletConnect sessions).

Read

Method	Returns
getConnections({ sort? })	All connections. sort: 'connectedAt' (newest first) or 'balanceDesc' (highest USD total first; uses cached balances)
getConnection(walletId)	One connection, or null
getConnectionsByProvider(provider)	Every instance of that payment-method provider
isConnected(provider)	true if any instance of that provider is connected
getAddresses()	Flattened { address, chainId, walletId }[]
getConnectionState()	{ connections, connectingProviders, errors, isRestoring, pairingUri, pairingDeeplinkUrl }
subscribe(listener)	Fires on connection-state changes; returns unsubscribe

const connections = client.wallets.getConnections({ sort: 'connectedAt' });

const off = client.wallets.subscribe(state => {
  state.connections;
  state.isRestoring;
  state.pairingUri;
  state.pairingDeeplinkUrl;
  state.connectingProviders;
  state.errors;
});

getConnectionState() fields:

Field	Meaning
connections	Current WalletConnection[]
connectingProviders	Providers with an in-flight connect
errors	Last error keyed by provider or walletId
isRestoring	Previous connections still rehydrating. Addresses may already exist; sign / send wait for status === 'connected'
pairingUri	Current WalletConnect URI (QR / copy), or null
pairingDeeplinkUrl	Same pairing as a mobile deep link, or null

sortWalletConnections(connections, sort, balances) is also exported if you sort a list yourself.

WalletConnection

Field	Meaning
walletId	Instance id for later calls
provider	IntegrationProvider, or null if WalletConnect paired a wallet that is not in the SDK registry
transport	'injected' or 'walletconnect'
name / icon	Display
namespaces	Per-namespace slices (eip155 / solana / bip122) with accounts and activeChainId
accounts	Flattened accounts across namespaces
connectedAt	Timestamp
isRestored	true when restored on load rather than freshly approved
status	'connected' | 'checking' | 'needsReconnect'. Sign / send require 'connected'
sessionTopic?	WalletConnect session topic
expiresAt?	WalletConnect session expiry
requiresPopup?	Injected privileged actions for this connection run in a popup

Restore

On client start the SDK restores previous connections. getConnectionState().isRestoring is true until that finishes. wallets:restored fires with the restored list.

Balances can be fetched from last-known addresses while restore is still running. Sign / send use status === 'connected'.

client.on('wallets:restored', ({ connections }) => {
  // restore finished
});

const next = await client.wallets.reconnect();
// `{ force: true }` re-prompts popup-routed injected connections

Disconnect

Method	Effect
disconnect(walletId)	One instance
disconnectProvider(provider)	Every instance of that provider (injected + all WalletConnect topics)
disconnectAll()	Every connection

await client.wallets.disconnect(walletId);
await client.wallets.disconnectProvider(IntegrationProvider.MetaMask);
await client.wallets.disconnectAll();

wallets:disconnected includes reason: 'user' | 'provider' | 'session_expired' | 'host'.

Connected wallets persist across restartSession().