Exovy Server

Backend API for a cryptocurrency-to-fiat exchange platform — enabling users across Africa to receive crypto deposits and instantly cash out to their local bank accounts in Nigerian Naira (NGN).

---

Table of Contents

• Overview
• Architecture
• Tech Stack
• Features
• Getting Started
• Environment Variables
• Database
• API Documentation
• Deployment
• Project Structure
• License

---

Overview

Exovy Server is a NestJS-based backend that powers a crypto-to-fiat exchange service. Users can:

1. Generate wallet addresses on multiple blockchain networks (Bitcoin, Ethereum, BSC, Polygon, Tron, Solana).
2. Deposit cryptocurrency to their generated wallets.
3. Automatically convert crypto to Nigerian Naira at competitive exchange rates.
4. Receive instant payouts to their Nigerian bank accounts via Paystack or Monnify.

The platform includes a full admin dashboard for managing users, transactions, exchange rates, KYC verification, and system settings.

---

Architecture

┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Mobile App  │────▶│  NestJS API      │────▶│  PostgreSQL     │
│  (Client)    │◀────│  (REST + WS)     │◀────│  (Prisma ORM)   │
└─────────────┘     └──────┬───────────┘     └─────────────────┘
                           │
              ┌────────────┼────────────────┐
              │            │                │
        ┌─────▼────┐ ┌────▼─────┐  ┌──────▼──────┐
        │  Tatum   │ │ Paystack │  │  CoinGecko  │
        │  (Chain) │ │ Monnify  │  │  (Prices)   │
        └──────────┘ └──────────┘  └─────────────┘
              │            │                │
        ┌─────▼────┐ ┌────▼─────┐  ┌──────▼──────┐
        │ Firebase │ │ Smile ID │  │  AWS S3     │
        │ (Push)   │ │ Dojah    │  │  (Uploads)  │
        └──────────┘ │ (KYC)    │  └─────────────┘
                     └──────────┘

---

Tech Stack

Layer	Technology
Framework	NestJS 11 (TypeScript)
Database	PostgreSQL with Prisma ORM
Auth	JWT (Passport.js) + OTP email verification
Blockchain	Tatum SDK, ethers.js, bitcoinjs-lib
Payments	Paystack, Monnify
Crypto Prices	CoinGecko, Coinbase (failover)
Real-time	Socket.IO (WebSocket price streaming)
KYC	Smile Identity, Dojah
Notifications	Firebase Cloud Messaging (FCM)
Email	Resend
File Storage	AWS S3
SMS	Africa's Talking
API Docs	Swagger / OpenAPI
Process Mgmt	PM2
Package Mgr	pnpm

---

Features

User-Facing

• Multi-chain wallet generation — Bitcoin, Ethereum, BSC, Polygon, Tron, Solana
• Automatic deposit detection — via Tatum webhook subscriptions
• Real-time price feeds — WebSocket-powered live crypto prices with CoinGecko/Coinbase failover
• Instant bank payouts — automatic NGN payout to Nigerian bank accounts
• Bank account management — add, verify, and manage payout destinations
• KYC verification — identity verification via Smile ID and Dojah with automatic provider failover
• Push notifications — transaction updates, security alerts, price alerts via Firebase
• QR codes — generated for wallet deposit addresses
• Transaction PIN — secondary security layer for sensitive operations
• Profile management — photo upload (S3), personal details, security settings

Admin Dashboard

• User management — view, suspend, activate users
• Transaction oversight — monitor deposits, approve/reject payouts
• Exchange rate control — set custom USD/NGN rates, spreads, and min/max amounts
• KYC management — review and approve/reject identity verifications
• Asset & network management — add/remove supported cryptocurrencies and networks
• Analytics dashboard — user stats, transaction volumes, revenue metrics
• Role-based access control (RBAC) — custom admin roles with granular permissions
• Payout provider management — switch between Paystack/Monnify, configure risk settings
• Push notification broadcasting — send targeted notifications to user segments
• In-app advertising — create and schedule promotional ads
• System settings — manage app-wide configuration (social links, contact info, legal pages)

Security & Reliability

• Rate limiting — multi-tier throttling (short/medium/long burst protection)
• Encrypted private keys — wallet private keys encrypted at rest
• Webhook signature verification — for Tatum blockchain events
• Provider health monitoring — automatic failover for price feeds and KYC providers
• Global exception handling — standardized error responses
• Input validation — request DTOs with class-validator

---

Getting Started

Prerequisites

• Node.js ≥ 18
• pnpm (package manager)
• PostgreSQL database
• Accounts on: Tatum, Paystack or Monnify, CoinGecko, Firebase, AWS S3, Resend

Installation

# Clone the repository
git clone <repository-url>
cd exovy-server

# Install dependencies
pnpm install

# Set up environment variables
cp env.example .env
# Edit .env with your credentials

# Generate Prisma client
pnpm exec prisma generate

