NexTrade Documentation

Full-stack cryptocurrency exchange platform with real-time trading, WebSocket streaming, multi-factor authentication, and admin analytics.

What is NexTrade?

NexTrade is a production-ready cryptocurrency trading platform that proxies all data through its own API server. Users connect their Binance API keys to execute real trades, while the platform adds authentication, fee management, analytics, and real-time data streaming.

Key Features

• Real-time market data — Proxied from Binance with Redis caching and WebSocket fan-out
• 7 order types — Limit, Market, Stop-Limit, Stop-Loss, Take-Profit, Take-Profit Limit, OCO
• Secure auth — Email/password with optional TOTP 2FA, account lockout, email verification
• Encrypted key storage — AES-256-GCM encryption for Binance API keys and TOTP secrets
• Trading fees — Configurable global and per-user maker/taker fees
• Admin panel — User management, fee configuration, platform statistics
• Analytics dashboard — Volume tracking, P&L, trade history with CSV export
• Demo mode — Simulated trading for users without API keys
• Docker-ready — Multi-stage builds, docker-compose, nginx with TLS

Tech Stack

Architecture

Request Flow

Backend Directory Structure

server/
├── prisma/
│   ├── schema.prisma          # Database models
│   └── seed.ts                # Admin account seeder
└── src/
    ├── index.ts               # Server bootstrap + graceful shutdown
    ├── config/env.ts          # Zod-validated environment config
    ├── plugins/               # Prisma, Redis, JWT, CORS, Helmet, Rate-Limit, WS
    ├── middleware/             # auth, admin, require-api-key
    ├── routes/                # auth, user, market, trading, analytics, admin
    ├── services/              # Business logic layer
    ├── lib/
    │   ├── crypto.ts          # AES-256-GCM encrypt/decrypt
    │   ├── password.ts        # Argon2id hash/verify
    │   ├── totp.ts            # TOTP generate/verify
    │   ├── email.ts           # Nodemailer templates
    │   └── binance/           # REST client + WS manager
    ├── cron/                  # Scheduled jobs
    ├── ws/                    # WebSocket handlers + fan-out
    └── __tests__/             # 354 backend tests

Getting Started

Prerequisites

• Node.js 22+ — Runtime
• pnpm — Package manager (corepack enable)
• PostgreSQL 17 — Database
• Redis 7 — Cache and session store
• Binance API Key — For live trading (optional for demo mode)

Quick Start

git clone <repo-url> nextrade
cd nextrade

# Frontend
pnpm install

# Backend
cd server
pnpm install

cp .env.example .env
# Edit .env — set DATABASE_URL, secrets, etc.

# Generate Prisma client + push schema
npx prisma generate
npx prisma db push

# Seed admin account
pnpm db:seed

# Terminal 1 — Backend (port 3007)
cd server && pnpm dev

# Terminal 2 — Frontend (port 3008)
cd .. && pnpm dev

curl http://localhost:3007/api/health
# {"success":true,"data":{"status":"ok","checks":{"database":"ok","redis":"ok"}}}

Configuration

Generate Secure Secrets

Never use default/example values in production. Generate cryptographically secure secrets:

# JWT secrets (min 32 characters)
openssl rand -base64 48

# Encryption key (64 hex chars = 256-bit AES key)
openssl rand -hex 32

Password Requirements

• Minimum 8 characters
• At least one lowercase letter
• At least one uppercase letter
• At least one number
• At least one special character

Default Admin Account

Created on first seed via pnpm db:seed:

Database Schema

7 Prisma models backed by PostgreSQL. All IDs are CUIDs. Financial values use Decimal(20,8) precision.

User

ApiKey

Binance API credentials encrypted with AES-256-GCM. Each key and secret has its own IV and auth tag.

Order

Trade

Each fill on an order creates a Trade record with fee details.

FeeConfig & UserFeeOverride

FeeConfig stores global maker/taker fees (default 0.1% each). UserFeeOverride allows per-user custom rates. The trading service resolves: UserFeeOverride ?? FeeConfig.

AnalyticsSnapshot

Daily aggregate of each user's trading activity. Created by the hourly analytics cron job. Contains: tradeCount, buyVolume, sellVolume, feesGenerated, realizedPnl.

Authentication

JWT Token Strategy

Login Flow

Account Lockout

• Threshold: 5 failed login attempts
• Duration: 15-minute lockout
• Tracking: Redis key lockout:<email> with TTL
• Reset: Automatically after TTL, or on successful login

2FA (TOTP)

Trading Engine

Supported Order Types

Order Lifecycle

