solana-sniper-bot/README.md

# ⚡ Solana Sniper Bot

Automated Solana meme coin trading bot — detects new tokens on pump.fun & Raydium, analyzes for rugs, executes via Jupiter + Jito, and manages your portfolio with tiered exits.

![Solana](https://img.shields.io/badge/Solana-black?logo=solana&logoColor=14F195)
![TypeScript](https://img.shields.io/badge/TypeScript-blue?logo=typescript&logoColor=white)
![License](https://img.shields.io/badge/License-MIT-green)

## Features

### 🔍 Token Scanner
- **pump.fun Monitor** — Real-time WebSocket listener for new token launches
- **Raydium Pool Scanner** — Detects new liquidity pools (V4 + CPMM)
- **Copy Trading** — Track profitable wallets and mirror their trades
- **Deduplication** — Unified scanner manager prevents double-detection

### 🛡️ Anti-Rug Analyzer
- **Mint Authority Check** — Is it revoked? (must be)
- **Freeze Authority Check** — Is it revoked? (must be)
- **LP Lock/Burn Verification** — Are liquidity tokens safe?
- **Top Holder Concentration** — Whale distribution analysis
- **Developer Wallet History** — Serial rug deployer detection
- **Social Verification** — Twitter, Telegram, Website check
- **Rugcheck.xyz Integration** — External risk scoring API
- **Token Scoring (0-100)** — Only trades tokens above your threshold

### ⚡ Trade Execution
- **Jupiter V6 SDK** — Optimal swap routing across all Solana DEXs
- **Jito Bundles** — MEV protection + faster transaction inclusion
- **Priority Fees** — Configurable fee strategy
- **Auto-Retry** — Smart retry with escalating fees on failure
- **Paper Trading** — Full simulation mode (no real transactions)

### 📊 Portfolio Management
- **Tiered Take Profits** — Sell 25% at 2x, 3x, 5x automatically
- **Stop Loss** — Configurable (default -30%)
- **Trailing Stop** — Activates at 2x+, trails at -20%
- **Time-Based Exit** — Dumps stale positions
- **Rug Detection Exit** — Emergency sell if liquidity vanishes
- **Real-Time Price Monitoring** — 5-second polling via Jupiter

### 🎮 Control Layer
- **Discord Alerts** — Rich embeds for every trade event
- **Kill Switch** — One command to close everything
- **Risk Manager** — Max position size, concurrent limits, daily loss cap
- **Paper Trade Mode** — Test everything risk-free

## Architecture

```
┌─────────────────────────────────────────────────┐
│                  CONTROL LAYER                   │
│   Risk Manager · Kill Switch · Discord Alerts    │
├──────────┬──────────┬──────────┬────────────────┤
│ SCANNER  │ ANALYZER │ EXECUTOR │   PORTFOLIO    │
│          │          │          │   MANAGER      │
│ pump.fun │ Rug Check│ Jupiter  │                │
│ Raydium  │ Scoring  │ Swap     │ Take Profit    │
│ Copy     │ Socials  │ Jito TX  │ Stop Loss      │
│ Trade    │ LP Check │ Retry    │ Trailing Stop  │
└──────────┴──────────┴──────────┴────────────────┘
         ↑               ↓
    Event Bus (typed events, async handlers)
         ↑               ↓
    SQLite DB (trades, positions, analytics)
```

## Quick Start

### 1. Clone & Install

```bash
git clone https://github.com/jakeshore/solana-sniper-bot.git
cd solana-sniper-bot
npm install
```

### 2. Configure

```bash
cp .env.example .env
# Edit .env with your settings
```

**Minimum required:**
- `HELIUS_API_KEY` — Get one at [helius.dev](https://helius.dev) ($0 for 50K credits/day)
- That's it for paper trading!

**For live trading also add:**
- `WALLET_PRIVATE_KEY` — Your bot wallet's base58 private key
- `PAPER_TRADE=false`

### 3. Generate a Wallet (optional)

```bash
npx tsx src/index.ts generate-wallet
```

This generates a fresh keypair. Fund it with SOL via Phantom/Solflare.

### 4. Run

```bash
# Paper trading (safe, no real money)
npm run paper

# Development mode
npm run dev

# Production
npm run build && npm start
```

## Configuration

### Environment Variables (.env)

| Variable | Default | Description |
|----------|---------|-------------|
| `HELIUS_API_KEY` | — | Helius RPC key (recommended) |
| `WALLET_PRIVATE_KEY` | — | Bot wallet private key (base58) |
| `PAPER_TRADE` | `true` | Paper trade mode |
| `MAX_POSITION_SIZE_SOL` | `0.5` | Max SOL per trade |
| `MAX_DAILY_LOSS_SOL` | `2` | Daily loss limit |
| `MIN_TOKEN_SCORE` | `70` | Minimum safety score (0-100) |
| `USE_JITO` | `true` | Use Jito for MEV protection |
| `DISCORD_WEBHOOK_URL` | — | Discord webhook for alerts |

### Trading Config (config.json)

```json
{
  "takeProfitTiers": [
    { "multiplier": 2, "sellPercent": 25 },
    { "multiplier": 3, "sellPercent": 25 },
    { "multiplier": 5, "sellPercent": 25 }
  ],
  "stopLossPercent": -30,
  "trailingStopPercent": -20,
  "maxHoldTimeMinutes": 60,
  "scanPumpFun": true,
  "scanRaydium": true,
  "copyTradeEnabled": false,
  "trackedWallets": []
}
```

### Copy Trading

Add wallets to track in `config.json`:

```json
{
  "copyTradeEnabled": true,
  "trackedWallets": [
    {
      "address": "WALLET_ADDRESS_HERE",
      "label": "Smart Whale #1",
      "tier": "S",
      "enabled": true,
      "maxCopyAmountSol": 1.0
    }
  ]
}
```

## Token Scoring

Every detected token is scored 0-100:

| Check | Points | Condition |
|-------|--------|-----------|
| Mint Authority | +20 / -30 | Revoked / Active |
| Freeze Authority | +15 / -20 | Revoked / Active |
| LP Locked/Burned | +10 | Verified safe |
| Top 10 Holders <30% | +15 | Good distribution |
| Has Socials | +5 each | Twitter, TG, Website |
| Dev History Clean | +10 / -10 | No prior rugs |
| Rugcheck.xyz | variable | External score |

**Default minimum: 70/100** — configurable via `MIN_TOKEN_SCORE`.

## Safety

⚠️ **This bot trades meme coins, which are extremely high risk.** Most tokens go to zero.

Built-in safety rails:
- ✅ Paper trade mode by default
- ✅ Max position size limit
- ✅ Daily loss limit with auto-shutdown
- ✅ Kill switch for emergencies
- ✅ Wallet isolation (use a dedicated bot wallet)
- ✅ No leverage, spot only
- ✅ Anti-rug scoring before every trade

**Start with paper trading. Then small amounts. Never trade more than you can afford to lose.**

## Tech Stack

| Component | Choice |
|-----------|--------|
| Language | TypeScript (ESM) |
| Runtime | Node.js |
| RPC | Helius / QuickNode |
| DEX | Jupiter V6 API |
| Speed | Jito Bundles |
| Database | SQLite (better-sqlite3) |
| Alerts | Discord Webhooks |

## Project Structure

```
src/
├── index.ts              # Main entry point & CLI
├── types/
│   └── index.ts          # All TypeScript types
├── scanner/
│   ├── pump-fun-scanner.ts    # pump.fun WebSocket listener
│   ├── raydium-scanner.ts     # Raydium new pool detector
│   ├── copy-trade-scanner.ts  # Wallet tracking & mirroring
│   └── index.ts               # Scanner manager
├── analyzer/
│   ├── token-analyzer.ts      # Token safety scoring
│   ├── rugcheck-api.ts        # Rugcheck.xyz integration
│   ├── liquidity-checker.ts   # LP lock/burn verification
│   └── index.ts               # Analyzer pipeline
├── executor/
│   ├── jupiter-swap.ts        # Jupiter V6 swap execution
│   ├── jito-bundler.ts        # Jito bundle submission
│   ├── trade-executor.ts      # High-level trade manager
│   └── index.ts               # Executor exports
├── portfolio/
│   ├── position-manager.ts    # Position tracking & exits
│   ├── price-monitor.ts       # Real-time price polling
│   └── index.ts               # Portfolio exports
├── control/
│   ├── discord-alerts.ts      # Discord webhook alerts
│   ├── kill-switch.ts         # Emergency stop
│   ├── risk-manager.ts        # Risk limit enforcement
│   └── index.ts               # Control exports
└── utils/
    ├── config.ts              # Configuration loader
    ├── database.ts            # SQLite database
    ├── event-bus.ts           # Inter-module events
    ├── logger.ts              # Colorful logging
    └── wallet.ts              # Wallet utilities
```

## License

MIT — Use at your own risk. The authors are not responsible for any financial losses.

## Disclaimer

This software is for educational purposes. Cryptocurrency trading involves substantial risk of loss. Past performance does not guarantee future results. Always do your own research and never invest more than you can afford to lose.