Wallet Integration Best Practices
25 practices for secure, resilient wallet UX.
-
Lazy-connect: Prompt wallet only when user initiates a signing action (Wallet Basics).
-
Show cluster badge: Devnet vs mainnet must be obvious in the header.
-
Validate RPC and wallet network match: Mismatch causes opaque simulation failures.
-
Use Wallet Standard discovery: Support multiple wallets - never hardcode one brand.
-
Client-only providers: Wrap wallet providers in
"use client"Next.js boundaries. -
Reset app state on disconnect: Clear caches keyed by pubkey.
-
Simulate before sign: Reduce failed approvals and fee waste.
-
Handle rejection copy: Users cancel - show friendly retry, not errors.
-
Disable double-submit: Debounce send buttons during confirmation.
-
Expose disconnect: Always visible account menu action.
-
autoConnect with loading UI: Avoid flash of disconnected content (Autoconnect & Session UX).
-
Never store secrets in localStorage: Only public keys and preferences.
-
SIWS with domain binding: Off-chain auth messages must include origin and expiry.
-
Verify signatures server-side: ed25519 check before issuing sessions.
-
Hardware wallet timeouts: Longer than software wallet defaults.
-
Test Phantom and Solflare: Two adapters minimum in QA.
-
Mobile MWA on real devices: Emulators miss intent edge cases.
-
Truncate addresses: Show first/last four chars - copy button for full.
-
Log adapter name in support tooling: Helps reproduce wallet-specific bugs.
-
Keep adapter + kit versions aligned: Follow create-solana-dapp lockfile.
-
Do not block read-only content: RPC reads work without connect.
-
Transaction previews: Summarize token deltas when possible.
-
Priority fees on mainnet: User txs need compute budget during congestion.
-
Accessible modals: Focus trap and keyboard navigation for connect UI.
-
Document wallet requirements: Help page listing supported wallets and browsers.
FAQs
wallet-adapter vs wallet-ui?
wallet-ui for new templates; wallet-adapter still widely used.
autoConnect default?
Yes for consumer apps with loading gate; no for high-security admin.
Ledger without adapter?
Users still connect through a broker wallet app.
Related
- Wallet Basics - intro examples
- @solana/kit Best Practices - client layer
- Transaction UX - confirmations
Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.