Documentation Index
Fetch the complete documentation index at: https://docs.shoal.xyz/llms.txt
Use this file to discover all available pages before exploring further.
Connect Shoal to Telegram for daily intelligence digests delivered to your team’s channel or group. The bot fetches top signal events and formats them as a clean, numbered digest.
What You Get
- Daily digest — Top signal events ranked by signal score, delivered on schedule
- Clean formatting — Numbered list with bold titles, signal scores, and concise summaries
- Channel or group delivery — Works with Telegram channels, groups, and supergroups
The daily digest is formatted as a single message:
🐚 Shoal Daily Digest — Mar 11, 2026
─────
🔥 Top Signal Events
1. Aave $21M Wrongful Liquidations (signal: 23.47)
Chaos Labs' automated oracle cap update mispriced wstETH
collateral, triggering ~$21M in wrongful liquidations.
Major DeFi risk story.
2. Nasdaq Tokenization Push (signal: 20.52)
Nasdaq moves closer to "always on" trading with tokenized
securities. SEC rule change filed — potential launch late
Q3 2026.
3. Gemini/Google Product Blitz (signal: 8.0)
Google drops Gemini Embedding 2 (multimodal), Nano Banana 2
(image gen), Lyria 3 (music gen), and Flash-Lite 3.1.
Massive product week.
- Rank and title (bold)
- Signal score — ratio of actual impressions to platform baseline
- Summary — concise 1-2 sentence description
The examples below use the canonical event aliases (summary, owners, significance) rather than the older compatibility fields.
Setup
1. Create a Telegram Bot
Message @BotFather on Telegram:
Follow the prompts to name your bot. BotFather gives you a token like 8345440207:AAFOdtxvg8FlzxIwrPbe6siNMoRg9gMYF4I.
2. Get Your Channel ID
Add the bot to your channel/group as an admin, then send a message. Fetch the chat ID:
curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates" | python3 -m json.tool
"chat": {"id": -100XXXXXXXXXX} — that negative number is your channel ID.
# .env
SHOAL_API_KEY=your_shoal_api_key
TELEGRAM_BOT_KEY=8345440207:AAFOdtxvg8FlzxIwrPbe6siNMoRg9gMYF4I
TELEGRAM_CHANNEL_ID=-1003846621812
4. Example Script
const SHOAL_API_KEY = process.env.SHOAL_API_KEY;
const TG_TOKEN = process.env.TELEGRAM_BOT_KEY;
const TG_CHAT = process.env.TELEGRAM_CHANNEL_ID;
async function sendDigest() {
// Fetch today's top signal events
const since = new Date(Date.now() - 24 * 3600_000).toISOString();
const res = await fetch(
`https://api.shoal.xyz/v1/signal/all?since=${encodeURIComponent(since)}&limit=10`,
{ headers: { Authorization: `Bearer ${SHOAL_API_KEY}` } }
);
const { data: events } = await res.json();
if (!events?.length) return;
// Sort by significance descending
events.sort((a, b) => (b.significance ?? b.signal ?? 0) - (a.significance ?? a.signal ?? 0));
const today = new Date().toLocaleDateString("en-US", {
month: "short", day: "numeric", year: "numeric",
});
let msg = `🐚 *Shoal Daily Digest — ${today}*\n─────\n\n🔥 *Top Signal Events*\n`;
events.forEach((e, i) => {
const orgs = (e.owners || e.eventOwner || []).map((o) => o.label).join(", ");
msg += `\n*${i + 1}. ${e.title}* (signal: ${e.significance ?? e.signal ?? "—"})\n`;
if (orgs) msg += `_${orgs}_\n`;
msg += `${e.summary || e.globalSummary}\n`;
});
// Send to Telegram
await fetch(`https://api.telegram.org/bot${TG_TOKEN}/sendMessage`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
chat_id: TG_CHAT,
text: msg,
parse_mode: "Markdown",
}),
});
}
sendDigest();
Architecture
┌──────────┐ cron / scheduled ┌──────────────┐
│ Script │ ◄────────────────────► │ Shoal API │
│ │ │ api.shoal.xyz│
└─────┬─────┘ └──────────────┘
│
│ sendMessage
▼
┌──────────────┐
│ TG Channel │
└──────────────┘
Comparison
| Feature | Slack | Telegram |
|---|
| Delivery | Real-time (60s polling) | Scheduled digest |
| Format | Rich Block Kit cards | Markdown messages |
| Interactivity | Slash commands | Bot commands (optional) |
| Best for | Team collaboration channels | Mobile-first alerts, executive summaries |
