Meme Token Screener

 ███╗   ███╗███████╗███╗   ███╗███████╗    ███████╗ ██████╗██████╗ ███████╗███████╗███╗   ██╗
 ████╗ ████║██╔════╝████╗ ████║██╔════╝    ██╔════╝██╔════╝██╔══██╗██╔════╝██╔════╝████╗  ██║
 ██╔████╔██║█████╗  ██╔████╔██║█████╗      ███████╗██║     ██████╔╝█████╗  █████╗  ██╔██╗ ██║
 ██║╚██╔╝██║██╔══╝  ██║╚██╔╝██║██╔══╝      ╚════██║██║     ██╔══██╗██╔══╝  ██╔══╝  ██║╚██╗██║
 ██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║███████╗    ███████║╚██████╗██║  ██║███████╗███████╗██║ ╚████║
 ╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝╚══════╝    ╚══════╝ ╚═════╝╚═╝  ╚═╝╚══════╝╚══════╝╚═╝  ╚═══╝

AI-Powered Meme Token Scanner with LLM Agent, Wallet Integration & Token Usage Analytics

What Is This?

An intelligent meme token screening system that combines real-time blockchain data with LLM-powered analysis to identify, score, and trade meme tokens on the Base chain.

Key differentiators:

LLM Agent Core — Every token analysis goes through an LLM agent that reasons about risk, narrative, and opportunity. Token usage is tracked per-session with full cost transparency.
Wallet Integration — Direct on-chain execution via Base chain wallet (buy, sell, snipe).
Token Usage Analytics — Track every LLM call: prompt tokens, completion tokens, cost per analysis, cumulative spend.
Telegram Bot Interface — Full control via Telegram commands with real-time alerts.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    Telegram Bot Interface                         │
│   /screen  /buy  /sell  /snipe  /price  /pnl  /usage  /alert   │
└───────┬─────────────┬──────────────┬──────────────┬─────────────┘
        │             │              │              │
        ▼             ▼              ▼              ▼
┌──────────────┐ ┌──────────┐ ┌───────────┐ ┌───────────────┐
│   Scanner    │ │  Wallet  │ │    LLM    │ │    Alert      │
│   Engine     │ │  Engine  │ │   Agent   │ │    Engine     │
├──────────────┤ ├──────────┤ ├───────────┤ ├───────────────┤
│ DexScreener  │ │ Base     │ │ Analysis  │ │ Price Monitor │
│ API          │ │ Chain    │ │ Scoring   │ │ Whale Track   │
│ Token Data   │ │ web3.py  │ │ Narrative │ │ Custom Alert  │
│ Liquidity    │ │ Uniswap  │ │ Reasoning │ │ Cron Jobs     │
└──────┬───────┘ └────┬─────┘ └─────┬─────┘ └───────┬───────┘
       │              │             │               │
       ▼              ▼             ▼               ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Token Usage Tracker                            │
│  prompt_tokens | completion_tokens | cost_usd | model | timestamp│
│  session_stats | daily_stats | cumulative | per_analysis_breakdown│
└─────────────────────────────────────────────────────────────────┘

Features

LLM Agent Analysis

Feature	Description
Risk Scoring	0-100 score based on liquidity, holders, contract safety, social signals
Narrative Detection	AI identifies meme narrative strength and virality potential
Contract Analysis	Detects honeypot, mint functions, ownership renounced
Social Sentiment	Analyzes Twitter/Telegram buzz for the token
Buy/Sell Reasoning	Agent explains why it recommends or warns against a trade

Token Usage Tracking

Metric	Granularity
Prompt Tokens	Per-call, per-session, daily
Completion Tokens	Per-call, per-session, daily
Estimated Cost (USD)	Per-call, per-session, cumulative
Model Used	Logged per-call
Analysis Duration	Latency tracking
Breakdown	Screen cost, alert cost, report cost

Wallet Operations

Feature	Status	Chain
Token Buy	Production	Base
Token Sell	Production	Base
Snipe (auto-buy on liquidity add)	Production	Base
Balance Check	Production	Base
Approve Token	Production	Base
Gas Estimation	Production	Base

Telegram Commands

