okjodom/minmo-pilot-api repository overview

⁠Minmo Pilot Swap Service

A production-ready Bitcoin-KES swap service that enables seamless conversion between Kenyan Shillings and Bitcoin using M-Pesa and Lightning Network.

⁠What It Does

Minmo Pilot makes it easy for Kenyan users to:

• Buy Bitcoin with M-Pesa payments (onramp)
• Sell Bitcoin for M-Pesa payouts (offramp)
• Get real-time exchange rates for accurate pricing
• Track swap progress with status updates

The service handles all the technical complexity of integrating M-Pesa payments with Lightning Network transactions, providing a simple REST API for developers to build Bitcoin applications in Kenya.

⁠Key Features

• 🔄 Bi-directional Swaps: KES ↔ BTC conversion in both directions
• 📱 M-Pesa Integration: Direct integration with Kenya's leading mobile money platform
• ⚡ Lightning Network: Fast, low-cost Bitcoin transactions
• 💱 Real-time Rates: Live BTC/KES exchange rates with caching
• 🔐 Secure API: Stack Auth authentication with user-scoped API keys
• 📊 Status Tracking: Real-time swap monitoring and notifications
• 🔔 Webhooks: Automated payment status updates

⁠Getting Started

⁠For Developers

1. Review the Documentation: Start with the Architecture Overview⁠ to understand the system
2. API Integration: Check the API Reference⁠ for endpoint details and examples
3. Authentication Setup: Follow the Authentication Guide⁠ to configure Stack Auth

⁠For System Administrators

1. Installation: See Deployment Guide⁠ for detailed setup instructions
2. Configuration: Review environment variables and service dependencies
3. Monitoring: Set up notifications using the Notifications Service⁠

⁠Quick API Test

# Get current exchange rate
curl "http://localhost:4000/swap/onramp/quote?currency=KES&amount=1000"

# Interactive API docs available at:
# http://localhost:4000/api

⁠Use Cases

⁠For Fintech Applications

• Bitcoin Wallets: Add KES onramp/offramp functionality
• Remittance Services: Enable Bitcoin-based cross-border transfers
• Trading Platforms: Provide local currency liquidity

⁠For Businesses

• Payment Processors: Accept Bitcoin payments, settle in KES
• E-commerce: Offer Bitcoin payment option with local currency conversion
• Financial Services: Build Bitcoin-enabled financial products

⁠For Developers

• Proof of Concepts: Rapid prototyping of Bitcoin-KES applications
• Integration Testing: Test Bitcoin payment flows with local currency
• Educational Projects: Learn Bitcoin/Lightning Network integration

⁠Documentation

Comprehensive documentation is available in the docs/ directory:

⁠Core Documentation

• API Reference⁠ - Complete REST API documentation with examples
• Architecture⁠ - System architecture and component overview
• Authentication⁠ - Stack Auth integration and API key management

⁠Service Documentation

• Fedimint Service⁠ - Lightning Network integration via Fedimint
• Intasend Service⁠ - M-Pesa payment processing integration
• FX Service⁠ - Exchange rate management and caching
• Notifications⁠ - Real-time notification system

⁠Technical Documentation

• Database Layer⁠ - MongoDB schema and repository patterns
• Deployment Guide⁠ - Production deployment and configuration

⁠Quick Navigation

• 🏗️ Getting Started: Begin with Architecture Overview⁠
• 🔌 API Integration: See API Reference⁠ for endpoints and examples
• 🔐 Authentication: Follow Auth Setup Guide⁠ for Stack Auth configuration
• ⚙️ Services: Explore individual service documentation for Fedimint⁠, Intasend⁠, and FX⁠

⁠Technical Requirements

• Node.js 18+ with Bun package manager
• MongoDB for transaction storage
• Fedimint clientd instance for Lightning Network
• Intasend account for M-Pesa integration
• Stack Auth project for API authentication

See Deployment Guide⁠ for detailed setup and configuration instructions.

⁠Status & Roadmap

Current Status: ✅ Production Ready

• Fully functional onramp/offramp operations
• Comprehensive API documentation
• Stack Auth integration complete
• MongoDB data layer implemented

Roadmap:

• Enhanced monitoring and analytics
• Additional payment provider integrations
• Rate limiting and performance optimizations

⁠Support & Community

• Documentation: Comprehensive guides in /docs
• API Reference: Interactive docs at /api endpoint
• Issues: Report bugs and feature requests via GitHub Issues
• Integration Support: Check the API Reference⁠ for detailed examples

Minmo Pilot - Making Bitcoin accessible through familiar payment methods in Kenya.