GXQ STUDIO - Advanced Solana DeFi Platform

April 21, 2026 · View on GitHub

The most advanced Solana DeFi platform with flash loan arbitrage, sniper bot, token launchpad, and comprehensive Web3 UI.

🚀 Quick Start

# Interactive setup
./quick-start.sh

# Or use Make commands
make help          # Show all available commands
make dev           # Start local development
make docker-up     # Start with Docker

🧠 Realise (Production Bootstrap)

powershell -ExecutionPolicy Bypass -File ./scripts/Bootstrap.ps1

Runs environment checks (Node.js + npm)
Installs dependencies (root + webapp + optional apps/api)
Initializes .env files from examples when missing
Builds the project (unless -SkipBuild is passed)

No-Drift completion tag: v1.0.0-STABLE @ 2026-04-21T10:30:49.889+00:00

flowchart LR
  cli[src + api] --> core[Root TypeScript runtime]
  web[webapp Next.js] --> core
  admin[admin Electron] --> web
  scripts[scripts/*] --> core

📦 Deployment Options

Deploy to any platform in minutes! See DEPLOYMENT.md for comprehensive guides.

Platform	Best For	Command	Guide
🌐 Vercel	Webapp (Serverless)	`vercel --prod`	Guide
🚂 Railway	Backend (Container)	`railway up`	Guide
☁️ AWS	Enterprise Scale	`make deploy-aws`	Guide
🔷 Azure	Microsoft Cloud	`make deploy-azure`	Guide
🐳 Docker	Any Server	`make docker-up`	Guide
💻 VPS	Full Control	`make deploy-vps`	Guide
🏠 Localhost	Development	`make dev`	Guide

Key Features

✅ Unified Server: Single entry point for all deployments
✅ Docker Orchestration: Backend + Webapp + Monitoring
✅ 50+ Make Commands: Simplified management
✅ Automated Scripts: One-command VPS deployment
✅ Health Checks: Kubernetes-compatible endpoints
✅ WebSocket Support: Real-time updates with auto-reconnect
✅ Monitoring: Prometheus + Grafana integration

🆕 Latest Updates

✨ Multi-Platform Deployment Support

✅ Unified Server: src/server.ts works across all platforms
✅ Docker Excellence: Multi-stage builds, dev & prod configs
✅ Comprehensive Docs: 26KB deployment guide covering 8+ platforms
✅ Automation: Makefile with 50+ commands, deployment scripts
✅ CI/CD: Docker build workflow, automated testing
✅ WebSocket Stability: Enhanced reconnection logic

✨ Production-Ready API with Comprehensive Validation & Automated Deployment

✅ Input Validation: Comprehensive validation for all API endpoints with type checking and sanitization
✅ Error Handling: Centralized error handling with standardized responses and custom error types
✅ CORS Configuration: Production-ready CORS with environment-aware configurations
✅ Automated Deployment: CI/CD workflows for Vercel and Railway with health checks and auto-rollback
✅ Enhanced Security: Rate limiting, input sanitization, and authentication validation
✅ Complete Documentation: Comprehensive guides for API, validation, deployment, and configuration

📖 Deployment Guide | Quick Start | API Validation

🌐 Web Application (NEW!)

Production-ready Next.js web app with full Solana integration!

Features

🔄 Jupiter Swap - Best rates across all Solana DEXs
🎯 Sniper Bot - Monitor and snipe new token launches (Pump.fun + 8-22 DEXs)
🚀 Token Launchpad - Launch tokens with 3D airdrop roulette game
🎁 Airdrop Checker - Wallet scoring and auto-claim with Jupiter integration
💎 Staking - Marinade, Lido, Jito, Kamino integration
⚡ Flash Loan Arbitrage - Real-time opportunity scanning and execution
📱 Responsive Design - Mobile, tablet, and desktop optimized
🎨 Modern UI - Solana-themed with purple, blue, green gradients and 3D effects

Quick Deploy to Vercel

⚠️ IMPORTANT: The deploy button above pre-configures Root Directory to webapp. If importing manually, set Root Directory to webapp in the project settings.

Via Vercel Dashboard (manual):

Go to https://vercel.com/new
Import: SMSDAO/TradeOS
Set Root Directory: webapp ← REQUIRED
Add env: NEXT_PUBLIC_RPC_URL
Deploy

Via Vercel CLI:

cd webapp
vercel --prod

See VERCEL_DEPLOYMENT_CASTQUEST.md for detailed instructions and troubleshooting.

Quick Deploy to Railway

Railway provides 24/7 backend hosting with automated arbitrage scanning!

Automated Setup:

bash scripts/setup-railway.sh

Manual Setup:

# Install Railway CLI
curl -fsSL https://railway.app/install.sh | sh

# Login and link to project
railway login
railway link 2077acd9-f81f-47ba-b8c7-8bf6905f45fc

# Set environment variables
railway variables --set SOLANA_RPC_URL="your-rpc-url"
railway variables --set WALLET_PRIVATE_KEY="your-private-key"

# Deploy
railway up

Features:

✅ 24/7 automated arbitrage scanning
✅ Auto-deployment on push to main
✅ Preview deployments for PRs
✅ Health check monitoring with auto-restart
✅ Secret synchronization workflow
✅ Automatic rollback on failure
✅ Real-time logs and metrics

Required Secrets:

RAILWAY_TOKEN - Railway API token
RAILWAY_PROJECT_ID - 2077acd9-f81f-47ba-b8c7-8bf6905f45fc
SOLANA_RPC_URL - Solana RPC endpoint
WALLET_PRIVATE_KEY - Wallet private key (base58)
ADMIN_USERNAME - Admin username
ADMIN_PASSWORD - Admin password
JWT_SECRET - JWT secret

📖 See docs/RAILWAY_DEPLOYMENT.md for complete Railway deployment guide.

🚀 Backend CLI Features

QuickNode Integration

RPC: High-performance Solana RPC endpoint
Functions: Serverless compute for price monitoring
KV Store: Key-value storage for opportunity caching
Streams: Real-time blockchain event monitoring

Flash Loan Providers (5 Providers)

Marginfi - 0.09% fee
Solend - 0.10% fee
Kamino - 0.12% fee
Mango - 0.15% fee
Port Finance - 0.20% fee

DEX Integrations (11 Programs)

Raydium
Orca
Serum
Saber
Mercurial
Lifinity
Aldrin
Crema
Meteora (mainnet-grade)
Phoenix (mainnet-grade)
OpenBook (mainnet-grade)

Arbitrage Strategies

⚡ Flash Loan Arbitrage: Leverage flash loans from 5 providers with fees ranging from 0.09%-0.20%
🔄 Triangular Arbitrage: Multi-hop trading using Jupiter v6 aggregator
🎯 Hybrid Strategy: Combine both approaches for maximum profitability

Token Support (30+ Tokens)

Native: SOL, wSOL, RAY, ORCA, MNGO, SRM, JUP, RENDER, JTO, PYTH, STEP
Stablecoins: USDC, USDT, USDH, UXD, USDR
Liquid Staking Tokens: mSOL, stSOL, jitoSOL, bSOL, scnSOL
Memecoins: BONK, WIF, SAMO, MYRO, POPCAT, WEN
GXQ Ecosystem: GXQ, sGXQ, xGXQ

Enhanced Scanner (NEW!)

🔍 Multi-Angle Scanning: Flash loan, triangular, and cross-DEX arbitrage detection
⚡ 1-Second Polling: Real-time opportunity detection with configurable intervals
🌐 20+ Aggregators: Jupiter + 12 direct DEX integrations for comprehensive coverage
💾 Historical Analysis: Database-backed tracking and analytics
📊 Dynamic Gas Estimation: Real-time compute unit estimation via Solana RPC
🎯 User-Configurable Slippage: Set maximum slippage tolerance
🔔 Live Notifications: Real-time alerts for profitable opportunities
📈 Performance Metrics: Detailed statistics and success rate tracking

Additional Features

🎁 Airdrop Checker: Automatic detection and claiming of airdrops
📋 Preset Management: Pre-configured strategies for different market conditions
🛡️ MEV Protection: Jito bundle integration to prevent front-running
⚡ Auto-Execution: Continuous monitoring and execution of profitable opportunities
🔧 Manual Execution: Review and manually execute opportunities with "sweet profit"
💰 Dev Fee System: Automatic 10% profit sharing to development wallet
💎 GXQ Ecosystem Integration: Native support for GXQ tokens

📦 Installation

# Clone the repository
git clone https://github.com/SMSDAO/TradeOS.git
cd TradeOS

# Install dependencies
npm install

# Build the project
npm run build

⚙️ Configuration

Copy the example environment file and configure your settings:

cp .env.example .env

Edit .env with your configuration:

# Solana Configuration
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
WALLET_PRIVATE_KEY=your_private_key_here

# QuickNode Configuration
QUICKNODE_RPC_URL=your_quicknode_rpc_url
QUICKNODE_API_KEY=your_quicknode_api_key
QUICKNODE_FUNCTIONS_URL=your_quicknode_functions_url
QUICKNODE_KV_URL=your_quicknode_kv_url
QUICKNODE_STREAMS_URL=your_quicknode_streams_url

# Arbitrage Configuration
MIN_PROFIT_THRESHOLD=0.005
MAX_SLIPPAGE=0.01
GAS_BUFFER=1.5

# Dev Fee Configuration (10% of profits)
DEV_FEE_ENABLED=true
DEV_FEE_PERCENTAGE=0.10
DEV_FEE_WALLET=monads.solana

🎯 Usage

Check Available Airdrops

npm start airdrops

Auto-Claim Airdrops

npm start claim

List Available Presets

npm start presets

Scan for Opportunities

npm start scan

Start Auto-Execution

npm start start

Manual Execution Mode

Review opportunities before executing:

npm start manual

Show Flash Loan Providers

npm start providers

Enhanced Scanner (NEW!)

Real-time multi-angle arbitrage detection with 1-second polling:

# Start enhanced scanner
npm start enhanced-scan

# View scanner statistics
npm start scanner-stats

# View database statistics
npm start db-stats

# Historical analysis
npm start history

See ENHANCED_SCANNER.md for complete documentation.

📋 Preset Strategies

1. Stablecoin Flash Loan Arbitrage

Strategy: Flash loan arbitrage with stablecoins
Tokens: USDC, USDT, USDH, UXD
Risk: Low
Min Profit: 0.3%

2. SOL Triangular Arbitrage

Strategy: Triangular arbitrage with SOL
Tokens: SOL, USDC, USDT, RAY, ORCA
Risk: Medium
Min Profit: 0.5%

3. Liquid Staking Token Arbitrage

Strategy: Hybrid approach with LSTs
Tokens: SOL, mSOL, stSOL, jitoSOL, bSOL
Risk: Low-Medium
Min Profit: 0.4%

4. Memecoin Flash Arbitrage

Strategy: High-frequency memecoin trading
Tokens: BONK, WIF, SAMO, MYRO, POPCAT
Risk: High
Min Profit: 1.0%

5. GXQ Ecosystem Arbitrage

Strategy: GXQ token ecosystem opportunities
Tokens: GXQ, sGXQ, xGXQ, SOL, USDC
Risk: Medium
Min Profit: 0.5%

6. DeFi Token Arbitrage

Strategy: Major DeFi token opportunities
Tokens: JUP, RAY, ORCA, MNGO, SRM
Risk: Medium
Min Profit: 0.6%

🛡️ MEV Protection

The system includes multiple layers of MEV protection:

Jito Bundle Integration: Bundle transactions to prevent front-running
Private RPC: Send transactions through private mempool
Dynamic Priority Fees: Optimize gas fees based on urgency
Dynamic Slippage: Market-aware slippage calculation based on volatility and liquidity
Safety Checks: Confidence scoring and opportunity validation

🏗️ Architecture

src/
├── config/          # Configuration and token definitions
├── providers/       # Flash loan provider implementations
├── dex/            # DEX integrations
├── integrations/   # QuickNode and Jupiter integrations
├── services/       # Core services (airdrop, presets, auto-execution)
├── strategies/     # Arbitrage strategies
├── types.ts        # TypeScript type definitions
└── index.ts        # Main entry point and CLI

🤖 Merge Automation (NEW!)

High-performance PowerShell script for automated branch merging with parallel processing:

Features

⚡ 5x Faster: Parallel processing reduces 42m → 8m (80% improvement)
🔄 Parallel Jobs: Up to 8 branches merged simultaneously
🛡️ Safe: Automatic conflict resolution, rollback, and health checks
📊 Monitored: Comprehensive performance metrics and benchmarking
🧪 Tested: Full test suite with health validation

Quick Start

# Merge specific branches
./scripts/Merge-Branches.ps1 -SourceBranches @("feature/auth", "feature/api")

# Auto-sweep all feature branches
./scripts/Merge-Branches.ps1 -AutoSweep -MaxParallelJobs 8

# Dry run (test without changes)
./scripts/Merge-Branches.ps1 -SourceBranches @("feature/test") -DryRun

Documentation

Merge Automation Guide - Complete user manual
GitHub Actions Integration - CI/CD workflows
Performance Results - Detailed benchmarks

Performance Benchmarks

Configuration	Time	Speedup	Memory
Sequential (baseline)	42m 30s	1.0x	2.1 GB
Parallel (4 jobs)	18m 45s	2.3x	3.2 GB
Optimized (8 jobs)	8m 30s	5.0x	3.5 GB

See Performance Results for detailed analysis.

🔧 Development

# Run in development mode
npm run dev

# Run linter
npm run lint

# Run tests
npm test

# Validate API endpoints
npm run validate-endpoints http://localhost:3000

# Test merge automation (PowerShell)
pwsh ./scripts/Test-MergeBranches.ps1

🔒 API Security & Validation

All API endpoints now include:

✅ Input Validation: Type checking, range validation, and sanitization
✅ Error Handling: Consistent error responses with detailed messages
✅ Rate Limiting: Protection against abuse (configurable per endpoint)
✅ CORS Configuration: Environment-aware cross-origin access control
✅ Authentication: JWT-based authentication with expiration
✅ Request Logging: Comprehensive logging for debugging and monitoring

See API Validation Guide for complete documentation.

🚀 Automated Deployment

Vercel Deployment

✅ Automatic deployment on push to main
✅ Health check validation after deployment
✅ Automatic rollback on failure
✅ Preview deployments for PRs
✅ Deployment status tracking

Railway Deployment

✅ Automatic deployment with health checks
✅ Retry logic for transient failures
✅ Endpoint validation tests
✅ Issue creation on deployment failure

See Deployment Automation Guide for setup instructions.

🧠 Autonomous Oracle - CI/CD Intelligence

The Autonomous Oracle continuously analyzes the codebase during CI/CD pipeline execution to ensure code quality, security, and performance optimization.

Key Capabilities

🏗️ Architecture Analysis: Detects circular dependencies, god classes, and architectural debt
🔒 Security Scanning: Identifies vulnerabilities, validates RBAC/encryption usage
⚡ Gas Optimization: Analyzes compute units and priority fees for Solana efficiency
⚙️ Mainnet Compatibility: Validates versioned transactions and best practices
🧬 Evolution Intelligence: Identifies technical debt and suggests modern patterns
🎫 Auto-Ticketing: Creates GitHub issues for critical findings

Health Score System

90-100: Excellent - Deploy with confidence
70-89: Good - Minor improvements recommended
50-69: Fair - Address issues before deployment
0-49: Poor - Critical issues require immediate attention

Integration

The oracle runs automatically in CI/CD and blocks deployment if critical issues are detected:

❌ Critical issues = Deployment blocked
⚠️ High issues (>2) = Review required
✅ No blockers = Safe to deploy

See AUTONOMOUS_ORACLE.md for complete documentation.

📊 Flash Loan Provider Comparison

Provider	Fee	Liquidity	Speed	Best For
Marginfi	0.09%	High	Fast	General arbitrage
Solend	0.10%	Very High	Fast	Large trades
Kamino	0.12%	High	Medium	Stable trades
Mango	0.15%	Medium	Fast	Leverage plays
Port Finance	0.20%	Medium	Medium	Niche opportunities

🎓 How It Works

Flash Loan Arbitrage

Detect price discrepancy across DEXs
Borrow funds via flash loan (no collateral)
Execute arbitrage trade
Repay loan + fee
Keep the profit

Triangular Arbitrage

Identify 3-token cycle opportunity
Use Jupiter v6 for optimal routing
Execute A → B → C → A trades
Profit from price inefficiencies

⚠️ Risk Disclaimer

Cryptocurrency trading and arbitrage involve significant risks:

Smart contract risks
Market volatility
MEV attacks
Slippage
Network congestion

Always test with small amounts first and never invest more than you can afford to lose.

📝 License

MIT License - see LICENSE file for details

🤖 Continuous Self-Optimization

NEW! Every PR is automatically analyzed and optimized by our self-optimization workflow:

Automated Actions

✅ Auto-fix ESLint Issues: Formatting, imports, and style violations
✅ Dead Code Detection: Finds unused exports, imports, and unreachable code
✅ Complexity Analysis: Identifies functions that need refactoring
✅ Test Coverage Gaps: Detects untested code and generates test templates
✅ Security Scanning: Flags risky patterns like eval(), type safety issues
✅ Inline PR Comments: Contextual recommendations on specific code lines

What Gets Automatically Fixed

Code formatting and style
Unused imports
Simple ESLint violations
Type inference improvements

What Gets Flagged for Review

High complexity functions (cyclomatic complexity > 10)
Security risks (eval, innerHTML, etc.)
Excessive any type usage
TODO/FIXME in production code
Low test coverage (<80%)
Mock/placeholder implementations

See Self-Optimization Guide for complete documentation.

Developer Commands

# Run all optimizations locally
npm run optimize

# Fix linting issues
npm run lint:fix
npm run lint:webapp:fix

# Analyze dead code
npm run dead-code:analyze

# Analyze test coverage gaps
npm run coverage:analyze

📚 Documentation

Getting Started

Quick Start Guide - Fast setup and common tasks
Deployment Ready - Mainnet deployment instructions
Implementation Summary - Complete feature overview

API & Validation

API Validation Guide - Input validation and error handling
Endpoint Configuration - Endpoint reference and configuration

Deployment & Operations

Deployment Automation - CI/CD workflows and automation
Vercel Deployment - Vercel-specific instructions
Enhanced Scanner - Real-time arbitrage scanning
Self-Optimization - Automated code quality workflow

DevOps & Automation

Merge Automation Guide - PowerShell merge automation (80% faster)
GitHub Actions Integration - CI/CD workflow integration
Performance Results - Benchmark analysis and optimization metrics

Features & Guides

Flash Loan Enhancements - Flash loan system details
Security Guide - Security best practices
Testing Guide - Testing procedures and coverage

🚀 Production Deployment

For complete mainnet deployment instructions, see DEPLOYMENT_READY.md including:

API keys & credentials setup
Security best practices
Testing checklist
Monitoring & maintenance
Troubleshooting guide
Expected profitability ($2,000-$10,000+/month)

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Before contributing:

Read the documentation in docs/
Follow the coding standards
Add tests for new features
Ensure all CI checks pass
Update documentation as needed

🔄 CI/CD Pipeline

This project includes a comprehensive CI/CD pipeline with automated testing, security scanning, and deployment previews.

Pipeline Features

Multi-Node Testing: Tests run on Node.js 18 and 20
Code Quality: ESLint with zero warnings policy
Type Safety: Strict TypeScript checking
Test Coverage: Automated coverage collection with 90% target
Security Scanning: CodeQL analysis and npm audit
Preview Deployments: Automatic Vercel and Railway previews for every PR
Auto-merge: Automated PR merging when all checks pass
Dual Deployment: Automatic deployment to both Vercel (webapp) and Railway (backend) on push to main

Running CI Checks Locally

# Run all validation checks
npm run validate

# Individual checks
npm run lint              # Lint backend
npm run lint:webapp       # Lint webapp
npm run type-check        # Type check backend
npm run type-check:webapp # Type check webapp
npm run test              # Run backend tests with coverage
npm run test:webapp       # Run webapp tests with coverage
npm run build             # Build both backend and webapp
npm run build:backend     # Build backend only
npm run build:webapp      # Build webapp only

Master Orchestration & Automation

The project includes a comprehensive master orchestration script that automates the full build, validation, and deployment pipeline:

# Run full master orchestration (recommended before deploying)
npm run master            # Complete build & validation pipeline

# Individual orchestration scripts
npm run env-check         # Validate required environment variables
npm run env-sync          # Check .env.example is in sync
npm run db-migrate        # Run database migrations (if DB configured)
npm run validate-build    # Validate all build artifacts exist
npm run health            # Run system health checks
npm run perf              # Generate performance report

Master Orchestration Pipeline Steps:

Environment validation (required variables)
Clean dependency installation (backend + webapp)
TypeScript type-checking (strict mode)
Code linting (ESLint with zero-warning policy)
Auto-fix pass (format & fix issues)
Backend build (TypeScript compilation)
Webapp build (Next.js production build)
Database schema validation & migration (if configured)
API health check configuration validation
Build artifact validation
Git operations (commit, tag, push)

Environment Requirements:

All required environment variables must be documented in .env.example as placeholders. The system validates:

Required variables are present in your local .env
All production variables are documented in .env.example
No real secrets are committed to .env.example

Database Support:

Optional PostgreSQL database support with automated migrations:

Schema: db/schema.sql
Migrations: npm run db-migrate
Configuration: Set DB_HOST, DB_USER, DB_PASSWORD, DB_NAME in .env

Required Secrets for CI/CD

Repository maintainers should configure these secrets in Settings → Secrets and variables → Actions:

Vercel Deployment (Webapp)

VERCEL_TOKEN - Vercel authentication token
VERCEL_PROJECT_ID - Vercel project ID
VERCEL_ORG_ID - Vercel organization/team ID
NEXT_PUBLIC_RPC_URL - Solana RPC URL for webapp

Railway Deployment (Backend)

RAILWAY_TOKEN - Railway API authentication token
RAILWAY_PROJECT_ID - Railway project ID (2077acd9-f81f-47ba-b8c7-8bf6905f45fc)
SOLANA_RPC_URL - Solana RPC endpoint URL
WALLET_PRIVATE_KEY - Wallet private key (base58 format)
ADMIN_USERNAME - Admin panel username
ADMIN_PASSWORD - Admin panel password
JWT_SECRET - JWT authentication secret

Code Coverage

CODECOV_TOKEN - Codecov upload token

Optional Notifications

SLACK_WEBHOOK - Slack webhook URL for notifications

CI/CD Workflow Results

Check the Actions tab to view workflow runs and results. Each PR will show:

✅ Lint and type checking results
✅ Test results with coverage report
✅ Security scan results
✅ Build success/failure
🔗 Preview deployment URL (when secrets are configured)

📧 Support

For support and questions:

Issues: Open a GitHub issue with appropriate labels
Documentation: Check the docs/ directory
Security: See SECURITY_GUIDE.md
Deployment: See DEPLOYMENT_AUTOMATION.md

🌟 Acknowledgments

Solana Foundation
Jupiter Aggregator
QuickNode
All flash loan providers and DEX protocols

Built with ❤️ by GXQ STUDIO

Key Features

✅ 5 Flash Loan Providers with fees from 0.09%-0.20%
✅ 11 DEX Integrations including Jupiter v6 aggregator
✅ 30+ Token Support including stablecoins, LSTs, and memecoins
✅ MEV Protection via Jito bundles and private RPC
✅ Real-time Monitoring with 1-second polling intervals
✅ Automated Deployment with health checks and rollback
✅ Comprehensive Validation for all API endpoints
✅ Production-Ready with complete documentation

Status: Production-Ready | Last Updated: December 2024