📊 Crypto Data Aggregator

🆓 100% Free • 🔑 No API Keys Required • ⚡ Real-Time Data • 📱 PWA Ready • 🤖 AI Agent & MCP Ready

Real-time cryptocurrency market data aggregator. Track 10,000+ coins, monitor 200+ DeFi protocols,
manage portfolios, set price alerts, and analyze market sentiment—all in one place.

Quick Start • Features • Deep Dive • API • AI Agents • Deploy • Docs

⚡ Quick Start

# Clone and run in 30 seconds
git clone https://github.com/nirholas/crypto-data-aggregator.git
cd crypto-data-aggregator
npm install
npm run dev

Open http://localhost:3000 — no API keys needed! 🎉

🎯 Why This Project?

| Feature | Crypto Data Aggregator | Paid Alternatives | | --------------- | ---------------------- | ----------------- | | API Key | ❌ None needed | Required | | Rate Limit | ✅ Generous free tier | Limited | | Self-Host | ✅ One click | No | | PWA | ✅ Installable | Rarely | | Open Source | ✅ MIT License | No | | DeFi Data | ✅ 200+ protocols | Extra cost |

✨ Features

📈 Market Data

• Live Prices — Real-time prices for 10,000+ cryptocurrencies
• Market Rankings — Market cap, volume, and supply data
• Gainers & Losers — Track top movers (1h, 24h, 7d, 30d)
• Trending Coins — CoinGecko trending + social signals
• Categories — Filter by DeFi, Gaming, Layer 2, Memecoins, and more
• New Listings — Discover newly listed tokens

🏦 DeFi Dashboard

• 200+ Protocols — TVL rankings from DeFiLlama
• Chain Analytics — Ethereum, Solana, Arbitrum, Base, and 50+ chains
• Category Filters — DEX, Lending, Bridges, Liquid Staking, Derivatives
• Protocol Comparison — Side-by-side TVL and metrics comparison
• DeFi Yields — Track yield farming APYs across protocols

📊 Advanced Analytics

| Tool | Description | | -------------------- | ------------------------------------------------------------------ | | 🔥 Heatmap | Visual market overview with size-by-market-cap | | 🔍 Screener | Filter coins by market cap, volume, price change, ATH distance | | ⚖️ Compare | Compare up to 5 coins side-by-side with historical charts | | 📉 Charts | Interactive price charts with OHLC candlesticks | | 😱 Sentiment | Fear & Greed Index with historical trends | | 📊 Volatility | Risk metrics, Sharpe ratios, max drawdowns | | 🔗 Correlation | Asset correlation matrix for portfolio diversification | | 💥 Liquidations | Real-time futures liquidation feed from major exchanges | | ⛽ Gas Tracker | Multi-chain gas prices (ETH, Polygon, Base, Arbitrum, Optimism) | | 📈 Derivatives | Funding rates, open interest, long/short ratios |

🐋 On-Chain Analytics

| Feature | Description | | -------------------- | -------------------------------------------------------------- | | Whale Tracking | Real-time large transaction alerts via Whale Alert API | | Exchange Flows | Track inflows/outflows from major exchanges | | Smart Money | Follow institutional and whale wallet movements | | Bitcoin On-Chain | Mempool stats, fee estimates, block data via Mempool.space | | Token Unlocks | Track upcoming vesting schedules via DeFiLlama emissions |

💼 Portfolio & Tracking

| Feature | Description | | ---------------------- | ------------------------------------------------------ | | 💰 Portfolio | Track holdings with P&L, cost basis, and allocation | | ⭐ Watchlist | Custom watchlists with drag-and-drop reordering | | 🔔 Price Alerts | Set alerts for price targets (above/below) | | 📤 Export | Export portfolio & watchlist as JSON/CSV | | 🔄 Exchange Sync | Import holdings from Binance, Coinbase, Kraken, OKX | | 📊 Analytics | Portfolio performance, allocation, and risk metrics |

🔐 Authentication & User Features

| Feature | Description | | -------------------- | ---------------------------------------------------------- | | OAuth Login | Sign in with Google, GitHub, or Discord | | Magic Links | Passwordless email authentication | | Email Alerts | Receive price alerts and digests via email (Resend) | | Newsletter | Daily/weekly crypto news digests | | Push Notifications| Browser push for breaking news |

🤖 AI Features

