A sophisticated cryptocurrency exchange simulator that models real-world market dynamics with simulated digital assets.
- Overview
- Features
- Project Structure
- Technology Stack
- Getting Started
- API Documentation
- Frontend Features
- Configuration
- Development
- Contributing
- License
CoinLabs is a full-stack cryptocurrency exchange simulator designed to model realistic market behavior. Unlike traditional crypto exchanges with real assets, CoinLabs operates in a controlled environment with simulated cryptocurrencies that respond to supply, demand, and market events—providing a sandbox for understanding crypto market mechanics.
Create an educational platform that demonstrates:
- How cryptocurrencies interact with supply and demand dynamics
- Market impact of simulated news and events
- Portfolio management and trading strategies
- Realistic price movements including volatility spikes
- 🔄 Real-time Market Simulation: Watch simulated cryptocurrencies respond to algorithmic supply/demand dynamics
- 📊 Advanced Trading Interface: Intuitive UI for buying/selling simulated assets
- 💼 Portfolio Management: Track holdings, performance, and transaction history
- 📈 Market Analytics: Real-time price charts, market overview, and technical indicators
- 🔐 User Authentication: Secure Supabase-based authentication
- 🎨 Modern UI/UX: Built with React, TypeScript, and Tailwind CSS using shadcn/ui components
- 📱 Responsive Design: Fully functional on desktop and mobile devices
- Multiple simulated cryptocurrencies to trade
- Real-time price updates and market data
- Buy/sell orders with instant execution
- Portfolio tracking and analytics
- Transaction history and performance metrics
- Supply and demand-driven price mechanics
- News event simulation affecting prices
- Market volatility and trend analysis
- Simulated altcoins with realistic price movements
CoinLabs/
├── backend/ # FastAPI backend server
│ ├── app/
│ │ ├── main.py # FastAPI application entry point
│ │ ├── sim_config.py # Simulation configuration
│ │ ├── run.bash # Startup script
│ │ ├── models/
│ │ │ └── crypto.py # Cryptocurrency data models
│ │ ├── routers/ # API route handlers
│ │ │ ├── crypto.py # Cryptocurrency endpoints
│ │ │ ├── market.py # Market data endpoints
│ │ │ └── portfolio.py # User portfolio endpoints
│ │ ├── services/ # Business logic layer
│ │ │ ├── crypto.py
│ │ │ ├── market.py
│ │ │ └── portfolio.py
│ │ └── utils/ # Utility functions
│ │ ├── auth.py # Authentication helpers
│ │ ├── db.py # Database operations
│ │ ├── granularity.py
│ │ └── simulator.py # Core simulation engine
│ └── requirements.txt # Python dependencies
│
├── frontend/ # React + TypeScript frontend
│ ├── src/
│ │ ├── App.tsx # Main application component
│ │ ├── main.tsx # Application entry point
│ │ ├── components/ # Reusable React components
│ │ │ ├── Navigation.tsx
│ │ │ ├── CryptoCard.tsx
│ │ │ ├── AddCryptoDialog.tsx
│ │ │ ├── CryptoDetailDialog.tsx
│ │ │ └── ui/ # shadcn/ui component library
│ │ ├── pages/ # Page components
│ │ │ ├── Dashboard.tsx
│ │ │ ├── MarketOverview.tsx
│ │ │ ├── Auth.tsx
│ │ │ ├── Settings.tsx
│ │ │ └── NotFound.tsx
│ │ ├── contexts/ # React context for state management
│ │ ├── hooks/ # Custom React hooks
│ │ ├── integrations/ # External service integrations
│ │ │ └── supabase/
│ │ └── styles/ # Global styles
│ ├── supabase/ # Supabase configuration & migrations
│ ├── package.json
│ ├── vite.config.ts
│ ├── tailwind.config.ts
│ └── tsconfig.json
│
├── LICENSE
└── README.md (this file)
| Technology | Version | Purpose |
|---|---|---|
| FastAPI | 0.121.1 | Modern, fast web framework |
| Uvicorn | 0.38.0 | ASGI server |
| Pydantic | 2.12.3 | Data validation |
| NumPy | 2.3.4 | Numerical computations |
| Supabase | 2.24.0 | Backend-as-a-Service (Auth, DB) |
| Python-dotenv | 1.2.1 | Environment configuration |
| Technology | Version | Purpose |
|---|---|---|
| React | 18.3.1 | UI library |
| TypeScript | 5.8.3 | Type-safe JavaScript |
| Vite | 7.2.2 | Build tool and dev server |
| Tailwind CSS | 3.4.17 | Utility-first CSS |
| shadcn/ui | Latest | Component library |
| React Router | 6.30.1 | Client-side routing |
| Recharts | 2.15.4 | Data visualization |
| TanStack Query | 5.83.0 | Server state management |
| Supabase JS | 2.80.0 | Frontend client |
- Supabase: PostgreSQL database, authentication, real-time features
- CORS: Enabled for frontend-backend communication
Before you begin, ensure you have the following installed:
- Node.js (v18 or higher) and npm/bun
- Python (3.11 or higher)
- Git
git clone https://github.com/AXAStudio/CoinLabs.git
cd CoinLabscd backend
# Create a virtual environment
python3 -m venv venv
# Activate the virtual environmentsource venv/bin/activate # On Windows: venv\Scripts\activate# Install dependencies
pip install -r requirements.txt
# Configure environment variables
cp .env.example .env # Create from template or configure manuallycd ../frontend
# Install dependencies with bun or npm
bun install
# OR
npm installcd backend
source venv/bin/activate
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000The backend API will be available at http://localhost:8000
In a new terminal:
cd frontend
bun run dev
# OR
npm run devThe frontend will be available at http://localhost:5173 (or the URL shown in your terminal)
Alternatively, use the provided startup script:
cd backend/app
bash run.bashFastAPI automatically generates interactive API documentation. Once the backend is running:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
GET /market/cryptocurrencies- Get all simulated cryptocurrenciesGET /market/cryptocurrencies/{symbol}- Get specific crypto detailsGET /market/overview- Get market overview dataGET /market/history/{symbol}- Get price history
GET /portfolio/balance- Get user balanceGET /portfolio/holdings- Get user holdingsPOST /portfolio/buy- Execute a buy orderPOST /portfolio/sell- Execute a sell orderGET /portfolio/history- Get transaction history
GET /crypto/list- List all cryptocurrenciesGET /crypto/{symbol}- Get crypto details
- Personal portfolio overview
- Holdings summary with real-time values
- Quick trade interface
- Performance metrics
- All available cryptocurrencies
- Real-time price updates
- Price charts and trends
- Market statistics
- User login/registration
- Secure authentication via Supabase
- Session management
- User preferences
- Account configuration
| Component | Purpose |
|---|---|
Navigation | Top navigation bar with menu |
CryptoCard | Display individual cryptocurrency info |
CryptoDetailDialog | Detailed crypto information modal |
AddCryptoDialog | Buy/sell cryptocurrency interface |
Edit backend/app/sim_config.py to customize:
- Simulation parameters
- Market dynamics
- Initial cryptocurrency data
- Price movement algorithms
- Vite Config:
frontend/vite.config.ts - Tailwind:
frontend/tailwind.config.ts - TypeScript:
frontend/tsconfig.json - ESLint:
frontend/eslint.config.js
Create a .env file in the backend directory:
SUPABASE_URL=your_supabase_urlSUPABASE_KEY=your_supabase_keyDATABASE_URL=your_database_url# Add other configuration as neededcd backend
uvicorn app.main:app
#### Frontend```bashcd frontendnpm inpm run dev### Code Quality- **Frontend**: ESLint with React and TypeScript support- **Backend**: Python linting (consider adding Ruff or Black)---## 📄 LicenseThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.---## 🌟 Acknowledgments- FastAPI for the excellent backend framework- React and TypeScript community- shadcn/ui for beautiful components- Supabase for seamless backend infrastructure---**Made by AXAStudio**