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:

// 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

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

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

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

Step 2: Add or update the key

COINGECKO_API_KEY=your-coingecko-api-key

Step 3: Restart service (if running)

# If using Docker
docker-compose restart

# If using systemd
systemctl restart token-aggregation

---

For Oracle Publisher Service

Step 1: SSH to Proxmox host

ssh root@192.168.11.10

Step 2: Access Oracle Publisher container

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

Step 3: Add CoinGecko API key

# 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:

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

systemctl restart oracle-publisher
systemctl status oracle-publisher

---

🔍 Verification

Verify Token Aggregation Service

# 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

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

# Check service logs
ssh root@192.168.11.10 "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 (Oracle & Monitoring table)

---

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