| Feature | Description | | -------------------- | ---------------------------------------------------------- | | AI Analysis | GPT-powered market analysis and insights | | AI Debate | Bull vs Bear AI debates on market topics | | Claim Extraction | Extract verifiable claims from news articles | | Clickbait Detector| Score headlines for clickbait content | | Summarization | AI-powered article summaries | | Ask AI | Natural language queries about crypto data |

⚡ Power User Features

• ⌨️ Keyboard Shortcuts — Vim-style navigation (j/k, g+h/t/w/p)
• 🔎 Command Palette — Quick actions with Cmd+K / Ctrl+K
• 🌙 Dark Mode — Beautiful dark theme with d toggle
• 📱 PWA — Install as app on mobile & desktop
• 🔄 Cross-Tab Sync — Watchlist syncs across browser tabs
• 🌍 18 Languages — Full i18n support

🧩 Integrations & SDKs

Official SDKs

| SDK | Installation | Features | | ------------ | --------------------------------------- | ----------------------------------- | | Python | curl -O .../crypto_news.py | Zero dependencies, async support | | TypeScript| npm install @crypto-data/sdk | Full types, SWR integration | | React | npm install @crypto-data/react | Hooks: useCryptoNews, usePrice | | Go | go get github.com/.../cryptonews | Goroutine-safe, context support | | PHP | composer require crypto-data/sdk | PSR-4, Guzzle HTTP | | JavaScript| npm install crypto-news-sdk | Browser & Node.js compatible |

Browser Extension

Chrome/Edge extension for quick crypto news access:

• Tab-based navigation (Latest, Breaking, DeFi, Bitcoin)
• Quick coin search and price lookup
• Configurable API base URL

Raycast Extension

Native Raycast commands:

• crypto-news — Latest news
• crypto-breaking — Breaking news
• crypto-trending — Trending topics

CLI Tool

npx crypto-news              # Latest news
npx crypto-news --bitcoin    # Bitcoin news only
npx crypto-news -s "ethereum" # Search
npx crypto-news --breaking   # Breaking news
npx crypto-news --json       # JSON output

MCP Server (AI Agents)

Model Context Protocol server for Claude, ChatGPT, and other AI assistants:

# Claude Desktop (stdio mode)
node mcp/index.js
ChatGPT Developer Mode (HTTP/SSE)
node mcp/index.js --http

Available Tools:

• getcryptonews — Latest headlines
• searchcryptonews — Search by keywords
• getdefinews — DeFi-specific news
• getbitcoinnews — Bitcoin news
• getmarketdata — Real-time prices
• gettrendingcoins — Trending cryptocurrencies

ChatGPT Plugin

OpenAPI-compatible plugin for ChatGPT:

• Full OpenAPI 3.0 specification at /chatgpt/openapi.yaml
• AI plugin manifest at /.well-known/ai-plugin.json

Embeddable Widgets

<!-- Price Ticker -->
<iframe src="https://your-domain.com/widget/ticker.html" />
<!-- News Carousel --> <iframe src="https://your-domain.com/widget/carousel.html" />

🎯 Feature Deep Dive

Market Heatmap

Visualize the entire crypto market at a glance with our interactive heatmap.

| Feature | Description | | ------------------------ | ----------------------------------------------------------- | | Size by Market Cap | Larger tiles = larger market cap (uses square root scaling) | | Color by Performance | Light = gains, Dark = losses (monochrome gradient) | | Timeframe Toggle | Switch between 24h and 7d performance | | Top N Filter | Show top 25, 50, or 100 coins | | Sort Options | Sort by market cap or absolute change | | Interactive Tiles | Click any coin to view details |

Color Scale:

• +20%+ — Lightest (near white)
• +10% — Light gray
• 0% — Mid gray
• -10% — Dark gray
• -20%+ — Darkest (near black)

Advanced Screener

Find coins matching your exact criteria with powerful filters and presets.

Filter Options:

| Filter | Range | Example | | ------------ | ------- | --------------- | | Market Cap | Min/Max | $1B - $10B | | 24h Volume | Min/Max | $100M+ | | Price | Min/Max | $0.01 - $100 | | 24h Change | Min/Max | +5% to +50% | | ATH Distance | Min/Max | -10% (near ATH) |

Built-in Presets:

| Preset | Criteria | | --------------- | ----------------------- | | 🐋 Large Caps | Market Cap > $10B | | 🦈 Mid Caps | $1B - $10B | | 🐟 Small Caps | $100M - $1B | | 🦐 Micro Caps | < $100M | | 🔥 Hot Today | 24h Change > +10% | | 📉 Dipping | 24h Change < -10% | | 🎯 Near ATH | Within -10% of ATH | | 💎 Far From ATH | More than -50% from ATH | | 📊 High Volume | Volume > $1B |

