Wallet verification

Prove that a user controls a wallet address with hooks from @swapped/connect-sdk/wallet-verification/react.

Typical use: confirm the user owns an address they submitted (for example a ramp destination) before you treat it as theirs.

This is a standalone product. It is not checkout, not a Connect session, and not a module on createSwappedConnectClient. Do not wrap this UI in SwappedConnectProvider - use WalletVerificationProvider.

Pick a path

The address lives in…	Hook
A self-custodial wallet (MetaMask, Phantom, Trust, …)	useVerifyWallet - user connects and signs
Coinbase.com	useCoinbaseVerification - user signs in to Coinbase

Signature today: EVM and Solana. Bitcoin self-custodial is not available yet. Coinbase OAuth can still verify a Bitcoin address that lives on Coinbase.

Prerequisites

1. A public session API key from Swapped (the same style of key you already use with Connect).
2. Mount the provider in the browser. Creating a client throws BROWSER_REQUIRED on the server (Node.js, SSR, RSC). In Next.js, mount this tree in a client component ('use client').
3. If your site sends a Content-Security-Policy, allow the hidden gateway iframe and API WebSocket - see Browser requirements.

import { WalletVerificationProvider } from '@swapped/connect-sdk/wallet-verification/react'

function App() {
  return (
    <WalletVerificationProvider
      apiKey="your-public-api-key"
      environment="staging"
      customerId="user-1234"
    >
      <VerifyPage />
    </WalletVerificationProvider>
  )
}

Or pass a client you created with createWalletVerification from @swapped/connect-sdk/wallet-verification. See WalletVerificationProvider.

How it works

You ask the user to prove control of customerId + address.

• customerId is your id for the end user (account id, user uuid - not a Swapped id).
• address is the wallet address they claim to control.

That pair is the reuse key. If it is already verified, the next start returns status: 'verified' immediately - skip the wallet prompt or Coinbase login.

Method	Hook	What the user does
signature	useVerifyWallet	Connect a self-custodial wallet and sign a challenge
exchange_oauth	useCoinbaseVerification	Sign in to Coinbase so Swapped can confirm the address

satoshi is reserved and not available in this client.

The provider owns customerId, network, address, the selected wallet, and the last result. Changing those props updates provider state; the next verify() / Coinbase start uses the latest values. Setters throw WALLET_VERIFICATION_IN_PROGRESS while a run is in flight.

Flow overview

Step	What happens	Docs
1. Wrap the tree	WalletVerificationProvider with apiKey or a client	Provider
2. Pick a path	Signature wallet, or Coinbase	above
3a. Signature	List wallets → prepare() / verify() → user connects and signs	Availability, Verify wallet
3b. Coinbase	startVerification() → new tab or same-tab redirect	Coinbase
4. Result	Read status on the returned record	Result

Walkthroughs: Wallets, Coinbase.

Hooks by topic

Topic	Hooks
Provider	WalletVerificationProvider, useWalletVerificationClient, useWalletVerification
Availability	useAvailableVerificationWallets, useWalletVerificationConnections
Verify wallet	useVerifyWallet
Coinbase	useCoinbaseVerification
Result	Returned WalletVerification and statuses
Errors	How failures surface and what to do

Only one verify or Coinbase verification may run on this client at a time (WALLET_VERIFICATION_IN_PROGRESS).