Skip to main content

​
Quick Start Guide

Get up and running with Sovran in just a few minutes. This guide walks you through downloading the app, creating your wallet, and making your first Bitcoin payment.

​
Overview

Sovran is a mobile Bitcoin wallet that uses Cashu ecash for instant, private payments. Here’s what you’ll do:
1

Download the App

Install Sovran from the App Store (iOS) or Play Store (Android). See the Installation page for detailed instructions and links.
2

Accept Terms and Complete Onboarding

On first launch, you’ll be presented with:
  1. Terms & Conditions: Review and accept to continue
  2. Onboarding Carousel: Learn about Sovran’s key features:
    • Bitcoin that feels like cash with ecash bearer tokens
    • Powered by Nostr, a decentralized network
    • Privacy by design with blind signatures
    • Stay private, stay sovereign
The onboarding screen features an interactive carousel. Swipe through the slides or tap to advance. When ready, swipe up to reveal the “Get Started” button.
Your BIP-39 seed phrase is automatically generated on first launch and stored securely using expo-secure-store with biometric support.
3

Explore Your Wallet

After onboarding, you’ll see the main wallet interface:
// File: app/(drawer)/(tabs)/index/index.tsx
// The wallet tab shows:
- Balance display with sats/fiat toggle
- Account pager (swipeable multi-account view)
- Send/Receive/Scan buttons
- Transaction history with filters
Key Components:
  • Balance Toggle: Tap to switch between sats, USD, EUR, or GBP
  • Account Pager: Swipe left/right to view different accounts
  • Quick Actions: Send, Receive, and Scan buttons for easy access
4

Backup Your Seed Phrase

Critical: Your seed phrase is your wallet. Without it, you cannot recover your funds.
  1. Open the drawer menu (swipe from left edge or tap menu icon)
  2. Navigate to Settings
  3. Go to Recovery settings
  4. View and securely store your 12-word BIP-39 seed phrase
Write down your seed phrase on paper. Never share it with anyone. Never store it digitally (screenshots, cloud storage, etc.). Anyone with your seed phrase can steal your Bitcoin.
Your seed phrase is used for:
  • Recovering ecash proofs from all known mints
  • Deriving your Nostr identity via NIP-06
  • Restoring pending send operations
5

Add a Mint

Before you can receive Bitcoin, you need to add at least one Cashu mint:
  1. Tap the Wallet header to open the mint selector
  2. Select Add Mint or browse discovered mints
  3. Choose from:
    • Community-recommended mints via Nostr (kind 38000 events)
    • Sovran-curated mints from the Sovran API
    • Custom mint URL (paste any Cashu mint URL)
// File: app/(mint-flow)/add.tsx
// Mints discovered via:
- useNostrDiscoveredMints() // Nostr kind 38000
- useSovranDiscoveredMints() // Sovran API
Each mint shows its KYM score (Know Your Mint) with:
  • Lightning node connectivity status
  • Success rates for swaps
  • Average swap times
  • Community ratings
Multi-mint architecture is a core security feature. Distribute your balance across multiple mints to reduce custodial risk.
6

Receive Your First Payment

Now you’re ready to receive Bitcoin:

​
Option A: Lightning Invoice

  1. Tap Receive on the wallet screen
  2. On the Lightning tab, tap Fixed Amount
  3. Enter the amount in sats
  4. Share the generated BOLT11 invoice via QR code or copy to clipboard
// File: components/screens/ReceiveScreen.tsx
// The receive screen supports:
- Lightning invoices (BOLT11)
- P2PK locking keys (if Quick Access enabled)
- NPC mint URLs for Lightning addresses

​
Option B: Cashu Token

To receive ecash directly from another Sovran user:
  1. Have the sender create an ecash token
  2. Receive via:
    • QR Code: Tap Scan and scan their QR
    • NFC: Enable NFC and tap devices together
    • Paste: Copy token from clipboard and paste
    • Deep Link: Open cashu:// or sovran:// URL
The token is automatically detected and claimed to your wallet.
7

Send Your First Payment

To send Bitcoin from Sovran:

​
Pay a Lightning Invoice

  1. Tap Send or Scan
  2. Scan a BOLT11 Lightning invoice QR code, or paste from clipboard
  3. Review the payment details (amount, mint, fees)
  4. Confirm to send
// File: hooks/coco/useProcessPaymentString.ts
// Sovran processes multiple payment formats:
- BOLT11 Lightning invoices
- Cashu ecash tokens
- Payment requests (NUT-18)
- cashu:// and sovran:// deep links

​
Send Ecash to Another User

  1. Tap Send
  2. Select Create Token
  3. Choose amount and mint
  4. Share via:
    • QR code (recipient scans)
    • NFC tap (contactless)
    • Copy to clipboard (paste into messaging app)
    • Encode with emojis (creative sharing)
Every transaction is tracked with its source (QR scan, NFC tap, clipboard paste, or deep link) visible in your transaction history.

​
Next Steps

Now that you’ve completed the basics, explore more advanced features:

Claim Lightning Address

Get a custom username@npubx.cash or username@sovran.money Lightning address

Nostr Messaging

Send encrypted messages and Cashu tokens via Nostr DMs (NIP-17)

Multi-Mint Management

Distribute your balance and rebalance across mints automatically

NFC Payments

Enable tap-to-pay contactless payments

​
Common Tasks

​
Switch Display Currency

Tap the currency pill in the header to switch between USD, EUR, GBP, or sats. Real-time fiat conversion uses cached BTC price data. 
// File: stores/settingsStore.ts — displayCurrency setting
// File: stores/pricelistStore.ts — BTC price cache

​
Filter Transactions

From the wallet screen:
  1. Tap Filter icon
  2. Filter by:
    • Currency (BTC, Lightning, ecash)
    • Payment type
    • Direction (sent/received)
    • Status (pending, complete, cancelled)
    • Month (horizontal month selector)
// File: app/(filter-flow)/filters.tsx
// File: components/blocks/Transactions.tsx

​
Set a Passcode

Protect your wallet with a 4-digit PIN:
  1. Go to Settings → Passcode
  2. Enter your desired 4-digit PIN
  3. Confirm the PIN
The passcode gate appears on app launch. 
// File: app/settings-pages/passcode.tsx
// File: components/blocks/PasscodeGate.tsx

​
Troubleshooting

​
I Can’t Receive Payments

  • Ensure you’ve added at least one mint
  • Check that the mint is online (audit data in mint info)
  • Verify the Lightning invoice amount is within mint limits

​
Transaction Stuck as Pending

If a Lightning payment is pending:
  1. Tap the transaction to view details
  2. Use the Refresh button to check status
  3. The transaction timeline shows each step’s progress
// File: components/blocks/Transaction/HistoryEntryTimeline.tsx
For ecash sends, you can rollback pending tokens:
  1. Go to Explore tab
  2. Tap Pending Ecash card
  3. Review pending sends and rollback to reclaim tokens

​
Lost Access to My Wallet

If you lose your device:
  1. Install Sovran on a new device
  2. Skip onboarding to access settings
  3. Go to Settings → Recovery
  4. Enter your 12-word seed phrase
  5. Start recovery to sweep all mints
// File: app/settings-pages/recovery.tsx
// Recovery process:
- Contacts each mint to restore proofs
- Recovers interrupted transactions
- May take several minutes
Recovery only works if you have your seed phrase. There is no other way to restore your funds.

​
Learn More

Build docs developers (and LLMs) love

Get started for freeTalk to us