DEV Community

Paarthurnax
Paarthurnax

Posted on

Connect CoinGecko API to Your Local AI Agent: Step-by-Step

#cryptocurrency #ai #python #beginners

Connect CoinGecko API to Your Local AI Agent: Step-by-Step

Real-time market data is the foundation of any useful crypto AI agent. Without accurate, fresh price data, your agent is flying blind.

CoinGecko is the best free option for this in 2026 — it covers 10,000+ coins, provides historical data, volume, market cap, and developer activity metrics. And their free API tier is genuinely useful.

This guide walks you through connecting CoinGecko to an OpenClaw local AI agent, step by step.

⚠️ Disclaimer: Not financial advice. Paper trading only. You can lose 100% of capital.

Why CoinGecko?

Before we start, a quick comparison of crypto data APIs:

API Free Tier Rate Limit Coverage
CoinGecko Yes (Demo) 30 calls/min 10,000+ coins
CoinMarketCap Limited 333 calls/day 9,000+ coins
Binance Yes 1200 calls/min Binance pairs only
Kraken Yes Varies Kraken pairs only

CoinGecko wins on coverage and simplicity. The free tier is enough for any home trader setup.

Step 1: Create Your CoinGecko Account

  1. Navigate to coingecko.com
  2. Click "Sign Up" in the top right
  3. Verify your email
  4. Go to Developer → API Keys in your dashboard
  5. Click "+ New API Key"
  6. Select Demo (free tier)
  7. Name it something like "OpenClaw Local Agent"
  8. Copy the key — you'll need it shortly

Free tier limits:

  • 30 calls/minute
  • Access to most endpoints
  • No historical OHLCV (use paid tier for that)

For paper trading and daily market scanning, 30 calls/minute is more than enough.

Step 2: Install OpenClaw (if not already done) 

npm install -g openclaw
openclaw start
Enter fullscreen mode Exit fullscreen mode

Follow the setup wizard. Choose local AI model (Ollama) for zero ongoing costs.

Step 3: Install the CryptoScanner Skill 

clawhub install crypto-scanner
Enter fullscreen mode Exit fullscreen mode

This installs the skill files to ~/.openclaw/workspace/skills/crypto-scanner/.

Step 4: Configure CoinGecko API Key

Run the configuration wizard:

openclaw skill configure crypto-scanner
Enter fullscreen mode Exit fullscreen mode

When prompted for "CoinGecko API Key", paste your Demo key.

Alternatively, set it manually in the config file:

// ~/.openclaw/workspace/skills/crypto-scanner/config.json
{
  "coingecko": {
    "api_key": "CG-your-key-here",
    "base_url": "https://api.coingecko.com/api/v3",
    "calls_per_minute": 30
  },
  "watchlist": ["bitcoin", "ethereum", "solana"],
  "paper_trading": true
}
Enter fullscreen mode Exit fullscreen mode

Note: CoinGecko uses full coin names (lowercase) not ticker symbols for most API calls.

Step 5: Test the Connection 

openclaw agent run crypto-scanner --test
Enter fullscreen mode Exit fullscreen mode

Expected output:

[crypto-scanner] Testing CoinGecko connection...
[crypto-scanner] ✓ Connected to CoinGecko API
[crypto-scanner] BTC: $67,432.18 (24h: +2.1%, vol: $32.4B)
[crypto-scanner] ETH: $3,891.44 (24h: +1.8%, vol: $18.2B)
[crypto-scanner] SOL: $184.32 (24h: +4.2%, vol: $4.1B)
[crypto-scanner] Connection healthy. Ready for paper trading.
Enter fullscreen mode Exit fullscreen mode

If you see errors, check:

  • API key is correct (no extra spaces)
  • You're on the Demo tier (not expired)
  • Your internet connection is working

Step 6: Understanding the CoinGecko Endpoints

Once connected, your agent has access to these key endpoints:

Price Data (used every scan cycle) 

# Fetched automatically by the skill
GET /simple/price?ids=bitcoin,ethereum&vs_currencies=usd&include_24hr_change=true
Enter fullscreen mode Exit fullscreen mode

Returns current prices and 24h change — lightweight and fast.

Market Data (used for signals) 

GET /coins/markets?vs_currency=usd&ids=bitcoin&sparkline=false
Enter fullscreen mode Exit fullscreen mode

Returns volume, market cap, price change over multiple timeframes.

Historical Data (used for backtesting) 

GET /coins/bitcoin/market_chart?vs_currency=usd&days=30
Enter fullscreen mode Exit fullscreen mode

Note: 30-day historical is available on free tier. Longer history requires paid.

Step 7: Configure Your Watchlist

Edit your config to specify which coins to track:

{
  "watchlist": [
    "bitcoin",
    "ethereum", 
    "solana",
    "cardano",
    "avalanche-2"
  ],
  "scan_interval_minutes": 60,
  "alert_on": {
    "price_change_pct_24h": 5,
    "volume_spike_multiplier": 2.5
  }
}
Enter fullscreen mode Exit fullscreen mode

Finding the right coin ID:

CoinGecko uses specific IDs. Find them at:
https://api.coingecko.com/api/v3/coins/list

Or search on coingecko.com and use the ID from the URL. For example, Avalanche's URL is /coins/avalanche-2 so the ID is avalanche-2.

Step 8: Set Up Intelligent Alerts

One of the best features: your AI agent can analyze the data and send smart alerts to Telegram.

Configure Telegram notifications:

{
  "notifications": {
    "telegram_bot_token": "your-bot-token",
    "telegram_chat_id": "your-chat-id",
    "alert_types": ["buy_signal", "sell_signal", "volume_spike", "daily_report"]
  }
}
Enter fullscreen mode Exit fullscreen mode

Set up a Telegram bot at t.me/BotFather — takes 2 minutes.

Step 9: Run Your First Full Scan 

openclaw agent run crypto-scanner --paper-trade --verbose
Enter fullscreen mode Exit fullscreen mode

Your agent will:

  1. Fetch prices for all watchlist coins via CoinGecko
  2. Calculate signals based on your rules
  3. Check against paper portfolio for actions
  4. Log everything with reasoning
  5. Send Telegram alert if signal triggered

Rate Limiting and Good Citizenship

With 30 calls/minute on the free tier, here's how to stay within limits:

  • Scan cycle: Set to 60+ minutes between full scans
  • Batch requests: The skill batches all watchlist coins into single API calls
  • Caching: Short-term price cache prevents redundant calls

The CryptoScanner skill handles all of this automatically.

Common Issues and Fixes

"401 Unauthorized": API key incorrect or expired. Regenerate in CoinGecko dashboard.

"429 Too Many Requests": You've exceeded the rate limit. Increase scan_interval_minutes.

Coin not found: Check the exact coin ID using the CoinGecko search or /coins/list endpoint.

No alerts received: Verify Telegram bot token and chat ID. Test with /start message to your bot.

Full Starter Package

The OpenClaw Crypto Home Trader 2026 package includes everything pre-configured:

  • CoinGecko integration with smart rate limiting
  • 5 crypto skills ready to install
  • Example watchlists for different risk profiles
  • Telegram alert templates
  • 30-day paper trading challenge

Get it at dragonwhisper36.gumroad.com

⚠️ Not financial advice. Paper trading only. You can lose 100% of capital in live trading. CoinGecko data accuracy depends on their service availability. Always verify prices before making real trading decisions.

Top comments (0)