Telegram Bot SDK

The Plaidly Telegram SDK lets you accept crypto payments directly in your Telegram bot — no redirect to an external checkout page.

Installation

Not yet published to the package registry

plaidly-sdk-tg is not yet published to npm — install from source until registry publication ships.

git clone https://github.com/plaidly/plaidly-sdk-tg.git
cd plaidly-sdk-tg
npm install
npm run build

Once published, the intended install command will be:

npm install plaidly-sdk-tg

Setup

import { PlaidlyTelegram } from 'plaidly-sdk-tg';

const plaidly = new PlaidlyTelegram({
  apiKey: process.env.PLAIDLY_API_KEY!,
  botToken: process.env.TELEGRAM_BOT_TOKEN!,
});

Create an invoice

const invoice = await plaidly.createInvoice({
  amount: 10,
  currency: 'USDC',
  chain: 'ton',
  description: 'Premium subscription — 1 month',
});

// Send to user
await ctx.reply(invoice.message, {
  reply_markup: invoice.keyboard,
});

The invoice.keyboard is an inline keyboard with a Pay button that opens a payment flow inside Telegram.

Listen for payment

plaidly.onPaid(invoice.sessionId, async (session) => {
  await fulfillSubscription(session.userId);
  await ctx.reply('Payment confirmed! Enjoy your premium access.');
});

Using with grammy

import { Bot } from 'grammy';
import { PlaidlyTelegram } from 'plaidly-sdk-tg';

const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
const plaidly = new PlaidlyTelegram({
  apiKey: process.env.PLAIDLY_API_KEY!,
  botToken: process.env.TELEGRAM_BOT_TOKEN!,
});

bot.command('pay', async (ctx) => {
  const invoice = await plaidly.createInvoice({
    amount: 5,
    currency: 'USDC',
    chain: 'ton',
    metadata: { userId: String(ctx.from!.id) },
  });

  await ctx.reply(`Pay $5 USDC to unlock premium features:`, {
    reply_markup: invoice.keyboard,
  });

  plaidly.onPaid(invoice.sessionId, async (session) => {
    await grantPremium(session.metadata.userId);
    await ctx.api.sendMessage(
      ctx.chat.id,
      'Payment received! Your premium is now active.',
    );
  });
});

bot.start();

Using with telegraf

import { Telegraf } from 'telegraf';
import { PlaidlyTelegram } from 'plaidly-sdk-tg';

const bot = new Telegraf(process.env.TELEGRAM_BOT_TOKEN!);
const plaidly = new PlaidlyTelegram({
  apiKey: process.env.PLAIDLY_API_KEY!,
  botToken: process.env.TELEGRAM_BOT_TOKEN!,
});

bot.command('buy', async (ctx) => {
  const invoice = await plaidly.createInvoice({
    amount: 20,
    currency: 'USDT',
    chain: 'tron',
    description: 'Lifetime access',
  });

  await ctx.reply(invoice.message, { reply_markup: invoice.keyboard });

  plaidly.onPaid(invoice.sessionId, () => ctx.reply('Thank you!'));
});

bot.launch();

Supported chains for Telegram

TON is the native Telegram chain and provides the best UX (deep link integration). Other chains work via QR code display:

Chain	UX
TON	Deep link (Telegram Wallet)
Solana	QR code / copy address
Tron	QR code / copy address
Ethereum	QR code / copy address

Webhook handling

The SDK manages its own internal webhook listener. For production deployments, configure the webhook URL in your dashboard to ensure events are delivered even when the bot is restarted.

Telegram Bot SDK

On this page