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.
EVM wallets (0x) share one quota across all supported EVM chains: you add a 0x wallet once and it's tracked on both BNB Chain and Robinhood Chain. Solana wallets have their own separate quota.
"✨ Add Recommended Wallets" lets you import the admin-curated set of historically successful wallets in one tap.
Pick BNB Chain from the chain menu in the bot, add 0x wallets, and the same engine applies: 2+ tracked wallets buying the same token, a confirmation window, then a fresh AI score (token 40% + wallet 60%). Sells are tracked too — a wallet that sells most of its position stops counting as an active buyer. BSC signals link out to PancakeSwap, DexScreener, BscScan and GMGN.AI, and carry a "Chain: BSC" line. Security screening runs on BSC-native sources (GoPlus + DexScreener + Birdeye); confirmed honeypots are filtered silently.
Pick Robinhood Chain from the chain menu, add 0x wallets, and the same coordinated-buy engine applies: 2+ tracked wallets buying the same token, a confirmation window, then a fresh AI score (token 40% + wallet 60%). Sells are tracked too. Wallet activity is ingested through QuickNode Streams, token market data comes from Birdeye, and wallet analytics come from GMGN. Signals link out to GMGN.AI, DexScreener and Blockscout, and carry a "Chain: Robinhood" line.
Honeypot screening isn't available on Robinhood Chain yet — every Robinhood signal carries a clear warning line. Trade carefully. (The security provider we use, GoPlus, does not support Robinhood Chain yet; when it does, screening turns on automatically.)
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.