Shoal Documentation

Reference for understanding the bot's logic, signal system, and PRO features.

First-Time Setup

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 the first session.

  1. Run /start to launch the bot
  2. Solve the CAPTCHA
  3. Accept the legal terms
  4. Pick a plan with /subscription
  5. Add wallets with /wallets

Buying a Subscription

Two plans: Starter ($50) and PRO ($175). Pay via Hel.io in USDC or SOL, connecting your Telegram wallet (Phantom, Solflare, OKX, Backpack).

Note: Payment is not possible from the website. All transactions go through the Telegram bot.

A subscription lasts 1 calendar month (Jan 4 → Feb 4). Cancel from the /subscription menu. Full refund if cancelled within the first 24 hours.

Wallet Management

Use /wallets to open the wallet menu. Add new wallets, remove existing ones, change aliases, or retry webhook registration from here.

Limits

  • Starter: 25 wallets
  • PRO: 125 wallets

"✨ Add Recommended Wallets" lets you import the admin-curated set of historically successful wallets in one tap.

AI Score System

Every signal gets an AI score from 0–100:

Final = Token Score (40%) + Wallet Score (60%)

Token score

Liquidity, holder count, top-10 share, LP lock status, and Token2022 security checks (non-transferable, transfer fee, freeze authority) make up the total.

Wallet score

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 System

Tokens that fail to clear your filters arrive as red flag messages. Four reasons:

  • mcap_below_threshold — token MCAP is below your minimum
  • mcap_above_threshold — token MCAP is above your maximum (added May 2026)
  • score_below_threshold — AI score is below your threshold
  • top10_above_threshold — top-10 holder share is too high

A 12-hour dedup applies per token to protect you from spam.

Rapid Growth (PRO)

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.

Filter Settings

Open via /settings:

  • 🧮 Buyer threshold: 2–10 (3–4 recommended)
  • ⏱️ Confirmation window: min 30s (10s for PRO)
  • 💼 Min MCAP: min $25K, recommended $40–75K
  • 🔝 Max MCAP: optional upper limit
  • 📤 AI score: 0–100 (30–50 recommended)
  • 🔟 Top 10: min 15%, recommended 25–35%

Min/Max MCAP

The MCAP filter has two bounds: minimum (required) and maximum (optional). System hard cap: $100M. Anything above is filtered out automatically.

Data: 0% success and 77% rug rate for $100M+ tokens. That's why the cap is enforced system-wide.

PRO Channels

PRO users can route signals to 2 separate channels:

  • 📢 Signal Channel: main signals
  • 🚩 Red Flag Channel: signals that hit the filter

You can also set a topic ID for forum groups. Add @TheShoalBot to the channel as an admin.

/ai Command (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).

Scenario Simulation (NEW · May 2026)

Two ways to use it:

1. Structured button

/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.

2. Natural language (Custom Q)

/ai → 🎯 Ask a custom question: "simulate score=40", "what if I set max to 1M?"

Sunday Settings Advisor (PRO)

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 Stats

Each signal's peak price is tracked across 24h / 7d / 30d / 90d windows and rolled up into wallet_stats:

  • success_count_*, fail_count_* — per-window counters
  • avg_peak_*, max_peak_* — peak averages
  • success_rate_* — success ratio

Profile tags: 🐢 late_bloomer (patient hold), ⚡ early_pump (24h sell), regular.

Wallet Pair Stats

When two wallets fire a signal together, the joint success rate is tracked. Three tiers:

  • 🚀 Golden Pair: ≥80% success + 3x+ avg peak
  • Strong Pair: ≥60% success
  • ⚠️ Risky Pair: under 40% (min 5 signals)

The tag is attached to the signal message.