AlphaLens

AlphaLens is a Web3 wallet and token analysis product built as a modular monolith.

The original motivation of AlphaLens is to explore how Web3 and AI can work together. In this vision, AI is not only a chatbot that explains blockchain data after the fact. It can become a human user's on-chain agent: reading wallet behavior, understanding risk, helping people make better trading and wealth-management decisions, and eventually assisting with actions on-chain under clear human control.

The current project starts with a practical foundation: collect reliable on-chain data first, turn it into structured wallet signals, and then let AI generate readable analysis reports from that data.

Tech Stack

• Frontend: Next.js 15, React 19, TypeScript, TailwindCSS
• Backend: Go 1.25+, Gin, GORM, PostgreSQL, Redis, Zap, Viper, JWT, Swagger
• AI: OpenAI-compatible provider abstraction for OpenAI, Claude/Gemini-compatible gateways, and future model swaps

Current Capabilities

• Wallet analysis with live RPC data
• Native balance, transaction count, contract detection, latest block
• Optional explorer-based recent transactions and address age
• Rule-based wallet scores: total, activity, asset, age, DeFi, and risk
• AI report generation based on structured wallet data
• Dockerized API, frontend, PostgreSQL, and Redis

Configuration

The backend loads defaults from config/config.yaml, then overrides them with environment variables prefixed by ALPHALENS_.

For local development, copy config/config.example.yaml to config/config.yaml and adjust the values you need.

Do not commit real API keys. Prefer environment variables for secrets.

AI

AI is configured under:

ai:
  provider: mock
  api_key: ""
  base_url: ""
  model: ""

Available provider values:

• mock: no external AI request; returns a local mock report
• openai: OpenAI-compatible /chat/completions request
• claude: OpenAI-compatible gateway request, useful for model relay services
• gemini: OpenAI-compatible gateway request, useful for model relay services

Example using an OpenAI-compatible relay:

ai:
  provider: claude
  api_key: ""
  base_url: "https://your-relay.example.com/v1"
  model: "your-model-name"

Then pass the key through an environment variable:

export ALPHALENS_AI_API_KEY="your-api-key"

Or copy the provided example file and edit it locally:

cp .env.example .env

Docker Compose example:

ALPHALENS_AI_PROVIDER=claude \
ALPHALENS_AI_API_KEY="your-api-key" \
ALPHALENS_AI_BASE_URL="https://your-relay.example.com/v1" \
ALPHALENS_AI_MODEL="your-model-name" \
docker compose up -d --build api frontend

The AI provider sends wallet analysis data to:

{base_url}/chat/completions

So the relay or model provider must support the OpenAI-compatible chat completions API.

On-chain Data

RPC and explorer endpoints are configured under onchain:

onchain:
  timeout_seconds: 8
  rpc:
    ethereum: https://rpc.flashbots.net
    base: https://mainnet.base.org
    optimism: https://mainnet.optimism.io
  explorer:
    ethereum: https://eth.blockscout.com/api
    base: https://base.blockscout.com/api

RPC provides balance, nonce, contract code, and latest block. Explorer APIs provide recent transactions and address age when available.

Run Locally

Start PostgreSQL and Redis:

make dev-up

Run the API:

make run

Health check:

curl http://localhost:8080/api/v1/health

Swagger UI:

http://localhost:8080/swagger/index.html

Frontend:

cd frontend
npm install
npm run dev

Frontend URL:

http://localhost:3000

Full stack with Docker:

docker compose up -d --build api frontend

Docker frontend URL:

http://localhost:3001

Frontend checks:

cd frontend
npm run typecheck
npm run build

API

• GET /api/v1/health
• GET /api/v1/token/{address}
• GET /api/v1/wallet/{address}?chain=ethereum
• POST /api/v1/report

Docker

Run the full stack in the background:

docker compose up -d --build api frontend

Check status:

docker compose ps

Follow logs:

docker compose logs -f api frontend