teleton-plugins

Community plugin directory for Teleton, the Telegram AI agent on TON.
Drop a plugin in ~/.teleton/plugins/ and it's live. No build step, no config.

---

Table of Contents

• How It Works
• Quick Start
• Available Plugins
• Build Your Own
• Plugin SDK
• Troubleshooting
• FAQ
• Community
• Contributors
• License

How It Works

User message
  → LLM reads tool descriptions
  → picks and calls a tool
  → execute(params, context) runs
  → result JSON → LLM
  → LLM responds to user

Teleton loads every folder from ~/.teleton/plugins/ at startup. Each plugin exports a tools array (or a function that receives the Plugin SDK). The execute function receives the LLM's parameters and a context with Telegram bridge access. The returned data object is serialized to JSON and fed back to the LLM.

Plugin lifecycle: manifest.json is read first, then migrate(db) runs if exported (for database setup), then tools are registered, start(ctx) is called if exported, and stop() on shutdown.

Quick Start

# 1. Create the plugins directory
mkdir -p ~/.teleton/plugins

# 2. Clone and copy any plugin
git clone https://github.com/TONresistor/teleton-plugins.git
cp -r teleton-plugins/plugins/example ~/.teleton/plugins/

# 3. Restart Teleton — the plugin loads automatically

No build step. Just copy and go. Plugins with npm dependencies are auto-installed at startup.

Available Plugins

25 plugins · 183 tools · Browse the registry

DeFi & Trading

Plugin	Description	Tools	Author
gaspump	Launch, trade, and manage meme tokens on Gas111/TON	13	teleton
stormtrade	Perpetual futures — crypto, stocks, forex, commodities	13	teleton
evaa	EVAA Protocol — supply, borrow, withdraw, repay, liquidate	11	teleton
stonfi	StonFi DEX — tokens, pools, farms, swap	8	teleton
dedust	DeDust DEX — pools, assets, trades, on-chain swaps	8	teleton
swapcoffee	swap.coffee aggregator — best rates across all DEXes	6	teleton
giftindex	GiftIndex ODROB — trade Telegram Gifts index on TON	6	teleton

Market Data & Analytics

Plugin	Description	Tools	Author
tonapi	TON blockchain data — accounts, jettons, NFTs, DNS, staking	20	teleton
giftstat	Telegram gift market data from Giftstat API	11	teleton
dyor	DYOR.io — trust score, price, metrics, holders, pools	11	teleton
geckoterminal	TON DEX pools — trending, OHLCV, batch prices	10	teleton
crypto-prices	Real-time prices for 5000+ coins	2	walged

Social & Messaging

Plugin	Description	Tools	Author
twitter	X/Twitter API v2 — search, post, like, retweet, follow	24	teleton
pic	Image search via @pic inline bot	1	teleton
vid	YouTube search via @vid inline bot	1	teleton
deezer	Music search via @DeezerMusicBot	1	teleton
voice-notes	Transcribe voice messages (Premium STT)	1	walged

TON Infrastructure

Plugin	Description	Tools	Author
multisend	Batch send TON/jettons to 254 recipients in one TX	5	teleton
sbt	Deploy and mint Soulbound Tokens (TEP-85)	2	teleton

Marketplace & NFTs

Plugin	Description	Tools	Author
fragment	Fragment marketplace — usernames, numbers, collectible gifts	6	teleton
webdom	TON domain marketplace — search, buy, sell, auction, DNS bid	12	teleton

Utilities & Games

Plugin	Description	Tools	Author
casino	Slot machine and dice games with TON payments and auto-payout	4	teleton
example	Dice roller and random picker	2	teleton
example-sdk	SDK example — greeting counter, balance check, announcements	3	teleton
weather	Weather and 7-day forecast via Open-Meteo	2	walged

Build Your Own

Three files. No build step. No npm install.

plugins/your-plugin/
  index.js         # exports tools[] or tools(sdk)
  manifest.json    # plugin metadata
  README.md        # documentation

Pattern A — Simple plugin (no SDK needed):

// index.js
export const tools = [
  {
    name: "hello",
    description: "Say hello to someone",
    parameters: {
      type: "object",
      properties: {
        name: { type: "string", description: "Who to greet" },
      },
      required: ["name"],
    },
    execute: async (params) => ({
      success: true,
      data: { message: `Hello, ${params.name}!` },
    }),
  },
];

Pattern B — Plugin with SDK (TON, Telegram, database):

// index.js
export const tools = (sdk) => [
  {
    name: "check_balance",
    description: "Check TON wallet balance",
    execute: async (params, context) => {
      const balance = await sdk.ton.getBalance();
      sdk.log.info(`Balance: ${balance?.balance}`);
      return { success: true, data: { balance: balance?.balance } };
    }
  }
];

See plugins/example/ for Pattern A and plugins/example-sdk/ for Pattern B.

Declaring secrets:

If your plugin needs API keys, declare them in manifest.json with the exact environment variable name:

