metadata

title: CryptoSentinel AI
emoji: 🚀
colorFrom: red
colorTo: red
sdk: docker
app_port: 7860
tags:
  - fastapi
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 to deploy as a Space (recommended).
API Keys for:
- Google Gemini: Obtain from Google AI Studio.
- (Optional but Recommended) CoinGecko: A free or Pro key from CoinGecko 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

Clone the repository:

git clone https://huggingface.co/spaces/mgbam/CryptoSentinel_AI
cd CryptoSentinel_AI

Install dependencies:
```
pip install -r requirements.txt
```
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:

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.