cryptocurrencyexchangeplatform-vgi538/README.md

# Cryptocurrency Exchange Platform

A comprehensive cryptocurrency exchange (CEX) platform built with FastAPI, featuring secure wallet management, transaction signing, fiat transfers, and crypto trading capabilities.

## Features

### 🔐 Authentication & Security
- JWT-based authentication system
- Secure password hashing with bcrypt
- Rate limiting middleware (100 requests/minute)
- Security headers middleware
- Input validation and sanitization

### 💰 Wallet Management
- Multi-currency crypto wallet support (BTC, ETH, USDT)
- Fiat account management (USD, EUR, GBP)
- Local private key generation and encryption
- Secure wallet address generation

### 💸 Transaction Handling
- Local transaction signing (no external APIs)
- Crypto send/receive functionality
- Fiat deposit/withdrawal system
- Transaction history and tracking
- Fee calculation and management

### 🏗️ Architecture
- Clean, modular codebase structure
- SQLAlchemy ORM with Alembic migrations
- Pydantic schemas for data validation
- Service layer pattern
- Comprehensive error handling

## Tech Stack

- **Framework**: FastAPI 0.104.1
- **Database**: SQLite with SQLAlchemy
- **Authentication**: JWT with python-jose
- **Cryptography**: ecdsa, bitcoin, web3, cryptography
- **Validation**: Pydantic
- **Server**: Uvicorn
- **Code Quality**: Ruff

## Project Structure

```
├── app/
│   ├── api/                 # API endpoints
│   │   ├── auth.py         # Authentication routes
│   │   ├── wallets.py      # Wallet management routes
│   │   └── transactions.py # Transaction routes
│   ├── core/               # Core configuration
│   │   ├── config.py       # Application settings
│   │   ├── security.py     # Security utilities
│   │   └── middleware.py   # Security middleware
│   ├── db/                 # Database configuration
│   │   ├── base.py         # SQLAlchemy base
│   │   └── session.py      # Database session
│   ├── models/             # Database models
│   │   ├── user.py         # User model
│   │   ├── wallet.py       # Wallet & fiat account models
│   │   └── transaction.py  # Transaction models
│   ├── schemas/            # Pydantic schemas
│   ├── services/           # Business logic
│   │   ├── auth.py         # Authentication service
│   │   ├── wallet.py       # Wallet service
│   │   └── transaction.py  # Transaction service
│   ├── utils/              # Utilities
│   │   ├── crypto.py       # Cryptocurrency utilities
│   │   └── validation.py   # Input validation
│   └── storage/            # Application storage
│       ├── db/             # SQLite database
│       └── logs/           # Application logs
├── alembic/                # Database migrations
├── requirements.txt        # Python dependencies
├── main.py                 # Application entry point
└── .env.example           # Environment variables template
```

## Installation & Setup

### 1. Clone the repository
```bash
git clone <repository-url>
cd cryptocurrencyexchangeplatform-vgi538
```

### 2. Install dependencies
```bash
pip install -r requirements.txt
```

### 3. Environment Configuration
```bash
cp .env.example .env
# Edit .env file with your configuration
```

**Required Environment Variables:**
- `SECRET_KEY`: JWT secret key (use a long, random string in production)
- `DATABASE_URL`: SQLite database path
- `BTC_NETWORK`: Bitcoin network (mainnet/testnet)
- `ETH_NETWORK`: Ethereum network (mainnet/goerli)

### 4. Database Setup
```bash
# Run migrations
alembic upgrade head
```

### 5. Run the application
```bash
# Development mode
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

# Production mode
python main.py
```

## API Documentation

Once running, access the interactive API documentation:
- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc
- **OpenAPI JSON**: http://localhost:8000/openapi.json

## API Endpoints

### Authentication
- `POST /auth/register` - User registration
- `POST /auth/login` - User login
- `GET /auth/me` - Get current user info

### Wallets
- `POST /wallets/crypto` - Create crypto wallet
- `POST /wallets/fiat` - Create fiat account
- `GET /wallets/crypto` - Get user's crypto wallets
- `GET /wallets/fiat` - Get user's fiat accounts
- `GET /wallets/crypto/{wallet_id}` - Get specific crypto wallet
- `GET /wallets/fiat/{account_id}` - Get specific fiat account

### Transactions
- `POST /transactions/crypto/send` - Send cryptocurrency
- `POST /transactions/fiat/deposit` - Deposit fiat currency
- `POST /transactions/fiat/withdraw` - Withdraw fiat currency
- `GET /transactions/crypto` - Get crypto transaction history
- `GET /transactions/fiat` - Get fiat transaction history
- `GET /transactions/crypto/{transaction_id}` - Get specific transaction

### System
- `GET /` - Application info
- `GET /health` - Health check endpoint

## Security Features

### 🔒 Private Key Management
- Private keys are generated locally using secure random number generation
- Keys are encrypted using PBKDF2 with SHA-256 and stored encrypted in database
- Encryption uses user-specific salts and application secret key

### 🛡️ Transaction Security
- All transactions are signed locally using the wallet's private key
- No external APIs required for transaction signing
- Transaction data integrity verified through cryptographic signatures

### 🚦 Rate Limiting
- 100 requests per minute per IP address
- Automatic cleanup of rate limit storage
- Configurable limits per endpoint

### 🔐 Input Validation
- Comprehensive input validation for all endpoints
- Email, password, and phone number format validation
- Transaction amount and currency validation
- Address format validation for different cryptocurrencies

## Supported Cryptocurrencies

- **Bitcoin (BTC)**: Testnet and Mainnet support
- **Ethereum (ETH)**: Goerli and Mainnet support  
- **Tether (USDT)**: ERC-20 token on Ethereum network

## Supported Fiat Currencies

- USD (US Dollar)
- EUR (Euro)
- GBP (British Pound)

## Error Handling

The application includes comprehensive error handling:
- HTTP status codes for different error types
- Detailed error messages for debugging
- Global exception handler for unhandled errors
- Validation errors with specific field information

## Development

### Code Quality
```bash
# Run linting and auto-fix
ruff check --fix .
```

### Testing
```bash
# Run tests (when implemented)
pytest
```

## Production Deployment

### Environment Variables for Production
- Set `DEBUG=False`
- Use a strong, unique `SECRET_KEY`
- Configure proper database URL
- Set appropriate CORS origins
- Use production cryptocurrency networks

### Security Considerations
- Use HTTPS in production
- Implement proper key management
- Set up database backups
- Monitor transaction activity
- Implement additional KYC/AML compliance

## License

This project is developed for educational and development purposes. Ensure compliance with financial regulations in your jurisdiction before production use.