crypto-sniper-oracle

# Crypto Sniper Oracle — Quantitative Market Intelligence + Reporting

## ⚠️ SCOPE & CAPABILITIES

**Core Function:** Fetch public market data and generate quantitative analysis.

**What it does:**
- ✅ Fetches public ticker data from Binance API
- ✅ Fetches public order book data from Binance API
- ✅ Calculates Order Book Imbalance (OBI)
- ✅ Calculates VWAP divergence
- ✅ Scores liquidity quality (spread in bps)
- ✅ Generates formatted analysis reports
- ✅ **[OPTIONAL]** Sends reports via Telegram
- ✅ **[OPTIONAL]** Scheduled cron jobs for automated reports

**What it does NOT do:**
- ❌ Place orders or execute trades
- ❌ Transfer funds
- ❌ Access private exchange data
- ❌ Read agent memory (beyond its own logs)
- ❌ Intercept or block other skills

---

## 🔧 Configuration Options

### **Mode 1: Analysis Only (Default)**

**No Telegram, manual invocation:**
```bash
# Just fetch data and analyze
python3 crypto_oracle.py --symbol BTCUSDT
```

**Use case:** Manual analysis on demand.

---

### **Mode 2: Telegram Reports (Optional)**

**Enable Telegram alerts and reports:**

**Required environment variables:**
```bash
export TELEGRAM_BOT_TOKEN="your_bot_token_here"
export TELEGRAM_CHAT_ID="your_chat_id_here"
```

**Configuration:**
```json
{
  "skills": {
    "crypto-sniper-oracle": {
      "enabled": true,
      "config": {
        "telegram_enabled": true
      }
    }
  }
}
```

**Use case:** Automated reports sent to Telegram.

---

### **Mode 3: Cron Jobs + Telegram (Automated)**

**Scheduled market reports:**

**Example cron jobs:**
```bash
# Daily report at 9am UTC
0 9 * * * /workspace/skills/crypto-sniper-oracle/reporter.py --mode daily

# Hourly anomaly check
0 * * * * /workspace/skills/crypto-sniper-oracle/reporter.py --mode hourly

# Price alerts every 15min
*/15 * * * * /workspace/skills/crypto-sniper-oracle/reporter.py --mode alerts
```

**Use case:** Fully automated market monitoring.

---

## 📊 Report Templates

### **1. Daily Market Report**...

# Crypto Sniper Oracle 🎯

**Institutional-grade quantitative market oracle with automated reporting**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Version](https://img.shields.io/badge/version-3.3.0-blue.svg)](https://github.com/georges91560/crypto-sniper-oracle)
[![Python](https://img.shields.io/badge/python-3.7+-blue.svg)](https://python.org)
[![Security](https://img.shields.io/badge/security-L1%20ReadOnly-green.svg)]()

Order Book Imbalance (OBI) · VWAP Analysis · Automated Reports · Telegram Alerts

---

## 🚀 What's New in v3.3.0

✅ **Telegram Integration** (optional)  
✅ **Automated Reports** (daily, hourly, alerts)  
✅ **Cron Job Support** (scheduled monitoring)  
✅ **Report Templates** (professional formatting)  
✅ **Multi-Symbol Analysis** (aggregate reports)  

---

## 🎯 Core Features

### **1. Quantitative Analysis**
- Order Book Imbalance (OBI) detection
- VWAP divergence calculation
- Liquidity scoring (spread in bps)
- Composite risk scoring (0-100)

### **2. Automated Reporting**
- Daily market summaries
- Hourly status checks
- Real-time anomaly alerts
- Multi-symbol aggregation

### **3. Telegram Delivery (Optional)**
- Sends reports to your Telegram
- Configurable (opt-in)
- Instant alerts on anomalies
- Full message history

---

## 📊 Usage Modes

### **Mode 1: Manual Analysis**

```bash
python3 crypto_oracle.py --symbol BTCUSDT
```

**Output:** JSON data with OBI, VWAP, spread

---

### **Mode 2: Generate Report (No Telegram)**

```bash
python3 reporter.py --mode daily --symbols BTCUSDT,ETHUSDT,SOLUSDT
```

**Output:** 
- Formatted report saved to `/workspace/reports/daily_2026-02-27.md`
- No Telegram delivery

---

### **Mode 3: Automated Reports + Telegram**

**Setup:**
```bash
export TELEGRAM_BOT_TOKEN="your_bot_token"
export TELEGRAM_CHAT_ID="your_chat_id"

python3 reporter.py --mode daily --symbols BTCUSDT,ETHUSDT
```

**Output:**
- Report saved locally
- Report sent...