SignalWhale

A self-hosted prediction-market whale tracker. SignalWhale watches Polymarket for large trades in real time, profiles every whale's true track record, and alerts your members — in-app, browser push, email, Telegram or webhook — the moment smart money moves.

The live feed — whale trades grouped by market, with money-flow overview, filters and live updates.

Overview

SignalWhale is a Laravel 13 application. Everything runs on your own server: trades are pulled from Polymarket's public market-data APIs (no API key, no account, no wallet — see the full endpoint reference), stored in your database, and served from your domain. Trader photos, market thumbnails, fonts and icons are all cached or bundled locally — the rendered pages make zero external requests.

Product tour

Dark theme — one click, fully themed.

Smart-money leaderboard with podium.

Whale profile — real win rate, P&L, streak, open bets.

Market page — live odds, holders, whale signal.

Alert rules with per-channel delivery log.

In-app inbox + optional desktop push.

Watchlist — followed whales with records.

Included marketing landing page.

Server requirements

Any hosting that runs Laravel works — shared hosting (cPanel/Plesk), a VPS, or Docker. The web installer verifies every requirement automatically before it lets you proceed.

Installation

A — Web installer (recommended)

1. Upload the archive to your server and extract it. Point your domain's document root at the public/ folder.
2. Copy .env.example to .env (most hosting file managers can rename a copy).
3. Open https://yourdomain.com — you are redirected to the installer automatically.
4. The installer checks your server, asks for a database (SQLite needs nothing at all) and your admin account.
5. Click Install SignalWhale. It generates the app key, runs migrations, creates your admin account and pulls the first batch of live whale trades. Typically under a minute.

The installer — server check, database, admin account.

Done — with your cron line ready to copy.

Nginx server block

Apache works out of the box via the bundled .htaccess. On Nginx, use this server block (adjust paths and PHP version):

server {
    listen 80;
    server_name yourdomain.com;
    root /var/www/signalwhale/public;
    index index.php;

    location / { try_files $uri $uri/ /index.php?$query_string; }
    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }
    location ~ /\.(?!well-known) { deny all; }
}

Manual MySQL import (optional)

Prefer creating the database yourself via phpMyAdmin? Import database/sql/signalwhale-mysql.sql (structure only, no data), set your DB_* values in .env, and the installer will detect the schema and skip migration. Most buyers won't need this — the installer and php artisan migrate create everything automatically on both SQLite and MySQL.

B — Manual install (terminal)

cp .env.example .env
php artisan key:generate
touch database/database.sqlite     # or set DB_* in .env for MySQL
php artisan migrate --force
php artisan whales:sync            # first data pull
php artisan tinker --execute="App\Models\User::create(['name'=>'Admin','email'=>'you@example.com','password'=>'choose-a-password','plan'=>'pro','is_admin'=>true,'terms_accepted_at'=>now()]);"

Cron job — keep the feed live

One cron entry powers everything: trade syncing, whale P&L refreshes, profile/image caching, alert delivery and the weekly digest (the individual schedules are listed in the pipeline section).

* * * * * php /path/to/signalwhale/artisan schedule:run >> /dev/null 2>&1

In cPanel: Advanced → Cron Jobs → add the line above with your real path. In Plesk: Tools & Settings → Scheduled Tasks.

How the data pipeline works

Understanding the flow makes everything else obvious:

Polymarket public APIs
      │
      ▼  whales:sync (every 5 min)
whale_trades table  ──►  AlertEvaluator ──► bell / push / email / Telegram / webhook
      │                                     (alert_events dedupes, alert_deliveries logs)
      ▼  whales:profiles (hourly) · whales:pnl (every 30 min) · whales:market-icons (hourly)
traders + trader_positions tables · public/avatars · public/market-icons
      │
      ▼
Feed · Leaderboard · Whale profiles · Market pages · Digest email

Every command is safe to run by hand (php artisan whales:sync) and safe to run repeatedly — inserts are idempotent.

External APIs & endpoints

SignalWhale consumes public, unauthenticated, read-only market-data endpoints. There are no API keys to obtain, nothing to sign up for, and no wallet or exchange account involved. Below is every external endpoint the application calls, exactly as it appears in the code.

Polymarket — Data API (data-api.polymarket.com)

Polymarket — Gamma API (gamma-api.polymarket.com)

Polymarket — CLOB API (clob.polymarket.com)

Kalshi (api.elections.kalshi.com — disabled by default)

Outbound integrations (only when you configure them)

Demo data & previewing

There is no fake data anywhere in SignalWhale. Every trade, odds figure, win rate and avatar you see — including in these screenshots — is live production data pulled from the APIs above. That has two practical consequences:

• A fresh install is immediately real. The installer's first sync typically lands 200–300 live whale trades; within a day of cron running you'll have thousands, plus resolved trader profiles and photos.
• No seed/fixture cleanup. There are no placeholder markets or lorem-ipsum whales to delete before going live.

The demo member account

For local evaluation you can seed a ready-made Pro member so you can try watchlists, alerts, exports and the bell without registering:

php artisan db:seed     # creates user@demo.com + admin@demo.com (password: password)

The login page shows “Demo user / Demo admin” quick-fill buttons only when these accounts exist. Production installs through the web installer never create it — your live site has exactly the admin account you chose, nothing else.

Resetting your data

php artisan migrate:fresh --force   # wipe everything (users included!)
php artisan whales:sync             # re-pull live data

Local caching & privacy

• Zero third-party requests in the browser. Fonts (Clash Display, General Sans, JetBrains Mono), the Lucide icon set and three.js are bundled in public/fonts and public/vendor. Trader photos and market thumbnails are served from public/avatars and public/market-icons. Your visitors' browsers only ever talk to your domain.
• Read-only public data. The app displays publicly available market data. It holds no funds, executes no trades, stores no private keys and never asks members for wallet credentials.
• No phone-home. SignalWhale contains no license pings, analytics beacons or update checks.

Email (SMTP)

Email powers password resets, email alerts, optional email verification and the weekly digest. Set your SMTP details in .env:

MAIL_MAILER=smtp
MAIL_HOST=smtp.yourprovider.com
MAIL_PORT=587
MAIL_USERNAME=postmaster@yourdomain.com
MAIL_PASSWORD=your-smtp-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=alerts@yourdomain.com
MAIL_FROM_NAME="SignalWhale"

