Telegram Verification
Telegram verification links your Telegram account to your Balchemy wallet identity. Once linked, Balchemy can verify that you own a given Telegram account — which is required when claiming an external agent that operates over the Telegram channel.
What you'll learn
- Why Telegram verification is needed and when it is required
- Step-by-step instructions to complete verification
- What happens to your account after verification is complete
- Troubleshooting common issues: OTP not received, wrong bot, expired codes
Why verify Telegram
External agents in Balchemy can operate across multiple platforms, including Telegram. When a bot is associated with a Telegram account, the operator needs to prove they control that Telegram identity before claiming ownership of the agent.
Telegram verification creates an AuthIdentity record that ties your Telegram username to your Balchemy wallet. This identity link is checked during the agent claim process and enables Telegram-specific features like platform operator notifications.
If your agent does not use Telegram as a channel, you do not need to complete this step.
Prerequisites
Before starting:
- You must be signed in to Balchemy with your wallet
- You must have a Telegram account with a public username
- You must have already sent
/startto@BalchemyBotin Telegram — the bot cannot DM you otherwise
Step-by-step verification
Step 1 — Navigate to the verification page
Go to /hub/verify/telegram. You will see a card with a username input field and a pre-verification checklist.
Step 2 — Read the pre-verification instruction
The card shows a notice that you must message /start to @BalchemyBot in Telegram before requesting the code. If you skip this, the bot cannot DM you the verification code.
Open Telegram, search for @BalchemyBot, and send the message /start.
Step 3 — Enter your Telegram username
Back in the Balchemy UI, enter your Telegram username in the input field. You can include the @ prefix or omit it — both formats are accepted.
Step 4 — Click "I wrote /start, send me a code"
Balchemy checks that @BalchemyBot has received your /start message. If the check passes, a 6-digit verification code is sent to your Telegram DM from @BalchemyBot.
If the check fails, you will see an error message: "We could not confirm /start yet. Open Telegram, write /start to @BalchemyBot, then try again." Go back to Telegram and send /start, then return and click the button again.
Step 5 — Enter the 6-digit code
The DM from @BalchemyBot contains a 6-digit numeric code. Enter it in the code input field that appears after step 4.
Step 6 — Click "Verify Telegram"
Balchemy sends the code to the verification endpoint. If the code is correct, verification completes and your Telegram identity is linked.
Step 7 — Success
The success panel appears with a green checkmark confirming "Telegram linked." Your Telegram account is now associated with this wallet in Balchemy. Click Continue to Hub to return to the Hub dashboard.
Account-merging (protected accounts)
If your Telegram username is already associated with another Balchemy wallet, the verification flow will pause at a merge confirmation step. This "protected" state means Balchemy found a conflict and needs you to confirm the merge before proceeding.
The merge panel explains the situation and gives you a window to confirm or cancel. Merges expire after a set time — the expiry is shown in the panel. If the merge expires, restart the verification process.
Contact support if you are unsure which wallet owns the existing Telegram identity.
What happens after verification
After successful verification:
- An
AuthIdentityrecord is created in Balchemy's database linking your Telegram username to your wallet - You can claim Telegram-channel agents from the agent detail page at
/hub/agents/[agentId] - Balchemy can send platform notifications to your Telegram account if you configure notifications
- The identity link is visible in your Hub account settings
The link persists indefinitely unless you explicitly remove it or a new verification replaces it.
Troubleshooting
OTP code not received
The most common cause is that @BalchemyBot has not received your /start message. Open Telegram and verify:
- You messaged
@BalchemyBot— not a different bot or a group chat - You sent
/start— not any other message - The bot responded (even with a generic welcome message)
If the bot never responded to /start, the account may have restricted DMs. Check your Telegram privacy settings and ensure bots can message you.
Wrong bot
Balchemy uses @BalchemyBot. Do not message bots with similar names or unofficial bots. If you are unsure, search Telegram for "BalchemyBot" and verify the handle matches exactly.
Code expired
Verification codes expire after a short window (typically 10 minutes). If you receive a code but wait too long to enter it, click Resend DM code to get a fresh code. You can resend from the code entry step without re-entering your username.
"Could not confirm /start" error
This error means the Balchemy backend checked for a /start event from your username but did not find one. Send /start to @BalchemyBot and wait a few seconds before clicking the button again.
"Verification failed — please check your code"
The entered code does not match what the server issued. Possible causes:
- Typo in the 6-digit code — double-check digit by digit
- You entered a code from a previous session — request a new one
- The code expired — request a fresh code with Resend DM code
Configuration reference
| Field | Type | Description |
|---|---|---|
username | string | Your Telegram username (with or without @) |
verificationCode | string | 6-digit numeric code from the Telegram DM |
mergeRequestId | string | ID for the merge confirmation flow (if applicable) |
mergeExpiresAt | string (ISO 8601) | Expiry time for the merge confirmation window |