Developer Setup Guide

Step-by-step instructions to configure and run the TokenSight AI local development environment.

Prerequisites

Before setting up TokenSight AI locally, ensure that your development machine has the following tools and account keys configured:

Node.js 18+

LTS version is recommended. Required to compile React components, execute Next.js route handlers, and run linting/build tools.

Supabase Project

Create a database project at supabase.com. Used to provision the PostgreSQL database, manage Row Level Security policies, and store profiles and scans.

Privy Console

Register an application at dashboard.privy.io to retrieve your Privy App ID and App Secret. Used for user identity and non-custodial wallet auth.

Solana RPC API Keys

Account endpoints with Helius, Birdeye, DexScreener, and Jupiter to retrieve real-time token states, pool reserves, and pricing feeds.

OpenRouter Key

API key from openrouter.ai to access LLM completion queries (e.g. gpt-4o-mini) for automated token summary analytics.

Step 1: Clone the Repository

Clone the TokenSight AI repository to your local computer and navigate into the workspace directory:

git clone https://github.com/mrarindam/TokenSight-Ai.git
cd TokenSight-Ai

Step 2: Install Dependencies

Install the required packages using npm. The workspace resolves all dependencies (Next.js, Privy, Supabase, Tailwind, Framer Motion) at the root level:

npm install

Step 3: Configure Environment Variables

Create a new file named .env.local in the root directory. Copy the keys from .env.example and populate them with your credentials:

# Supabase Credentials
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Privy Non-Custodial Authentication
NEXT_PUBLIC_PRIVY_APP_ID=your-privy-app-id
PRIVY_APP_SECRET=your-privy-app-secret

# Application URL Configurations
APP_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Solana API Keys & Services
BIRDEYE_API_KEY=your-birdeye-api-key
BAGS_API_KEY=your-bags-api-key
HELIUS_API_KEY=your-helius-api-key
JUPITER_API_KEY=your-jupiter-api-key

# LLM AI Integration (OpenRouter)
OPENROUTER_API_KEY=your-openrouter-key
OPENROUTER_MODEL=openai/gpt-4o-mini

# Telegram Integration
TELEGRAM_BOT_TOKEN=your-telegram-bot-token
CRON_SECRET=your-cron-secret

Step 4: Set Up Supabase Database Tables

Execute SQL queries in your Supabase SQL Editor to prepare the database. Ensure Row Level Security (RLS) is configured correctly for the tables:

users

Caches authenticated user profiles, Privy wallet identifiers, streak counters, and premium membership tiers.

user_stats

Tracks lifetime scan volumes, current streaks, experience levels, and league standings.

scans

Persists analyzed token details (mint addresses, overall intelligence scores, volume, risk checks).

price_alerts

Stores target prices, conditions, token metadata, and user links for Telegram notifications.

ip_scans

Logs rate-limiting activities mapping anonymous IP lookups to daily scan reset tickers.

Step 5: Run the Development Server

Start the local Next.js development server. The project will compile assets and launch on port 3000:

npm run dev

Step 6: Verify TypeScript Types

Confirm that the codebase has no compilation errors or type inconsistencies:

npx tsc --noEmit

Project Directory Structure

The workspace is structured cleanly as follows:

TokenSight-Ai/
├── .env.local                  # Environment keys
├── package.json                # Next.js and Tailwind configurations
├── tailwind.config.ts          # Styling theme configurations
│
└── src/
    ├── app/                    # Next.js App Router directories
    │   ├── api/                # Route handlers (scan, telegram alerts, trending)
    │   ├── scan/               # Token scanner pages
    │   ├── portfolio/          # Portfolio tracker dashboard
    │   ├── alerts/             # User price alerts manager
    │   ├── docs/               # Documentation routes
    │   └── layout.tsx          # Global styles wrapper
    │
    ├── components/             # Reusable React components
    │   ├── layout/             # Header, footer, app layouts
    │   ├── ui/                 # Buttons, modals, skeletons
    │   └── RecentActivity.tsx  # Dashboard tables
    │
    └── lib/                    # Shared helpers and utilities
        ├── auth.ts             # Privy auth checks and login sync hooks
        ├── streak-logic.ts     # User streak calculations
        └── ip-limit.ts         # Anonymous user limits logic