cryptop2ptradingplatform-f8a0bc/README.md

# Crypto P2P Trading Platform

A peer-to-peer cryptocurrency trading platform built with FastAPI and SQLite, similar to Binance P2P. This platform allows users to create buy/sell advertisements, place orders, and automatically handle payments and crypto transfers through a payment provider integration.

## Features

- **User Authentication**: JWT-based authentication with user registration and login
- **Wallet Management**: Multi-cryptocurrency wallet system with balance tracking and fund locking
- **Advertisement System**: Users can create buy/sell ads with customizable terms and conditions
- **Order Management**: Secure order placement with automatic fund locking and crypto release
- **Payment Integration**: Integration with payment providers for automatic account generation
- **Auto-Release**: Automatic crypto release to buyers after payment confirmation
- **Real-time Status Tracking**: Track order status from pending to completion
- **Health Monitoring**: Built-in health check endpoint for system monitoring

## Tech Stack

- **Backend**: FastAPI (Python)
- **Database**: SQLite with SQLAlchemy ORM
- **Authentication**: JWT tokens with bcrypt password hashing
- **Migrations**: Alembic for database migrations
- **API Documentation**: Auto-generated OpenAPI/Swagger docs
- **HTTP Client**: httpx for payment provider integration

## Project Structure

```
.
├── main.py                 # FastAPI application entry point
├── requirements.txt        # Python dependencies
├── alembic.ini            # Alembic configuration
├── alembic/               # Database migrations
│   ├── env.py
│   └── versions/
├── app/
│   ├── api/v1/            # API routes
│   │   ├── api.py         # Main API router
│   │   └── endpoints/     # Individual endpoint modules
│   ├── core/              # Core utilities
│   │   ├── config.py      # Application configuration
│   │   ├── deps.py        # Dependencies
│   │   └── security.py    # Security utilities
│   ├── db/                # Database configuration
│   │   ├── base.py        # SQLAlchemy base
│   │   └── session.py     # Database session
│   ├── models/            # SQLAlchemy models
│   ├── schemas/           # Pydantic schemas
│   └── services/          # Business logic services
└── storage/               # Application storage
    └── db/                # SQLite database files
```

## Installation

1. Clone the repository:
```bash
git clone <repository-url>
cd cryptop2ptradingplatform-f8a0bc
```

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

3. Set up environment variables (optional):
```bash
# Create .env file with the following variables (all optional):
SECRET_KEY=your-secret-key-here
SERVER_HOST=http://localhost:8000
PAYMENT_PROVIDER_API_URL=https://api.your-payment-provider.com
PAYMENT_PROVIDER_API_KEY=your-payment-provider-api-key
```

4. Run database migrations:
```bash
alembic upgrade head
```

5. Start the application:
```bash
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```

## Environment Variables

The following environment variables can be configured:

- `SECRET_KEY`: Secret key for JWT token generation (default: auto-generated)
- `SERVER_HOST`: Server host URL for API documentation links (default: http://localhost:8000)
- `PAYMENT_PROVIDER_API_URL`: Payment provider API base URL (optional)
- `PAYMENT_PROVIDER_API_KEY`: Payment provider API key (optional)

## API Documentation

Once the application is running, you can access:

- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc
- **OpenAPI JSON**: http://localhost:8000/openapi.json

## API Endpoints

### Authentication
- `POST /api/v1/auth/register` - Register a new user
- `POST /api/v1/auth/login` - Login and get access token

### Users
- `GET /api/v1/users/me` - Get current user profile
- `PUT /api/v1/users/me` - Update current user profile

### Cryptocurrencies
- `GET /api/v1/cryptocurrencies/` - List supported cryptocurrencies
- `GET /api/v1/cryptocurrencies/{id}` - Get cryptocurrency details

### Wallets
- `GET /api/v1/wallets/` - Get user's wallets
- `GET /api/v1/wallets/{cryptocurrency_id}` - Get specific wallet
- `POST /api/v1/wallets/{cryptocurrency_id}/lock` - Lock funds
- `POST /api/v1/wallets/{cryptocurrency_id}/unlock` - Unlock funds

### Advertisements
- `GET /api/v1/advertisements/` - List all advertisements
- `GET /api/v1/advertisements/my` - Get user's advertisements
- `POST /api/v1/advertisements/` - Create new advertisement
- `GET /api/v1/advertisements/{id}` - Get advertisement details
- `PUT /api/v1/advertisements/{id}` - Update advertisement
- `DELETE /api/v1/advertisements/{id}` - Cancel advertisement

### Orders
- `GET /api/v1/orders/` - Get user's orders
- `POST /api/v1/orders/` - Create new order
- `GET /api/v1/orders/{id}` - Get order details
- `PUT /api/v1/orders/{id}` - Update order
- `POST /api/v1/orders/{id}/confirm-payment` - Confirm payment (buyer)
- `POST /api/v1/orders/{id}/release` - Release crypto (seller)
- `POST /api/v1/orders/{id}/cancel` - Cancel order

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

## How It Works

### Trading Flow

1. **Advertisement Creation**: Users create buy/sell advertisements specifying:
   - Cryptocurrency type and amount
   - Price per unit
   - Minimum/maximum order amounts
   - Accepted payment methods
   - Terms and conditions

2. **Order Placement**: When a buyer places an order:
   - Seller's crypto is automatically locked
   - Payment account details are generated via payment provider API
   - Order expires in 30 minutes if not completed

3. **Payment Process**: 
   - Buyer receives payment account details (account number, bank name, reference)
   - Buyer makes payment to the provided account
   - System tracks payment status via payment provider API

4. **Automatic Release**: 
   - Once payment is confirmed, crypto is automatically released to buyer's wallet
   - Seller's locked funds are transferred to buyer
   - Order status is updated to completed

### Security Features

- JWT-based authentication
- Automatic fund locking prevents double-spending
- Payment verification through external provider
- Order expiration prevents indefinite locks
- Comprehensive audit trail

## Database Models

- **Users**: User accounts with authentication
- **Cryptocurrencies**: Supported crypto types
- **Wallets**: User balances per cryptocurrency
- **Advertisements**: Buy/sell listings
- **Orders**: Trade orders with status tracking
- **Payments**: Payment details and status

## Development

### Running in Development Mode

```bash
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```

### Database Migrations

Create a new migration:
```bash
alembic revision --autogenerate -m "Description of changes"
```

Apply migrations:
```bash
alembic upgrade head
```

### Code Linting

```bash
ruff check .
ruff format .
```

## Payment Provider Integration

The platform integrates with payment providers to:
- Generate temporary payment accounts for each order
- Verify payment status automatically
- Handle payment notifications via webhooks

If no payment provider is configured, the system uses mock data for demonstration purposes.

## Health Monitoring

The `/health` endpoint provides system status information:
```json
{
  "status": "healthy",
  "service": "crypto-p2p-platform",
  "version": "1.0.0"
}
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

This project is licensed under the MIT License.