🌌 Cosmic Vibe Generator

Read your onchain energy and generate unique cosmic moods with AI-powered insights, 3D visualizations, and meme magic.

For security and IP protection, the full production code is currently hosted privately. This repository demonstrates the project structure and documentation.

📖 Table of Contents

Overview
Features
Live Demo
Tech Stack
Getting Started
Architecture
API Documentation
Environment Variables
Deployment
Contributing
License

Overview

Cosmic Vibe Generator is an AI-powered onchain experience that reads your wallet's blockchain activity on Base Network and generates personalized cosmic readings. It combines real-time blockchain data analysis, AI-generated insights, 3D cosmic visualizations, and meme suggestions to create a unique, shareable experience.

What Makes It Special?

🤖 AI-Powered Insights: Uses Claude 3.5 Haiku to generate personalized cosmic readings based on your actual onchain activity
⛓️ Real Blockchain Data: Fetches live transaction history, token holdings, and gas analytics from Base Network
🌈 3D Cosmic Visualization: Interactive Three.js visualizations that respond to your onchain energy
🎭 Meme Magic: AI-curated meme suggestions via Tenor API that match your cosmic vibe
🏆 Gamification: 20+ achievements unlockable through app usage and onchain activity
💾 IPFS Storage: Permanent NFT metadata storage via Pinata
📊 Analytics Dashboard: Comprehensive metrics tracking with beautiful recharts visualizations
🚀 Token Launch Integration: Direct integration with Memebase for launching tokens

Features

🔐 Wallet & Authentication

SIWE (Sign-In with Ethereum) for secure, decentralized authentication
Multi-wallet support: Coinbase Wallet, MetaMask, Phantom, Rabby, Trust
Smart Wallet support via Coinbase's OnchainKit
Base Network integration with seamless RPC connectivity

🧠 AI-Powered Cosmic Readings

Personalized insights generated by Claude 3.5 Haiku
Analysis of:
- Transaction patterns and frequency
- Wallet age and activity level
- Gas spending habits
- Token holdings diversity
- Contract interactions
Cosmic attributes: Energy, Luck, Chaos, Wisdom, Power (0-100 scale)
Lucky numbers and elemental affinities (Fire, Water, Earth, Air, Ether)
Fallback deterministic generation when AI is unavailable

📊 Onchain Analytics

Real-Time Token Prices

Dual price sources: OnchainKit API (primary) + CoinGecko (fallback)
Live prices for: ETH, USDC, DEGEN, BRETT, TOSHI
Price change indicators and market caps
Automatic fallback handling

Deep Onchain Insights

Transaction history with full details
Gas analytics: Total burned, efficiency score, avg gas price
Portfolio tracking: Token balances with USD values
Network statistics: Total transactions, account age, last activity
Fun facts: Coffee equivalents, efficiency ratings

🎨 Visualizations

3D Cosmic Visual

Interactive Three.js scene with particle systems
Dynamic colors based on cosmic energy levels
Responsive animations that pulse with vibe intensity
Touch-friendly controls on mobile devices
Smooth camera movements and transitions

Analytics Charts

7-day activity trends (Area charts)
Daily engagement breakdown (Bar charts)
Activity distribution (Pie charts)
Cumulative progress (Line charts)
Built with recharts for beautiful, responsive visualizations

🏆 Gamification System

20+ Achievements in 4 Categories:

Crypto-Native Badges 💎

Diamond Hands (30+ days holding)
Cosmic Whale (1000+ transactions)
Based Builder (250+ transactions)
OG User (100+ days old account)
Early Adopter (30+ days old)

DeFi Achievements 🔥

DeFi Degen (10+ unique contracts)
Speed Runner (20+ txs/day average)
Gas Guzzler ($100+ gas burned)
Power User (100+ transactions)

App Engagement 🌟

Vibe Master (10 vibes generated)
NFT Collector (5 NFTs minted)
Token Launcher (first token launch)
Social Butterfly (5+ shares)
Analytics Pro (viewed analytics)
3D Explorer (visited 3D world)
Tour Graduate (completed onboarding)

Speed Achievements ⚡

Quick Starter (first vibe < 10 mins)
Speedster (NFT minted < 5 mins)
Lightning Fast (token launch < 5 mins)

📸 Export & Sharing

