solana-mobile-wallet

Solana wallets on mobile

Wallet connection and transaction signing through Mobile Wallet Adapter (MWA), wrapped by @wallet-ui/react-native-kit (or @wallet-ui/react-native-web3js on the legacy stack).

MWA requires a development build on Android. Expo Go will not work. If the project has no development build yet, or does not exist, start with the solana-mobile skill.

Step 1: pick the stack — do this before writing any code

Write kit code. @solana/kit with @wallet-ui/react-native-kit is the stack to reach for, and everything in this file describes it.

There is exactly one reason to write @solana/web3.js instead: the project already runs on it. Check package.json first.

Do not introduce web3.js into a kit project, or mix the two in one app. Their provider props, hook return values, and transaction construction all differ, so code from one silently fails on the other. If a project has no Solana client at all, that is a new build — use kit.

Adding a new wallet feature to an existing web3.js app is not a reason to migrate mid-task. Match what is there, and mention migration as a follow-up if it seems worth it.

Step 2: confirm the provider is mounted

useMobileWallet returns empty state without MobileWalletProvider above it. Look for it in the root layout or an app-providers module.

Build the cluster with the createSolana* helpers rather than by hand — a SolanaCluster also needs a label, which the helpers fill in:

import {
  type AppIdentity,
  createSolanaDevnet,
  MobileWalletProvider,
  type SolanaCluster,
} from '@wallet-ui/react-native-kit'

const identity: AppIdentity = { name: 'My App' }
const cluster: SolanaCluster = createSolanaDevnet({ url: 'https://api.devnet.solana.com' })

<MobileWalletProvider cluster={cluster} identity={identity}>
  {children}
</MobileWalletProvider>

createSolanaDevnet, createSolanaTestnet, and createSolanaLocalnet take optional props; createSolanaMainnet requires a url, since there is no sensible public default for mainnet.

The provider props are cluster, identity, and optional cache, createClient, children. There is no `chain` prop and no `endpoint` prop — passing those does nothing.

Every AppIdentity field is optional. name alone is enough to get started; add uri as a real deep link for anything shipping, since wallets display it during authorization and a placeholder can read as a phishing attempt.

Put QueryClientProvider from @tanstack/react-query above the wallet provider — the hook patterns below are queries and mutations.

Step 3: use the hook

import { useMobileWallet } from '@wallet-ui/react-native-kit'

const { account, connect, disconnect, client } = useMobileWallet()

What the hook actually returns on the kit stack:

Singular aliases exist for several of these — sendTransaction, signMessage, signTransactions — with the same signatures. The templates use the plural forms; either works, so follow whatever the project already uses.

Four things that trip people up:

1. There is no `connected` boolean. Derive it: const connected = !!account.
2. `signAndSendTransaction` takes `minContextSlot` as a second argument. Calling it with

only a transaction fails. Get the slot from getLatestBlockhash, or use sendTransactions(instructions), which handles this for you.

1. The kit hook exposes `client`, not `connection`. connection only exists on the

web3.js stack.

1. Include `chain` in every React Query key that holds chain data. Otherwise switching

cluster serves the previous network's cached balances, which looks like a wallet bug.

account.address is a kit Address (a branded string), so it interpolates into text directly. account.label is the wallet-supplied name and may be undefined.

Connect and disconnect

import { Pressable, Text } from 'react-native'
import { useMobileWallet } from '@wallet-ui/react-native-kit'

export function ConnectButton() {
  const { account, connect, disconnect } = useMobileWallet()

  async function onPress() {
    try {
      if (account) await disconnect()
      else await connect()
    } catch (error) {
      // The user dismissing the wallet picker lands here. Do not treat it as a crash.
      console.error(error)
    }
  }

  return (
    <Pressable onPress={onPress}>
      <Text>{account ? 'Disconnect' : 'Connect Wallet'}</Text>
    </Pressable>
  )
}

Always wrap connect() in try/catch — cancelling the wallet picker rejects the promise. Cancellation is a normal outcome, not an error state worth alarming the user about; see references/kit.md for how to tell cancellation apart from real failures.

Authorization is cached, so the app reconnects on restart without a new prompt.

Read chain data

Use client from the hook. There is no need to build a client of your own:

import type { Address } from '@solana/kit'
import { useQuery } from '@tanstack/react-query'
import { useMobileWallet } from '@wallet-ui/react-native-kit'

export function useGetBalance({ address }: { address: Address }) {
  const { chain, client } = useMobileWallet()

  return useQuery({
    queryFn: () => client.rpc.getBalance(address).send(),
    queryKey: ['get-balance', chain, address],
  })
}

Kit RPC calls are lazy: client.rpc.someMethod(...) builds a request and .send() runs it. Forget .send() and nothing errors — the data simply never arrives.

Balances come back as bigint lamports. Convert deliberately, and never with parseFloat:

export function lamportsToSol(lamports: bigint) {
  return Number(lamports) / 1e9
}

Send a transaction

Build instructions and hand them over. This covers most cases:

import { getAddMemoInstruction } from '@solana-program/memo'
import type { Instruction } from '@solana/kit'

const { sendTransactions } = useMobileWallet()

const instructions: Instruction[] = [getAddMemoInstruction({ memo: 'gm' })]
const signature = await sendTransactions(instructions)

sendTransactions handles blockhash, minContextSlot, fee payer, and signature decoding. It returns as soon as the wallet has submitted, so confirm the signature before treating the transaction as done — references/kit.md has the helper.

Reach for the explicit pipe form only when you need fee-payer control, a specific blockhash lifetime, or a fee pre-check. Full worked example, with the balance-versus-fee assertion and signature decoding: references/kit.md.

Reference material

• references/kit.md — kit stack: clusters and config, reading chain data,

transactions, sign-in with Solana, message signing, error handling

• references/web3js.md — legacy @solana/web3.js stack, and a migration

sketch

• references/troubleshooting.md — connection and signing

failures with known causes

When something here is ambiguous, read the template. The patterns in this skill follow `expo-kit-minimal`, which is a complete working app and stays current in a way prose does not:

npx solana-mobile@latest create /tmp/reference-app --template expo-kit-minimal --skip-install

Related skills

• solana-mobile — project setup, templates, emulators, development builds
• integration-privy — add Privy accounts and sessions on top of this wallet connection
• seeker-genesis-token — verify Seeker device ownership after connecting
• seeker-domains — display .skr names instead of raw addresses

Links

• Wallet UI: https://wallet-ui.dev
• MWA docs: https://docs.solanamobile.com/react-native/overview
• Solana Kit: https://www.solanakit.com