# Crypto Funding Rate Arbitrage Bot

Automated funding rate arbitrage trading system for 12 cryptocurrency exchanges.

## Project Status

**Current Version: Day 3 Complete**

- Day 1: Exchange Integrations & Funding Rate Scanner
- Day 2: Trading Engine & Position Management
- Day 3: Entry/Exit Strategies & Fee Optimization
- Day 4: Dashboard Development

## Overview

This project implements a fully automated funding rate arbitrage trading bot that:
- Monitors funding rates across 12 exchanges in real-time
- Identifies profitable arbitrage opportunities
- Executes perfect hedge positions (simultaneous long/short)
- Manages positions with optimized entry/exit strategies
- Calculates fees and validates profitability

## Architecture

### Core Componenets

**Day 1: Exchange Integrations**
- `ExchangeManager`: Handles connections to 12 exchanges using CCXT
- `FundingRateScanner`: Scans for arbitrage opportunities in real-time
- Supports: Binanace, BingX, Bitget, Bybit, Gate.io, HTX, KuCoin, MEXC, Phemex, OKX

**Day 2: Trading Engine**
- `TradingEngine`: Orchestrates opportunity execution and trading state
- `PositionManager`: Manages perfect hedge positions (long/short simultaneously)
- Order execution flow with proper error handling

**Day 3: Entry/Exit Strategies**
- `EntryStrategy`: Calculates optimal entry prices with slippage optimization
- `ExitStrategy`: Manages exits based on profit targets and time limits
- `FeeCalculator`: Calculates fees and validates net profit after fees
- `StrategyValidator`: Validates opportunities before execution

## Setup

### Prerequisites

- Python 3.9+
- Node.js 18+
- pip
- npm

### Backend Setup

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

2. Run the server:
```bash
cd backend
python main.py
```

The API will be available at `http://localhost:8000`

### Frontend Setup

1. Install Node.js dependencies:
```bash
cd frontend
npm install
```

2. Run the frontend development server:
```bash
npm run dev
```

The dashboard will be available at `http://localhost:3000`

## API Endpoints

### Opportunities
```
GET /api/opportunities - Get all arbitrage opportunities
GET /api/opportunities?symbols=BTC/USDT:USDT,ETH/USDT:USDT - Get opportunities for specific symbols
GET /api/opportunities/{symbol} - Get opportunities for a symbol
GET /api/funding-rates/{symbol} - Get funding rates across all exchanges
```

### Trading
```
POST /api/trading/execute - Execute an opportunity
POST /api/trading/enable - Enable trading
POST /api/trading/disable - Disable trading
GET /api/trading/status - Get trading engine status
```

### Position
```
GET /api/positions - Get all positions
GET /api/positions/active - Get active positions
GET /api/positions/{position_id} - Get specific position
POST /api/positions/{position_id}/close - Close a position
```

### Health
```
GET /api/health - Health check
GET / - API information
```

## Features

### Exchange Integration
- Connects to 12 major cryptocurrency exchanges
- Real-time funding rate monitoring
- Automatic reconnection handling
- Exchange-specific configuration support

### Opportunity Detection
- Scans funding rates across all exchanges
- Identifies profitable arbitrage pairs
- Calculates net funding rate after fees
- Filters opporunities by profitability threshold

### Trading Engine
- Perfect hedge execution (simultaneous long/short)
- Position lifecycle management
- Trading enable/disable controls
- Opportunity validation before execution

### Entry Strategy
- Order book depth analysis for optimal prices
- Slippage optimization (max 0.1% slippage)
- Fallback to ticker prices when needed
- Price calculation based on position size

### Exit Strategy
- Profit target-based exits
- Time-based exits (max 8 hours)
- Optimal exit price calculation
- Automatic position closing

### Fee Management
- Exchange-specific fee rates
- Total fee calculation (opening + closing)
- Net profit validation after fees
- Profitability checks before execution

## Testing

### Run Day 3 Test Script
Test all Day 3 functionality (entry/exit strategies, fee calculation):
```bash
cd backend
python test_day3.py
```

