ThunderTip
ThunderTip brings small Lightning payments into Telegram chats by asking each user to connect a wallet through Nostr Wallet Connect. It is non-custodial in the narrow funds sense, but the bot host, database, encryption key, Telegram identity mapping and wallet permissions still deserve a careful read.
What ThunderTip really is
ThunderTip is a Telegram bot that lets people send small Lightning payments inside Telegram chats without the bot keeping a shared balance. The official site calls it a fast, easy-to-use, non-custodial Telegram tip bot. The GitHub repository description is more technical: it facilitates Lightning transactions inside Telegram and connects to Lightning wallets through Nostr Wallet Connect.
That distinction is the whole product. ThunderTip is not a Lightning wallet. It is not a Nostr social client. It is not a relay, mint or exchange. It is a bot layer that maps Telegram users to wallet connection strings, asks the receiver wallet to create an invoice and asks the sender wallet to pay that invoice. Telegram is the chat surface; NWC is the wallet control rail.
The result is useful because Telegram groups already host Bitcoin communities, support channels and local circles. A tip bot can turn a useful answer, a design contribution or a small favor into an immediate sats payment. ThunderTip's pitch is that this should happen from each user's own wallet rather than from a custodial balance kept by the bot.
The result also needs careful language. Non-custodial means the bot does not hold a pooled balance for users. It does not mean the bot has no power. A connected NWC URI can authorize wallet actions within its permissions, and the bot server must be able to read that URI when it needs to make or pay invoices. Treat ThunderTip as a coordinator with access, not as a harmless sticker pack.
The Telegram user flow
The visible flow is simple. A user starts a conversation with the Telegram bot, opens `/connection`, chooses whether to create, update or delete a connection, and sends an NWC connection URI in a private chat with the bot. The site explicitly tells users not to treat the URI casually and says NWC lets users set limits such as duration and spendable amount.
Once connected, the sender can use `/tip
The receiver must be connected as well. The transaction helper initializes both sender and receiver from Telegram user IDs, then rejects the payment if either side has no NWC connection. That is an important limit for group operators. ThunderTip is not a magic one-sided payment rail where the sender can pay anyone with a Telegram account. The receiver needs a wallet connection that can make an invoice.
The bot also exposes `/balance`, `/nwc`, `/help` and `/start`. The balance command calls the sender's connected wallet provider and reports balance and currency. The NWC command explains the wallet-connection idea. The help command documents the basic command shapes. For an end user, this makes ThunderTip feel like a Telegram utility; under the hood, it is a wallet automation client.
What NWC changes
Nostr Wallet Connect is the reason ThunderTip can be non-custodial in the funds sense. NIP-47 describes a way for an app and a wallet service to communicate through encrypted Nostr events. The app gets a connection URI, sends requests, and the wallet service decides whether methods such as paying invoices, making invoices or reading balance are allowed.
For ThunderTip, this means the bot does not need to own a Lightning node account for all users. Instead, each user gives the bot a connection to that user's own wallet service. In the source, the `User` class creates an Alby SDK NWC provider from the decrypted `nostrWalletConnectUrl` and then calls methods such as `makeInvoice`, `sendPayment` and `getBalance`.
This is a big improvement over classic custodial chat bots, where users deposit funds into a shared bot account and hope the operator stays honest and solvent. With NWC, the wallet can remain the user's wallet. The bot can request actions, but the wallet service can enforce budgets, expiration, permissions and revocation.
The important reader move is to look at both sides. ThunderTip has to handle Telegram commands and stored connection strings correctly. The wallet must enforce the connection correctly. If your NWC connection allows broad spending forever, a non-custodial bot can still become a broad spend surface. If your connection is small, narrow and revocable, the same bot becomes much more reasonable.
How a tip is executed
The transaction code is plain enough to follow. ThunderTip creates user objects for the receiver and sender. It checks that the sender is not tipping themselves, that the amount parses cleanly, that both users have wallet connections and that the sender has enough balance according to the connected wallet's reported balance. Only after those checks does it ask wallets to act.
The receiver side comes first. The receiver wallet is asked to create an invoice for the requested amount with a memo describing the tip. If that invoice cannot be created, the bot returns a receiver connection error. This is why a receiver needs more than a public Lightning address. In ThunderTip's model, the receiver wallet is actively asked through NWC to make an invoice.
The sender side then pays. The sender provider is enabled, the sender balance is checked, and the sender wallet is asked to pay the invoice payment request. If the payment succeeds, the chat gets a message telling the group who sent sats to whom. If payment fails, the bot can distinguish sender connection problems, insufficient funds and other command-level errors.
There are still normal payment edges. Balance can change between check and payment. Routing fees can matter depending on wallet behavior. A receiver wallet may create an invoice that the sender wallet cannot route. A Telegram message can be deleted or a username can change. The code is careful enough to avoid obvious mistakes, but Lightning payments are still external actions with real-world failure modes.
Sender and receiver permissions
ThunderTip needs different wallet abilities for different users. A sender needs permission to pay invoices, and the balance command needs permission to read balance. A receiver needs permission to make invoices. If a user wants to both send and receive, the connection needs both sides of that behavior. That is the detail many casual NWC explanations skip.
The site tells users to define send limits and shows wallet logos such as Alby, Mutiny, Coinos, Lifpay and LNbits. That is a good starting message, but users should be more specific. For a Telegram tip bot, create a dedicated connection just for the bot. Give it a small spend limit. Set an expiration if the wallet supports it. Revoke it when you leave the group or stop using the bot.
Receivers should also think carefully. If your wallet supports an invoice-only or receive-limited connection, use that for receive-only use. If it does not, understand what the connection can do. A receiver connection that can also pay invoices may be more powerful than a receiver expects, especially if the same URI is stored for both tipping and receiving.
The public Telegram chat should never see the NWC URI. ThunderTip enforces the connection flow in private chat and throws a specific error when a connection request happens in a group. That is an important design choice. An NWC URI is a live authorization string, not a profile address. Paste it into the wrong place and you should revoke it.
The database and encryption model
The source uses Supabase for user storage. A user row stores the Telegram user ID, username and encrypted NWC connection link. When a user is loaded, the `User` class fetches that row, decrypts the connection string and creates the NWC provider. This lets the bot remember users across Telegram sessions and group messages.
ThunderTip's own site says connection URIs are stored with AES-256 encryption. The code shows the specific shape: it derives a 32-byte key from `PASSWORD + userID` with SHA-256, creates a random 16-byte IV, uses AES-256-CTR, and stores the IV and ciphertext together. That is better than saving plain connection strings in the database.
It is not the same as removing host trust. The bot process needs the environment password and the user's Telegram ID to decrypt the URI. Anyone who compromises the bot host, environment variables or code path may be able to recover active connection strings. AES-CTR also does not add an integrity tag by itself, so deployment security and database access controls matter.
This is the correct way to read the promise. Encryption at rest reduces accidental exposure and database-only leakage. It does not make an active service unable to use or misuse the connection. The safest user behavior is still to scope the NWC connection tightly, keep balances small, rotate if suspicious and never reuse a high-authority wallet URI across bots.
Telegram identity is convenient but soft
Telegram usernames are useful because people recognize them in chat, but they are not a cryptographic identity layer. ThunderTip stores usernames lowercased and can look up a receiver by username. It also updates the sender username when a tip is sent if Telegram reports a current username. That is practical, but it is not the same as a stable Nostr public key.
The reply-tip flow is usually safer because Telegram gives the bot the replied message's sender ID. A username command depends on the username mapping ThunderTip has stored. If a person changes their username, if a username is reassigned, or if a receiver has not used the bot recently enough to update their row, the mental model can drift from the chat's social expectation.
For small tips, this may be acceptable. For larger payments, do not treat a Telegram username as enough proof. Ask the person to confirm, send a tiny test amount, or use a direct wallet invoice outside the group. ThunderTip is built for quick social payments, not formal settlement between strangers.
Group privacy is also limited. The payment announcement can show who tipped whom. Telegram sees the chat context. The bot operator sees command timing and Telegram IDs. The connected wallets see invoice and payment activity. NWC content is encrypted over Nostr relays, but the surrounding Telegram and wallet metadata still exists.
The bot host is part of the trust boundary
ThunderTip is open source, which helps readers inspect its behavior. The repository is a TypeScript project using grammY for Telegram bot handling, Alby SDK for NWC/WebLN style wallet calls, Supabase for storage and Express for a simple server process. The package file lists an MIT license, and the GitHub metadata showed active code pushed as recently as January 2026.
Open source does not prove the deployed bot matches the repository, and it does not remove hosting risk. The public bot at `t.me/ThunderTip_bot` is a service. Users interact with the running deployment, not just the code. That deployment has environment variables, Supabase credentials, a bot token, an encryption password and operational logs.
The owner path is visible in the source too. Required environment variables include `BOT_TOKEN`, `SUPABASE_URL`, `SUPABASE_KEY`, `PASSWORD`, `OWNER_ID` and `PORT`. The bot catch handler can notify the configured owner when errors occur. Those are normal service details, but they are also reminders that a human-operated server sits between Telegram and the wallet connections.
Use ThunderTip the way you would use any small open-source payment coordinator. Prefer tiny limits. Prefer a dedicated connection. Confirm the official bot handle from the project site or repository, because Telegram bot impersonation is easy. If you self-host it, protect the bot token, Supabase key and password as payment infrastructure secrets.
Where it fits in the NWC map
ThunderTip appears in the Nostr Wallet Connect ecosystem as a tipping bot rather than as a wallet backend. The getAlby awesome-nwc list places it near other social payment bots, and external NWC posts describe Telegram communities experimenting with it. That is the right classification: it is an application that consumes wallet permissions.
This is different from Alby Hub, LNbits, Coinos or other wallet services. Those systems may generate NWC connections and authorize wallet methods. ThunderTip receives such a connection and uses it to perform a narrow social job. If you are drawing the architecture, ThunderTip sits between Telegram and the wallet service, with NWC as the authorization bridge.
It is also different from Zapper. Zapper is a browser micro-app for Nostr zaps and Lightning payment handoffs. ThunderTip is a Telegram bot for chat-native tips. Both can ask a wallet to pay, and both benefit from narrow permissions, but ThunderTip also stores user connection strings because a bot has to remember who in a Telegram group is connected.
The product is therefore most useful where Telegram is already the community venue. A Bitcoin design group, local meetup, support channel or builder chat can tip directly in the conversation. If the same people are primarily on Nostr clients, a Nostr-native zap flow may be cleaner. ThunderTip's strongest context is Telegram-first coordination with NWC behind it.
What can go wrong
The first failure is over-permission. If a user grants a connection with no practical budget or expiration, any bug, compromise or malicious deployment change has more room to hurt. NWC is powerful because it lets apps act on wallets. That power needs wallet-side limits, not only app-side promises.
The second failure is leaked connection strings. ThunderTip tries to keep `/connection` in private chat, but users can still paste secrets into the wrong place, screenshot them, reuse them or store them in unsafe notes. If a URI is ever exposed, revoke it. Do not debate whether the leak was probably harmless.
The third failure is receiver confusion. A sender may believe they are tipping a person in a group, but the bot can only pay the receiver connection associated with the Telegram ID or username it resolves. Usernames can move. People can impersonate names. The safest larger payment remains a direct confirmation and a test transaction.
The fourth failure is service drift. The bot may be down, the Supabase project may have issues, a wallet may change NWC behavior, a Telegram Bot API change may affect commands, or the deployed service may lag behind the repository. Small open-source tools can be excellent, but they need live verification before money moves.
How to test it safely
Start with the official site and bot handle. Use the link from the site or repository, then open a private chat with the bot. Do not begin in a group. Create a new NWC connection from a wallet you control, with a tiny budget and an expiration if your wallet supports it. Label it so you can find and revoke it later.
Connect one sender and one receiver wallet with tiny limits. Ask the receiver to connect first, then send a very small tip through a direct username command. Check the sender wallet, receiver wallet and Telegram chat. Then test the reply flow, because reply tips are the form people will actually use in group conversations.
Run the negative cases too. Try tipping without a receiver connection. Try a zero amount. Try a username that is not connected. Try `/connection` from a group and confirm the bot refuses to collect the URI there. These checks tell you whether the deployment behaves like the source code suggests.
Finally test revocation. Revoke the NWC connection in the wallet and try another tiny action. A wallet connection that cannot be cleanly revoked is not a connection you should give to a chat bot. If revocation works and the budget is small, ThunderTip becomes a much more comfortable experiment.
Operator notes for self-hosting
The repository is small enough for a technical operator to understand before deploying. It needs a Telegram bot token, Supabase URL and key, an encryption password, an owner ID and a port. It starts an Express server, configures grammY sessions and conversations, registers commands and starts polling. There is no hidden blockchain node inside the bot.
The serious deployment work is secret handling. `BOT_TOKEN` controls the Telegram bot. `SUPABASE_KEY` controls database access. `PASSWORD` helps decrypt stored connection URIs. If any of those leak, rotate them and assume wallet connections may need revocation. Logs should not print NWC URIs, invoices or full exception payloads that expose secrets.
Database rules matter too. The bot stores a row per Telegram user with connection data and username. Limit who can read and write that table. Backups should be protected because encrypted connection strings remain useful to an attacker who also finds the password. If you cannot protect the database, do not store live wallet authorizations there.
A self-hosted ThunderTip can be appropriate for a closed community if the operator is known and the wallet permissions are tight. It is a poor fit for anonymous large groups with high-value wallets. The best operator posture is boring: clear bot handle, clear limits, small default budgets, documented revocation and a habit of testing after upgrades.
The bottom line
ThunderTip is a useful example of what Nostr Wallet Connect unlocks outside Nostr social clients. Telegram remains the chat room. Lightning remains the payment network. NWC gives the bot a way to request wallet actions without taking custody of user balances. That is a good design direction for small community payments.
Its strongest claim is not that it removes trust. Its strongest claim is that it moves trust to a better shape. Instead of depositing sats into a bot wallet, users can connect their own wallets with limits. Instead of one custodian balance, there are many revocable wallet permissions. That is progress, but only when users actually use the limits.
The page to keep in mind is simple. Sender and receiver both connect wallets. The receiver wallet makes an invoice. The sender wallet pays it. The bot stores encrypted connection URIs and coordinates the chat command. Telegram identity is convenient but not cryptographic. The bot host and database are part of the security story.
If you use ThunderTip, begin with tiny amounts and a dedicated NWC connection. If you run ThunderTip, treat the bot token, Supabase credentials and encryption password as sensitive payment infrastructure. The tool is promising precisely because it is small and readable. Keep the permissions small and readable too.
Sources worth opening
Open the ThunderTip site first, then read the repository metadata, package file, user, command, conversation and transaction source files. Compare those with NWC, NIP-47, Alby SDK, Telegram Bot API, grammY and Supabase references before trusting the bot with a wallet connection.
- ThunderTip official site
- ThunderTip official logo image
- ThunderTip Telegram bot
- ThunderTip GitHub repository
- ThunderTip GitHub API metadata
- ThunderTip repository tree
- ThunderTip package file
- ThunderTip main bot entry
- ThunderTip user and encryption source
- ThunderTip command handlers
- ThunderTip conversation handlers
- ThunderTip connection conversation source
- ThunderTip transaction source
- ThunderTip error classes
- ThunderTip required environment constants
- ThunderTip Telegram bot config
- ThunderTip Supabase config
- Alby JavaScript SDK
- grammY bot framework
- grammY conversations plugin
- Supabase documentation
- Telegram Bot API
- Telegram bot features
- getAlby awesome-nwc
- getAlby awesome-nwc raw README
- Nostr Wallet Connect site
- Nostr Wallet Connect docs
- NIP-47 raw markdown
- Stacker News ThunderTip discussion
- Damus mirror of NWC ThunderTip note
- Nostr.com NWC profile
- Nostr Archives NWC profile mirror
- BitcoinApps directory
- ThunderTip favicon
- ThunderTip Telegram icon asset
- ThunderTip NWC logo asset
