Mobile Wallet Adapter (MWA)
Connect React Native apps to mobile wallets for authorize and sign.
Recipe
npm install @solana-mobile/mobile-wallet-adapter-protocol-web3js
# Prefer kit-compatible MWA bindings in new apps alongside @solana/kit@7.0.0When to reach for this:
- Android React Native / Expo Solana dApps.
- Seeker and Saga device targets.
- Any mobile flow needing external wallet app.
Working Example
import { transact } from "@solana-mobile/mobile-wallet-adapter-protocol-web3js";
async function connectMobileWallet() {
await transact(async (wallet) => {
const auth = await wallet.authorize({
cluster: "devnet",
identity: { name: "My dApp", uri: "https://example.com", icon: "favicon.ico" },
});
console.log("accounts", auth.accounts);
// sign transactions with wallet.signTransactions during same session
});
}What this demonstrates:
transactscopes wallet session to callback.- Identity metadata shown in wallet approval UI.
- Cluster must match RPC endpoint in app.
Deep Dive
How It Works
- Android intents launch wallet app and return results.
- Session authorization can persist across transact calls with stored auth token.
- iOS support evolves - check Solana Mobile docs for current status.
- Pair with kit transaction bytes for signing.
Gotchas
- Emulator-only testing - intents break subtly. Fix: physical device lab.
- Missing identity fields - wallet rejects authorize. Fix: complete name/uri/icon.
- Cluster mismatch - simulation errors. Fix: devnet everywhere in dev.
- Long transact callback - wallet timeout. Fix: minimize work inside session.
- Assuming extension APIs - MWA is not window.solana.
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
| In-app embedded wallet | Consumer onboarding | External wallet power users |
| Mobile web + wallet deep link | No app install | Native performance needs |
FAQs
App Router?
Providers in client layout.tsx; pages mix server + client components.
Secrets?
Server env only for keypairs; NEXT_PUBLIC_ for RPC URLs.
kit 7.0.0?
All examples use @solana/kit, not web3.js v1.
Wallet?
Signing only in client components.
Caching?
Revalidate on-chain reads carefully - chain is source of truth.
Actions?
HTTPS endpoints returning Solana Actions JSON.
Mobile?
Separate React Native app with MWA.
Testing?
Surfpool for integration; mock RPC in unit tests.
Mainnet?
Separate env files and program IDs.
Errors?
Decode simulation logs for user-facing messages.
Related
- Building a Mobile dApp - Expo setup
- Wallet Basics - concepts
- Deep Links & Session Handling - intents
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.