/screen <query>     — Search and analyze a token
/buy <token> <amt>  — Buy token with ETH amount
/sell <token> <pct>  — Sell percentage of holdings
/snipe <token> <amt> — Auto-buy when liquidity added
/price <token>       — Get current price
/pnl                 — Portfolio PnL summary
/usage               — LLM token usage report
/alerts              — List active alerts
/trending            — Trending tokens on Base
/rugcheck <token>    — Deep contract analysis
/status              — System status

Quick Start

Prerequisites

Python 3.11+
Telegram Bot Token (from @BotFather)
LLM API Key (OpenAI-compatible endpoint)
Base chain wallet with ETH

Installation

git clone https://github.com/joykinder67/meme-token-screener.git
cd meme-token-screener
pip install -r requirements.txt
cp config/.env.example .env
# Edit .env with your credentials
python -m src.main

Environment Variables

# Telegram
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_CHAT_ID=your_chat_id

# LLM Configuration
LLM_API_KEY=your_api_key
LLM_API_BASE=https://api.openai.com/v1
LLM_MODEL=gpt-4o-mini
LLM_MAX_TOKENS=2000
LLM_TEMPERATURE=0.3

# Base Chain Wallet
BASE_RPC_URL=https://mainnet.base.org
WALLET_PRIVATE_KEY=your_private_key
WALLET_ADDRESS=0xYourAddress

# DexScreener (no key needed, but rate limits apply)
DEXSCREENER_BASE_URL=https://api.dexscreener.com/latest/dex

# Token Usage Tracking
USAGE_DB_PATH=./data/token_usage.db
USAGE_ALERT_THRESHOLD_USD=10.00

Token Usage Analytics

The system tracks every LLM call with full transparency:

Per-Analysis Breakdown

┌─────────────────────────────────────────────────────┐
│ Token Analysis: PEPE on Base                         │
├─────────────────────────────────────────────────────┤
│ LLM Calls: 3                                         │
│ ├─ Risk Scoring:      847 prompt + 234 completion    │
│ ├─ Narrative Check:   512 prompt + 189 completion    │
│ └─ Contract Analysis: 1203 prompt + 567 completion   │
│                                                      │
│ Total: 2,562 prompt + 990 completion = 3,552 tokens  │
│ Cost: $0.0043 USD (gpt-4o-mini)                      │
│ Duration: 2.4s                                       │
└─────────────────────────────────────────────────────┘

Daily Summary

┌─────────────────────────────────────────────────────┐
│ Daily Usage — 2026-05-17                             │
├─────────────────────────────────────────────────────┤
│ Analyses: 47                                         │
│ Total Tokens: 156,832 (98,210 prompt + 58,622 compl)│
│ Total Cost: $0.19 USD                                │
│ Avg per Analysis: 3,337 tokens / $0.004 USD          │
│                                                      │
│ Breakdown by Operation:                              │
│ ├─ Screening:   89,420 tokens (57%)                  │
│ ├─ Alerts:      34,210 tokens (22%)                  │
│ ├─ Rugcheck:    21,890 tokens (14%)                  │
│ └─ Reports:     11,312 tokens (7%)                   │
└─────────────────────────────────────────────────────┘

Database Schema

CREATE TABLE token_usage (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
    operation TEXT NOT NULL,          -- 'screen', 'rugcheck', 'alert', 'report'
    model TEXT NOT NULL,              -- 'gpt-4o-mini', 'mimo-v2.5', etc.
    prompt_tokens INTEGER NOT NULL,
    completion_tokens INTEGER NOT NULL,
    total_tokens INTEGER NOT NULL,
    estimated_cost_usd REAL NOT NULL,
    latency_ms INTEGER,
    token_address TEXT,               -- related token if applicable
    session_id TEXT,
    metadata TEXT                     -- JSON blob for extra context
);

CREATE TABLE usage_sessions (
    session_id TEXT PRIMARY KEY,
    started_at DATETIME,
    ended_at DATETIME,
    total_prompt_tokens INTEGER DEFAULT 0,
    total_completion_tokens INTEGER DEFAULT 0,
    total_cost_usd REAL DEFAULT 0,
    analysis_count INTEGER DEFAULT 0
);

Scoring Engine

The LLM agent evaluates tokens across 5 dimensions:

Dimension	Weight	Data Source
Liquidity Safety	25%	DexScreener pool data
Holder Distribution	20%	On-chain analysis
Contract Safety	25%	Bytecode + ABI scan
Social Signal	15%	Twitter/Telegram metrics
Narrative Strength	15%	LLM reasoning