### Run Day 2 Test Script
Test Day 2 functionality (trading engine, position management):
```bash
cd backend
python test_day2.py
```

### Run Day 1 Test Script
Test Day 1 functionality (exchange connections, funding rate scanner):
```bash
cd backend
python test_day1.py
```

### Run Scanner CLI
Quick scan for opportunities:
```bash
cd backend
python run_scanner.py
python run_scanner.py BTC/USDT:USDT ETH/USDT:USDT
```

### Test API Endpoints
Once the server is running:
```bash
curl http://localhost:8000/api/opportunities
curl http://localhost:8000/api/funding-rates/BTC/USDT:USDT
curl http://localhost:8000/api/health
```

## Project Structure

```
Crypto Funding Rate Arbitrage Bot/
├── backend/
│   ├── main.py                 # FastAPI application
│   ├── core/
│   │   ├── exchange_manager.py      # Exchange connections
│   │   ├── funding_rate_scanner.py  # Opportunity scanner
│   │   ├── trading_engine.py         # Trading orchestration
│   │   ├── position_manager.py       # Position management
│   │   ├── entry_strategy.py         # Entry price optimization
│   │   ├── exit_strategy.py          # Exit conditions
│   │   ├── fee_calculator.py         # Fee calculations
│   │   └── strategy_validator.py     # Pre-execution validation
│   ├── api/
│   │   └── routes/
│   │       ├── opportunities.py      # Opportunity endpoints
│   │       ├── trading.py             # Trading endpoints
│   │       └── positions.py           # Position endpoints
│   ├── websocket/
│   │   └── manager.py                # WebSocket connection manager
│   ├── test_day1.py            # Day 1 tests
│   ├── test_day2.py            # Day 2 tests
│   ├── test_day3.py            # Day 3 tests
│   └── run_scanner.py          # CLI scanner tool
├── frontend/
│   ├── app/
│   │   ├── layout.tsx          # Root layout
│   │   ├── page.tsx            # Main page
│   │   └── globals.css         # Global styles
│   ├── components/
│   │   ├── Dashboard.tsx       # Main dashboard
│   │   ├── Header.tsx          # Header component
│   │   ├── StatsCards.tsx      # Stats cards
│   │   ├── OpportunitiesTable.tsx  # Opportunities table
│   │   ├── PositionsTable.tsx      # Positions table
│   │   ├── TradingControls.tsx     # Trading controls
│   │   ├── PerformanceChart.tsx    # Performance chart
│   │   └── FundingRateChart.tsx    # Funding rate chart
│   ├── contexts/
│   │   └── WebSocketContext.tsx    # WebSocket context
│   └── package.json            # Node.js dependencies
├── requirements.txt            # Python dependencies
└── README.md                   # This file
```

## Configuration

### Exchange Fees
Default fee rates are configured in `FeeCalculator`. Exchange-specific fees can be customized:
- Binance: 0.02% maker, 0.04% taker
- Bybit: 0.01% maker, 0.06% taker
- OKX: 0.02% maker, 0.05 taker

### Trading Parameters
- Default position size: 0.01 BTC equivalent
- Max slippage: 0.1%
- Min net funding rate: 0.02%
- Max position duration: 8 hours

## Development Progress

### Day 1
- Exchange integrations (12 exchanges)
- Real-time funding rate scanner
- Opportunity detection
- REST API endpoints

### Day 2
- Trading engine foundation
- Perfect hedge execution
- Position management
- Order execution flow

### Day 3
- Entry strategy with slippage optimization
- Exit strategy with profit targets
- Fee calculation and validation
- Strategy validation before execution

### Day 4
- Modern dashboard with real-time updates
- WebSocket integration for live data
- Performance charts and visualizations
- Trading controls and position management UI

## Notes

- **API Keys**: Required for live trading. The system works in demo mode without keys.
- **Testing**: All components are tested and working. Actual order placement requires API keys.
- **Security**: API keys should be stored securely and never committed to the repository.