Wallets (React)

Connect self-custodial wallets and deposit using hooks from @swapped/connect-sdk/react.

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

Prerequisites

1. Create a core client with a Swapped Connect sessionId (from your backend).
2. Call loadSession() and wrap your tree with SwappedConnectProvider.
3. Wrap wallet UI with WalletsProvider.

import { createSwappedConnectClient } from '@swapped/connect-sdk'
import {
  SwappedConnectProvider,
  WalletsProvider,
} from '@swapped/connect-sdk/react'

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

void client.loadSession()

function App() {
  return (
    <SwappedConnectProvider client={client}>
      <WalletsProvider>
        <WalletsFlow />
      </WalletsProvider>
    </SwappedConnectProvider>
  )
}

Available wallet → connect → walletId → transfer plan → submit

Flow overview

Step	What happens	Hook
1. Availability	Wallet payment methods + transports on this device	useAvailableWallets
2. Connect	Extension, WalletConnect, or open-in-wallet-app	Connect wallet / useWallet
3. Connections	Connected instances + active wallet	Connected wallets / useActiveWallet
4. Balances	Tokens (crypto + fiat)	useWalletBalances
5. Transfer plan	How this token reaches the session (direct / swap / bridge / unavailable)	Transfer plan
6. Amount + quote	Dual crypto/fiat input, min, quote	Amount & quote
7. Submit	Confirm in wallet; status; requires_retry	Submit (useWalletTransfer)
8. Done	Summary; restartSession()	useWalletCompletedTransactionSummary

Session must be loaded and active before submit. After a completed payment, call restartSession() before starting another one. Connected wallets persist across restartSession().

WalletsProvider tracks the active wallet and persists it in localStorage (survives refresh). A successful connect selects that instance; if the active wallet disconnects, the newest remaining connection is selected. Keep the selected token (and amount) in your own state.

usePrepareWalletTransfer({ enabled }) optionally warms swap/bridge currency lists when entering a wallets screen.

Term	Meaning
Available wallet	A payment-method wallet this device can connect. useAvailableWallets
Connection	One approved instance (walletId). Same brand can appear more than once. useWalletConnections
Active wallet	The selected walletId for UI. useActiveWallet
Transfer plan	How a token reaches the session (direct / swap / bridge / unavailable). Transfer plan

Walkthrough: Example.

Hooks

Full list: Wallets hooks. Use state hooks for UI and event hooks for side effects.

useAvailableWallets, useConnectWallet, useWallet, useWalletConnections, useActiveWallet, and the balance hooks require WalletsProvider. Transfer plan / quote / submit / summary hooks work under SwappedConnectProvider alone — but you still need a connected walletId. WalletsProvider is what tracks the active wallet and the connection list.