Any SMTP provider works (your host's mail server, Mailgun, Postmark, SES, Resend…). Test it with Forgot password on the login page. Both transactional emails are fully designed and on-brand:

Whale alert email.

Monday weekly digest.

Admin panel

Sign in with your admin account and open the avatar menu → Admin panel (/admin).

Operations dashboard — members, pipeline health with staleness warning, signup trend.

Settings — whale threshold, sync size, account flags, announcement banner.

Stripe billing (optional)

SignalWhale ships with a working Free → Pro upgrade flow via Stripe Checkout (Laravel Cashier). Without Stripe keys the pricing page still renders and everything else works — members simply can't self-upgrade (you can set plans from the admin panel).

1. In the Stripe dashboard create a recurring Price (e.g. $9/mo) and copy its price_… ID.
2. Add your keys to .env:

   STRIPE_KEY=pk_live_…
   STRIPE_SECRET=sk_live_…
   STRIPE_PRO_PRICE=price_…

3. Members upgrade on /pricing; manage/cancel runs through Stripe's hosted billing portal — you never touch card data (SAQ-A scope).

Telegram alerts (optional)

1. Message @BotFather on Telegram → /newbot → copy the token into .env as TELEGRAM_BOT_TOKEN=…
2. Start a chat with your new bot (press Start).
3. Get your chat ID: open https://api.telegram.org/bot<TOKEN>/getUpdates after sending the bot any message.
4. Paste the chat ID into any alert rule on /alerts — matching whale trades now land in Telegram.

Feature guide

Alert rules & the bell

Members create rules on /alerts: minimum trade size, side (buy/sell), category, keyword, or a specific wallet. Every matching trade lands in the in-app bell inbox (always) plus any configured channel — email, Telegram, webhook. Each delivery attempt is logged per channel with success/failure. The bell polls every 30 seconds on every page; members can additionally enable native desktop notifications (one click, browser-permission gated) that fire when the tab is in the background.

Watchlist, following & follow alerts

Starring a whale — on any trade card, the leaderboard or a profile — adds them to the member's watchlist and stars all of that whale's cards across the feed. The watchlist page shows each followed whale's live record: tier, win rate, W/L bar, P&L, open positions. A one-click Follow alerts switch pings the member (bell + desktop push) whenever any whale they follow trades — copy-trading, closed loop.

CSV export

Pro members can download the recent whale trades (up to 10,000 rows) and the full leaderboard as CSV from the feed and leaderboard toolbars; free members are pointed at the upgrade page. Files stream (no memory limits) and open cleanly in Excel.

Whale Score

Every market carries a 0–100 Whale Score — buy pressure weighted by each whale's proven track record over the last 72 hours. A sharp whale (≥60% win rate over ≥10 settled bets) moves the score at 2× weight; a whale with a losing record counts at 0.5×. Shown on feed cards and market pages; the feed can sort by it. The exact formula lives in app/Services/WhaleScore.php.

The accuracy scoreboard

Every six hours whales:resolve checks tracked markets for resolution and records whether the whale majority backed the winning outcome. The leaderboard shows the running total (“smart money called 113 of 169 resolved markets — 67% right”) and each resolved market page shows its verdict. Real receipts, generated automatically.

Market watchlists

Besides following whales, members can watch markets — one click on any market page. Every new whale trade in a watched market lands in their bell (and desktop push). Watched markets get their own section on the watchlist page.

Copy-trade simulator

Whale profiles include an honest “if you'd copied” panel: a flat $100 on each of the trader's recent settled bets, computed from real cash P&L. It shows losses as readily as gains, ignores fees/slippage by stated assumption, and carries a not-advice disclaimer.

Two-factor authentication

Any member can enable TOTP two-factor auth from account settings — scan a server-rendered QR (or enter the key manually) in Google Authenticator, 1Password or Authy, confirm one code, done. Sign-ins then require a 6-digit code after the password. Fully offline: no SMS gateway, no external service. Login, registration and password-reset endpoints are rate-limited against brute force, and members can delete their own account (password-confirmed) per the privacy policy.

First-visit tour

New visitors to the feed get a dismissible 3-step tour (live money → check the trader → follow & get alerted), remembered per browser.

Weekly digest

Every Monday 08:00 (server time) opted-in members receive the week in whale money: total volume, biggest moves, hottest markets, top performers. Members opt out in account settings; admins can disable it globally.

Account settings — profile, password, email preferences.

Customization

Branding & colors

No code needed for the basics: Admin → Settings → Branding lets you rename the product, upload a logo and pick an accent color. For deeper re-theming, the design system lives in CSS custom properties at the top of resources/css/app.css (--accent, surfaces, semantic green/red — defined once per theme). Change the tokens, rebuild:

npm install
npm run build

Whale threshold & feed noise

Admin → Settings → Whale threshold. Trades under this USD size are ignored at sync time. $5,000 is a good default; raise it for a quieter, higher-signal feed. Additionally, the feed automatically drops near-certainty trades (≤4¢ / ≥96¢) — a 99¢ "bet" carries no information.

Adding a data source

Sources implement one interface — app/Sources/MarketSource.php (key(), label(), available(), fetchTrades()). Register your class in SourceRegistry, flip it on in config, and its trades flow through the same ingest → alerts → feed pipeline. KalshiSource is a complete working reference.

Updating

1. Back up .env, your database (database/database.sqlite for SQLite) and the cached images (public/avatars, public/market-icons).
2. Upload the new release over the old files (releases never include .env).
3. Run php artisan migrate --force. Done.

FAQ & troubleshooting

The feed is empty after install

Run php artisan whales:sync and read the output table — it names each source and whether it was reachable. The usual cause is a firewall blocking outbound HTTPS to data-api.polymarket.com; ask your host to allow it.

I see a 500 error page

Check storage/logs/laravel.log for the real message. The most common causes are missing write permissions on storage/ and bootstrap/cache/ (755/775, owned by the web-server user).

Emails aren't arriving

Verify SMTP settings in .env; failed alert emails are logged in storage/logs/laravel.log with the provider's error, and alert deliveries show per-channel status on the alerts page.

Data feels stale

Admin → Dashboard shows the age of the newest trade. If it's old: confirm the cron is running. Without cron, the self-healing sync needs page traffic to trigger.

Win rates look different from someone's claimed record

SignalWhale computes records from redemption events plus settled positions (see the /activity endpoint) — an honest, survivorship-bias-corrected method. P&L comes from Polymarket's own cash P&L figures. We deliberately show conservative, verifiable numbers.

How do I make another user an admin?

Admin → Users → edit the user → tick Admin. Admins can't demote or delete themselves.

Can I close public registration?

Yes — Admin → Settings → untick Registration open. The register page then returns 403 and sign-up buttons hide.

Does this work without Stripe / Telegram / SMTP?

Yes. Every integration is optional and independent; the tracker, feed, leaderboard, profiles, watchlists and in-app alerts work with zero external accounts.

Is this financial advice / is it legal to run?

SignalWhale displays public market data for information purposes only — it is not financial advice, and it neither holds funds nor executes trades. Check the regulatory status of prediction markets in your jurisdiction before operating a public instance.

Credits & licenses