"secrets": {
  "api_key": { "env": "MYPLUGIN_API_KEY", "required": true, "description": "API key for MyService" },
  "webhook_secret": { "env": "MYPLUGIN_WEBHOOK_SECRET", "required": false, "description": "Optional webhook signing secret" }
}

Users can then configure secrets via:

• Environment variable: MYPLUGIN_API_KEY=sk-xxx (Docker, CI)
• WebUI: Plugins → Manage Secrets (auto-prompted on install)
• Telegram: /plugin set myplugin api_key sk-xxx

In your plugin code: sdk.secrets.require("api_key") or sdk.secrets.get("api_key").

Submission checklist:

• Three files: index.js, manifest.json, README.md
• manifest.json has all required fields (id, name, description, version, author)
• Tool names are prefixed with the plugin name (e.g. myplugin_action)
• sdkVersion declared in manifest if using the SDK
• Secrets declared with env field if the plugin needs API keys
• Tested locally (see below)
• Added to registry.json

Test locally:

# Verify your plugin loads without errors
node -e "import('./plugins/your-plugin/index.js').then(m => console.log('OK:', typeof m.tools === 'function' ? m.tools.length + ' (sdk)' : m.tools.length + ' tools'))"

# Or copy to Teleton and restart
cp -r plugins/your-plugin ~/.teleton/plugins/

Submit your plugin:

1. Fork this repo
2. Create plugins/your-plugin/ with the three files above
3. Add your plugin to registry.json
4. Open a PR

Full guide — manifest format, context API, best practices: CONTRIBUTING.md

Plugin SDK

The SDK gives your plugin access to TON, Telegram, secrets, storage, and more — without touching any internals.

Namespace	What it does
sdk.ton	Wallet balance, send TON/jettons, NFTs, transactions, payment verification, utilities
sdk.telegram	Messages, media (photo/video/voice/file/gif/sticker), polls, moderation, gifts, stories, raw GramJS
sdk.secrets	3-tier secret resolution (ENV → secrets store → pluginConfig) — get(), require(), has()
sdk.storage	Key-value store with TTL — no migrate() needed
sdk.db	Isolated SQLite database per plugin (requires migrate() export)
sdk.log	Prefixed logger (info, warn, error, debug)
sdk.config	Sanitized app config (no secrets)
sdk.pluginConfig	Plugin-specific config with defaults from manifest

// Send TON, verify payments, send Telegram messages — all through the SDK
await sdk.ton.sendTON("EQx...", 1.5, "payment for order #42");
const payment = await sdk.ton.verifyPayment({ amount: 1.5, memo: "order-42" });
await sdk.telegram.sendMessage(chatId, "Payment received!");

// New: secrets, storage, media, jettons
const apiKey = await sdk.secrets.require("api_key");
await sdk.storage.set("last_run", Date.now(), 3600);
await sdk.telegram.sendPhoto(chatId, buffer, { caption: "Done!" });
await sdk.ton.sendJetton(jettonMaster, to, amount);

Full SDK reference: CONTRIBUTING.md — Plugin SDK

Troubleshooting

Plugin not loading?

• Check that manifest.json exists and has valid JSON
• Verify the plugin exports tools (array or function): node -e "import('./plugins/name/index.js').then(m => console.log(m.tools))"
• Look for errors in the Teleton console output at startup
• Make sure the plugin folder name matches the id in manifest.json

Common errors:

Error	Cause	Fix
Cannot find module	Missing dependency	Add a package.json — deps are auto-installed at startup
tools is not iterable	tools export is not an array or function	Check your export: export const tools = [...] or export const tools = (sdk) => [...]
Plugin name collision	Two plugins share the same id	Rename one of the plugins in its manifest.json
SDK not available	Using sdk.* without the SDK pattern	Switch to Pattern B: export const tools = (sdk) => [...]

FAQ

Can I use npm packages? Yes. Add a package.json (and package-lock.json) to your plugin folder. Teleton auto-installs dependencies at startup.

How do I store data? Use sdk.db for SQL (requires exporting a migrate(db) function) or sdk.storage for simple key-value pairs with optional TTL.

How do I access TON or Telegram? Use the SDK (Pattern B): export const tools = (sdk) => [...]. Then call sdk.ton.* for wallet/blockchain operations and sdk.telegram.* for messaging.

How do I manage API keys? Declare them in manifest.json with the env field so users know exactly what to set. In your code, use sdk.secrets.require("key_name"). Secrets resolve in order: environment variable → secrets store (/plugin set) → pluginConfig (config.yaml).

Why is my plugin not showing tools? Make sure your tools export is either an array of tool objects or a function that returns one. Each tool needs at least name, description, and execute.

Community

• Telegram Group: questions, plugin ideas, support
• GitHub Issues: bug reports, feature requests
• Contributing Guide: how to build and submit plugins

Contributors

This project exists thanks to everyone who contributes.

Want to see your name here? Check out the Contributing Guide.

License

MIT — use it, fork it, build on it.

---

teleton-plugins — open source plugins for the TON ecosystem

Report Bug · Request Plugin · Contributing Guide