Additional Features:

• Real-time search with instant filtering
• Multi-column sorting (click any header)
• Add to watchlist directly from results
• Export filtered results to CSV

Coin Comparison

Compare up to 5 cryptocurrencies side-by-side with synchronized charts.

Metrics Compared:

| Metric | Description | | ------------------ | --------------------------- | | Current Price | Live price in USD | | Market Cap | Total market capitalization | | 24h Volume | Trading volume | | 24h/7d/30d Change | Price change percentages | | All-Time High | ATH price and distance | | Circulating Supply | Coins in circulation |

Chart Features:

• Synchronized historical charts
• Time range: 24h, 7d, 30d, 90d, 1Y
• Normalized percentage view
• Share comparison via URL

Sentiment Analysis

Track market psychology with Fear & Greed metrics and social signals.

Fear & Greed Index:

| Value | Label | Market Condition | | ------ | ---------------- | ---------------------------- | | 0-20 | 😱 Extreme Fear | Potential buying opportunity | | 21-40 | 😰 Fear | Cautious sentiment | | 41-60 | 😐 Neutral | Balanced market | | 61-80 | 😊 Greed | Optimistic sentiment | | 81-100 | 🤑 Extreme Greed | Potential correction |

Dashboard Components:

• Real-time Fear & Greed gauge
• Historical sentiment chart (30 days)
• Bullish/Bearish/Neutral breakdown
• Social volume metrics
• Top trending coins by sentiment

Portfolio Tracker

Professional-grade portfolio management with real-time P&L.

Portfolio Features:

| Feature | Description | | ------------------- | ------------------------------------------ | | Holdings | Add coins with amount, buy price, and date | | Real-Time Value | Live portfolio value calculation | | P&L Tracking | Profit/loss per coin and total | | Cost Basis | Average purchase price calculation | | Allocation | Pie chart of portfolio distribution | | 24h Change | Daily portfolio performance |

Transaction Types:

• Buy — Add to position
• Sell — Reduce position
• Transfer — Move between wallets

// Export format
{
  "holdings": [
    {
      "coinId": "bitcoin",
      "amount": 0.5,
      "totalCost": 25000,
      "averagePrice": 50000
    }
  ],
  "exportedAt": "2026-01-22T..."
}

Watchlist

Create and manage custom watchlists with real-time updates.

Features:

| Feature | Description | | ---------------------- | ------------------------------------ | | Unlimited Lists | Create multiple watchlists | | Drag & Drop | Reorder coins to your preference | | Quick Add | Star icon on any coin card | | Bulk Actions | Select multiple for batch operations | | Cross-Tab Sync | Changes sync instantly across tabs | | Persistent Storage | Saved to localStorage |

Export Formats:

• JSON — Full data with metadata
• CSV — Spreadsheet compatible
• Plain Text — Simple list of symbols

Price Alerts

Set price targets and get notified when coins hit your levels.

Alert Types:

| Type | Trigger | | --------------- | ------------------------------------ | | Price Above | Notify when price exceeds target | | Price Below | Notify when price drops below target |

Alert Features:

• Multiple alerts per coin
• Real-time price monitoring
• Visual notification when triggered
• Alert history with timestamps
• Enable/disable individual alerts

BTC > $100,000  →  "Bitcoin just broke $100K!"
ETH < $2,000    →  "Ethereum dipped below $2K"
SOL > $200      →  "Solana hit your target"

DeFi Dashboard

Comprehensive DeFi analytics powered by DeFiLlama.

Protocol Data:

| Metric | Description | | -------------- | ------------------------------ | | TVL | Total Value Locked in protocol | | 24h Change | TVL change in last 24 hours | | 7d Change | TVL change over 7 days | | Category | DEX, Lending, Bridge, etc. | | Chains | Supported blockchains | | Audits | Security audit status |

Chain Analytics:

• TVL by chain (Ethereum, Solana, etc.)
• Chain dominance percentages
• Cross-chain protocol distribution
• Bridge TVL tracking

• 🔄 DEXes (Uniswap, Curve, etc.)
• 🏦 Lending (Aave, Compound, etc.)
• 🌉 Bridges (Stargate, Across, etc.)
• 💧 Liquid Staking (Lido, Rocket Pool, etc.)
• 📈 Derivatives (GMX, dYdX, etc.)
• 🎰 Yield Aggregators (Yearn, Beefy, etc.)