# Run database migrations
pnpm exec prisma migrate dev

# Seed the database (optional)
pnpm run seed:all

Running the Server

# Development (watch mode)
pnpm run start:dev

# Production
pnpm run build
pnpm run start:prod

# With PM2
pnpm run pm2:start

The server will start on http://localhost:3000 (or the PORT specified in .env).

---

Environment Variables

Copy env.example to .env and configure each section:

Category	Variables
Database	DATABASE_URL
JWT	JWT_SECRET, JWT_ADMIN_SECRET, JWT_EXPIRES_IN
Email	RESEND_API_KEY, FROM_EMAIL
AWS S3	AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_S3_BUCKET
Firebase	FIREBASE_PROJECT_ID, FIREBASE_PRIVATE_KEY, FIREBASE_CLIENT_EMAIL
Crypto Prices	COINGECKO_API_KEY
Blockchain	TATUM_API_KEY_TESTNET, TATUM_API_KEY_MAINNET, TATUM_TESTNET, ENCRYPTION_KEY
Payouts	MONNIFY_* (5 vars), PAYSTACK_* (2 vars)
KYC	SMILE_* (3 vars), DOJAH_* (3 vars)
SMS	AT_USERNAME, AT_API_KEY, AT_SHORTCODE, AT_KEYWORD
App	NODE_ENV, PORT, APP_URL, FRONTEND_URL
Webhooks	WEBHOOK_SECRET

See env.example for the full list with descriptions.

---

Database

The application uses PostgreSQL with Prisma ORM. Key models:

• User — registered users with KYC status, PIN, referral codes
• Admin — admin users with role-based permissions
• WalletAddress — generated blockchain wallet addresses (encrypted keys)
• CryptoDeposit — outgoing crypto transactions with confirmation tracking
• CryptoPayout — outgoing fiat payouts to bank accounts
• BankAccount — user-linked Nigerian bank accounts
• Asset — supported cryptocurrencies with network associations
• AssetPrice / AssetRate — real-time prices and exchange rates
• Network — supported blockchain networks
• KYCVerification — identity verification records
• Notification — push notification history
• Ad — in-app promotional advertisements

Useful Commands

# Generate Prisma client after schema changes
pnpm exec prisma generate

# Create and apply migrations
pnpm exec prisma migrate dev --name <migration-name>

# View database in Prisma Studio
pnpm exec prisma studio

# Seed the database
pnpm run seed:all

---

API Documentation

Swagger documentation is auto-generated and available at:

http://localhost:3000/api

The API is organized into the following route groups:

Prefix	Description
/auth	Registration, login, OTP, password
/users	Profile management, KYC, settings
/crypto-assets	Crypto prices, asset listings
/wallet	Wallet generation, deposits, payouts
/bank-accounts	Bank account CRUD
/notifications	User notification management
/ads	In-app ad retrieval
/admin/*	All admin operations (requires admin JWT)
/webhooks	Tatum webhook receiver

---

Deployment

Staging

A deployment script is included for staging environments:

bash deploy-staging.sh

Production

# Build
pnpm run build

# Start with PM2
pnpm run pm2:start

# Or directly
pnpm run start:prod

PM2 Configuration

An ecosystem.config.js file is provided for PM2 process management with environment-specific configurations.

---

Project Structure

exovy-server/
├── prisma/
│   ├── schema.prisma          # Database schema (26 models, 16 enums)
│   ├── migrations/            # Database migration history
│   └── seed*.ts               # Database seeding scripts
├── src/
│   ├── main.ts                # Application entry point
│   ├── app.module.ts          # Root module
│   ├── auth/                  # Authentication (JWT, OTP, login/register)
│   ├── user/                  # User profiles, settings, KYC
│   ├── crypto/                # Crypto assets, prices, WebSocket feeds
│   ├── wallet/                # Wallet generation, deposits, payouts
│   ├── admin/                 # Admin dashboard (29 files, full back-office)
│   ├── notification/          # Push notifications (Firebase FCM)
│   ├── mail/                  # Email service (Resend)
│   ├── upload/                # File uploads (AWS S3)
│   ├── webhook/               # Tatum blockchain webhooks
│   ├── ad/                    # In-app advertising
│   └── common/                # Shared utilities
│       ├── decorators/        # Custom decorators
│       ├── guards/            # Auth guards (JWT, Admin)
│       ├── filters/           # Global exception filters
│       ├── interceptors/      # Response transformation
│       ├── services/          # Prisma, encryption services
│       ├── strategy/          # Passport strategies
│       ├── utils/             # Helper utilities
│       └── validators/        # Custom validators
├── test/                      # E2E tests
├── env.example                # Environment variable template
├── ecosystem.config.js        # PM2 configuration
├── deploy-staging.sh          # Staging deployment script
└── package.json

---

License

This project is UNLICENSED (private/proprietary).