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