Product guides - Telegram alerts

Telegram alerts

Private push alerts for price spikes and new arbitrage entries, delivered by a Telegram bot you own and tuned entirely to your thresholds.

Web3Map Telegram alerts push two kinds of signals straight to your phone: price spikes (abnormal moves on a venue across one or more time windows) and new entries (fresh arbitrage gaps that just appeared above your minimum spread). Both arrive in a private one-to-one Telegram chat between you and a bot that belongs to you. Web3Map never shares a single bot across users: you create the bot with BotFather, you hold the bot, and Web3Map only stores its token in encrypted form so the alert pipeline can post messages into your chat.

Requirements: an active Pro (or higher) plan and a Telegram account. The whole feature is gated on premium entitlement. On My Page, Free accounts do not see the Premium alerts card at all; accounts whose Pro time has lapsed see Upgrade to Pro to enable private Telegram alerts. instead of the setup card, and the server rejects registration and linking with Premium entitlement required.

How it fits together in one paragraph: you create a dedicated bot with @BotFather and paste its HTTP API token into the Premium alerts card on My Page. Web3Map validates the token, configures the bot's webhook and its slash-command menu, and hands you a one-time deep link. You open the deep link and send /start in the private chat, which binds that chat to your Web3Map account. From then on, alerts are pushed into that chat, and the very same chat doubles as a settings console: inline menus and slash commands let you toggle signals, edit thresholds, and manage mute lists without ever opening the website.

Setup walkthrough

Everything happens in the Premium alerts card on My Page (sidebar item Premium Alerts). The card kicker reads Telegram and the subtitle reads Receive premium price spikes and new entries in your private Telegram chat. The card is organized as three numbered panels that mirror the steps below.

1. Connect your bot.

   The Step 1 panel is titled Connect your bot with the description Create a dedicated bot with BotFather and register its token. It lists three instructions verbatim:

   1. Talk to @BotFather on Telegram and send /newbot.
   2. Copy the HTTP API token and paste it below. It is encrypted at rest.
   3. Open the generated deep link and send /start in the private chat.

   In Telegram, message @BotFather, send /newbot, pick a display name and a unique username for your bot, and BotFather replies with an HTTP API token that looks like 123456:ABC-DEF.... Paste it into the field labeled BotFather token (a password-style input with placeholder 123456:ABC-DEF... and the hint Stored encrypted. Rotate anytime.), then press Register bot.

   Before anything is saved, the server checks the token against Telegram itself:

   - The token must belong to a real bot. If it does not, registration fails with Telegram token does not belong to a bot.
   - The bot must not already be serving another service. If it has a webhook pointing somewhere else, registration fails with Telegram bot already has a foreign webhook.
   - One bot per Web3Map account. If your account already has a bot registered, you get A Telegram bot is already registered for this account. Use Rotate or Unlink before registering a new bot.
   - One account per bot token. A token already used by a different Web3Map account is rejected with This Telegram bot token is already connected to another Web3Map account. Unlink it from that account first, or create a new bot with BotFather and register the new bot token.

   If validation passes, Web3Map sets the bot's webhook (with a per-bot secret), installs the full slash-command menu on the bot, switches the bot's menu button to that command list, and stores your token encrypted. The credential starts in the pending_chat state because no private chat is linked yet. Token registration is rate limited to 5 attempts per 5 minutes.

2. Open the deep link and send /start.

   Right after registration the card shows a box with the kicker Deep link ready, an Expires timestamp in your local time, and the full link, shaped like https://t.me/your_bot?start=.... The link expires after 10 minutes and allows at most 5 attempts. If it lapses, press New deep link in the Step 2 panel to issue a fresh one (issuing a new link revokes the previous pending one).

   Open the deep link. Telegram opens your private chat with the bot and sends /start with the link token attached. On success the bot replies with the confirmation and immediately shows the settings menu:

   W

   my_web3map_alerts_bot

   bot

   /start14:02

   Web3Map premium Telegram alerts linked.
   
   Telegram alert settings
   
   Price spikes: on
   Sell Rise: on
   Buy Drop: on
   New entries: on
   New entries min spread: 1%
   
   Choose a section below. 14:02

   Price spikesNew entries

   Refresh

   Linking flips the credential to active, records your private chat, and creates your default alert preferences (all signal types on, default windows and thresholds). You are now receiving alerts.

3. Tune your alert rules.

   The Step 3 panel, Alert rules (Tune which signals are delivered to your Telegram chat.), is where you set which signals fire, per-window spike thresholds, the new-entry spread floor, and mute lists. It is covered in full in Alert rules (web). You can also change everything from inside the Telegram chat, see Command reference and Inline menus.