Download cosmic readings as PNG images
Shareable vibe cards with all attributes and AI insights
One-click social sharing to Twitter, Farcaster, Discord
Professional card design with gradients and shadows

🎭 Meme Integration

AI-curated memes via Tenor API
Memes matched to your cosmic vibe and personality
Infinite scroll with pagination support
High-quality GIF previews

🪙 NFT Minting

Mint your cosmic vibe as an NFT on Base
IPFS metadata storage via Pinata
Permanent, decentralized storage
BaseScan integration for viewing minted NFTs
Direct links to IPFS metadata

🚀 Token Launch (Memebase Integration)

Launch tokens directly from the app
Integration with Memebase platform
One-click deployment to Base Network
Track launched tokens in portfolio

📈 Metrics Dashboard

Three Comprehensive Tabs:

Overview Tab

Engagement score (0-100)
Activity level badges (Cosmic Master, Active Explorer, Rising Star, etc.)
Quick stats grid (vibes, NFTs, tokens, shares)

Engagement Tab

Detailed breakdown with progress bars:
- Vibe Generations
- NFT Mints
- Token Launches
- Social Shares
- Tour Completions

Onchain Tab

Wallet statistics
Transaction counts
Account age
Network information
Real-time session tracking

🎓 Guided Tour

9-step interactive onboarding
Spotlight effect highlighting current tour target
Progress indicators with visual dots
localStorage persistence (shows once)
Restart Tour button for replays
Covers all major features

🎨 UI/UX Excellence

Loading states for all async operations
Skeleton loaders for content placeholders
Animated transitions and micro-interactions
Dark mode optimized design
Mobile-responsive layouts
Touch-friendly controls
Accessibility features (ARIA labels, keyboard navigation)

Live Demo

Visit https://vibegen.streamlit.app/

Quick Start:

Open the app in a Web3-enabled browser
Connect your wallet (Coinbase, MetaMask, etc.)
Follow the guided tour to explore features
Generate your first cosmic vibe!

Tech Stack

Frontend

Next.js 15.3.8 - React framework with App Router
React 19 - UI library
TypeScript - Type safety
Tailwind CSS v4 - Styling
Framer Motion - Animations

Web3 & Blockchain

wagmi 2.18.2 - React hooks for Ethereum
viem 2.38.4 - TypeScript Ethereum library
OnchainKit 1.1.1 - Coinbase's Base toolkit
SIWE - Sign-In with Ethereum

3D Graphics

Three.js - 3D rendering engine
@react-three/fiber - React renderer for Three.js
@react-three/drei - Useful helpers for R3F

AI & APIs

Anthropic Claude 3.5 Haiku - AI-powered cosmic readings
Tenor API - Meme search and suggestions
Pinata API - IPFS storage for NFT metadata
CoinGecko API - Fallback price data

Data Visualization

Recharts - Beautiful, responsive charts
html2canvas - Screenshot generation for export

Storage & State

localStorage - Client-side persistence
Browser-native state management
No external state libraries needed

Getting Started

Prerequisites

Node.js 18+ and pnpm (or npm/yarn)
Base Network RPC URL (Alchemy, Infura, or public RPC)
API Keys:
- Anthropic Claude API key
- Pinata API key
- OnchainKit API key & Project ID
- Tenor API key (optional, embedded key provided)

Installation

# Clone the repository
git clone https://github.com/mrbrightsides/VibeGen.git
cd cosmic-vibe-generator

# Install dependencies
pnpm install

# Set up environment variables (see below)
cp .env.example .env.local

# Run development server
pnpm dev

# Open http://localhost:3000

Environment Variables

Create a .env.local file in the root directory:

# Blockchain
NEXT_PUBLIC_SDK_CHAIN_ID=8453
RPC_URL=https://base-mainnet.g.alchemy.com/v2/YOUR_KEY

# AI
ANTHROPIC_API_KEY=sk-ant-api03-xxxxx

# IPFS
PINATA_API_KEY=xxxxx

# OnchainKit (Coinbase)
NEXT_PUBLIC_ONCHAINKIT_API_KEY=xxxxx
NEXT_PUBLIC_ONCHAINKIT_PROJECT_ID=xxxxx

# Optional
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=xxxxx

See Environment Variables section for detailed descriptions.

Architecture

