Spaces:
Running
Running
| title: CryptoSentinel AI | |
| emoji: 🚀 | |
| colorFrom: red | |
| colorTo: red | |
| sdk: docker | |
| app_port: 7860 # ← must match the port you expose below | |
| tags: | |
| - fastapi # ← use an appropriate tag; “streamlit” only if using Streamlit | |
| pinned: false | |
| short_description: Combines cryptocurrency insights with AI-driven analytics. | |
| --- | |
| This file should be placed in the root directory of your project. It's written in Markdown. | |
| Generated markdown | |
| # 🤖 Sentinel Arbitrage Engine | |
| **Sentinel is a high-frequency, AI-powered arbitrage detection engine for cryptocurrency markets. It autonomously monitors real-time price dislocations between major decentralized oracles and provides AI-generated risk analysis and trading strategies.** | |
| This application is designed to identify and analyze fleeting arbitrage opportunities that exist between different price-reporting networks in the DeFi space. It uses a robust, multi-asset architecture and leverages Google's Gemini Pro for sophisticated, real-time decision support. | |
| --- | |
| ## ✨ Core Features | |
| * **Multi-Asset Monitoring:** Continuously tracks prices for multiple crypto assets (BTC, ETH, SOL, etc.) across different data sources simultaneously. | |
| * **Decentralized & Resilient:** Queries globally-accessible, censorship-resistant oracles (Pyth and Chainlink aggregators) to avoid CEX geoblocking and rate-limiting issues. | |
| * **AI-Powered Alpha Briefings:** For every detected opportunity, it uses the Gemini Pro API to generate a concise briefing, including: | |
| * **Risk Assessment** (LOW, MEDIUM, HIGH) | |
| * **Execution Strategy** (e.g., "Execute a flash loan arbitrage...") | |
| * **Rationale** (The "why" behind the risk assessment) | |
| * **Real-Time WebSocket UI:** The frontend uses a professional, Socket.IO-powered dashboard to display signals with millisecond latency. The UI is clean, data-dense, and built for at-a-glance interpretation. | |
| * **Asynchronous Architecture:** Built with Python, FastAPI, and `asyncio`, the entire engine is asynchronous from the ground up, ensuring high performance and concurrency. | |
| ## 🛠️ Tech Stack | |
| * **Backend:** Python 3.9+, FastAPI | |
| * **Real-Time Communication:** `python-socketio` | |
| * **Data Fetching:** `httpx` (for async HTTP requests) | |
| * **AI Engine:** Google Gemini Pro | |
| * **Data Sources:** | |
| * Pyth Network (On-chain data) | |
| * CoinGecko (Off-chain aggregated data) | |
| * **Frontend:** Vanilla JavaScript with the Socket.IO Client | |
| * **Styling:** Pico.css | |
| ## 🚀 Getting Started | |
| ### 1. Prerequisites | |
| * Python 3.9+ | |
| * An account with [Hugging Face](https://huggingface.co/) to deploy as a Space (recommended). | |
| * API Keys for: | |
| * **Google Gemini:** Obtain from [Google AI Studio](https://aistudio.google.com/). | |
| * **(Optional but Recommended)** **CoinGecko:** A free or Pro key from [CoinGecko API](https://www.coingecko.com/en/api). | |
| ### 2. Project Structure | |
| The project uses a standard package structure for scalability and maintainability. | |
| Use code with caution. | |
| Markdown | |
| / | |
| ├── app/ | |
| │ ├── init.py | |
| │ ├── arbitrage_analyzer.py | |
| │ ├── broker.py | |
| │ ├── main.py | |
| │ └── price_fetcher.py | |
| ├── static/ | |
| │ └── index.html | |
| ├── .gitignore | |
| ├── Dockerfile | |
| └── requirements.txt | |
| Generated code | |
| ### 3. Installation & Setup | |
| 1. **Clone the repository:** | |
| ```bash | |
| git clone https://huggingface.co/spaces/mgbam/CryptoSentinel_AI | |
| cd CryptoSentinel_AI | |
| ``` | |
| 2. **Install dependencies:** | |
| ```bash | |
| pip install -r requirements.txt | |
| ``` | |
| 3. **Configure Environment Secrets:** | |
| * If running locally, create a `.env` file and add your API key: | |
| ``` | |
| GEMINI_API_KEY="your_gemini_api_key_here" | |
| ``` | |
| * If deploying on Hugging Face Spaces, add `GEMINI_API_KEY` as a repository secret in your Space's **Settings** tab. | |
| ### 4. Running the Engine | |
| The application is run using `uvicorn`. From the root directory of the project, execute: | |
| ```bash | |
| uvicorn app.main:app --host 0.0.0.0 --port 7860 --reload | |
| Use code with caution. | |
| --reload enables hot-reloading for development. Remove this flag for production. | |
| Once running, navigate to http://127.0.0.1:7860 in your browser to view the Sentinel Arbitrage Engine dashboard. | |
| ⚙️ How It Works | |
| Lifespan Management: On startup, the lifespan manager in app/main.py initializes all necessary services (PriceFetcher, ArbitrageAnalyzer) and launches the main run_arbitrage_detector loop as a persistent background task. | |
| Data Fetching: The PriceFetcher runs in the background loop, making concurrent async calls to the Pyth and CoinGecko APIs to get the latest prices for all configured assets. | |
| Discrepancy Detection: The loop compares the prices from the two oracles for each asset. If the percentage difference exceeds the OPPORTUNITY_THRESHOLD, it's flagged as a potential arbitrage opportunity. | |
| AI Analysis: The detected opportunity data is passed to the ArbitrageAnalyzer, which constructs a detailed prompt for the Gemini API. | |
| Signal Emission: Gemini's structured response (Risk, Strategy, Rationale) is combined with the price data into a final "signal" object. This signal is then broadcast to all connected clients using sio.emit('new_signal', ...). | |
| Real-Time UI: The static/index.html page connects to the Socket.IO server. A JavaScript listener for the new_signal event receives the data and dynamically constructs a new table row, prepending it to the live signal stream. |