Skip to main content

​
Installation

Sovran is available for iOS and Android. Follow the instructions below to install on your device.

​
Requirements

​
iOS

  • iOS 13.0 or later
  • iPhone only (iPad not supported)
  • Camera permission for QR code scanning
  • Optional: NFC-capable device for tap-to-pay payments

​
Android

  • Android 5.0 (API level 21) or later
  • Camera permission for QR code scanning
  • Optional: NFC support for contactless payments

​
Download

iOS App Store

Download for iPhone

Android Play Store

Download for Android
Sovran is currently in active development. Check the GitHub repository for the latest release information and beta builds.

​
iOS Installation

​
From App Store

1

Open App Store

Navigate to the App Store on your iOS device.
2

Search for Sovran

Search for “Sovran Bitcoin Wallet” or use the direct link above.
3

Download and Install

Tap Get to download and install. You may need to authenticate with Face ID, Touch ID, or your Apple ID password.
4

Grant Permissions

On first launch, Sovran will request:
  • Camera: Required for scanning QR codes for payments
  • Photo Library (optional): To import QR codes from images
  • Location (optional): For BTCMap merchant discovery and transaction location stamps
  • Motion (optional): For parallax visual effects
  • NFC (optional): For contactless tap-to-pay
// From app.json — iOS permissions
{
  "NSCameraUsageDescription": "Sovran uses your camera to scan QR codes for payments",
  "NSPhotoLibraryUsageDescription": "Choose images with QR codes to scan",
  "NSLocationWhenInUseUsageDescription": "Show nearby merchants and add location to transactions",
  "NSMotionUsageDescription": "Create subtle parallax and visual effects",
  "NFCReaderUsageDescription": "Send and receive contactless payments"
}

​
Development Build (TestFlight)

For beta testing or development builds: 
# Build iOS for development using EAS
yarn build:dev:ios

# Submit to App Store
yarn submit:ios
Development builds are not available in the App Store. Use EAS Build for internal testing or TestFlight distribution.

​
Android Installation

​
From Play Store

1

Open Play Store

Navigate to Google Play Store on your Android device.
2

Search for Sovran

Search for “Sovran Bitcoin Wallet” or use the direct link above.
3

Install

Tap Install to download and install the app.
4

Grant Permissions

On first launch, grant the following permissions:
  • Camera: Required for QR code scanning
  • NFC (optional): For contactless payments
// From app.json — Android permissions
{
  "permissions": [
    "android.permission.CAMERA",
    "android.permission.RECORD_AUDIO",
    "android.permission.NFC"
  ]
}

​
APK Installation

For direct APK installation (advanced users): 
# Build Android APK for preview
yarn build:android:apk

# Submit to Play Store
yarn submit:android
Direct APK installation requires enabling “Install from Unknown Sources” in your Android settings. This is not recommended for most users.

​
Building from Source

Advanced users can build Sovran from source code.

​
Prerequisites

# Required tools
- Node.js 18 or later
- Yarn 1.22.22 or later
- Expo CLI
- Xcode (iOS) or Android Studio (Android)

​
Clone and Install

# Clone the repository
git clone https://github.com/SovranBitcoin/Sovran.git
cd Sovran

# Install dependencies
yarn install

# Apply patches
yarn postinstall

​
Development

# Start Expo development server
yarn start

# Run on iOS simulator
yarn ios

# Run on Android emulator
yarn android

# Run on physical device
yarn start:emulator:ios    # iOS
yarn start:emulator:android # Android

​
Code Quality Checks

Before committing, ensure all checks pass: 
# Run all checks
yarn lint          # ESLint
yarn type-check    # TypeScript
yarn pretty:check  # Prettier formatting
yarn knip          # Find unused exports/dependencies
yarn test          # Jest tests
All five checks must pass before any commit. See .cursor/rules/git-github-workflow.mdc for full git workflow requirements.

​
Production Builds

# Prebuild native projects
yarn prebuild

# Build for iOS (production)
yarn build:ios

# Build for Android (APK preview)
yarn build:android:apk

