Building a Telegram trading bot

Privy can power Telegram trading bots that trade on behalf of users. These bots can be controlled via commands in the Telegram app, natural language commands to LLMs, or purely agentic trading. At a high-level, there are two approaches to building a Telegram trading bot:

Bot-first: Users first create and interact with their wallet via Telegram commands to the bot in the Telegram app itself. Later, the user can “claim” their wallet by logging into a web or mobile app to send transactions and export their private key from that interface. Users can also eventually revoke permissions for the bot to transact on their behalf.
App-first: Users first create and interact with their wallet by logging into a web or mobile app with their Telegram account, or logging in with an alternate method and then linking their Telegram account. They can send transactions and export their private key from the app, and can also grant permissions to the bot to transact on their behalf.

Follow the guide below to learn how to build Telegram trading bots with Privy. Make sure to follow the appropriate section depending on if your app uses the bot-first or app-first setup.

Configuring your bot

To start, we’ll cover the basics of creating and setting up your Telegram bot that can send transactions.

Creating a bot

First, create a new Telegram bot if you haven’t already following the instructions below.

Show how to create a new bot

Create a new bot

Create a new chat with @BotFather
Create a new bot with the command /newbot
Choose a name for your bot
Choose a username for your bot
Safely store your bot token. It should be in the format of, BOT_ID:BOT_SECRET

Set up Node.js Telegram bot server

For this example, we will use Node.js to create a bot server, and specifically use the node-telegram-bot-api library.
Install the Telegram bot API library:

npm install node-telegram-bot-api

Create a new file called bot.js and add the following code:

const TelegramBot = require('node-telegram-bot-api');
const {PrivyClient} = require('@privy-io/server-auth');

// replace the value below with the Telegram token you receive from @BotFather
const token = 'YOUR_TELEGRAM_BOT_TOKEN';

// Create a bot that uses 'polling' to fetch new updates
const bot = new TelegramBot(token, { polling: true });

const privy = new PrivyClient('insert-app-id', 'insert-app-secret');

Your app is now ready to receive messages from Telegram!

Setting up commands

Next, enable your users to interact with the bot via the Telegram app by configuring your bot to respond to Telegram commands. Use the bot’s onText interface to register Telegram commands and the actions they should execute. For example, you might register a /createwallet command for users to create wallets via the Telegram app, or a /transact command for users to be able to transact.

Show how to set up a command

You can create a new command via the bot’s onText method like so:

bot.onText(/\/insert_command_name/, async (msg) => {
    await privy.walletApi.ethereum.sendTransaction(...)
});

As an example, you might have a /transact command that allows users to send transactions like so.

bot.onText(/\/transact/, async (msg) => {
  // Custom logic to infer the transaction to send from the user's message
  const transaction = getTransactionDetailsFromMsg(msg);

  // Get the Privy user object using the user's Telegram user ID (`msg.from.id`)
  const user = await privy.getUserByTelegramUserId(msg.from.id);

  // Search the user's linked accounts for their wallet
  const wallet = user?.linkedAccounts.find(
    (account): account is WalletWithMetadata =>
      account.type === 'wallet' && account.walletClientType === 'privy'
  );

  // Get the wallet ID from the wallet
  const walletId = wallet?.id;

  if (!walletId) throw new Error('Cannot determine wallet ID for user');

  // Send transaction
  await privy.walletApi.solana.sendTransaction({walletId, ...transaction});
});

Associating your user’s wallet ID with their Telegram user ID

In order for the Telegram bot to interact with a user’s wallet, the bot must be able to determine what the user’s wallet ID is.

Show how to get the wallet ID for the Telegram user

Within the command, you can access the user’s Telegram user ID via the message’s from.id property. You can then use the Privy client’s getUserByTelegramUserId method to get their full Privy user object, as well as their wallet ID.

import type {WalletWithMetadata} from '@privy-io/react-auth';

bot.onText(/\/log_wallet_id/, async (msg) => {
  // Get the Privy user object using the user's Telegram user ID (`msg.from.id`)
  const user = await privy.getUserByTelegramUserId(msg.from.id);

  // Search the user's linked accounts for their wallet
  const wallet = user?.linkedAccounts.find(
    (account): account is WalletWithMetadata =>
      account.type === 'wallet' && account.walletClientType === 'privy'
  );

  // Get the wallet ID from the wallet
  const walletId = wallet?.id;
  console.log('Wallet ID', walletId);
});

Bot-first setup

At a high-level, the bot-first setup works by creating a wallet associated with your user’s Telegram handle, allowing them to transact with the wallet via commands made to your bot, and enabling users to claim their wallet or control it from a web or mobile app if desired. Follow the steps below for more concrete guidance.

Create a wallet associated with your user

First, create a user in Privy and a wallet owned by that user. To allow your bot to transact on behalf of the user, create an authorization key and add it as an additional signer on the wallet.

bot.onText(/\/start/, async (msg) => {
    const telegramUserId = msg.from.id;
    // Create Privy user with Telegram user ID
    const privyUser = await privy.importUser({
        linkedAccounts: [{
            type: 'telegram',
            telegramUserId
        }]
    });

    // Create wallet with user owner and the bot as an additional signer
    const wallet = await privy.walletApi.createWallet({
        chainType: 'solana',
        owner: {
            userId: privyUser.id
        },
        signers: [{
            signerId: 'id-of-authorization-key-from-dashboard'
        }]
    });
});

Send transactions with the wallet

Next, allow the user to transact with commands send to the bot. You might implement a /transact command that takes input on the user to transact on their behalf.

Make sure to configure your Privy client with the private key for the authorization key you created in the Dashboard.

import type {WalletWithMetadata} from '@privy-io/server-auth';

bot.onText(/\/transact/, async (msg) => {
    // Custom logic to infer the transaction to send from the user's message
    const transaction = getTransactionDetailsFromMsg(msg);

    // Determine user's wallet ID from their telegram ID
    const user = await privy.getUserByTelegramUserId(msg.from.id);
    const wallet = user?.linkedAccounts.find((account): account is WalletWithMetadata => (account.type === 'wallet' && account.walletClientType === 'privy'));
    const walletId = wallet?.id;

    if (!walletId) throw new Error('Cannot determine wallet ID for user');

    // Send transaction
    await privy.walletApi.solana.sendTransaction({walletId, ...transaction});
});

Allow the user to claim their wallet and use it from your app

If you’d like users to be able to claim their wallet via a web or mobile app, configure your web app with Privy’s React SDK or your mobile app with Privy’s React Native SDK and enable Telegram login.Then, when users login to your app via Telegram, they can send transactions or export their private keys.

App-first setup

At a high-level, the app-first setup works by creating a wallet associated with your user when they login to your app with Telegram (or alternatively, link a Telegram account) and then adding a session signer to the wallet to allow the bot to transact on behalf of your user. Follow the steps below for more concrete guidance.

Instrument your app with Privy

If you have not already done so, instrument your web app with Privy’s React SDK or your mobile app with Privy’s React Native SDK and enable Telegram login.

Create wallets for your users

When your users login to your app with Telegram or link a Telegram account, create a wallet for them. Store a mapping between the ID of the created wallet and the user’s Telegram ID so that you can determine the user’s wallet within the bot’s code.

Add a session signer to the user's wallet

After the wallet has been created, add a session signer to the user’s wallet, which the bot can use to transact on the user’s behalf.Make sure to store the private key(s) associated with your signer ID securely in your server. Your Telegram bot or agent will need this to execute transaction requests.Follow the linked quickstart below to learn how to add a session signer to the user’s wallet.

Session signer quickstart

Request access to user wallets with session signers.

Execute actions with your signer

Finally, the bot can use the session signer to execute transactions on the user’s behalf when prompted. For instance, you might implement a /transact command that takes input on the user to transact on their behalf.

Make sure to configure your Privy client with the private key for the session signer (authorization key) you created in the Dashboard.

bot.onText(/\/transact/, async (msg) => {
    // Custom logic to infer the transaction to send from the user's message
    const transaction = getTransactionDetailsFromMsg(msg);

    // Determine user's wallet ID from their Telegram user ID
    const user = await privy.getUserByTelegramUserId(msg.from.id);
    const wallet = user?.linkedAccounts.find((account): account is WalletWithMetadata => (account.type === 'wallet' && account.walletClientType === 'privy'));
    const walletId = wallet?.id;

    if (!walletId) throw new Error('Cannot determine wallet ID for user');

    // Send transaction
    await privy.walletApi.solana.sendTransaction({walletId, ...transaction});
});

Sign requests

Sign requests to the Privy API with your session signer.

EVM

Take actions on EVM chains with Privy’s NodeJS SDK or REST API.

Solana

Take actions on Solana with Privy’s NodeJS SDK or REST API.

Recipes

​Configuring your bot

​Creating a bot

​Setting up commands

​Associating your user’s wallet ID with their Telegram user ID

​Bot-first setup

​App-first setup

Session signer quickstart

Sign requests

EVM

Solana

Configuring your bot

Creating a bot

Setting up commands

Associating your user’s wallet ID with their Telegram user ID

Bot-first setup

App-first setup