Onramper TMA Demo Bot

Reference Telegram bot that opens the Onramp Mini App with Onramper configuration.

What this bot does

• Handles /start and /onramp commands.
• Builds a shareable t.me deep link with all Onramper params base64url-encoded into startapp.
• Lets the Mini App decode startapp and forward those params to Onramper.

How params travel

The bot opens the Mini App via a shareable deep link:

https://t.me/<bot>/<app>?startapp=<encoded>

A t.me link can only carry the single startapp value, and Telegram restricts it to A-Z a-z 0-9 _ - and ~512 characters — no =, &, or %. So the bot base64url-encodes a JSON payload of params into startapp, and the Mini App (served at tma.onramper.com) decodes it back on launch.

Before encoding, the params are a plain object of Onramper widget parameters — apiKey and mode plus any extras:

{
  apiKey: "pk_prod_...",     // Onramper publishable widget key
  mode: "buy,sell,swap",     // enabled widget modes
  defaultFiat: "EUR",        // any extra Onramper widget param
  defaultCrypto: "eth",
  ... any other widget query params
}

// Encoding side (this bot — see encodeStartParam / buildShareableLink in index.js)
const params = { apiKey: "pk_prod_...", mode: "buy,sell,swap", defaultFiat: "EUR" };
const startParam = Buffer.from(JSON.stringify(params), "utf8")
  .toString("base64")
  .replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
const link = `https://t.me/OnramperBot/widget?startapp=${startParam}`;

// Decoding side (the Mini App frontend)
const json = atob(startParam.replace(/-/g, "+").replace(/_/g, "/"));
const params = JSON.parse(json);

Prerequisites

• Node.js >=20.19.0
• npm
• Telegram bot token from @BotFather
• Onramper publishable key (pk_prod_...)

Run this bot

cd bot
cp .env.example .env
npm install
npm start

For local development with file watch:

npm run dev

Environment variables

Variable	Required	Description
BOT_TOKEN	yes	Telegram bot token
ONRAMPER_API_KEY	yes	Onramper publishable widget key
BOT_USERNAME	yes	Bot username without @ (used to build the t.me deep link)
MINI_APP_SHORT_NAME	yes	Mini App short name set in @BotFather
ONRAMPER_MODE	no	buy, sell, swap, or comma-separated list
ONRAMPER_EXTRA_PARAMS	no	Extra widget params, e.g. country=us&defaultFiat=USD
DEBUG_BOT	no	Set 1 to log the generated link

Supported widget params

Any query parameter supported by Onramper can be passed via ONRAMPER_EXTRA_PARAMS.

Reference: Onramper supported widget parameters