Teleton Plugin Builder

You are building a plugin for Teleton, a Telegram AI agent on TON. Ask the user what plugin or tools they want to build, then follow this workflow.

Reference documentation

Before building, read the relevant reference files from the teleton-plugins repo:

• Full rules & SDK reference:

  CONTRIBUTING.md

  — complete guide with tool definition, SDK API tables, error handling, lifecycle, best practices, testing
• Simple plugin example:

  plugins/example/index.js

  — Pattern A (array of tools, no SDK)
• SDK plugin example:

  plugins/example-sdk/index.js

  — Pattern B (tools(sdk) with database, TON balance, Telegram messaging)
• Advanced SDK plugin:

  plugins/casino/index.js

  — real-world SDK plugin with TON payments, payment verification, isolated database, payout logic
• Registry:

  registry.json

  — list of all existing plugins (check for name conflicts)
• README.md — project overview, plugin list, SDK section

Read at least

CONTRIBUTING.md

Workflow

1. Ask the user what they want (plugin name, what it does, which API or bot)
2. Decide — determine if the plugin needs the SDK (see decision tree below)
3. Plan — present a structured plan and ask for validation
4. Build — create all files once the user approves
5. Install — copy to

   ~/.teleton/plugins/

   and restart

Step 1 — Understand the request

Determine:

• Plugin name — short, lowercase folder name (e.g.

  pic

  ,

  deezer

  ,

  weather

  )
• Plugin type:
  • Inline bot — wraps a Telegram inline bot (@pic, @vid, @gif, @DeezerMusicBot…)
  • Public API — calls an external REST API, no auth
  • Auth API — external API with Telegram WebApp auth
  • Local logic — pure JavaScript, no external calls
• Tools — list of tool names, what each does, parameters
• Does it need GramJS? — yes for inline bots and WebApp auth
• Does it need the SDK? — use the decision tree below

SDK Decision Tree