High-Level Overview

┌─────────────────────────────────────────────────────────┐
│                    Frontend (Next.js)                    │
├─────────────────────────────────────────────────────────┤
│  • React Components (TSX)                                │
│  • Wagmi/Viem for Web3                                   │
│  • Three.js for 3D                                       │
│  • Tailwind CSS for styling                              │
└────────────┬────────────────────────────┬────────────────┘
             │                            │
             │ API Routes                 │ Direct RPC
             │                            │
┌────────────▼────────────┐  ┌────────────▼────────────┐
│   Backend APIs          │  │    Base Network         │
│  • /api/generate-vibe   │  │  • Transaction History  │
│  • /api/ipfs-upload     │  │  • Token Prices         │
│  • /api/proxy           │  │  • Gas Analytics        │
└────────────┬────────────┘  └─────────────────────────┘
             │
             │
┌────────────▼──────────────────────────────────────────┐
│              External Services                         │
│  • Anthropic Claude API (AI)                          │
│  • Pinata (IPFS)                                       │
│  • CoinGecko (Prices)                                  │
│  • Tenor (Memes)                                       │
└────────────────────────────────────────────────────────┘

Directory Structure

cosmic-vibe-generator/
├── src/
│   ├── app/
│   │   ├── api/                  # Next.js API routes
│   │   │   ├── generate-vibe/    # Claude AI endpoint
│   │   │   ├── ipfs-upload/      # Pinata IPFS endpoint
│   │   │   └── proxy/            # External API proxy
│   │   ├── components/           # React components
│   │   │   ├── AchievementSystem.tsx
│   │   │   ├── CosmicVisual.tsx
│   │   │   ├── EnhancedAnalyticsCharts.tsx
│   │   │   ├── GuidedTour.tsx
│   │   │   ├── LoadingStates.tsx
│   │   │   ├── MetricsDashboard.tsx
│   │   │   ├── NFTMinter.tsx
│   │   │   ├── RealTokenPrices.tsx
│   │   │   ├── ShareableVibeCard.tsx
│   │   │   └── VibeExporter.tsx
│   │   ├── config/               # Configuration files
│   │   │   └── onchainkit.ts     # OnchainKit config
│   │   ├── lib/                  # Utility libraries
│   │   │   ├── vibeGenerator.ts  # Vibe generation logic
│   │   │   ├── vibeTypes.ts      # TypeScript types
│   │   │   └── wagmi.ts          # Wagmi configuration
│   │   ├── types/                # TypeScript types
│   │   │   └── api.ts            # OnchainKit API types
│   │   ├── layout.tsx            # Root layout
│   │   ├── page.tsx              # Main page
│   │   ├── providers.tsx         # React context providers
│   │   └── globals.css           # Global styles
│   └── tenor-api.ts              # Tenor API client
├── public/                       # Static assets
├── docs/                         # Additional documentation
├── README.md                     # This file
├── package.json                  # Dependencies
└── tsconfig.json                 # TypeScript config

Component Architecture

Core Components

VibeGenerator - Main orchestrator
- Fetches blockchain data
- Calls AI API
- Manages state
- Coordinates child components
CosmicVisual - 3D visualization
- Three.js scene rendering
- Particle systems
- Camera controls
- Responsive design
EnhancedAnalyticsCharts - Data visualization
- Area, Bar, Pie, Line charts
- 7-day activity tracking
- Recharts integration
AchievementSystem - Gamification
- 20+ achievement badges
- Progress tracking
- localStorage persistence
GuidedTour - Onboarding
- 9-step tour
- Spotlight effect
- Progress indicators

Data Flow

User Action (Connect Wallet)
    ↓
Fetch Onchain Data (wagmi/viem)
    ↓
Generate Cosmic Vibe (AI API)
    ↓
Render Components (React)
    ↓
Update Metrics (localStorage)
    ↓
Track Achievements

API Documentation

`/api/generate-vibe`

POST - Generate AI-powered cosmic reading

Request Body

{
  address: string;           // Wallet address
  transactionCount: number;  // Total transactions
  lastActivity: string;      // ISO timestamp
  walletAge: number;         // Days since creation
  balance: string;           // ETH balance
  uniqueContracts: number;   // Unique contract interactions
}

Response