Delivery status panel

The Step 2 panel is titled Delivery status with the description Live state of your Telegram credential and private chat. It shows three rows and two buttons. The panel refreshes every 30 seconds and again whenever you return to the browser tab.

Delivery row

The single answer to "am I receiving alerts right now". Shows Active only when all three conditions hold at once: your premium entitlement is valid, the bot credential is active, and a private chat is linked and active. Anything else shows Inactive.

Credential row

Shows your bot as @bot_username plus its raw status badge. Right after registering the token, before you send /start, the status is pending_chat. After linking it becomes active. If no bot has been registered yet the row shows Not registered.

Private chat row

The state of the one-to-one chat link. Shows Not linked before you open the deep link and send /start, active once linked, and paused if delivery is paused (either you ran /pause or you blocked the bot in Telegram).

New deep link button

Issues a fresh 10-minute deep link for the registered bot, revoking any previous pending link. Use it when the original link expired, when you hit the 5-attempt limit, or after a token rotation. Available only when a bot credential exists; otherwise the server replies No reconnectable Telegram bot credential. Deep link issuance is rate limited to 10 requests per 5 minutes.

Unlink button

Full disconnect. Revokes the credential, the chat link, and any pending deep link, deletes the stored encrypted token, and removes the webhook from your bot. After unlinking, the bot is entirely yours again with no Web3Map configuration on it. To start over you re-register a token from Step 1.

Alert types and message anatomy

Two alert families share the same delivery pipeline and the same formatting conventions:

Price spike messages

A price spike alert fires when a venue's price moves by at least your threshold inside one of the six polling windows. A first alert for an asset looks like this:

Buy  | $0.0512 -> $0.0721
Sell | $0.0509 -> $0.0718

Buy  | $0.0510 -> $0.0703
Sell | $0.0508 -> $0.0699

Buy  | $0.0489 -> $0.0721
Sell | $0.0486 -> $0.0718

Line by line:

Header line

Direction icon (chart-up for Sell Rise, chart-down for Buy Drop), then the triggering windows in brackets, for example [Sell Rise 30s, 5m], then the asset symbol as a link into the Web3Map graph, then the spike magnitude with sign. A Sell Rise shows a positive percentage; a Buy Drop shows a negative one, for example [Buy Drop 1h] SYMBOL -45.00%. When the alert is a continuation of an episode you were already alerted about, the elapsed time since the episode started is appended, for example (13m 20s).

Window subheaders

When two or more windows fired at once, each window gets its own bold subheader marked with an hourglass icon, for example 5m:, listed in ascending window order. A single-window alert skips the subheaders.

Venue line

One bold line per venue: venue name, a pipe, the chain in italics, then that venue's move, for example uniswap | eth: +32.10%. Each window block lists every spiking CEX and perp venue plus the best DEX per chain, capped at 8 venues per window.

CEX chain labels with D/W markers

For CEX venues the chain list carries deposit and withdrawal markers, for example eth(D/W), ton(D). D means deposits are open on that chain, W means withdrawals are open. A chain is listed only when its status is both enabled and fresh (updated within the last 5 minutes), so what you see is actionable, not stale exchange metadata.

Buy/Sell price block

A fixed-width block with two rows, Buy and Sell, each showing the previous price and the current price, for example $0.0512 -> $0.0721. Both sides are shown so you can see whether the spread itself widened or the whole book moved.

CA: line

The token contract address, rendered as tap-to-copy monospace. For multi-chain CEX venues the message shows a CA: header followed by one italic chain label and address per chain, each with its own link row.

Pool: line

DEX venues only: the pool address the quote came from, also tap-to-copy.

Link row CMC | DS | GMGN

Bold external links in a fixed order: CMC opens CoinMarketCap (the currency page when a slug is known, otherwise CoinMarketCap's DEX token page), DS opens DEXScreener, GMGN opens gmgn.ai. Each link is rendered only when that service supports the chain, so some rows show fewer links. Native coins get no link row.

Time line

Time: 2026-06-12 14:02:31 UTC. The snapshot timestamp of the alert in UTC.

From the second alert of an episode onward, the window block also appends a recap of the whole episode and a price trail:

Buy  | $13.00 -> $16.92
Sell | $12.97 -> $16.90

Recap line (circular-arrow icon)

+69.00% from start ($10.00 → $16.90) shows the cumulative move of the whole episode, from the price where the episode began to the latest alerted price. It appears once a window has alerted at least twice in the same episode.

PA: price trail (chart icon)

The episode's price progression, one point per alert (the window's extreme at each step), up to 6 points. Only the final segment is bold, so your eye lands on the latest move. PA stands for price action.

