Reference for understanding the bot's logic, signal system, and PRO features.
Open @TheShoalBot on Telegram and run /start. Solve the CAPTCHA and accept the legal terms. There is no free trial — a subscription is required from day one.
/start to launch the bot/subscription/walletsTwo plans: Starter ($50) and PRO ($175). Pay via Hel.io in USDC, SOL or USDT, using your own wallet (Phantom, Solflare, OKX, Backpack) on Hel.io's checkout page. The bot itself never connects to your wallet.
A subscription lasts 1 calendar month (Jan 4 → Feb 4) and does not auto-renew — renew manually via /subscription to continue. Full refund if you cancel within the first 24 hours.
Upgrading from Starter to PRO: your remaining Starter days become a credit at their full value (days left × $50/30) and the Hel.io checkout opens at $175 minus that credit — never below $25.
Use /wallets to open the wallet menu. Add new wallets, remove existing ones, change aliases, or retry webhook registration from here.
"✨ Add Recommended Wallets" lets you import the admin-curated set of historically successful wallets in one tap.
Every signal gets an AI score from 0–100:
Final = Token Score (40%) + Wallet Score (60%)
Liquidity, holder count, top-10 share, LP lock status, and Token2022 security checks (non-transferable, transfer fee, freeze authority) make up the total.
Last-30-day performance: Win Rate (30p), PnL (32p), Realized Profit (14p), Sold Avg Profit (10p), Fast TX (4p), honeypot penalty (-15p).
Full detail is available in chatbot_docs/technical.md.
Red flag messages are a PRO feature — tokens that fail to clear your filters arrive as red flag messages. Starter users don't receive these messages, but the underlying data is still recorded. Four reasons:
mcap_below_threshold — token MCAP is below your minimummcap_above_threshold — token MCAP is above your maximum (added May 2026)score_below_threshold — AI score is below your thresholdtop10_above_threshold — top-10 holder share is too highMCAP veto is no longer instant. When a token's market cap is out of your range (but above the $25K system floor) it enters the same confirmation wait as everyone else; the decision is made at the end with full analysis — if it recovers into range a signal is sent, if it dumps nothing is sent. The $25K floor still drops silently with no message.
A 2-hour dedup applies per token to protect you from spam.
Tokens that hit a red flag are watched for 5 minutes. Every new wallet buy adds +4 bonus points (capped at +16). If the bonus pushes the score past your threshold, a "🚀 Rapid Growth" signal is sent.
Toggle from /settings → 🚀 Rapid Growth.
Open via /settings:
The MCAP filter has two bounds: minimum (required) and maximum (optional). System hard cap: $100M. Anything above is filtered out automatically.
PRO users can route signals to 2 separate channels:
You can also set a topic ID for forum groups. Add @TheShoalBot to the channel as an admin.
Available on both Starter and PRO. 6 buttons: 📊 Performance, 🏆 Best & worst wallets, ⚙️ Optimize my settings, 🎲 Simulate scenario, 📈 Weekly summary, 🎯 Ask a custom question.
10 queries/day with a 1-hour cache. 🎲 Simulate scenario is rate-limit-free (Python computes instantly).
Two ways to use it:
/ai → 🎲 Simulate scenario, type one line:
min=155k, max=1M, score=40, top10=25
Python instantly computes against your historical data: monthly signals, success %, avg peak, MCAP band breakdown.
/ai → 🎯 Ask a custom question: "simulate score=40", "what if I set max to 1M?"
Every Sunday at 20:30 Istanbul, an AI settings recommendation arrives in DM. 8 pre-computed scenarios are handed to Gemini, the best one becomes the recommendation. Hit Apply to enable it immediately, or Reject to snooze it for 14 days.
Wallet-learning data is now recorded for all users, Starter included. Each signal's peak price is tracked across 24h / 7d / 30d / 90d windows and rolled up into wallet_stats — but this Birdeye outcome tracking runs only for active PRO users. Starter records are kept with tracking paused; upgrading to PRO auto-backfills them, and records for users who never upgrade are deleted after 90 days.
success_count_*, fail_count_* — per-window countersavg_peak_*, max_peak_* — peak averagessuccess_rate_* — success ratioProfile tags: 🐢 late_bloomer (patient hold), ⚡ early_pump (24h sell), regular.
When two wallets fire a signal together, the joint success rate is tracked. Three tiers:
The tag is attached to the signal message.