DEV Community

Cover image for wallet-alert-bot: Telegram and Discord alerts for Solana wallets
Abdeldjalil Chougui
Abdeldjalil Chougui

Posted on Originally published at abdeldjalilchougui.biz

wallet-alert-bot: Telegram and Discord alerts for Solana wallets

Some wallets are worth watching: a project treasury, a payout wallet, the account that receives customer payments on a test deployment. You want to know when tokens arrive or leave, without keeping an explorer tab open and refreshing it.

The first version of such a watcher is short. Open a websocket, subscribe to the wallet, print what comes in. Then the real problems appear. The socket drops and nobody notices. A notification is missed during a reconnect. The same transaction arrives twice. Every vote or dust transfer triggers a message until people mute the channel. And the chat API answers 429 when several alerts go out at once.

wallet-alert-bot is a small bot that handles those cases. It watches Solana wallets and posts an alert to Telegram, Discord, or both, when something relevant happens. An alert names the wallet by its label and short address, says whether the movement is incoming or outgoing, lists the amount per mint, lists the programs that were invoked, and ends with an explorer link for the right cluster.

The README is direct about what it is not. The project is not audited. It is devnet and testnet by default: it refuses mainnet RPC URLs unless you set allowMainnet: true. The bot is read-only, so it never holds keys and never signs. And alerts are informational: they can be late or missed, so do not use it as a security system.

What it does

Websocket first. On connect, the bot sends one logsSubscribe { mentions: [wallet] } per wallet and maps each subscription id back to its wallet. For each logsNotification, it fetches the transaction with getTransaction in jsonParsed form, and works out what changed for the watched wallet.

Polling as a fallback. getSignaturesForAddress(wallet, { until: lastSeen }) runs every pollIntervalMs while the socket is down. While the socket is up it still runs, four times less often, as a safety net for missed notifications. The first poll only sets the cursor, so restarting the bot does not replay the wallet's history into your channel.

Reconnect with backoff. When the websocket closes, the bot reconnects with exponential backoff and jitter: the delay starts at initialMs and doubles up to maxMs. It resets after a successful connection.

Dedupe. A (wallet, signature) key is processed once per dedupeTtlMs, whether it arrives over the websocket, from polling, or from both.

Filters. They are applied in a fixed order:

  1. failed transactions are dropped, unless includeFailed is set;
  2. excludePrograms removes transactions that involve programs you do not care about, such as Vote;
  3. programs keeps only transactions where one of the listed programs was invoked;
  4. thresholds apply last: minSol, minToken per mint or "*" for any mint, and direction (in, out or any).

The fee is not counted as an outgoing transfer, so a transaction where the wallet only paid fees never alerts.

Sinks. Telegram uses sendMessage with HTML escaping. Discord uses a webhook embed with allowed_mentions: none, so text inside a transaction cannot ping anyone. Both retry on HTTP 429 using the retry_after value the API returns.

How to use it

Clone the repository, build it, and copy the example config:

git clone https://github.com/AbdeldjalilChougui/wallet-alert-bot
cd wallet-alert-bot
pnpm install && pnpm build
cp examples/config.example.yaml config.yaml      # gitignored
export TELEGRAM_BOT_TOKEN=... TELEGRAM_CHAT_ID=... DISCORD_WEBHOOK_URL=...
node dist/main.js config.yaml                   # run
node dist/main.js config.yaml --dry-run         # print alerts instead of sending
node dist/main.js config.yaml --check <signature> <wallet>   # one-off: filter decision + message
Enter fullscreen mode Exit fullscreen mode

The config file is YAML. This is the example that ships with the project:

rpcUrl: https://api.devnet.solana.com
commitment: confirmed
pollIntervalMs: 15000         # polling fallback while the websocket is down (x4 while it is up)
dedupeTtlMs: 21600000         # 6 h
backoff: { initialMs: 1000, maxMs: 60000 }
wallets:
  - address: 9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin
    label: treasury
filters:
  minSol: 0.1                 # ignore dust
  minToken:
    "*": 1                    # any mint: at least 1 token
  direction: any              # in | out | any
  excludePrograms:
    - Vote111111111111111111111111111111111111111
  programs: []                # e.g. only alert when your program is involved
  includeFailed: false
telegram:
  botToken: ${TELEGRAM_BOT_TOKEN}
  chatId: ${TELEGRAM_CHAT_ID}
discord:
  webhookUrl: ${DISCORD_WEBHOOK_URL}
Enter fullscreen mode Exit fullscreen mode

Secrets are only ever read from ${ENV_VARS} in the config, so the file itself can be shared. A sink whose variable is unset is disabled. With no sinks configured at all, the bot runs as a dry run and prints alerts instead of sending them.

Two flags help while tuning filters. --dry-run prints every alert to the terminal. --check <signature> <wallet> takes one known transaction and shows the filter decision and the message it would produce, which is the quickest way to learn why a transaction did or did not alert.

Things to know

  • Not audited, and not a security system. Alerts can be late or missed. Use them to stay informed, not to protect funds.
  • Mainnet is refused by default. You have to set allowMainnet: true yourself, and the caveats above still apply.
  • One process, in-memory state. On restart, polling resumes from the newest signature. Anything that happened while the bot was stopped is not reported.
  • One subscription per wallet. logsSubscribe with mentions accepts one address per subscription, so N wallets use N subscriptions, and public RPCs limit how many you can open.
  • Display precision. Token amounts use JavaScript numbers for display, so precision is lost beyond about 15 significant digits.
  • What was tested. There are 19 tests, and none of them use the network. They cover activity extraction, filters and formatting on committed fixture transactions: four synthetic jsonParsed transactions (incoming SOL, dust, vote, failed) and one real devnet token payout captured once. They cover Telegram HTML escaping, the Discord payload, and both sinks with a mocked fetch, including the 429 retry_after path. They cover config parsing with env expansion and the mainnet refusal, the dedupe TTL and cap, and the backoff schedule. The Watcher itself is tested with a fake websocket and fake timers: subscription mapping, duplicate notifications, skipped transactions, reconnect delays, slow and fast polling intervals, and polling cursors with websocket and poll dedupe.
  • One live run. The bot was also run against devnet for 25 seconds in --dry-run. It subscribed over the websocket and printed three real token-transfer alerts. That is a short check, not a long-running test.

Why I built it

Watching a wallet looks like a twenty-line script, and the first twenty lines do work. What takes time is everything around them: a websocket that closes without warning, notifications lost in the gap, duplicates when two sources report the same signature, and a channel that fills with noise until nobody reads it.

I wanted those parts solved once and tested without a network, so the behaviour is known before the bot runs against a cluster. That is why the watcher is tested with a fake websocket and fake timers, and why the filters run in a documented order. A filter you can reason about, plus a --check command that explains a single transaction, makes it possible to tune alerts until the channel only gets messages worth reading.

Keeping the bot read-only was a design rule from the start. A process that only needs to observe should never be given a key.

Get the code

The bot, the example config, the fixtures and the tests are on GitHub: https://github.com/AbdeldjalilChougui/wallet-alert-bot. It is MIT licensed. Issues and pull requests are welcome.


Originally published at abdeldjalilchougui.biz.

Top comments (0)