Each dimension gets an LLM-generated score (0-100) with reasoning, then weighted into a final score.

Score Interpretation

80-100 — Strong buy signal, high confidence
60-79 — Moderate opportunity, proceed with caution
40-59 — Mixed signals, small position only
20-39 — High risk, avoid or very small gamble
0-19 — Likely rug/honeypot, do not buy

Project Structure

meme-token-screener/
├── src/
│   ├── __init__.py
│   ├── main.py                    # Application entry point
│   ├── core/
│   │   ├── __init__.py
│   │   ├── config.py              # Configuration management
│   │   ├── database.py            # SQLite database manager
│   │   └── scheduler.py           # Cron task scheduler
│   ├── llm/
│   │   ├── __init__.py
│   │   ├── agent.py               # LLM agent with reasoning
│   │   ├── prompts.py             # Prompt templates
│   │   ├── token_tracker.py       # Token usage tracking
│   │   └── cost_calculator.py     # Cost estimation per model
│   ├── scanner/
│   │   ├── __init__.py
│   │   ├── dexscreener.py         # DexScreener API client
│   │   ├── scoring.py             # Multi-dimensional scoring
│   │   └── trending.py            # Trending token detection
│   ├── wallet/
│   │   ├── __init__.py
│   │   ├── base_chain.py          # Base chain wallet operations
│   │   ├── uniswap.py             # Uniswap V2/V3 router
│   │   └── snipe.py               # Liquidity snipe engine
│   ├── telegram_bot/
│   │   ├── __init__.py
│   │   ├── bot.py                 # Bot initialization
│   │   ├── handlers.py            # Command handlers
│   │   └── formatters.py          # Message formatting
│   └── utils/
│       ├── __init__.py
│       ├── logger.py              # Structured logging
│       └── helpers.py             # Utility functions
├── config/
│   ├── .env.example               # Environment template
│   └── settings.yaml              # Default settings
├── data/                          # SQLite DB, usage logs
├── docs/
│   ├── architecture.md            # System architecture
│   ├── llm-integration.md         # LLM agent details
│   ├── token-usage.md             # Usage tracking guide
│   └── wallet-setup.md            # Wallet configuration
├── examples/
│   ├── screen_token.py            # Screen a token
│   ├── usage_report.py            # Generate usage report
│   └── batch_analysis.py          # Batch token analysis
├── tests/
│   ├── test_scanner.py
│   ├── test_llm_agent.py
│   └── test_token_tracker.py
├── requirements.txt
├── LICENSE
└── README.md

Tech Stack

Runtime: Python 3.11+
LLM: OpenAI-compatible API (GPT-4o-mini, MiMo-V2.5, DeepSeek)
Blockchain: web3.py, Base chain (L2)
DEX: Uniswap V2/V3 on Base
Data: DexScreener API
Bot: python-telegram-bot
Storage: SQLite (usage tracking, alerts, history)
Scheduling: APScheduler / cron

Cost Efficiency

Using gpt-4o-mini as default model:

Operation	Avg Tokens	Avg Cost	Frequency
Token Screen	3,500	$0.004	On-demand
Rugcheck	5,000	$0.006	On-demand
Price Alert Check	800	$0.001	Every 15 min
Auto-Screen Report	15,000	$0.018	Every 6 hours
Daily PnL Report	8,000	$0.010	Daily

Estimated daily cost: $0.15 - $0.50 depending on activity level.

License

MIT License — see LICENSE for details.

Built by joykinder67

Navigation Menu

Repository files navigation

Meme Token Screener

What Is This?

Architecture

Features

LLM Agent Analysis

Token Usage Tracking

Wallet Operations

Telegram Commands

Quick Start

Prerequisites

Installation

Environment Variables

Token Usage Analytics

Per-Analysis Breakdown

Daily Summary

Database Schema

Scoring Engine

Score Interpretation

Project Structure

Tech Stack

Cost Efficiency

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
config		config
data		data
docs		docs
examples		examples
src		src
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation

Meme Token Screener

What Is This?

Architecture

Features

LLM Agent Analysis

Token Usage Tracking

Wallet Operations

Telegram Commands

Quick Start

Prerequisites

Installation

Environment Variables

Token Usage Analytics

Per-Analysis Breakdown

Daily Summary

Database Schema

Scoring Engine

Score Interpretation

Project Structure

Tech Stack

Cost Efficiency

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages