solsniper - Production-Grade Solana Token Monitor

A high-performance, production-ready Solana token monitoring system that efficiently ingests, filters, enriches, and alerts on new token pool creations across multiple DEXs (Jupiter, Raydium, Orca).

🎯 Features

• Real-time Monitoring: WebSocket-based streaming from Helius with auto-reconnect
• Multi-DEX Support: Jupiter V6, Raydium AMM V4, Orca Whirlpool
• Smart Filtering: 95% message drop rate with light filters
• Risk Assessment: Automated checks for mint authority, freeze authority, ownership concentration
• Rate Limiting: Token bucket algorithm respecting 10 req/sec limits
• Caching: SQLite-based caching with TTL for efficient data reuse
• Alerts: Telegram and webhook notifications for qualified tokens
• Production Ready: Graceful shutdown, health checks, metrics, batch writes

📋 Requirements

• Node.js v20+
• TypeScript 5.3+
• RAM: 4GB minimum (runs efficiently under 16GB)
• Helius API Key: Required for RPC and WebSocket access

🚀 Quick Start

1. Installation

# Clone the repository
git clone <your-repo-url>
cd solsniper
Install dependencies
npm install
Copy environment file
cp .env.example .env

2. Configuration

Edit .env and set your Helius API key and other parameters:

# Required
HELIUSAPIKEY=yourheliusapikeyhere
Optional (for alerts)
TELEGRAMBOTTOKEN=yourtelegrambot_token
TELEGRAMCHATID=yourtelegramchat_id
WEBHOOK_URL=https://your-webhook-endpoint.com/alerts

3. Build and Run

# Build TypeScript
npm run build
Run in production
npm start
Or run in development mode
npm run dev

📊 System Architecture

WebSocket Stream → Light Filter → Ring Buffer → Enrichment → Risk Assessment → Alerts → Database

Components

• WebSocket Client (src/ws/client.ts): Connects to Helius with auto-reconnect
• Subscription Manager (src/ws/subscription.ts): Subscribes to DEX program logs
• Light Filter (src/filters/lightFilter.ts): Fast rejection of irrelevant messages
• Ring Buffer (src/filters/ringBuffer.ts): FIFO queue with overflow handling
• Enrichment (src/enrich/): Fetches metadata, liquidity, holder data
• Risk Assessor (src/risk/assessment.ts): Evaluates token safety
• Alert System (src/alerts/): Sends Telegram and webhook notifications
• Database (src/db/): SQLite with batch writes and caching

🔧 Configuration

Filtering Thresholds

MINLIQUIDITYUSD=30000          # Minimum $30k liquidity
MINTOKENAGE_MINUTES=5          # Wait 5 minutes after pool creation
MAXCREATOROWNERSHIP_PCT=60     # Max 60% creator ownership
MINHOLDERCOUNT=50              # Minimum 50 holders

Rate Limiting

RPCRATELIMIT=10                # 10 requests per second
RPCBURSTCAP=20                 # Burst capacity of 20

Cache TTLs

CACHETTLTOKENMETADATAHOURS=24   # Cache metadata for 24 hours
CACHETTLLIQUIDITY_MINUTES=5       # Cache liquidity for 5 minutes
CACHETTLHOLDERS_HOURS=3           # Cache holders for 3 hours

🔍 Monitoring

Health Check

# Check system health
curl http://localhost:3000/health

Response:

{   "status": "healthy",   "uptime": 3600000,   "websocket": { "connected": true },   "queues": { "ringBuffer": 234 } }

Metrics

# Prometheus-format metrics
curl http://localhost:3000/metrics

🚨 Alerts

Telegram Format

🚀 NEW POOL DETECTED
Token: $SYMBOL (NAME) Mint: AbC123...xyz789
💰 Liquidity: $45,230 📊 DEX: Raydium AMM V4 👥 Holders: 67 ⏰ Age: 12 minutes
⚠️ Risk Flags: • Creator holds 42% of supply
🔗 DexScreener | Solscan

Webhook Payload

{
  "alertType": "NEW_POOL",
  "timestamp": 1704067200000,
  "token": {
    "mint": "...",
    "name": "Example Token",
    "symbol": "EXMPL"
  },
  "pool": {
    "dex": "raydium",
    "liquidityUSD": 45230
  },
  "riskFlags": ["MINTAUTHORITYACTIVE"]
}

🐳 Docker Deployment

# Build image
docker build -t solsniper .
Run container
docker run -d \
  --name solsniper \
  --env-file .env \
  -p 3000:3000 \
  -v $(pwd)/data:/app/data \
  solsniper

Or use Docker Compose:

docker-compose up -d

🧪 Testing

DRY RUN Mode

Test without sending alerts or writing to database:

DRY_RUN=true npm start

Test Alerts

# Test Telegram
curl -X POST http://localhost:3000/test/telegram
Test Webhook
curl -X POST http://localhost:3000/test/webhook

📁 Project Structure

solsniper/
├── src/
│   ├── config/          # Configuration and constants
│   ├── ws/              # WebSocket client and subscriptions
│   ├── filters/         # Light filter and ring buffer
│   ├── enrich/          # Data enrichment (metadata, liquidity, holders)
│   ├── db/              # Database, cache, batch writer
│   ├── risk/            # Risk assessment and blacklist
│   ├── alerts/          # Telegram and webhook clients
│   ├── utils/           # Logger, metrics, rate limiter
│   └── index.ts         # Main entry point
├── data/                # SQLite database
├── blacklist.json       # Blacklisted wallets
├── .env                 # Environment variables
└── package.json

🛠️ Development

# Install dependencies
npm install
Run in development mode (with hot reload)
npm run dev
Build TypeScript
npm run build
Type checking
npx tsc --noEmit

📝 Logs

Structured JSON logging to stdout:

{
  "timestamp": "2024-01-01T12:00:00.000Z",
  "level": "INFO",
  "message": "Message passed filter",
  "signature": "...",
  "dex": "raydium"
}

Set log level:

LOG_LEVEL=debug npm start

🔒 Security

• Blacklist system for known scam wallets
• Risk scoring for suspicious tokens
• Rate limiting to prevent API abuse
• No private keys stored or required

📊 Performance

• Memory Usage: ~2-4GB under load
• Message Throughput: 1000+ messages/sec
• Filter Efficiency: 95%+ drop rate
• Alert Latency: <5 seconds from pool creation
• Database Size: ~1MB/day

🐛 Troubleshooting

WebSocket keeps disconnecting

• Check Helius API key is valid
• Verify network connectivity
• Check logs for error messages

No alerts being generated

• Ensure tokens meet minimum criteria (liquidity, holders, age)
• Check DRY_RUN is set to false
• Verify Telegram/Webhook configuration

High memory usage

• Reduce MESSAGEBUFFERSIZE
• Lower ENRICHMENTWORKERCOUNT
• Increase cache TTLs to reduce API calls

📚 Resources

• Helius Docs
• Solana Web3.js
• DexScreener API
• Jupiter API

📄 License

MIT

🤝 Contributing

Contributions welcome! Please open an issue or PR.

Built with ❤️ for the Solana ecosystem