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.

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.

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.

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.

Wallet Integration Best Practices

FAQs

Related

Search Documentation

Wallet Integration Best Practices

FAQs

Related