NEW  ──►  PARTIALLY_FILLED  ──►  FILLED
  │
  ├──►  CANCELED  (user cancel)
  ├──►  REJECTED  (validation failure)
  └──►  EXPIRED   (time-in-force expired)

Fee Calculation

Fees are calculated per fill:

fee = fillQuantity × fillPrice × feeRate

// Fee rate resolution:
effectiveRate = UserFeeOverride[userId] ?? FeeConfig.global
makerRate = effectiveRate.makerFee   // default 0.001 (0.1%)
takerRate = effectiveRate.takerFee   // default 0.001 (0.1%)

All financial calculations use Prisma Decimal (not JavaScript floats) to avoid precision loss.

Order Sync (Cron)

Every 10 seconds, the order-sync cron job:

• Queries all orders with status NEW or PARTIALLY_FILLED
• Polls Binance for each order's current status
• Records new fills as Trade records with fee calculations
• Updates order status and filledQty
• Broadcasts updates via WebSocket to the order owner

Market Data

All market data is proxied through the API server with Redis caching. The frontend never talks directly to Binance.

Cache Strategy

Supported Quote Assets

Trading pairs are filtered to: USDC, USDT, BTC, ETH, BNB

WebSocket System

Connection

// Connect with JWT authentication
ws://localhost:3007/ws?token=<accessToken>

// Max 3 concurrent connections per user

Message Protocol

Available Streams

• <symbol>@ticker — 24hr mini ticker updates
• <symbol>@depth — Order book updates
• <symbol>@kline_<interval> — Candlestick updates
• <symbol>@trade — Real-time trades
• <symbol>@aggTrade — Aggregate trades
• user:orders — Private order status updates (automatic)

Fan-Out Architecture

The server maintains one upstream Binance WebSocket connection per stream and fans out data to all subscribed clients. Reference counting ensures streams are unsubscribed after a 30-second grace period when no clients need them.

Analytics

Daily snapshots aggregated by the hourly cron job. Available via dashboard API and the frontend analytics page.

• Volume tracking — Buy/sell volume per day
• Trade count — Number of executed trades
• Fee totals — Platform fees generated
• Realized P&L — Profit/loss by symbol
• CSV export — Download trade history with formula injection protection

Admin Panel

Accessible to users with the ADMIN role. Admin role is verified against the database on every request (not just the JWT claim).

Capabilities

• Fee management — View/update global maker/taker fees, set per-user overrides
• User management — Paginated user list with order/trade/key counts, user detail view
• API key control — Deactivate or delete any user's API keys
• Order oversight — View all platform orders with user/symbol/status filters
• Platform stats — Total users, orders, trades, fees, active API keys

API Reference

All endpoints return JSON in the format: {"success": true, "data": {...}}. Errors return: {"success": false, "error": "message"}.

Responses include the X-Request-Id header (UUID) for traceability.

Authentication

Register Request

POST /api/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "MySecure@Pass1"
}

Login Response (TOTP disabled)

{
  "success": true,
  "data": {
    "tokens": {
      "accessToken": "eyJhbGci...",
      "refreshToken": "a1b2c3d4..."
    }
  }
}

Login Response (TOTP enabled)

{
  "success": true,
  "data": {
    "requiresTOTP": true,
    "tempToken": "tmp_a1b2c3..."
  }
}

Market Data

Klines Query Parameters

GET /api/market/klines/BTCUSDC?interval=1h&limit=500

// Intervals: 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M

Trading

Place Order Request

POST /api/trading/orders
Authorization: Bearer <accessToken>

{
  "symbol": "BTCUSDC",
  "side": "BUY",
  "type": "LIMIT",
  "price": "45000.00",
  "quantity": "0.001",
  "timeInForce": "GTC"
}

User Management

Analytics

Admin

Health Checks

Readiness Response

{
  "success": true,
  "data": {
    "status": "ready",
    "checks": {
      "database": "ok",
      "redis": "ok"
    },
    "timestamp": "2026-02-07T12:00:00.000Z"
  }
}

Frontend Application

Pages & Routes

State Management (Zustand)

useAuthStore

Manages authentication state. Stores tokens in localStorage, auto-refreshes on 401 responses.

• user — Current user profile (null if logged out)
• login(email, password) — Returns tokens or TOTP challenge
• register(email, password) — Creates account
• logout() — Clears tokens and state

useOrderStore

Dual-mode store: demo (localStorage simulation) when unauthenticated, API-backed when authenticated.

• isDemoMode — Toggleable; persisted in localStorage
• placeOrder() — Demo: simulates locally; Live: POST /api/trading/orders
• cancelOrder() — Demo: removes locally; Live: DELETE /api/trading/orders/:id
• Form state: formPrice, formQuantity, formSide, formType, etc.

useMarketStore