Charts & Technical Data

Interactive price charts with multiple timeframes and data types.

Chart Types:

| Type | Description | | --------------- | --------------------------- | | Line Chart | Simple price over time | | OHLC | Open, High, Low, Close bars | | Candlestick | Traditional trading view |

Timeframes:

• 24 hours
• 7 days
• 30 days
• 90 days
• 1 year
• Max (all available data)

• Price history
• Volume overlay
• Market cap history
• Price change annotations

🖥️ Pages & Routes

Market Data

| Route | Description | | --------------------- | ----------------------------------- | | / | Markets dashboard with global stats | | /markets | Full coin rankings table | | /markets/trending | Trending coins | | /markets/gainers | Top gainers by % change | | /markets/losers | Top losers by % change | | /markets/categories | Browse by category | | /markets/exchanges | Exchange volume rankings | | /markets/new | Recently listed coins |

Coin Details

| Route | Description | | ---------------- | ------------------------------------------------ | | /coin/[coinId] | Detailed coin page with charts, stats, and links |

Analytics

| Route | Description | | -------------- | ---------------------------------------- | | /defi | DeFi dashboard with protocols & chains | | /heatmap | Visual market heatmap | | /screener | Advanced coin screener with filters | | /compare | Compare multiple coins | | /sentiment | Fear & Greed analysis | | /movers | Top movers overview | | /volatility | Volatility analysis & risk metrics | | /correlation | Asset correlation matrix | | /liquidations| Futures liquidation feed | | /derivatives | Funding rates & open interest | | /gas | Multi-chain gas tracker | | /unlocks | Token unlock schedule |

User Features

| Route | Description | | --------------- | ------------------------------- | | /portfolio | Portfolio tracker | | /watchlist | Saved coins watchlist | | /alerts | Manage price alerts | | /auth/signin | Sign in with OAuth/Magic Link | | /settings | User preferences |

AI Features

| Route | Description | | --------------- | -------------------------------- | | /ai | AI market analysis | | /ai/debate | Bull vs Bear AI debates | | /ask | Natural language queries |

🔌 API Endpoints

All endpoints return JSON. Free tier requires no API key. Premium tier supports x402 micropayments.

Free API (v1)

# Get top 100 coins by market cap
curl "http://localhost:3000/api/market/coins"
Get coin details
curl "http://localhost:3000/api/market/snapshot/bitcoin"
Get price history (7 days)
curl "http://localhost:3000/api/market/history/bitcoin?days=7"
Search coins
curl "http://localhost:3000/api/market/search?q=ethereum"
DeFi protocols
curl "http://localhost:3000/api/defi"
Fear & Greed Index
curl "http://localhost:3000/api/sentiment"

Premium API (v2)

# GraphQL endpoint
curl -X POST "http://localhost:3000/api/v2/graphql" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ coins(limit: 10) { id name price } }"}'
Batch requests (up to 10 coins)
curl "http://localhost:3000/api/v2/batch?coins=bitcoin,ethereum,solana"
Volatility metrics
curl "http://localhost:3000/api/v2/volatility/bitcoin"
AI-powered analysis
curl -X POST "http://localhost:3000/api/premium/ai/analyze" \
  -H "Content-Type: application/json" \
  -d '{"coin": "bitcoin", "prompt": "What is the outlook?"}'

Endpoint Reference

| Endpoint | Method | Description | | -------------------------------- | ------ | ------------------------------------ | | /api/market/coins | GET | Paginated coin list with market data | | /api/market/snapshot/[coinId] | GET | Detailed coin data | | /api/market/history/[coinId] | GET | Historical price data | | /api/market/ohlc/[coinId] | GET | OHLC candlestick data | | /api/market/search | GET | Search coins by name/symbol | | /api/market/categories | GET | List all categories | | /api/market/exchanges | GET | Exchange rankings | | /api/defi | GET | Protocol TVL rankings | | /api/trending | GET | Trending coins | | /api/sentiment | GET | Fear & Greed index | | /api/gas | GET | Multi-chain gas prices | | /api/v1/alerts | GET | Price alerts | | /api/v1/whales | GET | Whale transactions | | /api/v1/liquidations | GET | Futures liquidations | | /api/v1/derivatives | GET | Funding rates & open interest | | /api/v2/graphql | POST | GraphQL API (premium) | | /api/v2/batch | GET | Batch coin data (premium) | | /api/v2/webhooks | POST | Webhook management (premium) | | /api/v2/volatility/[coinId] | GET | Volatility metrics (premium) | | /api/premium/ai/analyze | POST | AI market analysis | | /api/premium/ai/debate | POST | Bull vs Bear debate | | /api/premium/screener | GET | Advanced screener | | /api/premium/whales | GET | Premium whale tracking |

