Telegram bot
alerts and commands.
Connect a Telegram bot and the desk sends you its alerts and answers commands such as /status, /liq and /stop, only from your own chat. It uses long polling: no webhook and no open port.
01Create the bot
The commands on this page are written for the shell of macOS and Linux (bash or zsh). On Windows, run them in WSL (Windows Subsystem for Linux, Ubuntu) or Git Bash; in PowerShell, set a variable with $env:NAME="value" instead of export NAME=value. The node and npm commands work in any of them.
- Talk to @BotFatherIn Telegram, open
@BotFather, send/newbot, choose a name and a username. BotFather replies with a token. Treat it like a password. - Start a chat with your botOpen your bot and press Start, so it may write to you.
- Find your chat idSee below.
- Give the desk both values
You can store the token in the console instead (Integrations → Telegram bot token, owner only). The chat id is read only from the environment.export TELEGRAM_BOT_TOKEN=<token from BotFather> export TELEGRAM_CHAT_ID=<your chat id> npm start - Check
node src/cli.mjs doctorlists the Telegram variables, and the console's health page tests the token. When the desk starts, it sends a start message to your chat.
02Chat id and owner id
In a private chat with the bot, your chat id and your user id are the same number. One way to read it: send any message to your bot, then open this address in a browser and look for "chat":{"id":…}:
https://api.telegram.org/bot<token>/getUpdatesStop the desk while you do this; the desk reads the same update queue.
| Where the bot lives | Set | Who may command it |
|---|---|---|
| Private chat with you | TELEGRAM_CHAT_ID | Only you. |
| A group chat | TELEGRAM_CHAT_ID (the group id, negative) and TELEGRAM_OWNER_ID (your user id) | Only you, in that group. Without TELEGRAM_OWNER_ID the bot ignores commands in groups, so other members cannot send /stop. |
03Commands
| Command | Answer |
|---|---|
/status | Mode, equity, cash, open positions, hard-stop tier, kill switch, what blocks entries, pump.fun stream state. |
/report | PnL, win rate and the edge without the luckiest trades (same as npm run report). |
/positions | Open memecoin positions, and with the perps module the news-perp, HL copy and carry positions. |
/news | The strongest news events right now, per coin. |
/pump | pump.fun coins being watched and whether they pass the filters. |
/lanes | Which lanes are on, today's PnL per lane, and the lane lines of the report with exit grades. |
/smart | Smart-wallet count, the top wallets, coins several of them are buying now, and what they hold. |
/brief | The AI analyst's latest briefing: market read, risks, a stance per book, assets to watch (AI analyst). |
/research | The latest research in a few lines: trend profiles against BTC, whether any liquidation strategy beat random entries, the wallet book and the lane replay (Research & analytics). |
/copy | The copy-trade test: smart wallets copied with 0–30 s delay, out of sample, against random wallets. |
/wallet ADDRESS | A wallet from the research lists: total, realised and open PnL, rounds, the last five rounds and the in-sample copy result. |
/liq [COIN] | The liquidation map: nearest clusters above and below, and how much liquidates within ±5 %. |
/verify | Checks the journal's hash chain. |
/leaders | The scored Hyperliquid wallets being copied (HL copy, perps module). |
/stop | Kill switch on: no new entries; exits keep running. |
/resume | Kill switch off. If the hard stop is latched red, the reply warns that this also resets it and re-bases the equity peak. |
/help, /start | The command list. The bot also registers it as Telegram's / menu on start. |
Long answers are split into several messages (at most 5 per command).
04Alerts you will receive
- Desk start, paper buys and sells with PnL, closes, pairs that vanished.
- Strong news events, graduation alerts at 80 % and 95 % of the pump.fun curve, and with the perps module whale trades on Hyperliquid.
- Daily loss limit hit, hard-stop tier changes, hard-stop reset, allocator status changes, and with the perps module the portfolio gross cap.
- Liquidation map: 🧲 when the price comes within 1.5 % of a cluster of at least USD 5M, 💥 when the price runs through one. Each level alerts once per 6 hours.
Every alert is also printed in the terminal. If Telegram is unreachable, sends pause for a minute so the desk loop is not slowed down.
05Telegram channel mentions
This is separate from your bot. The SHILL agent can count how often a coin (a contract address or a $TICKER) is posted in public Telegram channels, by reading each channel's public web preview page (no account and no key). The count is one of the signals of the memecoin desk (Memecoin lanes).
Reading channel pages may be against Telegram's terms of service and the channel owners' wishes. Switch it on only for channels you are allowed to read.
{
"telegram": { "readChannels": true, "channels": ["<public channel name>"] }
}telegram.readChannels(defaultfalse): nothing is fetched unless it istrue.telegram.channels(default empty): bare public channel names, no@and no URL. Private channels cannot be read.telegram.everySeconds(default 45): how often the channels are read.node src/cli.mjs doctorwarns when channels are listed butreadChannelsis off:telegram.channels is set but telegram.readChannels is false — the channels are not read (opt-in).
06Good to know
- After you change the bot token in the console, restart the desk so the command listener uses it. Alerts pick up the new token right away.