# Meme Coin Trading Bot

Telegram bot dan internal dashboard khusus meme coin. Project ini fokus pada realtime token discovery, risk-first analysis, paper trading, dan guarded live execution melalui executor eksternal.

Bot tidak memberi jaminan profit. Semua sinyal bersifat probabilistik dan live trade dikunci oleh environment variable serta konfirmasi Telegram.

## Fitur

- Meme coin scanner berbasis DexScreener untuk pair metrics, liquidity, volume, buy/sell pressure, dan momentum.
- Scoring kandidat dengan verdict `PRIORITY_WATCH`, `RESEARCH`, atau `SKIP`.
- Analisis token lewat command Telegram dan pertanyaan bebas.
- Trade preview untuk `/buy` dan `/sell` dengan confirm/cancel.
- Paper trading sebagai default runtime.
- Live execution opsional lewat `TRADE_EXECUTOR_URL` dan `TRADE_EXECUTOR_TOKEN`.
- Optional Jupiter quote untuk Solana.
- AI risk review opsional via GitHub Models.
- Admin web Next.js untuk status provider dan guardrail runtime.

## Struktur Project

```text
apps/
  api/          Fastify API untuk scanner, analysis, quote, execute, health
  bot/          Telegram bot memecoin-only
  worker/       BullMQ worker untuk meme scan, analysis, alert scan
  admin-web/    Next.js internal dashboard
packages/
  core/         Types, constants, scoring engine, formatter, validation
  database/     Prisma schema untuk token, scan, trade, position, alert
  provider-adapters/ DexScreener, mock fallback, trade executor, AI provider
  prompts/      Prompt AI risk review
  queue/        Queue names
docs/           Product, architecture, operations, security notes
```

## File Penting

- `apps/bot/src/index.ts`: menu Telegram, scanner, analysis, buy/sell preview, confirm/cancel trade.
- `apps/api/src/server.ts`: endpoint `/meme/scan`, `/meme/search`, `/meme/analyze`, `/trade/quote`, `/trade/execute`.
- `packages/core/src/analysis-engine.ts`: scoring, filtering, mode inference, signal generation.
- `packages/provider-adapters/src/dexscreener.ts`: adapter DexScreener.
- `packages/provider-adapters/src/trade-executor.ts`: paper/live executor guardrail.
- `packages/database/prisma/schema.prisma`: schema persistence memecoin.
- `.env.example`: daftar env tanpa secret.

## Install

```bash
corepack enable
pnpm install --no-frozen-lockfile
pnpm db:generate
```

## Jalankan

```bash
cp .env.example .env
nano .env
docker compose up --build -d
```

Telegram command utama:

```text
/scan solana
/top
/analyze BONK
/buy TOKEN_ADDRESS 0.05
/sell TOKEN_ADDRESS 25
/settings
```

## Build dan Quality Gate

```bash
pnpm typecheck
pnpm lint
pnpm test
pnpm build
```

## Environment Variable

- `TELEGRAM_BOT_TOKEN`: token BotFather.
- `DATABASE_URL`: koneksi PostgreSQL container.
- `REDIS_URL`: koneksi Redis container.
- `TRADING_MODE`: `paper` atau `live`; default wajib `paper`.
- `DEFAULT_SLIPPAGE_BPS`: default slippage, misalnya `300` untuk 3%.
- `DEXSCREENER_BASE_URL`: default `https://api.dexscreener.com`.
- `TRADE_EXECUTOR_URL`: endpoint executor live eksternal.
- `TRADE_EXECUTOR_TOKEN`: bearer token executor live.
- `JUPITER_API_BASE_URL`: default `https://api.jup.ag`.
- `JUPITER_API_KEY`: optional untuk quote/rate limit Jupiter.
- `GITHUB_MODELS_TOKEN`: optional untuk AI risk review.

## Checklist Testing Manual

- `/start` menampilkan menu memecoin-only.
- `/scan solana` menampilkan kandidat atau empty state.
- `/analyze BONK` menghasilkan analysis card dengan warning dan disclaimer.
- Free text seperti `BONK bagus dibeli?` tetap menghasilkan analysis.
- `/buy TOKEN_ADDRESS 0.05` membuat trade preview mode paper.
- Tombol `Confirm` pada preview menghasilkan paper trade result.
- `/buy TOKEN_ADDRESS 0.05 live` ditolak jika executor belum dikonfigurasi.
- `/alert` menampilkan format alert.
- `/settings` menampilkan trading mode runtime dan slippage.
- API `/health`, `/meme/scan`, dan `/providers/status` merespons.

## Saran Pengembangan Berikutnya

- Tambahkan persistence penuh untuk scan run, trade order, dan positions.
- Hubungkan alert worker ke scheduler dan Telegram notification.
- Bangun executor live terpisah dengan wallet custody yang diaudit.
- Tambahkan rug-check provider, holder distribution, token lock, dan honeypot scanner.
- Tambahkan dashboard positions dan PnL dari database.