# AltSignal

Hyperliquid liquidation + smart-money + whale alerts on Telegram. **$9.99/mo USDC or card.**

## What it does

Subscribes to Hyperliquid's WebSocket for BTC, ETH, SOL, HYPE, WIF, DOGE, ARB and dispatches Telegram alerts when:
- **Liquidations** above $100K hit (with cascade-watch tag)
- **Whale spikes** $250K+ single trades
- **Smart-money** curated wallets move on subscribed coins

## Stack

- **Frontend**: Next.js 14 (app router, Tailwind, framer-motion)
- **Backend**: Nest.js (modular, Prisma, Telegraf, Polar SDK-less direct API)
- **DB**: Postgres 16 + Redis 7
- **Email**: Resend
- **Billing**: Polar.sh
- **WS**: native `ws` library + reconnect/ping
- **Auth**: magic-link → JWT cookie

## Repo layout

```
altsignal/
├── apps/
│   ├── api/           — Nest.js backend
│   │   ├── src/modules/
│   │   │   ├── auth/        — magic-link, JWT, Telegram link tokens
│   │   │   ├── users/       — user model bridge
│   │   │   ├── waitlist/    — landing form intake
│   │   │   ├── alerts/      — CRUD + dispatcher (per-user filtering, tier-gated delay)
│   │   │   ├── bot/         — Telegraf with /start /link /alerts /pause
│   │   │   ├── billing/     — Polar checkout URL + cancel + webhook with HMAC verify
│   │   │   ├── chains/hyperliquid/ — multi-coin WS listener with dedup
│   │   │   ├── email/       — Resend integration
│   │   │   ├── health/      — /v1/health
│   │   │   └── prisma/      — db service
│   │   ├── prisma/
│   │   │   ├── schema.prisma  — 9 models
│   │   │   └── seed.ts        — smart-money wallets
│   │   └── Dockerfile
│   └── web/           — Next.js frontend
│       ├── src/app/
│       │   ├── page.tsx            — landing
│       │   ├── login/page.tsx       — magic-link request
│       │   ├── verify/page.tsx      — magic-link consume + redirect
│       │   ├── dashboard/
│       │   │   ├── layout.tsx       — auth gate + nav
│       │   │   ├── page.tsx         — overview
│       │   │   ├── alerts/page.tsx  — CRUD UI
│       │   │   ├── telegram/page.tsx — link flow
│       │   │   └── billing/page.tsx  — plan picker, checkout, cancel
│       │   └── api/
│       │       ├── auth/{login,verify,logout}/route.ts
│       │       ├── proxy/[...path]/route.ts  — bearer-auth pass-through to backend
│       │       └── waitlist/route.ts
│       ├── src/middleware.ts        — /dashboard auth check
│       └── Dockerfile
└── infra/
    └── docker-compose.yml — postgres + redis + api + web + Traefik labels
```

## Local dev

```bash
pnpm install
docker compose -f infra/docker-compose.yml up -d postgres redis
cd apps/api
cp .env.example .env  # fill in
pnpm prisma migrate dev
pnpm prisma db seed
pnpm dev
# new terminal
cd ../web
pnpm dev
# open http://localhost:3001
```

## Production deploy

See `CHECKLIST.md`. Summary: set env vars, push to git, point Dokploy at `infra/docker-compose.yml`.

## End-to-end flow

```
visitor → /login (enter email)
       ↓ POST /api/auth/login
       backend creates AuthMagicToken, Resend sends email
       ↓ click magic link
visitor → /verify?token=...
       ↓ POST /api/auth/verify
       backend consumes token, returns sessionToken, cookie set
       ↓
user  → /dashboard (cookie carried)
       ↓
       /dashboard/telegram → POST /api/proxy/auth/telegram/link-code
       ↓ returns code + deep-link to @altsignal_bot
user  → Telegram, /start <code>  (or /link <code>)
       ↓ bot consumes TelegramLinkToken, links user.telegramAccount
       ↓
user  → /dashboard/alerts → "Add alert" → kind=liquidation, minUsd=100000
       ↓ POST /api/proxy/alerts → DB row + dispatch enables
       ↓
       Hyperliquid WS → trade arrives → matched against subs → Telegram message sent
       ↓
user  → /dashboard/billing → "Upgrade to Pro" → backend creates Polar checkout
       ↓ user pays USDC or card on polar.sh
       ↓ Polar webhook → backend bumps tier to "pro"
       ↓ next alert: no delay (was 6h on free)
       ↓
user  → cancel anytime → Polar DELETE subscription → tier back to free
```

## Pricing math

| Plan | Customers needed for $100/mo |
|---|---|
| Free | — |
| Pro $9.99 | **11 paying** |
| Plus $19.99 | 6 paying |

## What's intentionally v2

- Token unlock alerts (kind is there in DB, no producer yet — needs TokenUnlocks API integration)
- Multi-chain (Solana, Ethereum, Base) — `chains/` folder is structured for it
- Webhook delivery (Plus tier perk — wire after first Plus customer asks)
- Discord channel integration (same)
- Dashboard analytics (alert hit-rate per type)