react-native-solana-mobile-wallet-adapter

Unified cross-platform Solana wallet adapter for React Native and Expo.

• Android: Mobile Wallet Adapter (MWA) 2.0 protocol
• iOS: Phantom/Solflare deeplinks with encrypted sessions

Features

• ✅ Unified API for both iOS and Android
• ✅ Session persistence across app restarts
• ✅ Multiple wallet support (Phantom, Solflare, Backpack)
• ✅ Sign transactions, messages, and more
• ✅ Works with Expo Router
• ✅ TypeScript support

Installation

# Install the package
npm install react-native-solana-mobile-wallet-adapter

# Install required peer dependencies
npm install expo-linking expo-secure-store @solana/web3.js

# Android only - install MWA protocol (optional if iOS-only)
npm install @solana-mobile/mobile-wallet-adapter-protocol-web3js

Quick Start

import { transact, isConnected, getConnectedAddress } from 'react-native-solana-mobile-wallet-adapter';

// Connect to wallet
const result = await transact(async (wallet) => {
  const auth = await wallet.authorize({
    cluster: 'mainnet-beta',
    identity: {
      name: 'My App',
      uri: 'https://myapp.com',
      icon: 'favicon.ico',
    },
  });
  
  return auth.accounts[0].address;
});

// Check connection status
if (isConnected()) {
  console.log('Connected to:', getConnectedAddress());
}

App Configuration

Expo (app.json / app.config.ts)

{
  "expo": {
    "scheme": "myapp",
    "ios": {
      "infoPlist": {
        "LSApplicationQueriesSchemes": ["phantom", "solflare", "backpack"]
      }
    }
  }
}

Important: The scheme is required for iOS deeplink callbacks.

React Native CLI (Info.plist)

<!-- Allow querying wallet apps -->
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>phantom</string>
  <string>solflare</string>
  <string>backpack</string>
</array>

<!-- Register your app's URL scheme -->
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

Import Options

Option 1: Auto-detect platform (recommended)

import { transact } from 'react-native-solana-mobile-wallet-adapter';

// Automatically uses iOS or Android implementation
await transact(async (wallet) => { /* ... */ });

Option 2: Platform-specific imports

// iOS
import { transact } from 'react-native-solana-mobile-wallet-adapter/ios';

// Android  
import { transact } from 'react-native-solana-mobile-wallet-adapter/android';

Option 3: Explicit platform config

import { transact } from 'react-native-solana-mobile-wallet-adapter';
import { Platform } from 'react-native';

await transact(callback, { platform: Platform.OS as 'ios' | 'android' });

API Reference

transact<T>(callback, config?): Promise<T>

Opens a wallet session and executes the callback.

interface TransactConfig {
  platform?: 'ios' | 'android';       // Explicit platform
  wallet?: 'phantom' | 'solflare';    // iOS: wallet to use
  redirectScheme?: string;            // iOS: custom URL scheme
  walletUriBase?: string;             // Android: wallet URI base
}

MobileWallet Methods

authorize(params): Promise<AuthorizationResult>

const auth = await wallet.authorize({
  cluster: 'mainnet-beta',  // 'mainnet-beta' | 'devnet' | 'testnet'
  identity: {
    name: 'My App',
    uri: 'https://myapp.com',
    icon: 'favicon.ico',
  },
  authToken: previousToken,  // Optional: for re-authorization
});

// Returns:
// auth.accounts[0].address    - wallet address (string)
// auth.accounts[0].publicKey  - wallet public key (Uint8Array)
// auth.authToken              - session token

deauthorize(params): Promise<void>

await wallet.deauthorize({ authToken: auth.authToken });

signTransactions(params): Promise<Transaction[]>

const [signedTx] = await wallet.signTransactions({
  transactions: [transaction],
});

signMessages(params): Promise<Uint8Array[]>

const [signature] = await wallet.signMessages({
  addresses: [auth.accounts[0].address],
  payloads: [new TextEncoder().encode('Hello!')],
});

signAndSendTransactions(params): Promise<string[]> (Android only)

const signatures = await wallet.signAndSendTransactions({
  transactions: [tx],
  minContextSlot: slot,
});

Helper Functions

| Function | Description | |----------|-------------| | isConnected() | Returns true if there's an active session | | getConnectedAddress() | Returns the connected wallet address or null | | getConnectedWalletType() | Returns 'phantom' | 'solflare' | null (iOS only) | | disconnect() | Clears the session without calling the wallet | | getInstalledWallets() | Returns list of installed wallet apps (iOS) | | getSelectedWallet() | Returns the user's selected wallet (iOS) | | setSelectedWallet(wallet) | Sets the preferred wallet (iOS) | | handleRedirectUrl(url) | Handle deeplink callback (for Expo Router) |

Platform Differences

| Feature | Android (MWA) | iOS (Deeplinks) | |---------|---------------|-----------------| | signAndSendTransactions | ✅ | ❌ Deprecated | | Multiple wallet picker | ✅ System UI | Manual selection | | Background signing | ✅ | ❌ | | Session encryption | MWA protocol | X25519 |

Troubleshooting

"Could not detect platform" error

For local/linked packages, either:

1. Use platform-specific imports
2. Pass { platform: Platform.OS } in config
3. Configure Metro (see USAGE.md)

iOS wallet doesn't return to app

Ensure your scheme is configured in app.json and matches your deeplink setup.

Android wallet picker doesn't appear

Make sure @solana-mobile/mobile-wallet-adapter-protocol-web3js is installed.

Documentation

• 📖 USAGE.md - Complete integration guide with Expo Router
• 🔗 Solana Mobile Docs
• 👻 Phantom Deeplinks

License

MIT