🌟 Power Features (Often Overlooked)

These powerful endpoints are frequently missed - try them out!

AI Intelligence

| Endpoint | Method | Description | | -------------------- | ------ | --------------------------------------------- | | /api/signals | GET | AI-generated trading signals with confidence | | /api/narratives | GET | Dominant market narratives (ETF, AI, DeFi) | | /api/entities | GET | Named entity extraction from news | | /api/factcheck | POST | Verify claims in crypto news | | /api/clickbait | POST | Score headline quality (0-100) | | /api/ask | POST | Natural language Q&A about crypto | | /api/digest | GET | AI-curated daily news digest | | /api/origins | GET | Trace news to original sources |

Advanced Analytics

| Endpoint | Method | Description | | ---------------------------- | ------ | ------------------------------------ | | /api/analytics/anomalies | GET | Unusual pattern detection | | /api/analytics/sources | GET | Source credibility scores | | /api/analytics/headlines | GET | Track headline edits over time | | /api/bitcoin/halving | GET | Halving countdown with estimates |

Developer Tools

| Endpoint | Method | Description | | ---------------------- | ------ | ------------------------------ | | /api/v2/graphql | POST | Full GraphQL API for queries | | /api/v2/batch | POST | Batch multiple API calls | | /api/atom | GET | Atom feed (alt to RSS) | | /api/opml | GET | OPML export for RSS readers | | /api/sse | GET | Server-Sent Events stream | | /api/article?url= | GET | Fetch & summarize any article | | /api/v2/openapi.json | GET | OpenAPI 3.1 specification | | /docs/swagger | GET | Interactive Swagger UI |

📚 See docs/API.md for complete API reference with examples.

🤖 AI Agents

This API is designed for AI agent discoverability with full x402 payment protocol support.

Discovery Files

AI agents can discover this API through standard discovery endpoints:

| File | URL | Description | | ------------------ | ----------------------------- | ------------------------------------ | | llms.txt | /llms.txt | Quick reference for LLMs | | llms-full.txt | /llms-full.txt | Extended documentation with examples | | agents.json | /agents.json | Machine-readable endpoint catalog | | ai-plugin.json | /.well-known/ai-plugin.json | OpenAI plugin manifest |

x402 Payment Protocol

This API supports the x402 payment protocol for autonomous micropayments:

| Feature | Details | | --------------- | -------------------------------------- | | Protocol | HTTP 402 Payment Required | | Networks | Base (mainnet), Base Sepolia (testnet) | | Asset | USDC | | Min Payment | $0.001 per request | | No API Keys | Just pay and access |

For AI Agent Developers

import { wrapAxiosWithPayment, x402Client } from '@x402/axios';
import { registerExactEvmScheme } from '@x402/evm/exact/client';
import axios from 'axios';
import { privateKeyToAccount } from 'viem/accounts';
// Setup wallet const account = privateKeyToAccount('0xYourPrivateKey'); const client = new x402Client(); registerExactEvmScheme(client, { signer: account });
// Create payment-enabled HTTP client const api = wrapAxiosWithPayment(axios.create({ baseURL: 'https://your-domain.com/api' }), client);
// Payments are handled automatically on 402 responses const response = await api.get('/market/snapshot/bitcoin');

Bazaar Discovery

This API is registered with the x402 Bazaar for autonomous discovery:

import { HTTPFacilitatorClient } from '@x402/core/http';
import { withBazaar } from '@x402/extensions';
const client = withBazaar(   new HTTPFacilitatorClient({     url: 'https://x402.org/facilitator',   }) );
// Discover crypto data endpoints const resources = await client.extensions.discovery.listResources({ type: 'http' });

📚 See docs/X402_INTEGRATION.md for complete x402 integration guide.

📡 Data Sources

All data is fetched from free, public APIs — no API keys required for basic usage.

CoinGecko

| Data Type | Endpoint | Rate Limit | | ------------ | -------------------------- | --------------- | | Coin Prices | /coins/markets | 10-50 calls/min | | Coin Details | /coins/{id} | 10-50 calls/min | | Historical | /coins/{id}/market_chart | 10-50 calls/min | | OHLC | /coins/{id}/ohlc | 10-50 calls/min | | Search | /search | 10-50 calls/min | | Trending | /search/trending | 10-50 calls/min | | Categories | /coins/categories | 10-50 calls/min | | Exchanges | /exchanges | 10-50 calls/min |

