A real-time cryptocurrency arbitrage detection and trading system that monitors multiple exchanges for price differences and executes trades to profit from these differences.
This project consists of two main components:
- Backend (C# / .NET 9): A high-performance arbitrage detection and trading engine with a REST API and real-time SignalR hubs.
- Frontend (React/TypeScript): A web dashboard for monitoring arbitrage opportunities, trade results, and controlling the bot.
- Real-time arbitrage opportunity detection across multiple cryptocurrency exchanges
- Configurable risk management and trade parameters
- Paper trading mode for testing without real funds
- Dashboard for visualization of opportunities, trades, and statistics
- SignalR-based real-time updates
- Detailed statistics and performance metrics
- Extensible architecture for adding new exchanges
src/CryptoArbitrage.Domain- Domain models and entitiessrc/CryptoArbitrage.Application- Application logic, interfaces, and servicessrc/CryptoArbitrage.Infrastructure- Implementation of interfaces, repositories, exchange clientssrc/CryptoArbitrage.Api- REST API and SignalR hubs for frontend communicationsrc/CryptoArbitrage.Worker- Background worker for running the bottests/CryptoArbitrage.Tests- Unit and integration testsfrontend/arbitrage-dashboard- React web dashboard
- .NET 9 SDK
- Node.js (v16+) and npm (for frontend development)
- Docker and Docker Compose (for containerized setup)
- Git
-
Clone the repository:
git clone https://github.com/yourusername/crypto-arbitrage.git cd crypto-arbitrage -
Make the run script executable:
chmod +x run.sh
-
Run the application:
./run.sh
This will:
- Build and start the API project
- Start the Worker service
- Configure required services
-
Clone the repository:
git clone https://github.com/yourusername/crypto-arbitrage.git cd crypto-arbitrage -
Build the solution:
dotnet build
-
Run the API:
cd src/CryptoArbitrage.Api dotnet run
The API will be available at https://localhost:7000 with Swagger documentation at https://localhost:7000/swagger.
-
Navigate to the frontend directory:
cd frontend/arbitrage-dashboard -
Install dependencies:
npm install
-
Start the development server:
npm start
The dashboard will be available at http://localhost:3000.
This project includes Docker support for running the entire stack in containers, which is recommended for production or testing environments.
- API Service: The REST API that provides endpoints for managing the arbitrage system.
- Worker Service: The background worker that monitors exchanges and executes arbitrage opportunities.
- MongoDB: Database for storing arbitrage opportunities, trade results, and configurations.
- Redis: Used for caching and real-time messaging between services.
- Frontend: The React web dashboard.
We've provided a convenient shell script to manage the services. Make it executable first:
chmod +x start.shStart all services:
./start.shThis will build and start all services in the background. You can also use direct Docker Compose commands:
# Start in the background
docker-compose up -d
# Start in the foreground with logs
docker-compose up
# Stop services
docker-compose down
# Rebuild services
docker-compose build
# View logs
docker-compose logs -f- Frontend: http://localhost:3000
- API: http://localhost:5001/api
- MongoDB: mongodb://localhost:27017 (username: admin, password: password)
- Redis: localhost:6379
The system configuration is managed through appsettings.json files:
- A root-level
appsettings.jsoncontains global configuration shared between services - Service-specific configurations exist in their respective project directories
- Trading pairs to monitor
- Risk profile parameters (profit thresholds, position sizes, etc.)
- Exchange API credentials
- Paper trading settings
- Notification 8000 preferences
To use the bot with real exchanges, you need to configure API keys for each exchange in the settings section of the dashboard or in the appsettings.json file.
By default, the system is configured to run in paper trading mode, which means no real trades will be executed. This is ideal for testing and development.
To enable live trading (use with caution):
-
Edit the
appsettings.jsonfile:"CryptoArbitrage": { "PaperTradingEnabled": false, ... }
-
Add your exchange API keys:
"Exchanges": { "binance": { "ApiKey": "YOUR_API_KEY", "ApiSecret": "YOUR_API_SECRET", ... } }
Note: For security reasons, never commit your actual API keys to version control. Use environment variables or secrets management for production environments.
The project follows a clean architecture approach with:
- Domain-driven design principles
- CQRS pattern for separating reads and writes
- Repository pattern for data access
- Dependency injection for loose coupling
- SignalR for real-time communication
- React with Material-UI for the frontend
This project includes comprehensive testing to ensure API contracts are maintained:
./verify-contracts.shThis script verifies that:
- Frontend expects endpoints that exist in the OpenAPI specification
- Backend actually implements all endpoints defined in the OpenAPI specification
- Contract alignment is maintained across all layers
To prevent API contract issues from reoccurring, run:
# Run backend regression tests
cd backend
dotnet test --filter "ApiContractRegressionTests"
dotnet test --filter "OpenApiContractTests"These tests specifically verify:
- Critical endpoint availability: Ensures endpoints like
/api/statistics,/api/settings/bot/activity-logs, and/api/settings/bot/exchange-statusdon't go missing again - Bot control success responses: Verifies that start/stop endpoints return
success: truewhen they succeed - Response format consistency: Validates that endpoints return expected JSON structures (arrays vs objects)
- Status code correctness: Ensures endpoints return 200 OK instead of 404 Not Found
# Run comprehensive endpoint testing including regression tests
./test-backend-endpoints.shThis script:
- Tests all critical endpoints for HTTP 200 responses
- Runs automated regression tests
- Provides detailed results and prevents deployment of broken contracts
# Backend tests
cd backend
dotnet test
# Frontend tests
cd frontend/arbitrage-dashboard
npm test- Services fail to start: Ensure ports 3000, 5001, 27017, and 6379 are not already in use on your system.
- Connection issues between services: Make sure all services are running with
docker-compose ps. - API unreachable: Check if the service is running and view logs with
docker-compose logs api. - No arbitrage opportunities detected: Verify that the worker service is running and that the configuration is correct.
- Frontend connectivity issues: Ensure the API service is running and check browser console for CORS or other connection errors.
Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the MIT License - see the LICENSE file for details.
Trading cryptocurrencies involves significant risk. This software is for educational purposes only. Use at your own risk.