<p align="center">
<img src="assets/logo.png" alt="Ghost Logo" width="280">
</p>
<p align="center">
<strong>AI degen trading agent — track smart money, trade with privacy</strong>
<br>
<sub>Hunt alpha. Hide your trades. That's Ghost.</sub>
</p>
<p align="center">
<img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen" alt="Node.js">
<img src="https://img.shields.io/badge/typescript-5.3-blue" alt="TypeScript">
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-yellow" alt="MIT License"></a>
<img src="https://img.shields.io/badge/skills-120%2B-purple" alt="120+ Skills">
<img src="https://img.shields.io/badge/Solana-PumpFun-blueviolet" alt="PumpFun">
<img src="https://img.shields.io/badge/hackathon-%243M-orange" alt="$3M Hackathon">
</p>
<p align="center">
<a href="#quick-start">Quick Start</a> •
<a href="#webchat">WebChat</a> •
<a href="#wallet-clustering">Clustering</a> •
<a href="#privacy-trading">Privacy</a> •
<a href="#autonomous-wallet">Auto-Trade</a> •
<a href="#pumpfun-trading">PumpFun</a> •
<a href="#everything-we-built">Features</a> •
<a href="#channels">Channels</a> •
<a href="#documentation">Docs</a>
</p>
---
**Ghost** is your AI fellow trencher. It tracks smart money wallets, detects when wallet clusters converge on new tokens, and trades with built-in privacy — splitting across multiple wallets with randomized timing so YOUR moves stay invisible. Ghost even has its own wallet and can trade autonomously, sharing profits with you.
Powered by Claude with 120+ skills, wallet clustering engine, autonomous trading with safety rails, PumpFun SDK integration (zero fees), Jito bundle execution, and full Solana DeFi stack (Jupiter, Raydium, Orca, Meteora, PumpSwap). Chat via **21 messaging platforms** including built-in WebChat, Telegram, and Discord.
> **Built for [PumpFun $3M Hackathon](https://pump.fun)** — An autonomous AI trading agent that hunts alpha and hides your trades.
---
## Quick Start
```bash
git clone https://github.com/alsk1992/Ghostbot.git && cd Ghostbot
npm install --ignore-scripts && cp .env.example .env
# Add ANTHROPIC_API_KEY and SOLANA_PRIVATE_KEY to .env
npm run build && npm start
```
WebChat opens at `http://localhost:18789/webchat`. Say "gm" to Ghost.
<details>
<summary><strong>Environment variables</strong></summary>
```bash
# Required
ANTHROPIC_API_KEY=sk-ant-... # Claude API key
SOLANA_PRIVATE_KEY=... # Your Solana wallet (base58)
# Optional — enhances alpha detection
HELIUS_RPC_URL=... # Helius RPC (recommended for wallet clustering)
BIRDEYE_API_KEY=... # Birdeye API (fallback trade history)
# Channels (pick any)
TELEGRAM_BOT_TOKEN=...
DISCORD_BOT_TOKEN=...
```
</details>
---
## WebChat
Built-in browser interface at `http://localhost:18789/webchat` — no setup, no third-party dependencies.
**Interface:**
- Claude-style sidebar with 4 tabs: Chats, Projects, Artifacts, Code
- Create and organize conversations into project folders
- Artifacts and code blocks auto-extracted from chat history
- One-click copy for code snippets, search across all conversations
**Thinking Indicator:**
- Live spinner with elapsed timer while the AI generates
- Replaces generic typing dots with actual status feedback
**Unlimited History:**
- Every message stored in a dedicated database table (append-only, one row per message)
- No message cap — scroll back through entire conversation history
- Paginated loading so even 1000+ message chats load instantly
**Context Compacting:**
- Older messages automatically summarized so the AI never fully forgets what you discussed
- LLM receives a compressed recap of earlier conversation + the last 20 messages
**Session Management:**
- Create, rename, delete conversations via REST API
- Profile menu with language selector (9 languages), help, about
- Persistent across restarts (SQLite-backed)
---
## CLI
```bash
ghost onboard # Interactive setup wizard
ghost start # Start the gateway
ghost repl # Interactive REPL
ghost doctor # System diagnostics
ghost secure # Harden security
ghost mcp # Start MCP server (for Claude Desktop/Code)
ghost mcp install # Auto-configure Claude Desktop/Code
```
---
## Wallet Clustering
Ghost's core alpha engine — groups wallets that co-buy across multiple tokens to find smart money convergence.
**How it works:**
1. **Transaction indexing** — monitor target wallets via Helius enhanced API, standard Solana RPC, or Birdeye (3-tier fallback)
2. **Co-buy detection** — when wallet A and wallet B buy the same token within 60s, their co-buy score increases
3. **Cluster formation** — wallets with 3+ co-buys grouped via BFS connected components
4. **Cluster scoring** — ranked by co-buy count × wallet count × recency × win rate
5. **Convergence alerts** — when 3+ wallets from a high-scoring cluster buy the same NEW token → alert fires
```
/alpha track <wallet> Add wallet to tracking
/alpha wallets List tracked wallets with stats
/alpha clusters Show wallet clusters ranked by score
/alpha cluster <id> Cluster detail (wallets, win rate, PnL)
/alpha score <token> How many smart wallets are in this token
/alpha alerts Recent convergence alerts
/alpha live Real-time feed of cluster activity
/alpha start Start the clustering engine
/alpha stop Stop scanning
/alpha stats Service stats
```
**Data sources:** Helius RPC (primary) → Standard Solana RPC with DEX program ID detection (fallback) → Birdeye API (tertiary)
**DEX detection:** PumpFun, PumpSwap, Jupiter, Jupiter v4, Raydium, Raydium CPMM, Orca, Meteora — identified via on-chain program IDs
**Persistence:** SQLite tables for wallets, trades, co-buys, clusters, and alerts — survives restarts
**Wallet stats computed from trade history:** Win rate, average return %, total PnL SOL — paired buy/sell matching per mint
---
## Privacy Trading
Ghost makes your trades invisible to other trackers:
1. **Multi-wallet splitting** — split buy across 3-5 wallets via Jito bundles (atomic execution)
2. **Timing randomization** — random delays between wallet buys
3. **Amount obfuscation** — slightly randomize buy amounts (±5-15%)
4. **Fresh wallet rotation** — generate new wallets per trade, consolidate via Jito bundle
5. **MEV protection** — Jito private mempool, no public mempool exposure
```
/pump bundle-buy <mint> <sol> [--wallets N] Buy across N wallets atomically
/pump bundle-sell <mint> [--wallets N] Sell from N wallets atomically
/pump bundle-create <name> <symbol> <sol> Create + buy across wallets
```
All bundle operations use Jito for atomic execution — either all wallets trade or none do.
---
## Autonomous Wallet
Ghost has its own Solana wallet and can trade autonomously based on cluster convergence signals.
**How it works:**
1. **Fund Ghost** — send SOL to Ghost's auto-generated wallet
2. **Enable auto-trading** — Ghost watches for convergence alerts
3. **Auto-buy** — when 3+ smart wallets converge on a new token + cluster score meets threshold → Ghost buys
4. **Auto-exit** — positions monitored every 30s for take-profit (+100%) and stop-loss (-50%)
5. **Circuit breaker** — Ghost stops after 3 consecutive losses
```
/ghost fund Ghost's wallet address + balance
/ghost balance SOL balance
/ghost auto on Enable autonomous trading
/ghost auto off Disable
/ghost auto config View safety config
/ghost auto config <key> <value> Update setting
/ghost positions Open positions
/ghost history [--limit N] Trade history
/ghost close <id> Close specific position
/ghost close-all Close all positions
/ghost stats Performance dashboard
```
**Safety rails:**
| Setting | Default | Description |
|---------|---------|-------------|
| `maxPositionSol` | 0.1 | Max SOL per trade |
| `maxExposureSol` | 1.0 | Max total SOL in open positions |
| `circuitBreakerLosses` | 3 | Stop after N consecutive losses |
| `slippagePct` | 15 | Slippage tolerance % |
| `minClusterScore` | 5 | Min cluster score to trade on |
| `minConvergenceWallets` | 3 | Min wallets in convergence alert |
| `takeProfitPct` | 100 | Auto TP at +100% (2x) |
| `stopLossPct` | -50 | Auto SL at -50% |
**Persistence:** Trade history saved to `~/.ghost/ghost-trades.json` — positions survive process restarts. Consecutive loss counter restored from history.
---
## PumpFun Trading
Full PumpFun integration with three execution methods:
| Method | Fee | Speed | Use Case |
|--------|-----|-------|----------|
| **Official SDK** (`@pump-fun/pump-sdk`) | 0% | ~400ms | Default — zero external fees |
| **Jito Bundles** | Tip only | ~200ms | Multi-wallet atomic execution |
| **PumpPortal** (legacy) | 0.5% | ~300ms | Fallback with `--legacy` flag |
```
/pump buy <mint> <sol> Buy with official SDK (zero fee)
/pump buy <mint> <sol> --legacy Buy via PumpPortal (0.5% fee)
/pump sell <mint> <amount|%> Sell tokens
/pump create <name> <symbol> Create token via SDK
/pump bundle-buy <mint> <sol> Atomic multi-wallet buy
/pump bundle-sell <mint> Atomic multi-wallet sell
/pump bundle-create <name> <sym> <sol> Create + buy atomically
/pump watch <mint> 15s real-time price snapshot
/pump snipe <symbol> <sol> Auto-buy on new token launch
/pump stream [new|trades|migrations] Real-time platform feed
/pump top Top tokens by market cap
/pump new Latest launches
/pump graduating Tokens nearing graduation
/pump search <query> Search tokens
/pump info <mint> Token details + bonding curve
/pump holders <mint> Top holders
/pump chart <mint> Price chart (ASCII)
/pump portfolio Your PumpFun token holdings
/pump pnl Profit & loss breakdown
```
**38 commands total** — see `/pump help` for the full list.
**Bonding curve math:** Real constant-product AMM calculations for price estimation, slippage, and graduation tracking.
---
## Everything We Built
### At a Glance
| Category | What's Included |
|----------|-----------------|
| **Ghost Alpha** | Wallet clustering engine — co-buy detection, BFS cluster formation, convergence alerts, 3-tier trade indexing (Helius/RPC/Birdeye), DEX detection (9 programs), per-wallet PnL stats |
| **Ghost Auto** | Autonomous trading wallet — auto-generated keypair, signal-based trading, TP/SL monitoring, circuit breaker, trade persistence, safety rails |
| **Privacy Trading** | Multi-wallet Jito bundles — atomic execution across N wallets, fresh wallet generation with SOL funding, MEV protection |
| **PumpFun** | Official SDK (0% fee), PumpPortal (legacy), Jito bundles, token creation, sniping, real-time WebSocket streams, bonding curve math, 38 commands |
| **Messaging** | 21 platforms (Telegram, Discord, WhatsApp, Slack, Teams, Signal, Matrix, iMessage, LINE, Nostr, and more) + built-in WebChat with sidebar, unlimited history, context compacting |
| **Prediction Markets** | 10 platforms (Polymarket, Kalshi, Betfair, Smarkets, Drift, Manifold, Metaculus, PredictIt, Opinion.xyz, Predict.fun) |
| **Perpetual Futures** | 7 exchanges (Binance, Bybit, Hyperliquid, MEXC, Drift, Percolator, Lighter) with up to 200x leverage |
| **Solana DeFi** | Jupiter, Raydium, Orca, Meteora, Kamino, MarginFi, Solend, Pump.fun, PumpSwap, Bags.fm — with Jito MEV protection |
| **EVM DeFi** | Uniswap V3, 1inch, PancakeSwap, Virtuals Protocol, Clanker, Veil, ENS (ETH, ARB, OP, Base, Polygon) |
| **Trading Strategies** | 118+ strategies including momentum, mean reversion, DCA bots, smart routing, whale tracking, copy trading |
| **Risk Management** | Circuit breaker, VaR/CVaR, volatility regime detection, stress testing, Kelly sizing, daily loss limits, kill switch |
| **Token Security** | GoPlus-powered audits — honeypot detection, rug-pull analysis, holder concentration, risk scoring |
| **Whale Tracking** | Multi-chain monitoring (Solana, ETH, Polygon, ARB, Base, OP) with configurable thresholds |
| **Copy Trading** | Mirror successful wallets with sizing controls and SL/TP |
| **Arbitrage** | Cross-platform detection, combinatorial analysis, semantic matching, real-time scanning |
| **AI** | 8 LLM providers, 4 specialized agents, semantic memory, 18 tools |
| **Skills System** | 120+ bundled skills — lazy-loaded on first use so missing dependencies don't crash the app |
| **Data Persistence** | SQLite (local), LanceDB (semantic memory), PostgreSQL (analytics) — unlimited WebChat history, trade database |
| **i18n** | 10 languages (EN, ZH, ES, JA, KO, DE, FR, PT, RU, AR) |
| **Bridging** | Wormhole cross-chain transfers |
| **Payments** | x402 protocol for machine-to-machine USDC payments (Base + Solana) |
| **Automation** | Trading bots, cron jobs, webhooks, skills system |
---
## Channels (21)
Telegram, Discord, Slack, WhatsApp, Teams, Matrix, Signal, iMessage, LINE, Nostr, Twitch, **WebChat**, and more.
All channels support real-time sync, rich media, and offline queuing. WebChat is the built-in browser interface with a full sidebar UI, unlimited message history, and conversation management — see [WebChat](#webchat) above.
---
## Prediction Markets (10)
| Platform | Trading | Type |
|----------|:-------:|------|
| Polymarket | ✓ | Crypto (USDC) |
| Kalshi | ✓ | US Regulated |
| Betfair | ✓ | Sports Exchange |
| Smarkets | ✓ | Sports |
| Drift | ✓ | Solana DEX |
| Manifold | data | Play Money |
| Metaculus | data | Forecasting |
| PredictIt | data | US Politics |
| Opinion.xyz | ✓ | BNB Chain |
| Predict.fun | ✓ | BNB Chain |
---
## Crypto & DeFi
**Solana:** Jupiter, Raydium, Orca, Meteora, Kamino, MarginFi, Solend, Pump.fun, PumpSwap, Bags.fm — with Jito MEV protection
**EVM (5 chains):** Uniswap V3, 1inch, PancakeSwap, Virtuals Protocol on Ethereum, Arbitrum, Optimism, Base, Polygon — with Flashbots MEV protection
**Bridging:** Wormhole cross-chain transfers (ETH ↔ Solana, Polygon ↔ Base)
---
## Perpetual Futures (7 Exchanges)
| Exchange | Max Leverage | KYC | Type |
|----------|--------------|-----|------|
| Binance | 125x | Yes | CEX |
| Bybit | 100x | Yes | CEX |
| Hyperliquid | 50x | No | DEX |
| MEXC | 200x | No | CEX |
| Drift | 20x | No | DEX (Solana) |
| Percolator | Varies | No | On-chain (Solana) |
| Lighter | 50x | No | DEX (Arbitrum) |
Long/short, cross/isolated margin, TP/SL, liquidation alerts, funding tracking.
---
## AI System
**8 LLM providers:** Claude (primary), GPT-4, Gemini, Groq, Together, Fireworks, AWS Bedrock, Ollama
**4 agents:** Main, Trading, Research, Alerts
**18 tools:** Browser, docker, exec, files, git, email, sms, webhooks, sql, vision
**Memory:** Semantic search (LanceDB), hybrid BM25, user profiles, persistent facts
**Personality:** Ghost is a degen — confident, direct, uses crypto slang naturally. Celebrates wins, jokes about losses. Never boring.
---
## Advanced Trading
**Whale Tracking:** Multi-chain monitoring (Solana, ETH, Polygon, ARB, Base, OP) with configurable thresholds
**Copy Trading:** Mirror successful wallets with sizing controls and SL/TP
**Swarm Trading:** Coordinated multi-wallet PumpFun trading (20 wallets, Jito bundles)
**Smart Routing:** Best price across Jupiter, Raydium, Orca, Meteora
**Token Security:** GoPlus-powered audits — honeypot detection, rug-pull analysis, holder concentration
**Arbitrage:** Cross-platform detection with semantic matching, liquidity scoring, Kelly sizing
---
## Architecture
```
┌──────────────────────────────────────────────────────────────────────────────┐
│ GATEWAY & USER INTERFACE │
│ HTTP • WebSocket • Auth • Rate Limiting │
│ 21 Channels: WebChat, Telegram, Discord, Slack, Teams, Matrix, Signal... │
└──────────────────────────────────────────┬─────────────────────────────────────┘
│
┌──────────────────────────────────────────┴─────────────────────────────────────┐
│ AI AGENTS LAYER (4) │
│ Main (Claude) • Trading (Exec) • Research (Data) • Alerts (Monitor) │
│ 120+ Skills • 18 Tools • LanceDB Memory • Degen Personality │
└──────────────────────────────────────────┬─────────────────────────────────────┘
│
┌──────────────────────────────────────────┴─────────────────────────────────────┐
│ GHOST ALPHA LAYER │
│ Wallet Clustering • Co-Buy Detection • Convergence Alerts │
│ Autonomous Wallet • TP/SL Monitor • Circuit Breaker • Trade Persistence │
│ Privacy Trading • Multi-Wallet Splitting • Jito Bundles • MEV Protection │
└──────────────────────────────────────────┬─────────────────────────────────────┘
│
┌──────────────────────┬───────────────┼───────────────┬────────────────────┐
▼ ▼ ▼ ▼ ▼
┌──────────────────┐ ┌──────────────┐ ┌──────────────┐ ┌─────────────┐ ┌────────────┐
│ PUMPFUN │ │ SOLANA DeFi │ │ EVM DeFi │ │ PREDICTION │ │ PERPETUAL │
│ │ │ │ │ │ │ MARKETS │ │ FUTURES │
├──────────────────┤ ├──────────────┤ ├──────────────┤ ├─────────────┤ ├────────────┤
│ Official SDK │ │ Jupiter │ │ Uniswap V3 │ │ Polymarket │ │ Binance │
│ (0% fee) │ │ Raydium │ │ 1inch │ │ Kalshi │ │ Bybit │
│ Jito Bundles │ │ Orca │ │ PancakeSwap │ │ Betfair │ │ Hyper- │
│ (tip only) │ │ Meteora │ │ Virtuals │ │ Smarkets │ │ liquid │
│ PumpPortal │ │ PumpSwap │ │ Clanker │ │ Drift │ │ MEXC │
│ (0.5% legacy) │ │ Kamino │ │ Veil │ │ Manifold │ │ Drift │
│ │ │ MarginFi │ │ (ETH, ARB, │ │ Metaculus │ │ Percolator │
│ Token Creation │ │ Solend │ │ OP, Base, │ │ PredictIt │ │ Lighter │
│ Sniping │ │ Bags.fm │ │ Polygon) │ │ Opinion.xyz │ │ │
│ Real-time │ │ │ │ │ │ Predict.fun │ │ Up to │
│ Streams │ │ Jito MEV │ │ Flashbots │ │ │ │ 200x │
│ Bonding Curve │ │ Protection │ │ MEV Protect. │ │ CLOB Orders │ │ leverage │
│ Math │ │ │ │ │ │ │ │ │
└──────────────────┘ └──────────────┘ └──────────────┘ └─────────────┘ └────────────┘
│ │ │ │
┌────────────────┴────────────────┴────────────────┴────────────────┴────────┐
│ COMMON EXECUTION & DATA LAYER │
│ Order Builder • Balance Checker • Slippage Estimator • Fee Calculator │
│ Real-time P&L • Wallet Clustering DB • Trade History • Alert System │
│ Whale Tracking • Copy Trading • Token Security • Risk Engine │
└────────────────────────────────┬───────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────┐
│ DATA PERSISTENCE LAYER │
├───────────────────────────────────────────────────┤
│ SQLite: Wallets, clusters, co-buys, alerts, │
│ trades, WebChat, configs, earnings │
│ JSON: Ghost wallet keypair, autonomous trades │
│ LanceDB: Semantic memory, embeddings, profiles │
└───────────────────────────────────────────────────┘
```
---
## Configuration
```bash
# Required
ANTHROPIC_API_KEY=sk-ant-...
SOLANA_PRIVATE_KEY=...
# Recommended (for wallet clustering)
HELIUS_RPC_URL=https://mainnet.helius-rpc.com/?api-key=...
BIRDEYE_API_KEY=...
# Channels (pick any)
TELEGRAM_BOT_TOKEN=...
DISCORD_BOT_TOKEN=...
# Trading
POLYMARKET_API_KEY=...
```
Data stored in `~/.ghost/` (SQLite database, wallet, trades — auto-created on first run).
---
## Skills & Extensions
**120+ bundled skills** across trading, alpha, automation, and infrastructure — lazy-loaded on first use so missing dependencies don't crash the app. Run `/skills` to see status.
| Category | Skills |
|----------|--------|
| Ghost | Wallet clustering, autonomous wallet, privacy trading, convergence alerts |
| PumpFun | Buy/sell/create, bundles, sniping, streams, charts, portfolio |
| Trading | Polymarket, Kalshi, Betfair, Hyperliquid, Binance, Bybit, MEXC, Drift, Jupiter, Raydium, Orca, DCA (16 platforms) |
| Analysis | Arbitrage detection, whale tracking, copy trading, token security audits |
| Automation | Cron jobs, triggers, bots, webhooks |
| AI | Memory, embeddings, multi-agent routing |
---
## Security
- Sandboxed execution (shell commands need approval)
- Encrypted credentials (AES-256-GCM)
- Audit logging for all trades
- Ghost wallet backed up on corruption (fund protection)
- Circuit breaker stops autonomous trading after consecutive losses
---
## Documentation
| Document | Description |
|----------|-------------|
| [User Guide](./docs/USER_GUIDE.md) | Commands, chat usage, workflows |
| [API Reference](./docs/API_REFERENCE.md) | HTTP/WebSocket endpoints, authentication |
| [Architecture](./docs/ARCHITECTURE.md) | System design, components, data flow |
| [Deployment](./docs/DEPLOYMENT.md) | Environment variables, Docker, production |
| [Trading](./docs/TRADING.md) | Execution, bots, risk management |
| [Security](./docs/SECURITY_AUDIT.md) | Security hardening, audit checklist |
| [OpenAPI Spec](./docs/openapi.yaml) | Full OpenAPI 3.0 specification |
---
## Development
```bash
npm run build # Build
npm run dev # Hot reload
npm test # Run tests
npm run typecheck # Type check
npm start # Start Ghost
```
### Docker
```bash
docker compose up --build
```
---
## Summary
| Category | Count |
|----------|------:|
| Messaging Channels | **21** |
| Bundled Skills | **120+** |
| PumpFun Commands | **38** |
| Prediction Markets | **10** |
| Futures Exchanges | **7** |
| Solana DeFi Protocols | **10** |
| EVM Chains | **5** |
| LLM Providers | **8** |
| AI Tools | **18** |
| DEXs Detected | **9** |
| Languages | **10** |
---
## License
MIT — see [LICENSE](./LICENSE)
---
<p align="center">
<strong>Ghost</strong> — Hunt alpha. Hide your trades.
<br>
<sub>Built with Claude by Anthropic</sub>
</p>