Telegram bot

@HatchScoreBot is Hatch's in-chat scoring interface for Telegram. It is the fastest way for a group of traders to score Four.meme tokens without leaving the conversation.

What it does

/score <address> — returns a full Hatch score card (band, 6 signals, aggregate, preliminary flag, links to the full breakdown and the roast).
/score <four.meme URL> — same, but extracts the address from any URL that embeds one (four.meme, pancakeswap, bscscan, dexscreener, dextools, gmgn, birdeye).
Auto-detect in groups — paste any 0x address or four.meme URL in a group and the bot replies with a score card. No command prefix needed.
Fresh scoring — if a token has never been scored before, the bot fetches its on-chain metadata (name, symbol) and runs a full scoring pass live in the chat. Typically 15–30 seconds.
Cached scoring — if the contract has been scored before, the bot replies instantly with the latest stored result.
Links everywhere — every reply links to the full breakdown at gohatch.fun/score/<id> and the roast at gohatch.fun/roast/<id>.

How to use it

Open Telegram and search @HatchScoreBot (or tap the link on the Hatch landing page).
Hit Start — you'll get the welcome card.
In a DM: just paste any address or URL.
In a group: add the bot with messaging permissions. No admin rights needed. Paste addresses — bot replies as threaded responses.

Example

/score 0x55d398326f99059ff775485246999027b3197955

Reply:

✅ Green band · 87/100

• Meme: 92/100 — Clear concept, clean execution.
• Name: 84/100 — Memorable, no ticker collisions.
• Image: 88/100 — Original art, high detail.

[Full breakdown →]  ·  [Roast 🔥]

Group-chat etiquette

The bot only auto-replies to messages that contain a 0x address or a four.meme URL. It does not respond to unrelated chat.
Replies are always threaded (reply_to_message_id set) so they don't interrupt the group flow.
No commands are required in groups — the bot detects intent from the pasted content.

Privacy

The bot does not store chat messages. Only the scored contract address and its public on-chain metadata are persisted.
Scores generated via the bot are indistinguishable from scores generated via the web or API — they enter the same public score index (leaderboards, percentile, OG share).
No wallet signatures are requested. The bot is read-only from the user's perspective.

For developers

The webhook endpoint is POST /telegram/webhook on the API project. Authenticated by a shared secret set as TELEGRAM_WEBHOOK_SECRET and passed via Telegram's X-Telegram-Bot-Api-Secret-Token header (or ?secret=… query as a fallback).
Commands are discovered from apps/api/src/modules/telegram/commands/ at build time. Adding a new command is one new file plus one line in handler.ts.
The bot is stateless. State (cached scores, creators, leaderboards) lives in the main Postgres.
Rate-limiting piggybacks on the API's existing per-route limits; the bot cannot exceed what a direct API caller can.

Roadmap

/watch <address> — subscribe to band changes, alert when a score crosses green→amber or amber→red
/compare <addr1> <addr2> — head-to-head card, same shape as /score/[id]/vs/[other]
/graveyard — top 10 worst-scored new launches from the last 24h
/leaderboard today — green-band leaders from the last 24h
Inline mode — @HatchScoreBot 0x… in any chat

Setup (self-host)

If you fork Hatch and run your own bot:

/newbot with @BotFather on Telegram. Copy the token.
Set on your API deployment:
- TELEGRAM_BOT_TOKEN=<token>
- TELEGRAM_WEBHOOK_SECRET=<any 32+ char random string>
After deploy, register the webhook:

curl -s "https://api.telegram.org/bot<TOKEN>/setWebhook" \
  -d "url=https://your-api-host/telegram/webhook" \
  -d "secret_token=<WEBHOOK_SECRET>"

Expected response: {"ok":true,"result":true}.

DM the bot, send /start. If it replies, you're live.

What it does

/score <address> — returns a full Hatch score card (band, 6 signals, aggregate, preliminary flag, links to the full breakdown and the roast).

/score <four.meme URL> — same, but extracts the address from any URL that embeds one (four.meme, pancakeswap, bscscan, dexscreener, dextools, gmgn, birdeye).

Auto-detect in groups — paste any 0x address or four.meme URL in a group and the bot replies with a score card. No command prefix needed.

Fresh scoring — if a token has never been scored before, the bot fetches its on-chain metadata (name, symbol) and runs a full scoring pass live in the chat. Typically 15–30 seconds.

Cached scoring — if the contract has been scored before, the bot replies instantly with the latest stored result.

Links everywhere — every reply links to the full breakdown at gohatch.fun/score/<id> and the roast at gohatch.fun/roast/<id>.

How to use it

Open Telegram and search @HatchScoreBot (or tap the link on the Hatch landing page).

Hit Start — you'll get the welcome card.

In a DM: just paste any address or URL.

In a group: add the bot with messaging permissions. No admin rights needed. Paste addresses — bot replies as threaded responses.

✅ Green band · 87/100 • Meme: 92/100 — Clear concept, clean execution. • Name: 84/100 — Memorable, no ticker collisions. • Image: 88/100 — Original art, high detail. [Full breakdown →] · [Roast 🔥]

Group-chat etiquette

The bot only auto-replies to messages that contain a 0x address or a four.meme URL. It does not respond to unrelated chat.

Replies are always threaded (reply_to_message_id set) so they don't interrupt the group flow.

No commands are required in groups — the bot detects intent from the pasted content.

Privacy

The bot does not store chat messages. Only the scored contract address and its public on-chain metadata are persisted.

Scores generated via the bot are indistinguishable from scores generated via the web or API — they enter the same public score index (leaderboards, percentile, OG share).

No wallet signatures are requested. The bot is read-only from the user's perspective.

For developers

The webhook endpoint is POST /telegram/webhook on the API project. Authenticated by a shared secret set as TELEGRAM_WEBHOOK_SECRET and passed via Telegram's X-Telegram-Bot-Api-Secret-Token header (or ?secret=… query as a fallback).

Commands are discovered from apps/api/src/modules/telegram/commands/ at build time. Adding a new command is one new file plus one line in handler.ts.

The bot is stateless. State (cached scores, creators, leaderboards) lives in the main Postgres.

Rate-limiting piggybacks on the API's existing per-route limits; the bot cannot exceed what a direct API caller can.

Roadmap

/watch <address> — subscribe to band changes, alert when a score crosses green→amber or amber→red

/compare <addr1> <addr2> — head-to-head card, same shape as /score/[id]/vs/[other]

/graveyard — top 10 worst-scored new launches from the last 24h

/leaderboard today — green-band leaders from the last 24h

Inline mode — @HatchScoreBot 0x… in any chat

Setup (self-host)

If you fork Hatch and run your own bot:

/newbot with @BotFather on Telegram. Copy the token.

Set on your API deployment:

TELEGRAM_BOT_TOKEN=<token>
TELEGRAM_WEBHOOK_SECRET=<any 32+ char random string>

After deploy, register the webhook:

curl -s "https://api.telegram.org/bot<TOKEN>/setWebhook" \ -d "url=https://your-api-host/telegram/webhook" \ -d "secret_token=<WEBHOOK_SECRET>"

Expected response: {"ok":true,"result":true}.

DM the bot, send /start. If it replies, you're live.