proxmox/docs/04-configuration/COINGECKO_API_KEY_SETUP.md

# CoinGecko API Key Configuration

**Last Updated:** 2026-01-31  
**Document Version:** 1.0  
**Status:** Active Documentation

---

**Date:** 2026-01-26  
**Status:** ✅ **API Key Added**

---

## ✅ API Key Added

**CoinGecko API Key:** `your-coingecko-api-key`

**Key Type:** Demo API Key (Free tier)  
**Format:** `CG-...` prefix indicates demo API key

---

## 📋 Where the API Key is Used

### 1. Token Aggregation Service

**Location:** `smom-dbis-138/services/token-aggregation/`

**Configuration:**
- **File:** `.env` or `.env.example`
- **Variable:** `COINGECKO_API_KEY=your-coingecko-api-key`

**Usage:**
- The `CoinGeckoAdapter` automatically uses this key
- Uses Pro API endpoint when key is present: `https://pro-api.coingecko.com/api/v3`
- Sends key in header: `x-cg-pro-api-key: your-coingecko-api-key`
- Provides higher rate limits (500+ calls/minute vs 10-50 without key)

**Code Reference:**
```typescript
// smom-dbis-138/services/token-aggregation/src/adapters/coingecko-adapter.ts
this.apiKey = process.env.COINGECKO_API_KEY;
const baseURL = this.apiKey
  ? 'https://pro-api.coingecko.com/api/v3'
  : 'https://api.coingecko.com/api/v3';
```

---

### 2. Oracle Publisher Service

**Location:** VMID 3500 (Oracle Publisher Container)  
**Path:** `/opt/oracle-publisher/.env`

**Configuration:**
The Oracle Publisher service can use the CoinGecko API key in the URL:

**Option 1: Using Environment Variable in URL**
```bash
COINGECKO_API_KEY=your-coingecko-api-key
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}
DATA_SOURCE_1_PARSER=ethereum.usd
```

**Option 2: Direct URL with Key**
```bash
DATA_SOURCE_1_URL=https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd&x_cg_demo_api_key=your-coingecko-api-key
DATA_SOURCE_1_PARSER=ethereum.usd
```

**Note:** The Oracle Publisher service uses the demo API key format (`x_cg_demo_api_key`) in the URL.

---

## 🔧 Setup Instructions

### For Token Aggregation Service

**Step 1: Update .env file**

```bash
cd smom-dbis-138/services/token-aggregation
nano .env
```

**Step 2: Add or update the key**

```bash
COINGECKO_API_KEY=your-coingecko-api-key
```

**Step 3: Restart service** (if running)

```bash
# If using Docker
docker-compose restart

# If using systemd
systemctl restart token-aggregation
```

---

### For Oracle Publisher Service

**Gas (Chain 138 / Besu):** In `/opt/oracle-publisher/.env`, use **`GAS_LIMIT=400000`** (not `100000`). The aggregator `updateAnswer` call can **run out of gas** at 100k (`gasUsed == gasLimit`, failed receipt) even when `isTransmitter` is true. Align with `ORACLE_UPDATE_GAS_LIMIT` in `smom-dbis-138/scripts/update-oracle-price.sh`. **`GAS_PRICE=1000000000`** (1 gwei) matches that script’s legacy defaults.

**Quoted URLs in `.env`:** `DATA_SOURCE_1_URL` (and Coinbase `DATA_SOURCE_2_URL`) must be **double-quoted** when passed through **systemd `EnvironmentFile`**, because unquoted `&` in query strings can be parsed incorrectly and corrupt the value. **`scripts/update-oracle-publisher-coingecko-key.sh`** uses `grep` + `append` (not `sed` with `&` in the replacement). Do not use `sed 's|...|...&...|'` for URLs that contain `&`.

**Dotenv sources for provisioning:** `scripts/lib/load-project-env.sh` loads **project root `.env`** then **`smom-dbis-138/.env`** — so `PRIVATE_KEY` / `DEPLOYER_PRIVATE_KEY`, `COINGECKO_API_KEY` (root `.env`), and `AGGREGATOR_ADDRESS` are available to `scripts/deployment/provision-oracle-publisher-lxc-3500.sh` and `scripts/update-oracle-publisher-coingecko-key.sh`.