​
Configuration

​
App Metadata

From app.json: 
{
  "expo": {
    "name": "Sovran",
    "slug": "sovran",
    "version": "0.0.61",
    "scheme": ["sovran", "cashu"],
    "userInterfaceStyle": "dark",
    "ios": {
      "bundleIdentifier": "com.sovranbitcoin",
      "buildNumber": "1"
    },
    "android": {
      "package": "com.sovranbitcoin",
      "versionCode": 2
    }
  }
}
Sovran supports two URI schemes for deep linking:
  • sovran:// - Sovran-specific deep links
  • cashu:// - Cashu token standard
// File: hooks/useDeeplink.ts
// Processes cashu:// and sovran:// URLs
// Automatically routes to appropriate screen

​
Post-Installation

​
First Launch

On first launch, Sovran will:
  1. Generate a BIP-39 seed phrase
  2. Store it securely using expo-secure-store
  3. Derive Nostr keys via NIP-06
  4. Show terms and conditions
  5. Present onboarding carousel
// File: components/blocks/AppGate.tsx
// Gate order: Terms → Onboarding → Keys → App

​
Data Storage

Sovran stores data locally:
  • Secure Store: Seed phrase, Nostr private keys (encrypted)
  • AsyncStorage: Settings, preferences, transaction history
  • SQLite: Cashu proofs and wallet state (via coco-cashu-expo-sqlite)
// From package.json
{
  "dependencies": {
    "expo-secure-store": "~55.0.8",
    "@react-native-async-storage/async-storage": "2.2.0",
    "expo-sqlite": "~55.0.10",
    "coco-cashu-expo-sqlite": "1.1.2-rc.47"
  }
}
All data is stored locally on your device. Sovran does not transmit your seed phrase, private keys, or transaction data to any server.

​
Troubleshooting

​
iOS Installation Issues

Error: “Untrusted Developer” If installing a development build:
  1. Go to Settings → General → VPN & Device Management
  2. Trust the developer certificate
Camera Permission Denied
  1. Go to Settings → Sovran
  2. Enable Camera permission

​
Android Installation Issues

Error: “App not installed”
  • Ensure you have enough storage space
  • Check that “Install from Unknown Sources” is enabled (APK only)
  • Uninstall any previous versions first
NFC Not Working Some Android devices require:
  1. Settings → Connected devices → Connection preferences
  2. Enable NFC

​
Build Issues

Metro bundler errors 
# Clear Metro cache
npx expo start --clear

# Reset node_modules
rm -rf node_modules
yarn install
Native build errors 
# Clean prebuild
yarn prebuild --clean

# iOS: Clean build folder
cd ios && xcodebuild clean && cd ..

# Android: Clean gradle
cd android && ./gradlew clean && cd ..

​
System Requirements

​
Minimum Hardware

  • RAM: 2GB minimum, 4GB recommended
  • Storage: 200MB for app, additional space for transaction data
  • Network: Internet connection required for Lightning payments and Nostr features

​
Supported Features by Platform

FeatureiOSAndroid
Cashu Ecash✅✅
Lightning✅✅
Nostr DMs✅✅
NFC Payments✅✅
QR Scanning✅✅
Biometric Lock✅✅
Background Fetch✅Limited

​
Version Information

From package.json: 
{
  "name": "Sovran",
  "version": "1.0.0",
  "dependencies": {
    "expo": "^55.0.4",
    "react-native": "0.83.2",
    "coco-cashu-core": "^1.1.2-rc.47",
    "@nostr-dev-kit/ndk-mobile": "^0.2.2"
  }
}
Current Version: 0.0.61 (build 1 for iOS, versionCode 2 for Android)

​
Next Steps

After installation, proceed to the Quick Start Guide to set up your wallet and make your first payment.

Quick Start

Set up your wallet in minutes

Security Guide

Learn how to keep your Bitcoin safe

GitHub Issues

Report bugs or request features

Community

Join the Sovran community

Build docs developers (and LLMs) love

Get started for freeTalk to us