{
  success: true,
  data: {
    energy: number;         // 0-100
    luck: number;          // 0-100
    chaos: number;         // 0-100
    wisdom: number;        // 0-100
    power: number;         // 0-100
    element: string;       // "Fire" | "Water" | "Earth" | "Air" | "Ether"
    prediction: string;    // AI-generated message
    cosmicNumber: number;  // 1-100
    timestamp: string;
  }
}

`/api/ipfs-upload`

POST - Upload NFT metadata to IPFS via Pinata

Request Body

{
  metadata: {
    name: string;
    description: string;
    image: string;
    attributes: Array<{
      trait_type: string;
      value: string | number;
    }>;
  }
}

Response

{
  success: true,
  ipfsHash: string;      // "QmXxx..."
  ipfsUrl: string;       // "ipfs://QmXxx..."
  gatewayUrl: string;    // "https://gateway.pinata.cloud/ipfs/QmXxx..."
}

`/api/proxy`

POST - Proxy for external API calls (handles CORS)

Request Body

{
  protocol: "https";
  origin: string;        // e.g., "api.example.com"
  path: string;          // e.g., "/v1/search"
  method: "GET" | "POST" | "PUT" | "DELETE";
  headers: Record<string, string>;
  body?: any;            // Optional request payload
}

Environment Variables (Detailed)

Required Variables

`NEXT_PUBLIC_SDK_CHAIN_ID`

Type: number
Description: Chain ID for Base Network
Values:
- 8453 - Base Mainnet
- 84532 - Base Sepolia Testnet
Example: 8453

`RPC_URL`

Type: string
Description: RPC endpoint for Base Network
Providers:
- Alchemy: https://base-mainnet.g.alchemy.com/v2/YOUR_KEY
- Infura: https://base-mainnet.infura.io/v3/YOUR_KEY
- Public: https://mainnet.base.org
Example: https://base-mainnet.g.alchemy.com/v2/abc123

`ANTHROPIC_API_KEY`

Type: string
Description: API key for Claude AI
Get it: https://console.anthropic.com/
Format: sk-ant-api03-xxxxx
Example: sk-ant-api03-jmUHB7KMjwz2IE0r_-wxt0eTJC5r...

`PINATA_API_KEY`

Type: string
Description: API key for Pinata IPFS
Get it: https://app.pinata.cloud/
Example: defe46eca26f7f1679ca

`NEXT_PUBLIC_ONCHAINKIT_API_KEY`

Type: string
Description: API key for Coinbase OnchainKit
Get it: https://portal.cdp.coinbase.com/
Example: xxxxx-xxxxx-xxxxx-xxxxx

`NEXT_PUBLIC_ONCHAINKIT_PROJECT_ID`

Type: string
Description: Project ID for OnchainKit
Get it: https://portal.cdp.coinbase.com/
Example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Optional Variables

`NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID`

Type: string
Description: WalletConnect Cloud project ID
Get it: https://cloud.walletconnect.com/
Required for: Enhanced wallet connection UI
Example: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Deployment

Vercel (Recommended)

Push to GitHub

git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/mrbrightsides/VibeGen.git
git push -u origin main

Deploy to Vercel
- Go to vercel.com
- Click "New Project"
- Import your GitHub repository
- Add environment variables from .env.local
- Click "Deploy"
Custom Domain (Optional)
- Add your domain in Vercel dashboard
- Update DNS records
- SSL is automatic

Docker

# Dockerfile
FROM node:18-alpine AS base
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

FROM node:18-alpine AS runner
WORKDIR /app
COPY --from=base /app/.next ./.next
COPY --from=base /app/public ./public
COPY --from=base /app/package*.json ./
RUN npm install --production
EXPOSE 3000
CMD ["npm", "start"]

# Build and run
docker build -t cosmic-vibe-generator .
docker run -p 3000:3000 --env-file .env.local cosmic-vibe-generator

Environment-Specific Builds

# Development
pnpm dev

# Production build
pnpm build
pnpm start

# Preview deployment
vercel --prod

Contributing

We welcome contributions! Here's how you can help:

Development Setup

Fork the repository

Clone your fork

git clone https://github.com/mrbrightsides/VibeGen.git
cd cosmic-vibe-generator

