First Whale

First Whale tracks pseudonymous Polymarket wallets whose first observed public trade is at least $10,000 notional.

Stack

• Node.js + TypeScript monorepo (Turbo + workspaces)
• API: Express + BullMQ + Redis + Prisma
• DB: PostgreSQL
• Frontend: Next.js + Tailwind CSS
• Provider abstraction: mock and live Polymarket providers (config flag)

Product behavior

• First-time bet is wallet-level and based only on public data.
• No identity/deanonymization features.
• Read-only analytics only (no trading, no private keys).
• Notional formula: size * price.
• Alert when first observed trade notional >= threshold.

Monorepo layout

• apps/api: backend API + ingestion worker
• apps/web: dashboard UI
• packages/db: Prisma schema/client
• packages/polymarket: provider abstraction (mock/live)
• packages/shared: shared types/env/decimal helpers

Local infrastructure

From the repo root (requires Docker):

• pnpm dev:infra (same as docker compose up -d — starts Postgres and Redis on 5432 and 6379)

If Docker is not running, the API still starts, but the database and ingestion queue stay unavailable until Postgres/Redis are up. After infra is up, run migrations: pnpm db:migrate, then pnpm dev.

Setup

1. Copy env:
   • cp .env.example .env
2. Start Postgres + Redis (Docker Compose, or your own). Match DATABASE_URL and REDIS_URL in .env.
3. Install dependencies using your package manager (pnpm recommended by package.json).
4. Generate Prisma client:
   • pnpm db:generate
5. Run migrations:
   • pnpm db:migrate
6. Run apps:
   • API: pnpm --filter @first-whale/api dev
   • Web: pnpm --filter @first-whale/web dev

API endpoints

• GET /api/alerts with pagination and filters: minNotional, market, side, fromDate, toDate
• GET /api/wallets/:address
• GET /api/health
• POST /api/admin/ingest
• POST /api/admin/backfill
• GET /api/admin/runs

Detection and edge cases

• Realtime mode uses current ingestion windows.
• Backfill mode paginates deeper history and recalculates first-seen trades.
• If an older trade is found later, previous active alerts are invalidated and recomputed.

Configuration

• USE_MOCK_POLYMARKET=true for MVP/demo mode.
• Set USE_MOCK_POLYMARKET=false to use live Polymarket public APIs.

Test

• apps/api/src/detector.test.ts validates threshold behavior for first-time whale detection.

AWS readiness notes

• Keep API and worker in separate process groups/tasks.
• Swap local Postgres/Redis with RDS + ElastiCache.
• Add CloudWatch log export from structured pino logs.
• Place API behind ALB/API Gateway and restrict admin routes.

Publish to GitHub

1. Install the GitHub CLI (gh) if needed, or use the web UI to create an empty repository (no README).

2. Log in: gh auth login

3. From the repo root, create the remote and push the existing main branch:

   gh repo create first-whale --public --source=. --remote=origin --push

   If the name first-whale is taken, pick another (for example firstwhale or first-whale-app).

   Without gh: add the empty repo as origin and git push -u origin main.