Wallet verification

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

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. There is no sessionId and no HMAC. React apps can use the same factory, or the hooks in Wallet verification (React).

Pick a path

The address lives in…	Use
A self-custodial wallet (MetaMask, Phantom, Trust, …)	client.wallets - user connects and signs
Coinbase.com	client.coinbase - 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.

You do not build the message the wallet signs. The server issues a challenge; verify() signs it as returned.

Prerequisites

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

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

const client = createWalletVerification({
  apiKey: 'your-public-api-key',
  environment: 'staging', // omit or 'production' for live
})

Reuse this instance for the life of the verification UI. Call destroy() on teardown. Do not reuse a Connect client.wallets or client.coinbase here - those require a session.

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	Module	What the user does
signature	client.wallets	Connect a self-custodial wallet and sign a challenge
exchange_oauth	client.coinbase	Sign in to Coinbase so Swapped can confirm the address

satoshi is reserved and not available in this client.

Flow overview

Step	What happens	Docs
1. Create client	Public apiKey, optional environment	Client
2. Pick a path	Signature wallet, or Coinbase	above
3a. Signature	List wallets → verify() or prepareVerify() → 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.

Methods by topic

Topic	Methods
Client	createWalletVerification, destroy
Availability	wallets.getAvailable, requiresDeepLink, supportsWalletConnect
Verify wallet	wallets.prepareVerify, wallets.verify, connect, getConnections, cancelPairing
Coinbase	coinbase.startVerification, openVerificationTab, completeVerification, cancelVerification
Result	Returned WalletVerification and statuses
Errors	How failures surface and what to do

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