Current trading pair, ticker data, and pair list loaded from the API.

Design System

Color Palette

Typography

Component Patterns

• Border radius: 8px (cards, inputs, buttons)
• Borders: 1px solid #2A2A2A (no shadows)
• Transitions: 150ms color/background transitions
• Buy buttons: Green background (#18E589), black text
• Sell buttons: Red background (#E5484D), white text
• Primary action: Blue background (#218CFF), white text
• Scrollbars: 4px thin, #2A2A2A thumb

Security

Security Headers

Encryption Details

Input Validation

All endpoints validate input with Zod schemas. Invalid input returns 400 with detailed field-level errors:

{
  "success": false,
  "error": "Validation failed",
  "details": [
    "password: Password must contain a special character",
    "email: Invalid email"
  ]
}

Additional Protections

• Request body limit: 1MB max
• CORS: Locked to FRONTEND_URL in production
• Trust proxy: Enabled in production for correct client IP behind nginx
• CSV injection: Values starting with =, +, -, @ are prefixed with '
• Error masking: 5xx errors return "Internal server error" in production (no stack traces)
• Email enumeration: /forgot-password always returns success (doesn't reveal if email exists)

Rate Limiting

Rate limiting is backed by Redis for distributed consistency across cluster nodes.

Deployment

Production Checklist

Deploy with Docker Compose

# Create .env from template
cp server/.env.production.example .env

# Generate secrets
echo "JWT_ACCESS_SECRET=$(openssl rand -base64 48)" >> .env
echo "JWT_REFRESH_SECRET=$(openssl rand -base64 48)" >> .env
echo "ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env

# Start all services
docker compose up -d

# Run database migration + seed
docker compose exec api npx prisma migrate deploy
docker compose exec api npx prisma db seed

# Check logs
docker compose logs -f api

Deploy with PM2 (without Docker)

# Build backend
cd server && pnpm build

# Start with PM2 (cluster mode)
pm2 start ecosystem.config.cjs --env production

# Monitor
pm2 monit

# View logs
pm2 logs crypto-exchange-api

Docker

Architecture

Image Details

Health Check Dependencies

Services start in order via health checks: postgres → redis → api → frontend → nginx

Nginx Configuration

Routing Rules

TLS Configuration

• Protocols: TLS 1.2 + TLS 1.3
• Ciphers: ECDHE-ECDSA and ECDHE-RSA with AES-128/256-GCM-SHA256/384
• OCSP Stapling: Enabled
• Session Tickets: Disabled (forward secrecy)
• HSTS: 1 year, includeSubDomains, preload

SSL Certificate Setup

# Using Let's Encrypt with certbot
certbot certonly --standalone -d yourdomain.com

# Copy to nginx/ssl/
cp /etc/letsencrypt/live/yourdomain.com/fullchain.pem nginx/ssl/
cp /etc/letsencrypt/live/yourdomain.com/privkey.pem nginx/ssl/

# For local development (self-signed)
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout nginx/ssl/privkey.pem \
  -out nginx/ssl/fullchain.pem \
  -subj "/CN=localhost"

CI / CD

GitHub Actions pipeline runs on every push to main and on pull requests.

Pipeline Stages

Concurrency

Uses GitHub Actions concurrency groups — new pushes cancel in-progress runs for the same branch.

Backups

Database Backup

# Manual backup
./server/scripts/backup.sh

# Automated via cron (daily at 2 AM)
0 2 * * * /path/to/server/scripts/backup.sh >> /var/log/backup.log 2>&1

Creates compressed pg_dump files in /app/backups/. Old backups are automatically rotated after 30 days.

Database Restore

# List available backups
./server/scripts/restore.sh

# Restore specific backup
./server/scripts/restore.sh /app/backups/crypto_exchange_20260207_020000.sql.gz

Monitoring

Health Endpoints

Use for uptime monitoring and container orchestration:

Logging

Structured JSON logging in production via Pino. Pretty-printed in development.

# View API logs (Docker)
docker compose logs -f api

# View nginx access logs
tail -f nginx/logs/access.log

# PM2 logs
pm2 logs crypto-exchange-api --lines 100

Key Metrics to Monitor

• Health endpoint response time — Alert if >5s
• Database connections — Prisma connection pool
• Redis memory usage — Should stay below 256MB limit
• Error rate — 5xx responses in nginx access logs
• WebSocket connections — Active connection count
• Cron job execution — Order-sync and market-refresh logs

Cron Jobs

Environment Variables

Backend (server/.env)

Frontend (.env.local)

Docker Compose (.env at root)

Troubleshooting

Common Issues

docker compose ps
docker compose logs postgres
docker compose logs redis

cd server && pnpm db:seed