💡 Pro Tip: Set COINGECKOAPIKEY for 500+ calls/min with Pro plan.

DeFiLlama

| Data Type | Endpoint | Rate Limit | | --------- | ----------------- | ---------- | | Protocols | /protocols | Unlimited | | TVL | /tvl/{protocol} | Unlimited | | Chains | /chains | Unlimited |

Alternative.me

| Data Type | Endpoint | Rate Limit | | ------------ | -------- | ---------- | | Fear & Greed | /fng/ | Unlimited |

🔎 Command Palette

Power user's best friend — access any feature instantly with Cmd+K / Ctrl+K.

Available Commands

Navigation: | Command | Description | |---------|-------------| | 🏠 Go to Home | Navigate to markets dashboard | | 📈 Go to Markets | Full coin rankings | | 🏦 Go to DeFi | DeFi protocol dashboard | | 🔥 Go to Trending | Trending coins | | 🚀 Go to Movers | Top gainers and losers | | ⭐ Go to Watchlist | Your saved coins | | 💼 Go to Portfolio | Portfolio tracker | | ⚖️ Go to Compare | Coin comparison | | 🔥 Go to Heatmap | Market heatmap | | 🔍 Go to Screener | Advanced screener |

Actions: | Command | Description | |---------|-------------| | 🌙 Toggle Dark Mode | Switch theme | | 🔔 Manage Alerts | Open alerts panel | | ⌨️ Keyboard Shortcuts | Show help modal |

Search: Type any coin name to search instantly!

⌨️ Keyboard Shortcuts

Power user navigation — works everywhere!

Navigation

| Key | Action | | --------- | ------------------------- | | j / k | Navigate down/up in lists | | Enter | Open selected item | | Escape | Close modal / blur input |

Quick Access (g + key)

| Key | Action | | ----- | --------------- | | g h | Go to Home | | g t | Go to Trending | | g w | Go to Watchlist | | g p | Go to Portfolio | | g c | Go to Compare | | g d | Go to DeFi |

Actions

| Key | Action | | -------------- | ----------------------------- | | / or Cmd+K | Open search / command palette | | d | Toggle dark mode | | ? | Show shortcuts help |

📱 Progressive Web App (PWA)

Install Crypto Data Aggregator as an app on any device!

Features

| Feature | Description | | ------------------- | -------------------------------------- | | 📲 Installable | Add to home screen on mobile & desktop | | 📴 Offline Mode | Browse cached data without internet | | ⚡ Fast Loading | Aggressive caching strategies | | 🔄 Auto Updates | Seamless background updates |

Install

Desktop (Chrome/Edge):

• Click the install icon in the address bar
• Or use Menu → "Install Crypto Data Aggregator"

• Open in Safari (iOS) or Chrome (Android)
• Tap "Add to Home Screen"

🚀 Deployment

One-Click Deploy

Docker

# Build and run
docker build -t crypto-data-aggregator .
docker run -p 3000:3000 crypto-data-aggregator

Manual Deployment

# Install dependencies
npm install
Build for production
npm run build
Start production server
npm start

🔧 Environment Variables

| Variable | Required | Default | Description | | -------------------------- | -------- | ---------------------------------- | ---------------------------------- | | Market Data | | | | | COINGECKOAPIKEY | No | - | Pro API key for higher rate limits | | COINGECKOBASEURL | No | https://api.coingecko.com/api/v3 | API base URL | | DEFILLAMABASEURL | No | https://api.llama.fi | DeFiLlama API URL | | Authentication | | | | | AUTH_SECRET | Yes* | - | NextAuth secret (for OAuth) | | GOOGLECLIENTID | No | - | Google OAuth client ID | | GOOGLECLIENTSECRET | No | - | Google OAuth client secret | | GITHUBCLIENTID | No | - | GitHub OAuth client ID | | GITHUBCLIENTSECRET | No | - | GitHub OAuth client secret | | DISCORDCLIENTID | No | - | Discord OAuth client ID | | DISCORDCLIENTSECRET | No | - | Discord OAuth client secret | | TWITTERCLIENTID | No | - | Twitter OAuth client ID | | TWITTERCLIENTSECRET | No | - | Twitter OAuth client secret | | Email | | | | | RESENDAPIKEY | No | - | Resend API key for email | | AI Providers | | | | | OPENAIAPIKEY | No | - | OpenAI API key for AI features | | ANTHROPICAPIKEY | No | - | Anthropic Claude API key | | GROQAPIKEY | No | - | Groq API key (fast inference) | | Storage | | | | | UPSTASHREDISREST_URL | No | - | Upstash Redis URL | | UPSTASHREDISREST_TOKEN | No | - | Upstash Redis token | | Exchange APIs | | | | | BINANCEAPIKEY | No | - | Binance API key for portfolio sync | | BINANCEAPISECRET | No | - | Binance API secret | | COINBASEAPIKEY | No | - | Coinbase API key | | KRAKENAPIKEY | No | - | Kraken API key | | x402 Payments | | | | | X402PRIVATEKEY | No | - | Wallet private key for x402 | | X402FACILITATORURL | No | https://x402.org/facilitator | x402 facilitator URL |

