Setup — start here

End-to-end setup for the alert loop. Brain → Telegram → you trade manually → wallet tracks → app monitors.Five steps; do them in order. Each row goes green when its check passes.

1Create the Telegram bot + set TELEGRAM_BOT_TOKEN env

1. Open Telegram → message @BotFather → /newbot → follow prompts, save the token it gives you.

2. Never paste the token in any UI or chat — anyone with it controls your bot. Set it as an env var:

# On Railway → Variables → New
TELEGRAM_BOT_TOKEN=<your token here>

3. Redeploy. Status: not configured yet.

2Get your Telegram chat ID

1. Open Telegram, find your bot, send /start

2. Send /chatid — bot replies with your numeric chat ID

3. Paste it here:

3Set your Polymarket wallet address

The /my-bets page reads ERC-1155 token holdings directly from this address.

4Schedule the cron jobs (3 endpoints)

Use Railway-cron, GitHub Actions, cron-job.org, or any external scheduler. Each call needs the x-cron-key header.

Your CRON_KEY:

<your CRON_KEY>

Three jobs:

Every 5 minutes — send new alerts:

curl -X POST "/api/alerts/dispatch" -H "x-cron-key: <your CRON_KEY>"

Status: never run

Every 15 minutes — match alerts to wallet fills:

curl -X POST "/api/alerts/journal" -H "x-cron-key: <your CRON_KEY>"

Status: never run

Every 6 hours — grade matched alerts on resolution:

curl -X POST "/api/alerts/journal/grade" -H "x-cron-key: <your CRON_KEY>"

Status: never run

💾 Backup .dataBackup = downloadable JSON snapshot of journal + prefs (excludes secrets).

5OpenAI API key

Required for: engine recommendations + AI rationale on alerts. Without it, the brain falls back to rules-only mode (whale-conviction picks still work). Cost: ~$0.0001 per rationale, ~$0.005 per engine pick (gpt-4o-mini).

Stored on the server’s disk volume; never echoed back to the UI. To enable AI rationale on every alert (whale moves, fragile books, arbs), also set ALERT_AI_RATIONALE=1 as an env var on Railway. Bot rec alerts always include the engine’s reasoning.

6(Optional) Twitter / X (twitterapi.io) key

Enables live tweet feed at /twitter for tracked accounts + keywords (Iran, oil, ceasefire, Hormuz, etc.). Without it the page falls back to sample data. Sign up at twitterapi.io.

⚡Quick actions

One-click ops to skip manual setup steps.

🐋 Seed whale intel

Pulls top 100 Polymarket traders by 7-day P&L and scores them. Populates the calibration page + feeds the engine. Run once after install or to refresh scores.

📌 Watch geopolitics preset

Adds Iran airspace, US-Iran strikes, ceasefire, Hormuz, oil > $100, etc. to your watchlist. All get Telegram alerts on ≥5¢ drift or imminent resolution.

7(Optional) Email digest mirror of Telegram alerts

Hourly recap email of everything Telegram sent in the last hour. Useful for reviewing what fired while you were away. Requires RESEND_API_KEY env (or SMTP_*).

Add to your cron schedule:

curl -X POST "/api/alerts/email-digest" -H "x-cron-key: <your CRON_KEY>"   # hourly

8(Optional) Daily Telegram recap

Once-a-day summary of yesterday’s alerts: how many fired, how many you acted on, win/loss split, top earner, biggest miss, and any winners you didn’t act on. Schedule it for whatever morning hour you check Telegram.

curl -X POST "/api/alerts/daily-recap" -H "x-cron-key: <your CRON_KEY>"   # daily, e.g. 13:00 UTC = 8am EST