proxmox/docs/archive/historical/ORACLE_API_KEYS_REQUIRED.md

# Oracle Publisher API Keys - Requirements

**Date**: $(date)  
**Status**: API Keys Recommended/Required

---

## 🔍 Current Issues

### CoinGecko API
- **Error**: `429 Too Many Requests`
- **Cause**: Free tier rate limit exceeded
- **Solution**: API key recommended for higher rate limits
- **Status**: API key is **OPTIONAL** but **RECOMMENDED**

### Binance API
- **Error**: `451 Service unavailable from a restricted location`
- **Cause**: Geo-blocking (not API key issue)
- **Solution**: Use alternative API or proxy
- **Status**: API key won't help - need alternative data source

---

## ✅ API Key Requirements

### CoinGecko API Key (Recommended)

**Why**: Free tier has strict rate limits (10-50 calls/minute). With an API key, you get:
- Higher rate limits (up to 500 calls/minute for paid plans)
- More reliable service
- Better support

**How to Get**:
1. Visit: https://www.coingecko.com/en/api/pricing
2. Sign up for free tier (Basic plan)
3. Get your API key from dashboard

**How to Configure**:
```bash
# Add to /opt/oracle-publisher/.env
COINGECKO_API_KEY=your_api_key_here
```

**Update URL**:
```bash
# Original (no key):
DATA_SOURCE_1_URL=https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd

# With API key:
DATA_SOURCE_1_URL=https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd&x_cg_demo_api_key=YOUR_KEY
# OR (for Pro):
DATA_SOURCE_1_URL=https://pro-api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd&x_cg_pro_api_key=YOUR_KEY
```

### Binance API

**Status**: Not an API key issue - Binance is geo-blocking requests from certain locations.

**Solutions**:
1. **Remove Binance** - Use only CoinGecko (with API key)
2. **Use Alternative APIs**:
   - CoinMarketCap (requires API key)
   - CryptoCompare (free tier available)
   - OpenExchangeRates (for fiat conversions)

---

## 🔧 Recommended Configuration

### Option 1: CoinGecko Only (with API key)

```bash
# /opt/oracle-publisher/.env
DATA_SOURCE_1_URL=https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd&x_cg_demo_api_key=YOUR_KEY
DATA_SOURCE_1_PARSER=ethereum.usd
# Remove or comment out Binance source
# DATA_SOURCE_2_URL=...
```

### Option 2: Multiple Sources (CoinGecko + Alternative)

```bash
# CoinGecko (with API key)
DATA_SOURCE_1_URL=https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd&x_cg_demo_api_key=YOUR_KEY
DATA_SOURCE_1_PARSER=ethereum.usd

# Alternative: CryptoCompare (no key needed)
DATA_SOURCE_2_URL=https://min-api.cryptocompare.com/data/price?fsym=ETH&tsyms=USD
DATA_SOURCE_2_PARSER=USD
```

### Option 3: CoinMarketCap (requires API key)

```bash
DATA_SOURCE_1_URL=https://pro-api.coinmarketcap.com/v1/cryptocurrency/quotes/latest?symbol=ETH&convert=USD
DATA_SOURCE_1_PARSER=data.ETH.quote.USD.price
COINMARKETCAP_API_KEY=your_key_here
# Add header: X-CMC_PRO_API_KEY: your_key_here
```

---

## 🚀 Quick Fix: Add CoinGecko API Key

```bash
ssh root@192.168.11.10
pct exec 3500 -- bash
cd /opt/oracle-publisher
nano .env

# Add or update:
COINGECKO_API_KEY=your_api_key_here
DATA_SOURCE_1_URL=https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd&x_cg_demo_api_key=${COINGECKO_API_KEY}

# Remove Binance (geo-blocked):
# DATA_SOURCE_2_URL=https://api.binance.com/api/v3/ticker/price?symbol=ETHUSDT

# Save and restart service
systemctl restart oracle-publisher
```

---

## 📝 Update Python Script

The Python script needs to be updated to:
1. Support API keys in URLs (template variables)
2. Add custom headers for APIs that require them (like CoinMarketCap)
3. Handle API key rotation

**Example update needed**:
```python
# In fetch_price_from_source method
url = source.url
if hasattr(config, 'coingecko_api_key') and config.coingecko_api_key:
    url = url.replace('${COINGECKO_API_KEY}', config.coingecko_api_key)

headers = {}
if 'coinmarketcap' in url.lower() and hasattr(config, 'coinmarketcap_api_key'):
    headers['X-CMC_PRO_API_KEY'] = config.coinmarketcap_api_key

response = requests.get(url, headers=headers, timeout=10)
```

---

## ✅ Summary

| API | API Key Required? | Current Issue | Solution |
|-----|------------------|---------------|----------|
| **CoinGecko** | Optional (recommended) | Rate limiting (429) | Get free API key for higher limits |
| **Binance** | No | Geo-blocking (451) | Remove or use alternative API |
| **CoinMarketCap** | Yes | Not configured | Add API key if using |
| **CryptoCompare** | No | Not configured | Free alternative option |

---

**Recommendation**: Get a free CoinGecko API key and remove Binance source.

---

**Last Updated**: $(date)