Create a branch
```
git checkout -b feature/amazing-feature
```
Make your changes
- Follow the existing code style
- Add TypeScript types for all new code
- Test thoroughly on both desktop and mobile
Commit your changes
```
git commit -m "Add amazing feature"
```
Push to your fork
```
git push origin feature/amazing-feature
```
Open a Pull Request
- Describe your changes
- Link any related issues
- Add screenshots for UI changes

Code Style Guidelines

TypeScript: Use explicit types, avoid any
Components: Functional components with hooks
Naming:
- Components: PascalCase
- Functions: camelCase
- Constants: UPPER_SNAKE_CASE
Imports: Group and sort (React → Third-party → Local)
Comments: Explain "why", not "what"

Testing

# Run type checking
pnpm tsc --noEmit

# Run build test
pnpm build

# Manual testing checklist
- [ ] Connect wallet
- [ ] Generate vibe
- [ ] View 3D visualization
- [ ] Check analytics
- [ ] Mint NFT
- [ ] Export vibe card
- [ ] Test on mobile
- [ ] Test different wallets

License

This project is licensed under the MIT License.

MIT License

Copyright (c) 2025 Cosmic Vibe Generator

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Acknowledgments

Coinbase for OnchainKit and Base Network
Anthropic for Claude AI
Pinata for IPFS infrastructure
Vercel for hosting platform
Base community for inspiration and support
Coin Gecko for free real time token prices public API

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Telegram: @khudriakhmad
Discord: Join our community

🗺️ Roadmap

Phase 1 ✅ (Completed)

Phase 2 🚧 (In Progress)

Multi-chain support (Optimism, Arbitrum)
Social leaderboards with rankings
Advanced 3D scenes and interactions
More AI models (GPT-4, Gemini)
Custom NFT artwork generation

Phase 3 🔮 (Planned)

Built with ❤️ on Base

ELPEEF • RANTAI

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
ARCHITECTURE.md		ARCHITECTURE.md
LICENSE		LICENSE
README.md		README.md
app.py		app.py

License

mrbrightsides/VibeGen

Folders and files

Latest commit

History

Repository files navigation

🌌 Cosmic Vibe Generator

Read your onchain energy and generate unique cosmic moods with AI-powered insights, 3D visualizations, and meme magic.

📖 Table of Contents

Overview

What Makes It Special?

Features

🔐 Wallet & Authentication

🧠 AI-Powered Cosmic Readings

📊 Onchain Analytics

Real-Time Token Prices

Deep Onchain Insights

🎨 Visualizations

3D Cosmic Visual

Analytics Charts

🏆 Gamification System

20+ Achievements in 4 Categories:

📸 Export & Sharing

🎭 Meme Integration

🪙 NFT Minting

🚀 Token Launch (Memebase Integration)

📈 Metrics Dashboard

Three Comprehensive Tabs:

🎓 Guided Tour

🎨 UI/UX Excellence

Live Demo

Quick Start:

Tech Stack

Frontend

Web3 & Blockchain

3D Graphics

AI & APIs

Data Visualization

Storage & State

Getting Started

Prerequisites

Installation

Environment Variables

Architecture

High-Level Overview

Directory Structure

Component Architecture

Core Components

Data Flow

API Documentation

/api/generate-vibe

Request Body

Response

/api/ipfs-upload

Request Body

Response

/api/proxy

Request Body

Environment Variables (Detailed)

Required Variables

NEXT_PUBLIC_SDK_CHAIN_ID

RPC_URL

ANTHROPIC_API_KEY

PINATA_API_KEY

NEXT_PUBLIC_ONCHAINKIT_API_KEY

NEXT_PUBLIC_ONCHAINKIT_PROJECT_ID

Optional Variables

NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID

Deployment

Vercel (Recommended)

Docker

Environment-Specific Builds

Contributing

Development Setup

Code Style Guidelines

Testing

License

Acknowledgments

Support

🗺️ Roadmap

`/api/generate-vibe`

`/api/ipfs-upload`

`/api/proxy`

`NEXT_PUBLIC_SDK_CHAIN_ID`

`RPC_URL`

`ANTHROPIC_API_KEY`

`PINATA_API_KEY`

`NEXT_PUBLIC_ONCHAINKIT_API_KEY`

`NEXT_PUBLIC_ONCHAINKIT_PROJECT_ID`

`NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID`

Packages