The Plugin SDK (

tools(sdk)

Use

tools(sdk)

sdk.ton.getBalance()

sdk.ton.getAddress()

sdk.ton.sendTON()

sdk.ton.verifyPayment()

sdk.ton.getPrice()

sdk.ton.getTransactions()

sdk.ton.getJettonBalances()

sdk.ton.getJettonInfo()

sdk.ton.sendJetton()

sdk.ton.getNftItems()

sdk.ton.getNftInfo()

sdk.ton.toNano()

sdk.ton.fromNano()

sdk.ton.validateAddress()

sdk.telegram.sendMessage()

sdk.telegram.editMessage()

sdk.telegram.sendReaction()

sdk.telegram.sendDice()

sdk.telegram.sendPhoto()

sdk.telegram.sendFile()

sdk.telegram.deleteMessage()

sdk.telegram.pinMessage()

sdk.telegram.scheduleMessage()

sdk.telegram.createPoll()

sdk.telegram.createQuiz()

sdk.telegram.banUser()

sdk.telegram.muteUser()

sdk.telegram.getStarsBalance()

sdk.telegram.sendGift()

sdk.telegram.sendStory()

sdk.telegram.getUserInfo()

sdk.telegram.getChatInfo()

sdk.db

export function migrate(db)

sdk.storage

sdk.secrets

sdk.pluginConfig

manifest.defaultConfig

sdk.log.info()

sdk.log.error()

sdk.ton.dex.quote()

sdk.ton.dex.swap()

sdk.ton.dex.quoteSTONfi()

sdk.ton.dex.quoteDeDust()

sdk.ton.dns.check()

sdk.ton.dns.resolve()

sdk.ton.dns.startAuction()

sdk.ton.dns.bid()

sdk.ton.dns.link()

sdk.ton.dns.setSiteRecord()

sdk.ton.getJettonPrice()

sdk.ton.getJettonHolders()

sdk.telegram.getScheduledMessages()

sdk.telegram.sendScheduledNow()

sdk.telegram.getDialogs()

sdk.telegram.getHistory()

sdk.telegram.transferCollectible()

sdk.telegram.getUniqueGift()

sdk.bot.onInlineQuery()

sdk.bot.keyboard()

sdk.on("tool:after", handler)

Use

tools = [...]

• Only calls external APIs (REST, GraphQL) — no TON blockchain interaction
• Does not need to send Telegram messages from code (only returns data to LLM)
• Does not need persistent state (no database)
• Does not need plugin-specific config

Examples:

weather

gaspump

pic

sdk.telegram.getRawClient()

casino

example-sdk

Note: Inline bots and WebApp auth plugins can use either

context.bridge.getClient().getClient()

permissions: ["bridge"]

sdk.telegram.getRawClient()

Step 2 — Present the plan

Show this to the user and wait for approval:

Plugin: [name]
Pattern: [A (simple) | B (SDK)]
Reason: [why SDK is/isn't needed]

Tools:
| Tool        | Description              | Params                              |
|-------------|--------------------------|-------------------------------------|
| `tool_name` | What it does             | `query` (string, required), `index` (int, optional) |

SDK features used: [none | sdk.ton, sdk.db, sdk.telegram, sdk.log, sdk.pluginConfig]

Files:
- plugins/[name]/index.js
- plugins/[name]/manifest.json
- plugins/[name]/README.md
- registry.json (update)

Do NOT build until the user says go.

Step 3 — Build

Create all files in

plugins/[name]/

index.js

ESM only — always

export const tools

module.exports

Choose the right pattern:

Pattern A: Simple tools (array)

For plugins that don't need TON, Telegram messaging, or persistent database.

Reference:

plugins/example/index.js

const myTool = {
  name: "tool_name",
  description: "The LLM reads this to decide when to call the tool. Be specific.",
  parameters: {
    type: "object",
    properties: {
      query: { type: "string", description: "Search query" },
      index: { type: "integer", description: "Which result (0 = first)", minimum: 0, maximum: 49 },
    },
    required: ["query"],
  },
  execute: async (params, context) => {
    try {
      // logic here
      return { success: true, data: { result: "..." } };
    } catch (err) {
      return { success: false, error: String(err.message || err).slice(0, 500) };
    }
  },
};

export const tools = [myTool];

Pattern B: SDK tools (function)

For plugins that need TON blockchain, Telegram messaging, isolated database, or config.

Reference:

plugins/example-sdk/index.js

plugins/casino/index.js

export const manifest = {
  name: "my-plugin",
  version: "1.0.0",
  sdkVersion: ">=1.0.0",
  description: "What this plugin does",
  defaultConfig: {
    some_setting: "default_value",
  },
};

// Optional: export migrate() to get sdk.db (isolated SQLite per plugin)
export function migrate(db) {
  db.exec(`CREATE TABLE IF NOT EXISTS my_table (
    id TEXT PRIMARY KEY,
    value TEXT
  )`);
}

export const tools = (sdk) => [
  {
    name: "my_tool",
    description: "What this tool does",
    parameters: { type: "object", properties: {}, },
    scope: "always", // "always" | "dm-only" | "group-only" | "admin-only"
    category: "data-bearing", // "data-bearing" (reads/queries) | "action" (writes/modifies)
    execute: async (params, context) => {
      try {
        // SDK namespaces:
        // sdk.ton      — getAddress(), getBalance(), getPrice(), sendTON(), getTransactions(), verifyPayment()
        //                 getPublicKey(), getWalletVersion(), createJettonTransfer()
        //                 getJettonBalances(), getJettonInfo(), sendJetton(), getJettonWalletAddress()
        //                 getNftItems(), getNftInfo(), toNano(), fromNano(), validateAddress()
        // sdk.telegram — sendMessage(), editMessage(), deleteMessage(), forwardMessage(), pinMessage()
        //                 sendDice(), sendReaction(), getMessages(), searchMessages(), getReplies()
        //                 sendPhoto(), sendVideo(), sendVoice(), sendFile(), sendGif(), sendSticker()
        //                 downloadMedia(), setTyping(), getChatInfo(), getUserInfo(), resolveUsername()
        //                 getParticipants(), createPoll(), createQuiz(), banUser(), unbanUser(), muteUser()
        //                 getStarsBalance(), sendGift(), getAvailableGifts(), getMyGifts(), getResaleGifts()
        //                 buyResaleGift(), sendStory(), scheduleMessage(), getMe(), isAvailable(), getRawClient()
        // sdk.db       — better-sqlite3 instance (null if no migrate())
        // sdk.storage  — get(), set(key, val, {ttl?}), delete(), has(), clear() — auto-created KV, no migrate needed
        // sdk.secrets  — get(key), require(key), has(key) — resolves ENV → secrets file → pluginConfig
        // sdk.log      — info(), warn(), error(), debug()
        // sdk.config   — sanitized app config (no secrets)
        // sdk.pluginConfig — plugin-specific config from config.yaml merged with defaultConfig
        // sdk.bot      — isAvailable, username, onInlineQuery(), onCallback(), onChosenResult(),
        //                 editInlineMessage(), keyboard() — null if no bot manifest
        // sdk.on       — on(hookName, handler, opts?) — 13 hooks: tool:before/after/error,
        //                 prompt:before/after, session:start/end, message:receive, etc.

        const balance = await sdk.ton.getBalance();
        sdk.log.info(`Balance: ${balance?.balance}`);
        return { success: true, data: { balance: balance?.balance } };
      } catch (err) {
        return { success: false, error: String(err.message || err).slice(0, 500) };
      }
    },
  },
];

// Optional: runs after Telegram bridge connects
export async function start(ctx) {
  // ctx.bridge, ctx.db, ctx.config, ctx.pluginConfig, ctx.log
}

// Optional: runs on shutdown
export async function stop() {
  // cleanup
}

SDK error handling:

• Read methods (

  getBalance

  ,

  getPrice

  ,

  getTransactions

  ,

  getMessages

  ,

  getJettonBalances

  ,

  getNftItems

  ) return

  null

  or

  []

  on failure — never throw
• Write methods (

  sendTON

  ,

  sendJetton

  ,

  createJettonTransfer

  ,

  sendMessage

  ,

  sendDice

  ,

  sendPhoto

  ,

  banUser

  ) throw

  PluginSDKError

  with

  .code

  :

  • WALLET_NOT_INITIALIZED

    — wallet not set up

  • INVALID_ADDRESS

    — bad TON address

  • BRIDGE_NOT_CONNECTED

    — Telegram not ready

  • SECRET_NOT_FOUND

    —

    sdk.secrets.require()

    called for missing secret

  • OPERATION_FAILED

    — generic failure

GramJS import (only if plugin needs raw Telegram MTProto)

import { createRequire } from "node:module";
import { realpathSync } from "node:fs";

const _require = createRequire(realpathSync(process.argv[1]));
const { Api } = _require("telegram");

Per-plugin npm dependencies

Plugins can have their own npm deps. Add

package.json

package-lock.json

npm ci --ignore-scripts

Use two

createRequire

import { createRequire } from "node:module";
import { realpathSync } from "node:fs";

// Core deps (from teleton runtime)
const _require = createRequire(realpathSync(process.argv[1]));
// Plugin-local deps (from plugin's node_modules/)
const _pluginRequire = createRequire(import.meta.url);

const { Address } = _require("@ton/core");                              // core
const { getHttpEndpoint } = _pluginRequire("@orbs-network/ton-access"); // plugin-local

Setup:

cd plugins/your-plugin && npm init -y && npm install <deps>

package.json

package-lock.json

node_modules/

With SDK plugins, prefer

sdk.telegram.getRawClient()

context.bridge.getClient().getClient()

API fetch helper (for plugins calling external APIs)

const API_BASE = "https://api.example.com";

async function apiFetch(path, params = {}) {
  const url = new URL(path, API_BASE);
  for (const [key, value] of Object.entries(params)) {
    if (value !== undefined && value !== null) {
      url.searchParams.set(key, String(value));
    }
  }
  const res = await fetch(url, { signal: AbortSignal.timeout(15000) });
  if (!res.ok) {
    throw new Error(`API error: ${res.status} ${await res.text().catch(() => "")}`);
  }
  return res.json();
}

Inline bot pattern (@pic, @vid, @gif, @DeezerMusicBot…)

Preferred (SDK Pattern B) — define tools inside the

(sdk) => [...]

export const tools = (sdk) => [{
  name: "my_inline_bot",
  description: "...",
  parameters: { ... },
  execute: async (params, context) => {
    const client = sdk.telegram.getRawClient();
    // ... same GramJS API calls
  },
}];

Legacy (Pattern A) — uses

context.bridge

execute: async (params, context) => {
  try {
    const client = context.bridge.getClient().getClient();
    const bot = await client.getEntity("BOT_USERNAME");
    const peer = await client.getInputEntity(context.chatId);

    const results = await client.invoke(
      new Api.messages.GetInlineBotResults({
        bot, peer, query: params.query, offset: "",
      })
    );

    if (!results.results || results.results.length === 0) {
      return { success: false, error: `No results found for "${params.query}"` };
    }

    const index = params.index ?? 0;
    if (index >= results.results.length) {
      return { success: false, error: `Only ${results.results.length} results, index ${index} out of range` };
    }

    const chosen = results.results[index];

    await client.invoke(
      new Api.messages.SendInlineBotResult({
        peer,
        queryId: results.queryId,
        id: chosen.id,
        randomId: BigInt(Math.floor(Math.random() * 2 ** 62)),
      })
    );

    return {
      success: true,
      data: {
        query: params.query,
        sent_index: index,
        total_results: results.results.length,
        title: chosen.title || null,
        description: chosen.description || null,
        type: chosen.type || null,
      },
    };
  } catch (err) {
    return { success: false, error: String(err.message || err).slice(0, 500) };
  }
}

WebApp auth pattern (Telegram-authenticated APIs)

let cachedAuth = null;
let cachedAuthTime = 0;
const AUTH_TTL = 30 * 60 * 1000;

async function getAuth(bridge, botUsername, webAppUrl) {
  if (cachedAuth && Date.now() - cachedAuthTime < AUTH_TTL) return cachedAuth;
  const client = bridge.getClient().getClient();
  const bot = await client.getEntity(botUsername);
  const result = await client.invoke(
    new Api.messages.RequestWebView({ peer: bot, bot, platform: "android", url: webAppUrl })
  );
  const fragment = new URL(result.url).hash.slice(1);
  const initData = new URLSearchParams(fragment).get("tgWebAppData");
  if (!initData) throw new Error("Failed to extract tgWebAppData");
  cachedAuth = initData;
  cachedAuthTime = Date.now();
  return cachedAuth;
}

Payment verification pattern (SDK)

Reference:

plugins/casino/index.js

export function migrate(db) {
  db.exec(`CREATE TABLE IF NOT EXISTS used_transactions (
    tx_hash TEXT PRIMARY KEY,
    user_id TEXT NOT NULL,
    amount REAL NOT NULL,
    game_type TEXT NOT NULL,
    used_at INTEGER NOT NULL DEFAULT (unixepoch())
  )`);
}

export const tools = (sdk) => [{
  name: "verify_and_process",
  execute: async (params, context) => {
    const payment = await sdk.ton.verifyPayment({
      amount: params.amount,
      memo: params.username,
      gameType: "my_service",
      maxAgeMinutes: 10,
    });

    if (!payment.verified) {
      const address = sdk.ton.getAddress();
      return { success: false, error: `Send ${params.amount} TON to ${address} with memo: ${params.username}` };
    }

    // Process the verified payment...
    // payment.playerWallet — sender's address (for refunds/payouts)
    // payment.compositeKey — unique tx identifier
    // payment.amount — verified amount

    return { success: true, data: { verified: true, from: payment.playerWallet } };
  }
}];

manifest.json

{
  "id": "PLUGIN_ID",
  "name": "Display Name",
  "version": "1.0.0",
  "description": "One-line description",
  "author": { "name": "teleton", "url": "https://github.com/TONresistor" },
  "license": "MIT",
  "entry": "index.js",
  "teleton": ">=1.0.0",
  "tools": [
    { "name": "tool_name", "description": "Short description" }
  ],
  "permissions": [],
  "tags": ["tag1", "tag2"],
  "repository": "https://github.com/TONresistor/teleton-plugins",
  "funding": null
}

Notes:

• Add

  "sdkVersion": ">=1.0.0"

  only if using

  tools(sdk)

  (Pattern B)
• Add

  "permissions": ["bridge"]

  only if using

  context.bridge

  directly (not needed with SDK)

• permissions

  is

  []

  for most plugins
• Add

  "secrets"

  to declare required/optional secrets (see Secrets section below)

Declaring secrets in manifest

If your plugin needs API keys or other secrets, declare them in the manifest:

{
  "secrets": {
    "api_key": { "required": true, "description": "API key for service X" },
    "webhook_url": { "required": false, "description": "Optional webhook endpoint" }
  }
}

Then access them via

sdk.secrets.get("api_key")

sdk.secrets.require("api_key")

README.md

# Plugin Name

One-line description.

| Tool | Description |
|------|-------------|
| `tool_name` | What it does |

## Install

mkdir -p ~/.teleton/plugins
cp -r plugins/PLUGIN_ID ~/.teleton/plugins/

## Usage examples

- "Natural language prompt the user would say"
- "Another example prompt"

## Tool schema

### tool_name

| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `query` | string | Yes | — | Search query |

registry.json

Add to the

plugins

{
  "id": "PLUGIN_ID",
  "name": "Display Name",
  "description": "One-line description",
  "author": "teleton",
  "tags": ["tag1", "tag2"],
  "path": "plugins/PLUGIN_ID"
}

Step 4 — Install and commit

1. Copy:

   cp -r plugins/PLUGIN_ID ~/.teleton/plugins/

2. Commit:

   git add plugins/PLUGIN_ID/ registry.json && git commit -m "PLUGIN_NAME: short description"

3. Ask user if they want to push.

Rules

• ESM only —

  export const tools

  , never

  module.exports

• JS only — the plugin loader reads

  .js

  files only
• Tool names —

  snake_case

  , globally unique across all plugins, prefixed with plugin name
• Defaults — use

  ??

  (nullish coalescing), never

  ||

• Errors — always try/catch in execute, return

  { success: false, error }

  , slice to 500 chars
• Timeouts —

  AbortSignal.timeout(15000)

  on all external fetch calls
• Per-plugin npm deps — plugins needing external packages add

  package.json

  +

  package-lock.json

  ; teleton auto-installs at startup. Use the dual-require pattern (see below)
• GramJS — always

  createRequire(realpathSync(process.argv[1]))

  , never

  import from "telegram"

• Client chain —

  context.bridge.getClient().getClient()

  OR

  sdk.telegram.getRawClient()

  for raw GramJS
• SDK preferred — when using SDK, prefer

  sdk.telegram

  over

  context.bridge

  ,

  sdk.db

  over

  context.db

• Scope — add

  scope: "dm-only"

  on financial/private tools,

  scope: "group-only"

  on moderation tools,

  scope: "admin-only"

  for admin-only tools
• Category — add

  category: "data-bearing"

  for read/query tools,

  category: "action"

  for write/modify tools
• Secrets — use

  sdk.secrets

  instead of hardcoded keys; declare in

  manifest.secrets

• Storage — prefer

  sdk.storage

  for caching and temp state over

  sdk.db

  (no

  migrate()

  needed)
• SDK decision — only use Pattern B if the plugin actually needs TON, Telegram messaging, database, secrets, storage, or config (see decision tree)

Context object

Available in

execute(params, context)

bridge

db

sdk.db

chatId

senderId

isGroup

true

false

config

SDK object

Available only in

tools(sdk)

sdk.ton

getAddress()

getBalance(addr?)

getPrice()

sendTON(to, amount, comment?)

getTransactions(addr, limit?)

verifyPayment(params)

getPublicKey()

getWalletVersion()

getJettonBalances(ownerAddr?)

getJettonInfo(jettonAddr)

sendJetton(jettonAddr, to, amount, opts?)

getJettonWalletAddress(ownerAddr, jettonAddr)

createJettonTransfer(jettonAddr, to, amount, opts?)

getNftItems(ownerAddr?)

getNftInfo(nftAddr)

toNano(amount)

fromNano(nano)

validateAddress(addr)

sdk.telegram

sendMessage(chatId, text, opts?)

editMessage(chatId, msgId, text, opts?)

deleteMessage(chatId, msgId, revoke?)

forwardMessage(fromChat, toChat, msgId)

pinMessage(chatId, msgId, opts?)

searchMessages(chatId, query, limit?)

scheduleMessage(chatId, text, scheduleDate)

getReplies(chatId, msgId, limit?)

getMessages(chatId, limit?)

sendPhoto(chatId, photo, opts?)

sendVideo(chatId, video, opts?)

sendVoice(chatId, voice, opts?)

sendFile(chatId, file, opts?)

sendGif(chatId, gif, opts?)

sendSticker(chatId, sticker)

downloadMedia(chatId, msgId)

setTyping(chatId)

getChatInfo(chatId)

getUserInfo(userId)

resolveUsername(username)

getParticipants(chatId, limit?)

sendDice(chatId, emoticon, replyToId?)

sendReaction(chatId, msgId, emoji)

createPoll(chatId, question, answers, opts?)

createQuiz(chatId, question, answers, correctIdx, explanation?)

banUser(chatId, userId)

unbanUser(chatId, userId)

muteUser(chatId, userId, untilDate?)

getStarsBalance()

sendGift(userId, giftId, opts?)

getAvailableGifts()

getMyGifts(limit?)

getResaleGifts(limit?)

buyResaleGift(giftId)

sendStory(mediaPath, opts?)

getMe()

isAvailable()

getRawClient()

sdk.db

better-sqlite3

export function migrate(db)

sdk.storage

get(key)

set(key, value, opts?)

delete(key)

has(key)

clear()

migrate()

sdk.secrets

get(key)

require(key)

has(key)

PLUGINNAME_KEY

pluginConfig

sdk.log

info()

warn()

error()

debug()

sdk.config

sdk.pluginConfig

config.yaml

manifest.defaultConfig

sdk.bot

isAvailable

username

onInlineQuery(handler)

onCallback(pattern, handler)

onChosenResult(handler)

editInlineMessage(id, text, opts?)

keyboard(rows)

null

sdk.on

on(hookName, handler, opts?)

tool:before

tool:after

tool:error

prompt:before

prompt:after

session:start

session:end

message:receive

response:before

response:after

response:error

agent:start

agent:stop

sdk.secrets — Secret management

Resolves secrets from multiple sources in priority order: environment variable (

PLUGINNAME_KEY

~/.teleton/plugins/data/name.secrets.json

pluginConfig

// Check if a secret is available
if (sdk.secrets.has("api_key")) {
  const key = sdk.secrets.get("api_key"); // string | undefined
}

// Require a secret (throws PluginSDKError with code SECRET_NOT_FOUND if missing)
const apiKey = sdk.secrets.require("api_key");

Declare required secrets in

manifest.json

{
  "secrets": {
    "api_key": { "required": true, "description": "API key for service X" }
  }
}

sdk.storage — Key-value storage with TTL

Auto-created

_kv

migrate()

null

// Set a value with optional TTL (milliseconds)
sdk.storage.set("rate_limit:user123", { count: 1 }, { ttl: 60000 }); // expires in 60s

// Get a value (returns undefined if missing or expired)
const data = sdk.storage.get("rate_limit:user123");

// Check existence (respects TTL)
if (sdk.storage.has("rate_limit:user123")) { /* ... */ }

// Delete a key (returns true if it existed)
sdk.storage.delete("rate_limit:user123");

// Clear all keys for this plugin
sdk.storage.clear();

sdk.bot — Inline bot features

null

bot

manifest.json

// Check if bot is available
if (sdk.bot.isAvailable) {
  const botName = sdk.bot.username; // string — bot username

  // Register inline query handler
  sdk.bot.onInlineQuery(async (query) => {
    // handle inline query
  });

  // Register callback handler for a pattern
  sdk.bot.onCallback("action:*", async (data) => {
    // handle callback
  });

  // Register chosen inline result handler
  sdk.bot.onChosenResult(async (result) => {
    // handle chosen result
  });

  // Edit an inline message
  await sdk.bot.editInlineMessage(inlineMessageId, "Updated text", { parseMode: "HTML" });

  // Build a keyboard
  const kb = sdk.bot.keyboard([
    [{ text: "Button 1", callback: "action:1" }, { text: "Button 2", callback: "action:2" }],
  ]); // BotKeyboard
}

sdk.on — Event hooks

Register handlers for agent lifecycle and tool execution events. 13 hook types available.

// Tool hooks
sdk.on("tool:before", (event) => { /* before any tool executes */ });
sdk.on("tool:after", (event) => { /* after any tool executes */ });
sdk.on("tool:error", (event) => { /* when a tool throws */ });

// Prompt hooks
sdk.on("prompt:before", (event) => { /* before prompt is sent to LLM */ });
sdk.on("prompt:after", (event) => { /* after LLM responds */ });

// Session hooks
sdk.on("session:start", (event) => { /* session begins */ });
sdk.on("session:end", (event) => { /* session ends */ });

// Message hooks
sdk.on("message:receive", (event) => { /* incoming message */ });

// Response hooks
sdk.on("response:before", (event) => { /* before response is sent */ });
sdk.on("response:after", (event) => { /* after response is sent */ });
sdk.on("response:error", (event) => { /* response error */ });

// Agent hooks
sdk.on("agent:start", (event) => { /* agent starts */ });
sdk.on("agent:stop", (event) => { /* agent stops */ });

// Optional: pass options
sdk.on("tool:after", handler, { priority: 10 });

sdk.ton — Jetton & NFT methods

Jettons (TEP-74)

// Get all jetton balances for the agent wallet (or a specific address)
const balances = await sdk.ton.getJettonBalances(); // JettonBalance[]
const otherBalances = await sdk.ton.getJettonBalances("UQ...");

// Get jetton metadata
const info = await sdk.ton.getJettonInfo("EQ...jetton_master"); // JettonInfo | null

// Send jettons
const result = await sdk.ton.sendJetton(
  "EQ...jetton_master",  // jetton master address
  "UQ...recipient",       // destination
  "1000000000",           // amount in smallest units
  { comment: "payment" }  // optional
); // JettonSendResult

// Get jetton wallet address
const wallet = await sdk.ton.getJettonWalletAddress("UQ...owner", "EQ...jetton"); // string | null

NFTs

// Get all NFTs for the agent wallet (or a specific address)
const nfts = await sdk.ton.getNftItems(); // NftItem[]

// Get NFT metadata
const nft = await sdk.ton.getNftInfo("EQ...nft_address"); // NftItem | null

Wallet info

const pubKey = sdk.ton.getPublicKey();       // string | null — hex ed25519 public key
const version = sdk.ton.getWalletVersion();  // string — always "v5r1"

Jetton transfer (sign without broadcast)

// Sign a jetton transfer (TEP-74) without broadcasting
const transfer = await sdk.ton.createJettonTransfer(
  "EQ...jetton_master",  // jetton master address
  "UQ...recipient",       // destination
  "1000000000",           // amount in smallest units
  { comment: "payment" }  // optional
); // SignedTransfer — throws WALLET_NOT_INITIALIZED, OPERATION_FAILED

Utilities

const nano = sdk.ton.toNano(1.5);           // bigint — 1500000000n
const tons = sdk.ton.fromNano(1500000000n);  // string — "1.5"
const valid = sdk.ton.validateAddress("UQ..."); // boolean

sdk.telegram — Extended methods

Media

// photo/video/voice/file/gif can be a file path (string) or Buffer
await sdk.telegram.sendPhoto(chatId, "/path/to/image.jpg", { caption: "Look!" });
await sdk.telegram.sendVideo(chatId, videoBuffer, { caption: "Video" });
await sdk.telegram.sendVoice(chatId, voiceBuffer, { caption: "Listen" });
await sdk.telegram.sendFile(chatId, "/path/to/doc.pdf", { caption: "Document" });
await sdk.telegram.sendGif(chatId, gifBuffer);
await sdk.telegram.sendSticker(chatId, stickerBuffer);

// Download media from a message
const buffer = await sdk.telegram.downloadMedia(chatId, messageId); // Buffer | null

// Show typing indicator
await sdk.telegram.setTyping(chatId);

Message management

await sdk.telegram.deleteMessage(chatId, messageId, true); // revoke=true deletes for everyone
await sdk.telegram.forwardMessage(fromChatId, toChatId, messageId);
await sdk.telegram.pinMessage(chatId, messageId, { silent: true });
const results = await sdk.telegram.searchMessages(chatId, "query", 20);
const replies = await sdk.telegram.getReplies(chatId, messageId, 10);
await sdk.telegram.scheduleMessage(chatId, "Reminder!", new Date("2026-03-01T10:00:00Z"));

Social & lookup

const chat = await sdk.telegram.getChatInfo(chatId);       // ChatInfo | null
const user = await sdk.telegram.getUserInfo(userId);        // UserInfo | null
const peer = await sdk.telegram.resolveUsername("username"); // ResolvedPeer | null
const members = await sdk.telegram.getParticipants(chatId, 100); // UserInfo[]

Interactive

await sdk.telegram.createPoll(chatId, "Favorite color?", ["Red", "Blue", "Green"], { anonymous: false });
await sdk.telegram.createQuiz(chatId, "2+2=?", ["3", "4", "5"], 1, "Basic math!");

Moderation

await sdk.telegram.banUser(chatId, userId);
await sdk.telegram.unbanUser(chatId, userId);
await sdk.telegram.muteUser(chatId, userId, Math.floor(Date.now() / 1000) + 3600); // mute 1h

Stars & Gifts

const balance = await sdk.telegram.getStarsBalance(); // number
await sdk.telegram.sendGift(userId, giftId, { message: "Enjoy!" });
const gifts = await sdk.telegram.getAvailableGifts();   // StarGift[]
const mine = await sdk.telegram.getMyGifts(10);          // ReceivedGift[]
const resale = await sdk.telegram.getResaleGifts(10);    // StarGift[]
await sdk.telegram.buyResaleGift(giftId);

Stories

await sdk.telegram.sendStory("/path/to/media.jpg", { caption: "Check this out!" });

Raw GramJS client

const client = sdk.telegram.getRawClient(); // raw GramJS TelegramClient | null
// Use for inline bots, WebApp auth, custom MTProto calls

SDK Types reference

JettonBalance

jettonAddress

balance

metadata

JettonInfo

address

totalSupply

metadata

JettonSendResult

hash

lt

success

SignedTransfer

createJettonTransfer

NftItem

address

collectionAddress

metadata

ownerAddress

ChatInfo

id

title

type

participantsCount

username

UserInfo

id

firstName

lastName

username

phone

bot

ResolvedPeer

id

type

username

MediaSendOptions

caption?

replyToId?

silent?

PollOptions

anonymous?

multipleChoice?

quizMode?

StarGift

id

name

price

availability

image

ReceivedGift

id

fromUser

gift

date

message

SecretDeclaration

required

description

StorageSDK

get()

set()

delete()

has()

clear()

SecretsSDK

get()

require()

has()

ToolCategory

"data-bearing"

"action"

StartContext

bridge

db

config

pluginConfig

log

Bridge methods (legacy)

Only needed for Pattern A plugins that use

context.bridge

await context.bridge.sendMessage({ chatId, text, replyToId?, inlineKeyboard? });
await context.bridge.sendReaction(chatId, messageId, emoji);
await context.bridge.editMessage({ chatId, messageId, text, inlineKeyboard? });
await context.bridge.setTyping(chatId);
const msgs = await context.bridge.getMessages(chatId, limit);
const peer = context.bridge.getPeer(chatId);
const gramjs = context.bridge.getClient().getClient();