integration-privy

Privy on Solana mobile

Privy owns the user: a durable account identifier and a JWT a backend can verify. Mobile
Wallet Adapter owns the keys. Privy signs nothing in this setup — every signature still
comes from the wallet app.

Sign-In-With-Solana joins the two. Privy generates a message, MWA signs it, Privy exchanges
the signature for a session.

Reach for this when an app needs a stable user record across devices, a server-verifiable
session, or login methods beyond a wallet. An app that only needs a connected address does not
need Privy — use the solana-mobile-wallet skill alone.

Android only, and a development build only. MWA has no iOS support and does not run in
Expo Go, which caps the whole integration.

Before you start

Requirement	Where it comes from
A working useMobileWallet()	solana-mobile-wallet skill
A development build on Android	solana-mobile skill
A Privy app ID and client ID	The Privy dashboard — step 1

Step 1: create the Privy app

Do this first. Two of these values are compile-time environment variables, and one dashboard
toggle decides whether login works at all.

1. Sign in at https://dashboard.privy.io and click New app on the organization overview
2. Name it, select Mobile app, create it, and save the App ID
3. Under User management > Authentication, in the External wallets card, enable
   SVM (Solana) wallets
4. Under App settings > Clients, set the app identifier to the expo.android.package
   value from app.json, and save the Client ID

The SVM wallets toggle is the one that is easy to skip and expensive to debug — while it is
off, login rejects every SIWS attempt even though the wallet signed correctly. The app
identifier matters because Privy checks the calling app's package name against the client.

EXPO_PUBLIC_PRIVY_APP_ID=your-privy-app-id
EXPO_PUBLIC_PRIVY_CLIENT_ID=your-privy-client-id

Both are public client-side identifiers, so EXPO_PUBLIC_ is correct. The Privy app secret
never belongs in a mobile app — anything prefixed EXPO_PUBLIC_ is readable in the shipped
bundle. The secret is for server code only.

Step 2: install and configure

npx expo install @privy-io/expo @privy-io/expo-native-extensions

@privy-io/expo carries a long peer dependency list that shifts between releases — passkeys,
secure store, web browser, crypto, viem. Install what the version you picked asks for rather
than copying a list from anywhere, including from here.

Three pieces of native wiring are required, and the SDK fails in a different place for each:

• Crypto and text-encoding polyfills, loaded from the entry module before anything else
• expo-secure-store and expo-web-browser in app.json plugins
• A Metro resolver override so jose resolves to its browser build

Full contents for each, and how to confirm they took: references/setup.md.
Rebuild natively (npx expo run:android) after this step — a JS reload will not pick up the
new native modules.

Step 3: mount the providers

import { PrivyProvider } from '@privy-io/expo'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { type AppIdentity, createSolanaDevnet, MobileWalletProvider } from '@wallet-ui/react-native-kit'
import type { ReactNode } from 'react'

const cluster = createSolanaDevnet()
const identity: AppIdentity = { name: 'My App', uri: 'myapp://myapp' }
const privyAppId = process.env.EXPO_PUBLIC_PRIVY_APP_ID
const privyClientId = process.env.EXPO_PUBLIC_PRIVY_CLIENT_ID
const queryClient = new QueryClient()

export function AppProviders({ children }: { children: ReactNode }) {
  if (!privyAppId || !privyClientId) {
    throw new Error('Missing Privy environment variables')
  }

  return (
    <QueryClientProvider client={queryClient}>
      <PrivyProvider appId={privyAppId} clientId={privyClientId}>
        <MobileWalletProvider cluster={cluster} identity={identity}>
          {children}
        </MobileWalletProvider>
      </PrivyProvider>
    </QueryClientProvider>
  )
}

PrivyProvider and MobileWalletProvider do not depend on each other, so their relative
nesting is free — but both must sit above every screen, and QueryClientProvider above both
if the hooks below are queries and mutations.

Throwing on missing environment variables is deliberate. Undefined values reach Privy as a
malformed app ID and surface much later as an opaque initialization error.

clientId is typed optional in PrivyProviderProps, which is misleading here: Privy's mobile
documentation treats it as required, and the dashboard issues one per mobile client. Pass it.

Step 4: wait for isReady

usePrivy() returns state that is meaningless until the SDK finishes reading stored tokens:

