🚀 Smart Order Router (SOR)

A professional-grade TypeScript Smart Order Router that intelligently routes Bitcoin orders across multiple exchanges to achieve optimal execution with real-time market data from CoinGecko.

✨ Features

🔄 Smart Routing

• Bitcoin Smart Routing: Routes Bitcoin orders across 2 top exchanges (Binance, Coinbase)
• Intelligent Algorithms: BestPrice, TWAP, VWAP, Liquidity-based routing
• Real-time Optimization: Continuously finds the best execution venues

📊 Live Market Data

• CoinGecko Integration: Real-time cryptocurrency prices and market data
• Bitcoin Trading: BTC/USD with real exchange data
• Price Charts: Interactive line graphs with multiple timeframes (price data only)
• Crypto Logos: Beautiful UI with official cryptocurrency logos

🎯 Trading Features

• Demo Trading: Risk-free simulation with $100,000 virtual balance
• Order Management: Complete order lifecycle tracking
• Portfolio Analytics: Real-time P&L and performance metrics
• WebSocket Integration: Real-time updates and notifications

🎨 Modern UI

• Next.js Frontend: Modern React-based trading interface
• Responsive Design: Works on desktop and mobile
• Dark/Light Theme: Beautiful UI with theme switching
• Real-time Charts: Interactive price charts with lightweight-charts

🏗️ Architecture

Backend (TypeScript)

src/
├── core/                    # Business logic
│   ├── routing/            # SOR algorithms
│   ├── trading/            # Trading engine
│   └── orders/             # Order management
├── adapters/               # External integrations
│   └── coingecko/          # CoinGecko API
├── infrastructure/         # Technical concerns
│   ├── api/               # WebSocket & REST API
│   └── config/            # Configuration
└── shared/                # Common utilities

Frontend (Next.js)

frontend/
├── app/                   # Next.js app router
├── components/            # React components
│   ├── trading/           # Trading interface
│   ├── ui/                # Base components
│   └── layout/            # Layout components
├── services/              # API services
└── store/                 # State management

🚀 Quick Start

Prerequisites

• Node.js v20+
• npm or yarn

Installation

# Clone the repository
git clone <repository-url>
cd smart-order-router

# Install dependencies
npm install

# Install frontend dependencies
cd frontend && npm install && cd ..

Running the Application

1. Start Backend (Terminal 1)

# Start API server with WebSocket
npm run api

2. Start Frontend (Terminal 2)

# Start Next.js development server
cd frontend
npm run dev

3. Demo Mode (Terminal 3)

# Run demo trading scenarios
npm run demo

Access the Application

• Frontend: http://localhost:3000
• Backend API: http://localhost:8080
• WebSocket: ws://localhost:8080

📈 Demo Trading

The application includes a comprehensive demo mode:

• Virtual Balance: Start with $100,000
• Real Market Data: Live prices from CoinGecko
• Bitcoin Focus: 2 top exchange venues for BTC/USD
• Order Execution: Simulated trading with real market conditions
• Analytics: Track performance and P&L

npm run demo

🔧 Configuration

Environment Variables

Create .env.local in the root directory:

# CoinGecko API (optional - works without key for free tier)
COINGECKO_API_KEY=your_api_key_here

# Server Configuration
PORT=8080
NODE_ENV=development

Trading Configuration

Edit src/configs/appConfig.ts:

export const TRADING_CONFIG = {
  supportedSymbols: ['BTC/USD', 'ETH/USD', 'ADA/USD', 'DOT/USD', 'LINK/USD'],
  defaultCurrency: 'usd',
};

🧪 Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test suite
npm test -- --testNamePattern="routing"

📚 API Documentation

WebSocket Messages

Client to Server

// Subscribe to market data
{ type: "SUBSCRIBE_MARKET_DATA" }

// Place order
{ 
  type: "PLACE_ORDER", 
  payload: { symbol: "BTC/USD", side: "BUY", quantity: 0.001 } 
}

// Get price series
{ 
  type: "GET_PRICE_SERIES", 
  payload: { symbol: "BTC/USD", timeframe: "1d" } 
}

// Get crypto metadata
{ 
  type: "GET_COIN_METADATA", 
  payload: { symbols: ["BTC/USD", "ETH/USD"] } 
}

Server to Client

// Market data update
{ 
  type: "MARKET_DATA_UPDATE", 
  payload: { symbol: "BTC/USD", data: [...] } 
}

// Order result
{ 
  type: "ORDER_RESULT", 
  payload: { status: "FILLED", symbol: "BTC/USD", ... } 
}

// Price series
{ 
  type: "PRICE_SERIES", 
  payload: { symbol: "BTC/USD", timeframe: "1d", points: [...] } 
}

🏆 Performance

• Rate Limiting: Respects CoinGecko's 100 req/min free tier
• Real-time Updates: WebSocket-based live data
• Efficient Routing: Optimized algorithms for best execution
• Scalable Architecture: Modular design for easy extension

🔒 Security

• Demo Mode Only: No real money trading
• Input Validation: Comprehensive data validation
• Error Handling: Graceful error recovery
• Rate Limiting: Protection against API abuse

🚀 Production Deployment

Docker

# Build and run with Docker
docker build -t smart-order-router .
docker run -p 8080:8080 -p 3000:3000 smart-order-router

Environment Setup

# Production environment
NODE_ENV=production
PORT=8080
COINGECKO_API_KEY=your_production_key

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow TypeScript best practices
• Write comprehensive tests
• Update documentation
• Use conventional commit messages
• Ensure code passes linting

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• CoinGecko for providing excellent cryptocurrency market data API
• Next.js for the amazing React framework
• Lightweight Charts for beautiful, performant charts
• Zustand for simple state management

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki

---

⚠️ Disclaimer: This is a demo trading application. No real money is involved. Always do your own research before making any financial decisions.