*Required only if using authentication features.

Create .env.local for local development:

# Required for authentication
AUTH_SECRET=your-random-secret-key
Optional: For production with higher rate limits
COINGECKOAPIKEY=yourapikey
COINGECKOBASEURL=https://pro-api.coingecko.com/api/v3
Optional: For AI features
OPENAIAPIKEY=sk-...
Optional: For email notifications
RESENDAPIKEY=re_...
Optional: For Redis caching
UPSTASHREDISREST_URL=https://...
UPSTASHREDISREST_TOKEN=...

💡 Note: No API keys required for basic usage! The free tier works great for development and

small-scale deployments.

🛠️ Tech Stack

| Layer | Technology | | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | | Framework | Next.js 16 with App Router | | Language | TypeScript 5 | | Styling | Tailwind CSS 4 | | Data Fetching | SWR with stale-while-revalidate | | Charts | Recharts | | Animations | Framer Motion | | Icons | Lucide React + Heroicons | | Testing | Vitest + Playwright + Testing Library | | i18n | next-intl with 18 languages | | Auth | NextAuth.js with OAuth + Magic Links | | Email | Resend for transactional email | | Storage | Upstash Redis with memory fallback | | APIs | CoinGecko • DeFiLlama • Alternative.me • Whale Alert |

Supported Languages

🇺🇸 English • 🇪🇸 Español • 🇫🇷 Français • 🇩🇪 Deutsch • 🇮🇹 Italiano • 🇵🇹 Português • 🇳🇱 Nederlands • 🇵🇱 Polski • 🇷🇺 Русский • 🇹🇷 Türkçe • 🇸🇦 العربية • 🇯🇵 日本語 • 🇰🇷 한국어 • 🇨🇳 简体中文 • 🇹🇼 繁體中文 • 🇻🇳 Tiếng Việt • 🇹🇭 ไทย • 🇮🇩 Indonesia

⚡ Caching & Performance

Multi-layer caching strategy for optimal performance and API efficiency.

Caching Layers

| Layer | TTL | Purpose | | ----------------- | ------------ | ---------------------------------- | | Memory Cache | 30s-5min | Server-side request deduplication | | SWR Cache | Configurable | Client-side stale-while-revalidate | | ISR | 60s | Incremental Static Regeneration | | Browser Cache | Varies | HTTP cache headers |

Cache TTL by Data Type

| Data Type | TTL | Reason | | --------------- | ---------- | --------------------- | | Coin Prices | 30 seconds | Real-time market data | | Coin List | 5 minutes | Rarely changes | | Historical Data | 10 minutes | Immutable past data | | DeFi TVL | 2 minutes | Updates frequently | | Fear & Greed | 5 minutes | Daily updates | | Categories | 1 hour | Rarely changes | | Exchanges | 5 minutes | Volume updates |

Performance Features

• Edge Runtime — API routes run on the edge for low latency
• Request Deduplication — Multiple simultaneous requests share one API call
• Stale-While-Revalidate — Show cached data while fetching fresh
• Incremental Static Regeneration — Pages rebuild on-demand
• Code Splitting — Load only what's needed

📁 Project Structure

crypto-data-aggregator/
├── src/
│   ├── app/                    # Next.js App Router pages
│   │   ├── api/                # 100+ API routes
│   │   │   ├── market/         # Market data endpoints
│   │   │   ├── v1/             # Free tier API
│   │   │   ├── v2/             # Premium tier API
│   │   │   ├── premium/        # Paid features (AI, screener)
│   │   │   ├── auth/           # OAuth & magic links
│   │   │   ├── exchanges/      # Exchange sync
│   │   │   └── webhooks/       # Webhook management
│   │   ├── coin/[coinId]/      # Coin detail pages
│   │   ├── compare/            # Coin comparison
│   │   ├── correlation/        # Correlation matrix
│   │   ├── defi/               # DeFi dashboard
│   │   ├── derivatives/        # Derivatives dashboard
│   │   ├── gas/                # Gas tracker
│   │   ├── heatmap/            # Market heatmap
│   │   ├── liquidations/       # Liquidation feed
│   │   ├── markets/            # Market listings
│   │   ├── portfolio/          # Portfolio tracker
│   │   ├── screener/           # Advanced screener
│   │   ├── sentiment/          # Sentiment analysis
│   │   ├── volatility/         # Volatility analysis
│   │   └── watchlist/          # User watchlist
│   ├── components/             # 100+ React components
│   │   ├── portfolio/          # Portfolio components
│   │   ├── watchlist/          # Watchlist components
│   │   ├── alerts/             # Alert components
│   │   ├── auth/               # Auth UI components
│   │   └── ...                 # Shared components
│   └── lib/                    # 70+ utility modules
│       ├── market-data.ts      # CoinGecko API client
│       ├── defillama.ts        # DeFiLlama client
│       ├── cache.ts            # Memory caching layer
│       ├── storage.ts          # Redis/memory storage
│       ├── auth.ts             # Authentication logic
│       ├── email.ts            # Resend email service
│       ├── exchange-sync.ts    # Exchange API integrations
│       ├── ai-providers.ts     # OpenAI/Anthropic/Groq
│       └── x402.ts             # x402 micropayments
├── sdk/                        # Official SDKs
│   ├── python/                 # Python SDK
│   ├── typescript/             # TypeScript SDK
│   ├── react/                  # React hooks & components
│   ├── go/                     # Go SDK
│   ├── php/                    # PHP SDK
│   └── javascript/             # Browser/Node.js SDK
├── cli/                        # Command line tool
├── mcp/                        # MCP server for AI agents
├── extension/                  # Chrome browser extension
├── raycast/                    # Raycast extension
├── widget/                     # Embeddable widgets
├── examples/                   # Integration examples
├── chatgpt/                    # ChatGPT plugin
├── docs/                       # Documentation
├── public/                     # Static assets & PWA files
└── scripts/                    # Build & setup scripts

📚 Documentation

| Document | Description | | -------------------------------------------- | --------------------------------------------- | | Documentation Index | Full documentation overview | | API Reference | Complete endpoint documentation with examples | | Architecture | System design, data flow & caching strategy | | Tech Stack | Technologies, libraries & tools | | Components | UI component library & usage | | Data Sources | External APIs & caching strategies | | Development | Local setup, debugging & workflow | | Testing | Vitest setup, mocking & coverage | | Deployment | Vercel, Railway, Docker, self-hosting | | Performance | Optimization strategies & monitoring | | Security | Security practices & hardening | | Authentication | OAuth, magic links & session management | | PWA Guide | Progressive Web App features | | x402 Integration | Micropayments & API monetization | | AI Agents | MCP server & AI integrations | | Troubleshooting | Common issues & solutions | | Changelog | Version history & upgrades |

Integration Examples

| Example | Description | | ---------------------------------- | ------------------------------------ | | Discord Bot | Discord bot for crypto updates | | Slack Bot | Slack integration for news | | Telegram Bot | Telegram bot with Python | | Telegram Digest | Daily digest bot | | LangChain Tool| LangChain integration for AI agents | | x402 Payment | x402 micropayment example | | Real-time Stream | WebSocket streaming client | | API Key Usage | API key authentication example |

🧪 Development

# Install dependencies
npm install
Start development server
npm run dev
Run tests
npm test
Run tests with UI
npm run test:ui
Type checking
npm run typecheck
Linting
npm run lint
Format code
npm run format
Run all checks
npm run check-all

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

# Fork the repository
Create a feature branch
git checkout -b feature/amazing-feature
Commit changes
git commit -m 'Add amazing feature'
Push to branch
git push origin feature/amazing-feature
Open a Pull Request

📄 License

MIT License — See LICENSE for details.

Stop paying for crypto data APIs.
_{Made with 💜 for the community}

⭐ Found this useful? Give it a star! ⭐
_{It helps others discover this project}

⭐ Star • 🐛 Report Bug • 💬 Discussions