🚀 Quick Start (5 Minutes)

For experienced developers who want to get running fast:

# 1. Clone and install
git clone https://github.com/danilobatson/ai-trading-agent-gemini.git
cd ai-trading-agent-gemini
npm install

# 2. Copy environment template
cp .env.example .env.local

# 3. Add your API keys (see detailed setup below)
# Edit .env.local with your 5 required API keys

# 4. Set up database tables
# Copy SQL schema below → paste in Supabase SQL Editor

# 5. Start development
npm run dev          # Next.js app (localhost:3000)
npm run inngest:dev  # Inngest dev server (localhost:8288)

🎯 Need the detailed setup? Continue reading for step-by-step instructions with account creation guides. Review our guide on dev.to if you need more assistance

📋 Prerequisites

You'll Need:

• Node.js 18+ installed
• Basic knowledge of React/TypeScript
• A code editor (VS Code recommended)
• 20 minutes for complete setup

5 API Keys Required:

1. 🌙 LunarCrush API Subscription required
2. 🤖 Google Gemini API (AI analysis) - Free tier available
3. 🗄️ Supabase (database & real-time) - Free tier available
4. ⚡ Inngest (background jobs) - Free tier available

🔧 Detailed Setup Guide

Step 1: Project Installation

# Clone the repository
git clone https://github.com/danilobatson/ai-trading-agent-gemini.git
cd ai-trading-agent-gemini

# Install dependencies
npm install

# Create environment file
cp .env.example .env.local

Step 2: LunarCrush API Setup 🌙

LunarCrush provides real-time social sentiment data for cryptocurrencies with unique metrics like AltRank™ and Galaxy Score™.

1. Sign up: Visit lunarcrush.com/signup
2. Choose a plan:
   • Individual - Perfect for this project
   • Builder - For production apps
3. Generate API key
4. Add to .env.local:

LUNARCRUSH_API_KEY=your_api_key_here

💡 Why LunarCrush? Powers the social sentiment analysis with unique metrics unavailable elsewhere:

• Mentions: Social post volume (24h)
• Interactions: Total social engagement
• Creators: Unique content creators (diversity indicator)
• AltRank™: Proprietary market + social ranking
• Galaxy Score™: Asset health indicator (0-100)

Step 3: Google Gemini AI Setup 🤖

Google's Gemini AI generates intelligent trading recommendations based on social patterns.

1. Get API key: Visit aistudio.google.com
2. Create new project or use existing one
3. Generate API key: API Keys → Create API Key
4. Add to .env.local:

GOOGLE_GEMINI_API_KEY=your_gemini_api_key_here

💡 Why Gemini? Excellent reasoning capabilities for financial analysis and trading signal generation with structured outputs.

Step 4: Supabase Database Setup 🗄️

Supabase provides PostgreSQL database with real-time subscriptions for live progress tracking.

1. Create account: Visit supabase.com → "Start your project"
2. Create new project:
   • Project name: ai-trading-agent
   • Database password: (save this securely)
   • Region: Choose closest to you
3. Get credentials: Click Project Overview
   • Copy Project URL and anon public key
4. Add to .env.local:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key_here

💡 Why Supabase? Real-time database updates power our live progress tracking without polling.

Step 5: Database Schema Creation 📊

In your Supabase dashboard:

1. Go to SQL Editor
2. Click "New query"
3. Copy and paste this entire script:

-- AI Trading Agent Database Schema
-- Copy and paste this entire script into your Supabase SQL Editor

