README.md

---
---
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.