New entry messages

A new entry alert fires when an arbitrage pair enters the live opportunity book above your minimum spread. The message is a compact briefing of the whole opportunity: what moved, the best executable route, both sides of the book, alternative routes, and the contract addresses.

Venue     | Price   | Gap    | Chain(W)
uniswap   | $0.0512 | +12.3% | eth
binance   | $0.0518 | +11.0% | eth, ton
gate [FB] | $0.0524 | +9.7%  | -
+2 more venues

Venue     | Price   | Gap    | Chain(D)
binance   | $0.0575 | +12.3% | ton
okx       | $0.0561 | +9.6%  | eth
binance.P | $0.0566 | +10.5% | -

Route                 | Gap    | Bridge
eth -> ton            | +12.3% | stargate
eth                   | +9.6%  | -
eth -> Binance -> ton | +6.0%  | Binance
arb -> base           | +5.5%  | Unknown

Line by line:

Header line

[NEW ENTRY], then the asset symbol as a graph link, then the largest gap found in the venue tables below.

Gap maintained: line (persistent entries)

When the gap is still open but prices have not moved recently, the message replaces the mover block with a single bold line such as Gap maintained: 1h 5m, telling you how long the spread has survived.

Mover: block (fresh entries)

When the entry is fresh, a bold line names the venue that moved, the direction triangle, the 30-second move, and which side of the book it affects: an up triangle means a rising price on the SELL side, a down triangle means a falling price on the BUY side. The second line shows the previous and current price with the chain in italics. If the mover is a DEX, tap-to-copy CA: and Pool: lines follow. If a fresh entry's gap has also been open for more than 5 minutes, an extra Gap maintained: line is added.

Best Route: blockquote (star icon)

A bold quoted block with up to four lines: Buy: venue, chain, and price; Sell: venue, chain, and price; Bridge: how value moves between the two legs; Gap: the spread of this specific route. The bridge can be a protocol such as stargate(eth->ton), a CEX relay where the exchange itself moves the asset between chains, written like Binance(eth->ton), or unknown when no known path exists. When both legs sit on the same token and chain, the Bridge: line is omitted entirely. Route discovery walks the token-level bridge topology plus CEX deposit/withdraw relays, and only counts deposit/withdraw legs whose status is fresh and enabled.

Price: section, BUY and SELL tables

Two fixed-width tables sharing the same column widths: Venue | Price | Gap | Chain(W) for the buy side and Venue | Price | Gap | Chain(D) for the sell side. Chain(W) lists the chains you can withdraw to after buying at that venue; Chain(D) lists the chains you can deposit from before selling there. Only fresh and enabled chains are listed; - means none qualify right now, and perp venues always show - because there is nothing to move on-chain. [FB] after a venue name marks a fallback price, meaning the primary quote source was unavailable and a secondary one was used. Each side lists up to 12 venues (every CEX plus the best DEX per chain take priority), with a +N more venues line when the book is deeper. Exchanges that could not form a pair but still have a fresh price are included for comparison, with their gap computed against the global best counterparty.

Route: table (globe icon)

Alternative routes ranked by gap, formatted Route | Gap | Bridge. A single chain id means a same-chain route with no bridge (-). Multi-hop routes show the path, for example eth -> Binance -> ton with the CEX named in the Bridge column, or arb -> base with Unknown when no known bridge connects the legs. Only routes with a gap of at least 5% are listed, up to 8 rows.

CA: section

The closing section lists one contract address per chain, with the chain in italics and the address in tap-to-copy monospace. Tokens that belong to the Best Route legs claim their chain's slot first. Each address gets its own external link row.

External links CMC | DS | GMGN

Fixed order. CMC is CoinMarketCap, DS is DEXScreener, GMGN is gmgn.ai. A link only renders when that service supports the chain, which is why the ton address above shows only CMC. Native coins get no link row at all.

When alerts fire and when they repeat

Alert volume is controlled by episode logic, not by blunt time cooldowns. The goal: never send you the same information twice, and never go quiet while a move is still developing.

Price spikes: per-user episodes

Each spike episode is tracked per user and per asset, with anchors per window and venue. The anchor is the last price you were actually alerted at, not a global market reference:

• First alert: fires when a window's live move reaches your threshold for that window and no live episode exists for you yet.
• Follow-up alert: fires only when the price moves again, in the same direction, by at least your threshold, measured from your last alerted price. The follow-up shows that anchor as the previous price, the percentage relative to it, and the elapsed time since the episode started in the header, for example (13m 20s).
• Episode expiry: after 1 hour with no further qualifying move, the episode ends. The next spike on that asset starts a fresh episode with a fresh first alert.
• Windows are independent: a 30s episode and a 5m episode on the same asset can fire separately; when several windows qualify at the same moment they are merged into one message with per-window subheaders.
• No duplicate content: the send gate is content newness. A message whose venue legs and trail end-point are identical to what you already received is suppressed, while a genuinely progressed episode or a different window passes immediately. Anchors only advance when an alert is actually scheduled to you, so a failed delivery never silently eats an alert.

This is why you do not get ten identical messages during a sideways wobble: each follow-up requires a full additional threshold-sized move from the exact price you last saw.

New entries: recency gate plus cooldowns

• First alert: sent when a qualifying pair entered the opportunity book within the last hour. Entries older than that are never alerted as new.
• Re-alerts: while an entry stays fresh (the gap appeared less than 5 minutes ago, or a venue printed a 30-second move of at least 1%), it can re-alert at most once per hour. Once it turns persistent (the gap survives without fresh movement), re-alerts slow to at most once every 2 hours, and the message shows the Gap maintained: line instead of a mover.
• Phantom guard: if the best buy and best sell are the same venue, no alert is sent at all.

Alert rules on the web

The Step 3 panel Alert rules (Tune which signals are delivered to your Telegram chat.) is the full-width control surface for everything the bot delivers. Changes are collected locally and applied only when you press Save changes; the footer reminds you with Changes apply only after you save.

Signal types

Four master toggles, all on by default:

Price spikes

Description on screen: Abnormal movement across polling windows. The master switch for the whole spike family. Off means no spike alerts regardless of window settings.

Sell Rise

Notify when sell-side prices rise sharply. Direction toggle: alerts where the sell price ran up (an opportunity to sell high).

Buy Drop

Notify when buy-side prices drop sharply. Direction toggle: alerts where the buy price fell hard (an opportunity to buy low).

New entries

Fresh arbitrage opportunities above the spread floor. The master switch for new-entry alerts.

Spike windows

Six cells, one per window, each with an on/off checkbox and a percentage threshold input (minimum 10). The window labels read 30 s window, 1 min window, 5 min window, 15 min window, 30 min window, and 1 hour window.

The shape of the defaults is deliberate: short windows need violent moves to matter (30% in 30 seconds), while the 1 hour window only speaks up for near-doubles (95%). Thresholds below 10% are rejected by the server with Price spike threshold must be >= 10. If you type something that is not a number, the card shows Spike threshold for {window} must be a valid number.

New entries minimum spread

The field labeled New entries minimum spread takes a percentage with a floor of 1 (default 1%). Entries below your floor are never delivered. Values below 1 are rejected with Telegram new entries min spread must be >= 1; non-numeric input shows New entries min spread must be a valid number.

Mute lists

Two collapsible groups, one per alert family, and they are fully independent of each other:

New entries group

Description: Suppress new-entry alerts by token, CEX, or chain. Hint under the token input: Enter one exact token symbol at a time. Mutes new-entry alerts only, not price spikes.

Price spikes group

Description: Suppress price-spike alerts by token, CEX, or chain. Hint: Price-spike mutes start empty and do not inherit new-entry mutes. Muting a token for new entries does nothing to its spike alerts, and vice versa.

Each group has three tabs, Tokens, CEX, and Chains, with per-tab count badges and chip tags TKN, CEX, and NET. The group header shows None or {n} muted, plus an Unsaved badge while you have pending edits. Inputs are exact-match only:

• Tokens: placeholder Exact token symbol. The symbol must resolve to exactly one asset; a typo, an unknown symbol, or an ambiguous one returns Enter the exact token symbol.
• CEX: placeholder binance. Unknown exchange ids are rejected with Unknown CEX id.
• Chains: placeholder polygon. Unknown chain ids are rejected with Unknown chain id.

Press Hide (or Enter) to add, press Unhide on a chip to remove. An empty tab shows Nothing muted yet. Limits per list: 1000 tokens, 100 CEXes, 200 chains; exceeding the token limit shows Hidden asset limit reached.

Saving

The Save changes button applies everything at once and then enters a 30 second cooldown, during which the footer shows Next save available in {n}s. Nothing takes effect before you save.

Command reference

Most of the command list is installed on your bot at registration time, so Telegram's command menu (the / button) autocompletes them. A few commands (/start, /settings, /help, /cancel, /spikes, /newentries, /unlink) are recognized when typed but do not appear in the autocomplete menu. Anything the bot does not recognize answers with the help text.

Session and navigation

Delivery control

Price spike settings

Window arguments are given in seconds: 30, 60, 300, 900, 1800, or 3600 (30s, 1m, 5m, 15m, 30m, 1h). Every successful command replies with a summary of your current settings.

Malformed input replies with the usage line: Usage: /spikes on|off, /spikes rise on|off, /spikes drop on|off, /spikes window <seconds> on|off, /spikes threshold <seconds> <pct>.

New entry settings

The same command also routes mute subcommands (/newentries hide SOL behaves like /hide SOL). Malformed input replies Usage: /newentries on|off, /newentries min <pct>, /newentries hide <SYMBOL>, /newentries unhide <SYMBOL>, /newentries hidden.

New-entry mute commands

Price-spike mute commands

The spike_ prefix manages the separate price-spike lists. Replies follow the same patterns with hidden for price spikes. wording, and the list titles are Price spike Hidden List, Price spike Hidden CEX List, and Price spike Hidden chain List.

A few exchanges in practice:

Inline menus

Sending /menu, /settings, or /start in a linked chat opens an interactive settings console built from inline keyboards. Unlike text commands, menu changes are staged in a draft: toggles and edited numbers accumulate until you press Save changes. While a draft exists, every screen shows the line Draft changes pending. and gains Save changes and Discard draft buttons.

Root settings menu

Price spikes / New entries

Open the two settings sub-screens.

Save changes

Applies the draft and replies Changes saved. Saving is rate limited to once per 30 seconds; too soon replies Save is rate limited. Try again in {n}s. Pressing it with nothing staged replies No draft changes to save.

Discard draft

Drops all staged changes and replies Draft discarded.

Refresh

Redraws the menu with the latest saved state.

Price spike settings screen

Toggle all price spikes

Stages a flip of the master switch in the draft.

Sell Rise on / Buy Drop on

Direction toggles; the label always shows the current state (on or off) and pressing stages the opposite.

Window rows, for example 30s on + Edit threshold

Each of the six windows gets a row: the left button toggles the window in the draft, the right button opens a numeric prompt for the threshold. When a window is off, the right button reads Edit threshold (off) and pressing it answers {window} is off. Turn it on before editing the threshold. Turn the window on first, then edit.

Hidden tokens / Hide token, Hidden CEX / Hide CEX, Hidden chain / Hide chain

The left buttons open the price-spike hidden list screens; the right buttons start a text prompt to add an entry. Mute changes from these prompts apply immediately, they are not part of the draft.

Back

Returns to the root menu. The draft survives navigation.

New entry settings screen

The first button's label flips with state (Turn off new entries while on). Edit minimum spread opens a numeric prompt with the text Send the new entries minimum spread as a percentage number., the example Example: 7.5, and Send /cancel to stop.

Numeric input prompts

Non-numeric input replies Please send a valid number. and re-shows the prompt; out-of-range values reply with the validation message (for example Price spike threshold must be >= 10) and re-prompt. A successful value lands in the draft, the settings screen redraws, and nothing is live until you press Save changes.

Text input prompts (hide and unhide)

The Hide token, Hide CEX, and Hide chain buttons prompt for one exact value, for example Send one exact token symbol to hide from new-entry alerts. with Example: SOL and Send /cancel to stop. These prompts attach a one-time reply keyboard with a Cancel button and an input placeholder such as Exact token symbol (e.g. SOL), Exact CEX id (e.g. binance), or Exact chain id (e.g. polygon). Unlike toggles and thresholds, hide and unhide actions from these prompts apply immediately and return you to the relevant hidden list screen.

Hidden list screens

The CEX and chain variants swap the action buttons for Hide CEX / Unhide CEX and Hide chain / Unhide chain. The price-spike versions of these screens use Back to price spikes instead of Back to new entries.

Mute lists

There are exactly six mute lists, and they are all independent of one another. The new-entry lists and the price-spike lists never share entries: muting a token for new entries does not silence its spikes, and the price-spike lists start empty rather than inheriting anything.

How muting changes what you receive: a muted token removes the entire message for that asset. A muted CEX or chain does not drop the message; it removes the matching venue or chain rows, so the alert is rebuilt without them.

You can manage every list from three places, and they all write to the same data:

• The web card: the Mute lists groups in Alert rules on My Page (staged, applied on Save changes).
• Bot commands: the slash commands in the table above (applied immediately).
• Inline menus: the Hide token / Hide CEX / Hide chain prompts and hidden list screens (applied immediately).

Pausing, breaking, and recovering

Every way delivery can stop, and the exact way back:

Security model

Troubleshooting

Exact messages you may encounter, what they mean, and what to do: