MavaPay Off-ramp Demo

A demo app that converts Bitcoin (Lightning) to ZAR and sends it to a South African bank account using the MavaPay API.

How It Works

1. Dashboard shows the live BTC/ZAR exchange rate
2. You click "Off-ramp" and enter: amount (sats), bank, account number
3. The app verifies the bank account via MavaPay name enquiry
4. MavaPay creates a quote and returns a Lightning invoice
5. You pay the invoice from any Lightning wallet
6. MavaPay converts BTC to ZAR and sends it to the bank account
7. The app polls transaction status until complete

No real money is involved -- this uses the MavaPay staging environment.

Prerequisites

• Python 3.8+
• A MavaPay account with a staging API key

Setup

1. Clone the repo

git clone https://github.com/xyephy/mavapay-offramp.git
cd mavapay-offramp

2. Install dependencies

pip install -r requirements.txt

3. Get your MavaPay API key

Sandbox (recommended for testing):

1. Create an account at https://staging.mavapay.co
2. Go to Settings > API Keys & Webhooks
3. Copy your Secret Key

Production:

1. Create an account at https://mavapay.co/create-account
2. Complete account verification
3. Go to Settings > API Keys & Webhooks
4. Copy your Secret Key

API docs: https://docs.mavapay.co

4. Create the .env file

cp .env.example .env

Open .env and replace your_mavapay_staging_key_here with your actual key:

MAVAPAY_API_KEY=your_actual_staging_key

5. Run the app

python app.py

Open http://127.0.0.1:5002 in your browser.

Usage

1. The dashboard shows the current BTC/ZAR exchange rate
2. Click Off-ramp to Bank
3. Enter the amount in satoshis (e.g. 50000)
4. Select a bank and enter the account number
5. Click Verify to confirm the account holder name
6. Click Get Quote to see the exchange rate and fees
7. Pay the Lightning invoice shown (QR code or copy the invoice string)
8. Wait for MavaPay to process the payout

API Endpoints

Method	Route	Description
GET	/	Dashboard with exchange rate
GET	/offramp	Off-ramp form
GET	/api/health	Check MavaPay connectivity
GET	/api/price	Get BTC/ZAR exchange rate
GET	/api/banks/<country>	List banks for a country (ZA, NG, KE)
POST	/api/verify_account	Verify bank account (name enquiry)
POST	/api/get_quote	Create quote, returns Lightning invoice
GET	/api/check_payout/<hash>	Poll payout status
GET	/status/<tx_hash>	Transaction status page

Tech Stack

• Flask -- Python web framework
• MavaPay API -- BTC-to-fiat off-ramp (staging)
• qrcode + Pillow -- QR code generation for Lightning invoices