-- Table: trading_signals
-- Stores AI-generated trading signals with confidence scores and reasoning
CREATE TABLE trading_signals (
  id TEXT PRIMARY KEY,
  symbol TEXT NOT NULL,
  signal TEXT NOT NULL CHECK (signal IN ('BUY', 'SELL', 'HOLD')),
  confidence INTEGER NOT NULL CHECK (confidence >= 0 AND confidence <= 100),
  reasoning TEXT NOT NULL,
  metrics JSONB NOT NULL,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Indexes for trading_signals table (for performance)
CREATE INDEX idx_trading_signals_symbol ON trading_signals (symbol);
CREATE INDEX idx_trading_signals_created_at ON trading_signals (created_at DESC);
CREATE INDEX idx_trading_signals_signal ON trading_signals (signal);

-- Table: analysis_jobs
-- Tracks background job progress and status for real-time UI updates
CREATE TABLE analysis_jobs (
  id TEXT PRIMARY KEY,
  status TEXT NOT NULL DEFAULT 'started',
  current_step TEXT DEFAULT 'Initializing...',
  step_message TEXT DEFAULT 'Starting analysis...',
  progress_percentage INTEGER DEFAULT 0,
  event_data JSONB,
  signals_generated INTEGER DEFAULT 0,
  alerts_generated INTEGER DEFAULT 0,
  duration_ms INTEGER,
  started_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  completed_at TIMESTAMP WITH TIME ZONE,
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Indexes for analysis_jobs table (for performance)
CREATE INDEX idx_analysis_jobs_status ON analysis_jobs (status);
CREATE INDEX analysis_jobs_progress_idx ON analysis_jobs (status, started_at DESC, progress_percentage);

4. Click "Run" to execute the script
5. Verify tables: Go to Table Editor → you should see trading_signals and analysis_jobs tables

Step 6: Inngest Background Jobs Setup ⚡

Inngest handles our AI analysis pipeline with real-time progress tracking.

1. Create account: Visit inngest.com → "Sign up"
2. Create new app:
   • App name: ai-trading-agent
3. Get keys: Settings → Keys
   • Copy Event Key (starts with inngest_)
   • Copy Signing Key (starts with signkey_)
4. Add to .env.local:

INNGEST_EVENT_KEY=inngest_your_event_key_here
INNGEST_SIGNING_KEY=signkey_your_signing_key_here

💡 Why Inngest? Enables complex multi-step AI workflows with real-time progress tracking without blocking the user interface.

Step 7: Final Environment Check ✅

Your .env.local should look like this:

# LunarCrush API (Required)
LUNARCRUSH_API_KEY=lc_your_key_here

# Google Gemini AI (Required)
GOOGLE_GEMINI_API_KEY=your_gemini_key_here

# Supabase Database (Required)
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key_here

# Inngest Background Jobs (Required)
INNGEST_EVENT_KEY=inngest_your_event_key_here
INNGEST_SIGNING_KEY=signkey_your_signing_key_here

🚀 Running the Application

Development Mode

Terminal 1 - Next.js App:

npm run dev

→ Visit http://localhost:3000

Terminal 2 - Inngest Dev Server:

npm run inngest:dev

→ Visit http://localhost:8288 for job monitoring

Testing the Complete Pipeline

1. Open the app: http://localhost:3000
2. Click "Generate Trading Signals"
3. Watch real-time progress: 7-step analysis with live progress tracking
4. Monitor Inngest: Check localhost:8288 for detailed job execution
5. View results: Trading signals appear automatically when complete

Expected Flow:

Initialize Analysis (14%) →
Prepare Symbol List (28%) →
Fetch Social Data (42%) →
AI Signal Generation (57%) →
Save to Database (71%) →
Generate Summary (85%) →
Complete Analysis (100%)

🏗️ Architecture Overview

Technology Stack

Data Flow Architecture

    A[User Triggers Analysis] --> B[Inngest Background Job]
    B --> C[LunarCrush API]
    C --> D[Social Metrics]
    D --> E[Google Gemini AI]
    E --> F[Trading Signals]
    F --> G[Supabase Database]
    G --> H[Real-time UI Updates]

Real-Time Progress System

// Real-time progress tracking flow
1. User clicks "Generate Trading Signals"
2. Frontend calls /api/trigger → generates jobId
3. Inngest workflow starts → uses consistent jobId
4. Each step updates database → analysis_jobs table
5. Frontend subscribes → Supabase real-time events
6. Progress bar advances → 14% → 28% → ... → 100%
7. Signals appear → when job status = 'completed'

Key Files Structure

src/
├── app/
│   ├── api/
│   │   ├── signals/route.ts      # Fetch trading signals & jobs
│   │   ├── trigger/route.ts      # Start analysis pipeline
│   │   ├── job-status/route.ts   # Check job progress
│   │   └── inngest/route.ts      # Inngest webhook endpoint
│   ├── layout.tsx                # App layout with metadata
│   └── page.tsx                  # Main dashboard with real-time UI
├── functions/
│   └── signal-analysis.ts        # 7-step Inngest workflow
├── hooks/
│   └── useJobProgress.ts        # Progress supabase subscription
├── lib/
│   ├── lunarcrush.ts            # LunarCrush API client
│   ├── gemini.ts