Value	Type	Notes
isReady	boolean	Everything else is provisional until this is true
user	User | null	null when unauthenticated — not undefined
error	Error | null	Initialization failures, typically storage access
logout	() => Promise<void>	No-op when nobody is signed in
getAccessToken	() => Promise<string | null>	Call per request; never cache the result

const { error, isReady, user } = usePrivy()

if (!isReady) return <Loading />
if (error) return <ErrorCard message={error.message} />

Rendering a signed-out state while isReady is false makes an already-authenticated user
flash through a login screen on every cold start.

Step 5: sign in with SIWS

The whole integration is this one sequence: generate, sign, exchange.

import { useLoginWithSiws } from '@privy-io/expo'
import type { Address } from '@solana/kit'
import { useMutation } from '@tanstack/react-query'
import { fromUint8Array, useMobileWallet } from '@wallet-ui/react-native-kit'

const siwsDomain = 'myapp.com'
const siwsUri = 'myapp://privy-login'

export function usePrivySignInMutation(address: Address) {
  const { generateMessage, login } = useLoginWithSiws()
  const { signMessages } = useMobileWallet()

  return useMutation({
    mutationFn: async () => {
      const { message } = await generateMessage({
        from: { domain: siwsDomain, uri: siwsUri },
        wallet: { address: address.toString() },
      })

      const signedPayload = await signMessages(new TextEncoder().encode(message))

      await login({ message, signature: fromUint8Array(signedPayload) })
    },
  })
}

Call it only once a wallet is connected — useMobileWallet().account must be defined, since
signMessages triggers its own authorization otherwise.

Three encoding details decide whether this works:

1. Pass account.address, which is base58. account.addressBase64 also exists; it is
   MWA's wire format and Privy will not accept it. Privy's own recipe spends three lines
   converting base64 to base58 because it drives the raw protocol — @wallet-ui/react-native-kit
   has already done that conversion for you.
2. fromUint8Array produces base64, not base58. It is a re-export of js-base64. Privy
   wants the base64 string here; base58 fails verification.
3. Do not slice the bytes. signMessages resolves to MWA's signed payload, not a bare
   64-byte signature. Base64-encode it whole and hand it over — the template and Privy's
   recipe both do exactly this.

from.domain is an RFC 3986 authority: a bare host, no scheme and no path. from.uri is a
full URI and is normally your app's deep link. Keep both stable — they are embedded in the
signed message the user sees in their wallet.

Linking a wallet to an account that already exists, and verifying the session on a server:
references/siws.md.

Step 6: sign out of both

const { logout } = usePrivy()
const { disconnect } = useMobileWallet()

await logout()
await disconnect()

Doing one without the other leaves the app in a half-signed-out state. disconnect() alone
keeps a live Privy session with no wallet behind it; logout() alone leaves the wallet
authorized and re-signs in silently on the next attempt.

Which side owns what

Concern	Owner
Private keys and signing	The wallet app, over MWA
Connected address	useMobileWallet().account
User identity across devices	usePrivy().user
Server-verifiable session	usePrivy().getAccessToken()
Sending transactions	useMobileWallet().sendTransactions

There is no Privy signer in this setup. A user is signed in to Privy and connected over MWA as
two independent facts, and the UI has to handle every combination — most usefully "connected
but not signed in", which is where the sign-in button belongs.

Reference material

• references/setup.md — polyfills, Metro config, app.json plugins,
  environment variables, and how to verify each one landed
• references/siws.md — the SIWS exchange in depth, linking additional
  wallets, server-side token verification, and the raw-protocol variant without Wallet UI
• references/troubleshooting.md — Privy-specific failures and
  their causes

The patterns here follow
expo-kit-privy,
a complete working app. Read it when this file is ambiguous:

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

Related skills

• solana-mobile-wallet — MWA connection, signing, and sending, which this builds on
• solana-mobile — development builds, emulators, toolchain checks
• seeker-genesis-token — SIWS verified server-side without Privy, when a JWT is overkill

Links

• Privy Solana MWA recipe: https://docs.privy.io/recipes/solana/adding-solana-mwa
• Privy Expo SIWS login: https://docs.privy.io/guide/expo/authentication/siws
• Privy dashboard: https://dashboard.privy.io