OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add solana-mobile/solana-mobile-skills --skill integration-privy
Add Privy authentication to a Solana Expo Android app on top of Mobile Wallet Adapter, using Sign-In-With-Solana. Use when installing @privy-io/expo, mounting PrivyProvider, logging a user in with useLoginWithSiws, linking a wallet to an existing Privy account, reading the Privy access token from a backend, or debugging a Privy plus MWA setup.
npx skills add solana-mobile/solana-mobile-skills --skill integration-privy
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.
| 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 |
Do this first. Two of these values are compile-time environment variables, and one dashboard toggle decides whether login works at all.
expo.android.package
value from app.json, and save the Client IDThe 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.
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.
@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:
expo-secure-store and expo-web-browser in app.json pluginsjose resolves to its browser buildFull 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.
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.
isReadyusePrivy() 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 |
Rendering a signed-out state while isReady is false makes an already-authenticated user
flash through a login screen on every cold start.
The whole integration is this one sequence: generate, sign, exchange.
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:
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.fromUint8Array produces base64, not base58. It is a re-export of js-base64. Privy
wants the base64 string here; base58 fails verification.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.
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.
| 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.
app.json plugins,
environment variables, and how to verify each one landedThe patterns here follow
expo-kit-privy,
a complete working app. Read it when this file is ambiguous:
solana-mobile-wallet — MWA connection, signing, and sending, which this builds onsolana-mobile — development builds, emulators, toolchain checksseeker-genesis-token — SIWS verified server-side without Privy, when a JWT is overkillimport { 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>
)
}const { error, isReady, user } = usePrivy()
if (!isReady) return <Loading />
if (error) return <ErrorCard message={error.message} />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) })
},
})
}const { logout } = usePrivy()
const { disconnect } = useMobileWallet()
await logout()
await disconnect()npx solana-mobile@latest create /tmp/reference-app --template expo-kit-privy --skip-install