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**
**Trigger:** Cron (9am daily) or manual command
**Content:**
```markdown
📊 CRYPTO MARKET DAILY REPORT
{date} | Powered by Wesley
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯 MARKET OVERVIEW (10 pairs analyzed)
🟢 BULLISH SETUPS (OBI > +0.15)
• BTCUSDT: OBI +0.18, Spread 2.1 bps
Price vs VWAP: +0.5% (above average)
Signal: Strong buying pressure
• ETHUSDT: OBI +0.12, Spread 3.5 bps
Price vs VWAP: +0.3%
Signal: Moderate bullish
🔴 BEARISH SETUPS (OBI < -0.15)
• SOLUSDT: OBI -0.16, Spread 8.2 bps
Price vs VWAP: -0.8%
Signal: Selling pressure
💰 LIQUIDITY QUALITY
Excellent (< 5 bps): 5 pairs
Good (5-10 bps): 3 pairs
Poor (> 30 bps): 2 pairs
📈 TOP MOVERS (24h)
+12.3% SOLUSDT (volatility: HIGH)
+8.1% ETHUSDT (volatility: MODERATE)
-5.2% BNBUSDT (volatility: MODERATE)
🎯 TRADING OPPORTUNITIES
→ BTC: Bullish setup confirmed (OBI +0.18)
→ ETH: Moderate strength, watch for breakout
→ SOL: Avoid - selling pressure + poor liquidity
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Generated: 2026-02-27 09:00:00 UTC
Next report: 2026-02-28 09:00:00 UTC
```
---
### **2. Anomaly Alert**
**Trigger:** OBI spike, spread explosion, or volume surge
**Content:**
```markdown
🚨 MARKET ANOMALY DETECTED
Time: 15:23:45 UTC
Asset: BTCUSDT
📊 Anomaly Type: OBI SPIKE
• Previous OBI: +0.05
• Current OBI: +0.22
• Change: +340% in 15 minutes
💰 Liquidity: EXCELLENT (2.3 bps)
📈 Price vs VWAP: +0.6%
💡 Implication:
Strong buying pressure surge detected.
Potential upward price movement imminent.
🎯 Suggested Action:
Consider LONG entry if other signals align.
Monitor closely for next 30 minutes.
[View Full Analysis]
```
---
### **3. Hourly Summary**
**Trigger:** Cron (every hour)
**Content:**
```markdown
⚡ HOURLY MARKET CHECK
{timestamp}
🔍 Scanned: 10 pairs
🟢 Bullish: 3
🔴 Bearish: 2
⚪ Neutral: 5
📊 Notable Changes:
• BTC OBI: +0.05 → +0.12 (↑)
• ETH Spread: 3.2 → 5.8 bps (↑)
⚠️ Alerts: None
Next check: {next_hour}
```
---
## 🔐 File Access (Expanded)
**READ:**
- `/workspace/skills/crypto-sniper-oracle/crypto_oracle.py` (data fetcher)
- `/workspace/skills/crypto-sniper-oracle/reporter.py` (report generator)
- `/workspace/skills/crypto-sniper-oracle/templates/*.md` (report templates)
**WRITE:**
- `/workspace/.oracle_cache.json` (45s cache)
- `/workspace/MARKET_ANALYSIS.md` (analysis reports)
- `/workspace/TRADING_LOGS.md` (audit trail)
- `/workspace/reports/daily_{date}.md` (archived reports)
- `/workspace/reports/alerts_{date}.log` (alert history)
---
## 🌐 Network Access (Expanded)
**Always allowed:**
- ✅ `https://api.binance.com/api/v3/*` (public market data)
**Conditionally allowed (if Telegram enabled):**
- ✅ `https://api.telegram.org/bot{token}/*` (send messages only)
**Never allowed:**
- ❌ Binance private endpoints
- ❌ Order placement endpoints
- ❌ Withdrawal endpoints
---
## 📋 Cron Job Specifications
### **Daily Report**
```bash
# Schedule: 9am UTC daily
0 9 * * * /workspace/skills/crypto-sniper-oracle/reporter.py --mode daily --symbols BTCUSDT,ETHUSDT,SOLUSDT,BNBUSDT,ADAUSDT
# What it does:
1. Fetch data for all symbols
2. Calculate OBI, VWAP, spread for each
3. Aggregate into daily report
4. Send via Telegram (if enabled)
5. Archive to /workspace/reports/daily_{date}.md
```
---
### **Hourly Check**
```bash
# Schedule: Every hour
0 * * * * /workspace/skills/crypto-sniper-oracle/reporter.py --mode hourly --symbols BTCUSDT,ETHUSDT
# What it does:
1. Quick scan of key pairs
2. Compare vs previous hour
3. Detect significant changes
4. Alert if anomaly detected
```
---
### **Price Alerts**
```bash
# Schedule: Every 15 minutes
*/15 * * * * /workspace/skills/crypto-sniper-oracle/reporter.py --mode alerts --symbols BTCUSDT
# What it does:
1. Check for OBI spikes (>50% change)
2. Check for spread explosions (>100% increase)
3. Check for volume surges (>200% of average)
4. Send immediate Telegram alert if detected
```
---
## 🛠️ How It Works
### **LAYER 1 — Data Acquisition (Unchanged)**
Same as v3.2.1 - uses `crypto_oracle.py` to fetch data.
---
### **LAYER 2 — Report Generation (NEW)**
```
PROCEDURE Generate_Report(mode, symbols):
1. FETCH DATA FOR ALL SYMBOLS
For each symbol in symbols:
data[symbol] = call_oracle(symbol)
2. AGGREGATE METRICS
Calculate:
- How many bullish (OBI > 0.15)
- How many bearish (OBI < -0.15)
- Average spread across all symbols
- Top movers by price change %
3. LOAD TEMPLATE
template = load_template(f"{mode}_report.md")
4. POPULATE TEMPLATE
report = template.format(
date=now(),
bullish_pairs=format_bullish(data),
bearish_pairs=format_bearish(data),
liquidity_summary=format_liquidity(data),
top_movers=format_movers(data)
)
5. SAVE REPORT
Write to /workspace/reports/{mode}_{date}.md
6. IF TELEGRAM ENABLED:
send_telegram_message(report)
7. LOG EXECUTION
Write to /workspace/TRADING_LOGS.md
```
---
### **LAYER 3 — Telegram Delivery (NEW)**
```
PROCEDURE Send_Telegram_Report(report):
1. VALIDATE CREDENTIALS
IF TELEGRAM_BOT_TOKEN not set:
→ Log error: "Telegram not configured"
→ ABORT
IF TELEGRAM_CHAT_ID not set:
→ Log error: "Chat ID not configured"
→ ABORT
2. FORMAT MESSAGE
# Telegram has 4096 char limit
IF len(report) > 4000:
→ Split into multiple messages
→ Send sequentially
3. SEND VIA API
POST https://api.telegram.org/bot{token}/sendMessage
Body:
{
"chat_id": "{chat_id}",
"text": "{report}",
"parse_mode": "Markdown"
}
4. HANDLE RESPONSE
IF success:
→ Log: "Report sent to Telegram"
IF error:
→ Log error details
→ Retry once after 5s
→ If still fails: Save to /workspace/failed_reports/
```
---
## 🔒 Security & Privacy
### **Data Collection:**
- Public market data only
- No authentication for Binance API
- No personal data
### **Data Processing:**
- All calculations local
- Cache temporary (45s TTL)
- Reports stored locally
### **Telegram (Optional):**
- User must explicitly enable
- User provides bot token + chat ID
- Only sends TO user's Telegram
- No data sent to third parties
- Can be disabled anytime
### **Transparency:**
- All Telegram sends logged
- All reports archived
- Full audit trail in TRADING_LOGS.md
---
## 📚 Installation & Setup
### **Basic Setup (No Telegram):**
```bash
git clone https://github.com/georges91560/crypto-sniper-oracle.git
cd crypto-sniper-oracle
cp -r * /workspace/skills/crypto-sniper-oracle/
chmod +x /workspace/skills/crypto-sniper-oracle/*.py
```
---
### **Telegram Setup (Optional):**
**Step 1: Create Telegram Bot**
```
1. Open Telegram, search @BotFather
2. Send: /newbot
3. Follow prompts, get BOT_TOKEN
```
**Step 2: Get Chat ID**
```
1. Send message to your bot
2. Visit: https://api.telegram.org/bot{YOUR_TOKEN}/getUpdates
3. Find "chat":{"id":123456789}
```
**Step 3: Configure**
```bash
export TELEGRAM_BOT_TOKEN="1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"
export TELEGRAM_CHAT_ID="123456789"
```
**Step 4: Test**
```bash
python3 /workspace/skills/crypto-sniper-oracle/reporter.py --mode test
```
Expected: "✅ Test message sent to Telegram"
---
### **Cron Setup (Optional):**
```bash
# Edit crontab
crontab -e
# Add jobs:
0 9 * * * /workspace/skills/crypto-sniper-oracle/reporter.py --mode daily
0 * * * * /workspace/skills/crypto-sniper-oracle/reporter.py --mode hourly
*/15 * * * * /workspace/skills/crypto-sniper-oracle/reporter.py --mode alerts
```
---
## 📊 Usage Examples
### **Example 1: Manual Analysis**
```bash
python3 crypto_oracle.py --symbol BTCUSDT
```
**Output:** JSON data (same as v3.2.1)
---
### **Example 2: Generate Report (No Telegram)**
```bash
python3 reporter.py --mode daily --symbols BTCUSDT,ETHUSDT
```
**Output:**
- Report saved to `/workspace/reports/daily_2026-02-27.md`
- No Telegram send
---
### **Example 3: Generate + Send Telegram**
```bash
# With env vars set
export TELEGRAM_BOT_TOKEN="..."
export TELEGRAM_CHAT_ID="..."
python3 reporter.py --mode daily --symbols BTCUSDT,ETHUSDT
```
**Output:**
- Report saved locally
- Report sent to Telegram
- Logged in TRADING_LOGS.md
---
### **Example 4: Alert Check**
```bash
python3 reporter.py --mode alerts --symbols BTCUSDT
```
**If anomaly detected:**
```
🚨 Alert sent to Telegram
📝 Logged to /workspace/reports/alerts_2026-02-27.log
```
**If no anomaly:**
```
✅ No alerts - market normal
```
---
## 🎯 Transparency Statement
### **What This Skill Does:**
**Without Telegram:**
- Fetches public data
- Calculates metrics
- Generates reports
- Saves locally
**With Telegram (User Opt-In):**
- All of above PLUS
- Sends reports to user's Telegram
- User must provide bot token + chat ID
- User can disable anytime
### **What This Skill Does NOT Do:**
- Does NOT read agent memory
- Does NOT intercept other skills
- Does NOT trade or place orders
- Does NOT access private data
- Does NOT send data to third parties (except user's own Telegram if enabled)
### **Network Behavior:**
**Default:**
- Binance public API only
**With Telegram Enabled:**
- Binance public API
- Telegram API (send messages only, to user's bot)
---
## 📄 License
MIT License - See [LICENSE](LICENSE)
---
**Version:** 3.3.0
**Security Level:** L1 (Default) / L2 (With Telegram)
**Author:** Georges Andronescu (Wesley Armando)
**Repository:** https://github.com/georges91560/crypto-sniper-oracle
---
**END OF SKILL**
标签
skill
ai
