Skip to main content

​
Get started with Medusa Wallet

This guide will walk you through getting started with Medusa Wallet, from installation to sending your first Lightning payment.
1

Download and install the app

Download Medusa Wallet from the App Store (iOS) or Google Play Store (Android).See the Installation guide for detailed platform-specific instructions.
The app is built with Expo and requires iOS 13+ or Android 5.0+ (API level 21+)
2

Create your account

When you first launch the app, you’ll see the intro screen. Tap “Get Started” to begin.

​
Sign up process

On the sign up screen, you’ll need to provide:
  • Username - Your unique identifier for logging in
  • Email - Can be any email, even a throwaway address
  • Password - Secure password for your account
You can use a throwaway email address if you prefer maximum privacy. Just make sure you remember your username and password!
The sign up process automatically:
  1. Creates your account on the LNbits backend
  2. Generates your first default wallet
  3. Creates a Lightning address ([email protected])
// What happens behind the scenes
const accessToken = await lnbits.register(username, email, password)
const user = await lnbits.getUser(accessToken)
// Your first wallet is automatically created!
3

Set up security

After creating your account, set up security features to protect your wallet:

​
PIN code

Create a 4-digit PIN code that you’ll use to unlock the app:
  1. Navigate to Settings > Security
  2. Enable “App PIN”
  3. Enter your 4-digit PIN twice to confirm

​
Biometric authentication (optional)

Enable Face ID or Touch ID for faster access:
  1. Go to Settings > Security > Biometric
  2. Toggle on biometric authentication
  3. Authenticate with your device’s biometric sensor
You’ll need to have a PIN set up before enabling biometric authentication. The biometric feature is a convenience option that falls back to PIN if needed.
4

Create your first wallet (optional)

Your account comes with a default wallet, but you can create additional wallets to organize your funds.

​
Creating a new wallet

  1. Go to the Wallets screen
  2. Tap the “New Wallet” button
  3. Enter a name for your wallet (e.g., “Savings”, “Daily Spending”)
  4. Tap “Create Wallet”
Each wallet has:
  • Its own balance
  • Separate transaction history
  • Unique Lightning address
  • Individual admin and invoice keys
You can have as many wallets as you need to organize your Bitcoin.
5

Receive your first payment

Let’s receive some sats to get started!

​
Option 1: Lightning invoice

  1. Select the wallet you want to receive funds in
  2. Tap “Receive”
  3. Enter the amount you want to receive (in sats)
  4. Optionally add a memo/description
  5. Tap “Create Lightning Request”
  6. Share the QR code or copy the Lightning invoice
The invoice looks like this:
lnbc100n1p3...[Lightning invoice]
Lightning invoices are typically valid for a limited time. Make sure to share it promptly with the sender!

​
Option 2: Lightning address

Your Lightning address is automatically created when you sign up:
[your-wallet-id]@wallet.medusa.bz
Anyone can send you sats using this address, similar to an email address!

​
Real-time notifications

The app uses WebSocket connections to notify you instantly when payments are received:
// Behind the scenes
lnbits.subscribeInkeyWs(inkey, (amount) => {
  toast.success(`Received ${amount} sats!`)
})
6

Send your first payment

Ready to send some sats? Here’s how:

​
Scanning a Lightning invoice

  1. Tap “Send” or the scan icon
  2. Allow camera permissions when prompted
  3. Scan the recipient’s Lightning invoice QR code
  4. Review the payment details (amount, recipient, memo)
  5. Tap “Confirm Send”
  6. Wait for the payment to complete
Camera permissions are required to scan QR codes. The app only uses the camera for scanning - it doesn’t store or transmit any images.

​
Pasting a Lightning invoice

If you have an invoice copied to your clipboard:
  1. Tap “Send”
  2. If camera access is denied, you’ll see a “Paste” option
  3. The app will automatically detect Lightning invoices, addresses, or URLs from your clipboard
  4. Review and confirm the payment

​
Payment confirmation

After sending, you’ll see a success message and the payment will appear in your transaction history with:
  • Amount sent
  • Timestamp
  • Recipient information
  • Fee paid
  • Fiat value at time of payment
7

View your transaction history

Keep track of all your payments:
  1. Select any wallet to view its transactions
  2. See incoming (green) and outgoing (red) payments
  3. Tap any transaction to view details
  4. Add personal notes to transactions for your records
Each transaction shows:
  • Amount in sats and your selected fiat currency
  • Timestamp with relative time (“2 hours ago”)
  • Description/memo
  • Payment hash
  • Fee information
You can add private notes to any transaction. These notes are stored locally and help you remember what each payment was for.

​
Next steps

Now that you have your wallet set up, explore these features:

Buy Bitcoin

Purchase sats with your credit card using the built-in voucher system - no KYC required

Swap to onchain

Move funds between Lightning and Bitcoin onchain using Boltz swaps

Create multiple wallets

Organize your funds across different wallets for savings, spending, etc.

Customize settings

Change your preferred fiat currency, Bitcoin unit (sats/BTC), language, and theme

​
Getting help

Need assistance?
  • Report bugs on GitHub Issues
  • Check the changelog for recent updates and fixes
  • Join the community discussions
Medusa Wallet is open source! You can view the code, contribute, or fork it on GitHub.

Build docs developers (and LLMs) love

Get started for freeTalk to us