**Step 1: SSH to Proxmox host**

```bash
ssh root@192.168.11.12
```

**Step 2: Access Oracle Publisher container** (VMID 3500 runs on **r630-02**)

```bash
pct exec 3500 -- bash
cd /opt/oracle-publisher
nano .env
```

**Step 3: Add CoinGecko API key**

```bash
# Add the key
COINGECKO_API_KEY=your-coingecko-api-key

# Update DATA_SOURCE_1_URL to include the key
DATA_SOURCE_1_URL=https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd&x_cg_demo_api_key=your-coingecko-api-key
DATA_SOURCE_1_PARSER=ethereum.usd
```

**Or use environment variable:**

```bash
COINGECKO_API_KEY=your-coingecko-api-key
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}
DATA_SOURCE_1_PARSER=ethereum.usd
```

**Step 4: Restart service**

```bash
systemctl restart oracle-publisher
systemctl status oracle-publisher
```

---

## 🔍 Verification

### Verify Token Aggregation Service

```bash
# Check if key is loaded
cd smom-dbis-138/services/token-aggregation
grep COINGECKO_API_KEY .env

# Test CoinGecko adapter
npm run test -- coingecko-adapter.test.ts
```

### Verify Oracle Publisher Service

```bash
# Check .env file
ssh root@192.168.11.12 "pct exec 3500 -- cat /opt/oracle-publisher/.env | grep COINGECKO"

# Check service logs
ssh root@192.168.11.12 "pct exec 3500 -- journalctl -u oracle-publisher -n 50 | grep -i coingecko"

# Should see successful price fetches without 429 rate limit errors
```

---

## 📊 API Key Benefits

### Without API Key
- **Rate Limit:** 10-50 calls/minute
- **Endpoint:** `https://api.coingecko.com/api/v3`
- **Issues:** Frequent 429 "Too Many Requests" errors

### With API Key (Demo/Free Tier)
- **Rate Limit:** 500+ calls/minute
- **Endpoint:** `https://pro-api.coingecko.com/api/v3` (for token-aggregation)
- **Benefits:** 
  - Higher rate limits
  - More reliable service
  - Better support
  - No 429 errors (within limits)

---

## 🔐 Security Notes

1. **Never commit API keys to version control**
   - ✅ `.env` files are in `.gitignore`
   - ✅ `.env.example` files have placeholder values
   - ⚠️ Never commit actual `.env` files

2. **Key Rotation**
   - Rotate keys if accidentally exposed
   - Monitor API usage for suspicious activity
   - Use different keys for dev/staging/production

3. **Access Control**
   - Limit access to `.env` files (chmod 600)
   - Use secrets management in production (AWS Secrets Manager, Azure Key Vault, etc.)

---

## 📝 Files Updated

1. ✅ **Root `.env.example`**
   - Added `COINGECKO_API_KEY=your-coingecko-api-key`
   - Added section for Price Feed & Market Data APIs

2. ✅ **Token Aggregation `.env.example`**
   - Updated `COINGECKO_API_KEY` with actual key
   - Added comment with documentation link

---

## 🚀 Next Steps

1. **Update Actual .env Files**
   - Copy key from `.env.example` to `.env` files
   - Update Oracle Publisher service `.env` (VMID 3500)
   - Restart services to apply changes

2. **Verify Services**
   - Test Token Aggregation service with CoinGecko
   - Verify Oracle Publisher fetches prices successfully
   - Check logs for rate limit errors (should be gone)

3. **Monitor Usage**
   - Monitor API usage in CoinGecko dashboard
   - Check service logs for any errors
   - Verify price updates are working

---

## 📚 Related Documentation

- **Oracle Setup:** `docs/04-configuration/metamask/ORACLE_PRICE_FEED_SETUP.md`
- **Token Aggregation:** `smom-dbis-138/services/token-aggregation/README.md`
- **Oracle Publisher (VMID 3500):** [ALL_VMIDS_ENDPOINTS.md](ALL_VMIDS_ENDPOINTS.md) (Oracle & Monitoring table)

---

**Last Updated:** 2026-01-26  
**Status:** ✅ API key added to configuration files