teleton-plugins

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

</div>

<details> <summary><strong>Table of Contents</strong></summary>

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

</details>

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

Option 1 — WebUI Marketplace (recommended)

teleton start --webui

Open the WebUI in your browser, go to Plugins > Marketplace tab, and install any community plugin with one click. No manual copy, no git clone — browse, install, done.

Option 2 — Manual install

# 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. ESM only.

plugins/your-plugin/
├── index.js         # exports tools[] or tools(sdk)
├── manifest.json    # registry metadata (marketplace, discovery)
└── README.md        # documentation

Pattern A — Simple (static array)

For plugins that only call external APIs and return data to the LLM. No TON, no Telegram messaging, no state.

// index.js
export const tools = [
  {
    name: "myplugin_search",
    description: "Search for something — the LLM reads this to decide when to call the tool",
    parameters: {
      type: "object",
      properties: {
        query: { type: "string", description: "Search query" },
      },
      required: ["query"],
    },
    execute: async (params, context) => {
      try {
        const res = await fetch(`https://api.example.com/search?q=${encodeURIComponent(params.query)}`, {
          signal: AbortSignal.timeout(15_000),
        });
        if (!res.ok) return { success: false, error: `API returned ${res.status}` };
        const data = await res.json();
        return { success: true, data };
      } catch (err) {
        return { success: false, error: String(err.message || err).slice(0, 500) };
      }
    },
  },
];

Pattern B — SDK plugin (function)

For plugins that need TON blockchain, Telegram messaging, database, inline bot mode, or secrets. Export tools as a function that receives the SDK, and add an inline manifest for runtime config:

// index.js
export const manifest = {
  name: "my-plugin",
  version: "1.0.0",
  sdkVersion: ">=1.0.0",
  description: "What this plugin does",
  defaultConfig: { threshold: 50 },
  // bot: { inline: true, callbacks: true },  // uncomment for inline mode
};

// Optional: enables sdk.db (isolated SQLite per plugin)
export function migrate(db) {
  db.exec(`CREATE TABLE IF NOT EXISTS scores (
    user_id TEXT PRIMARY KEY,
    points INTEGER NOT NULL DEFAULT 0
  )`);
}

export const tools = (sdk) => [
  {
    name: "myplugin_balance",
    description: "Check TON wallet balance and current price",
    parameters: { type: "object", properties: {} },
    scope: "dm-only",         // "always" | "dm-only" | "group-only" | "admin-only"
    category: "data-bearing", // "data-bearing" (reads) | "action" (writes)
    execute: async (params, context) => {
      try {
        const balance = await sdk.ton.getBalance();
        const price = await sdk.ton.getPrice();
        sdk.log.info(`Balance: ${balance?.balance ?? "unknown"} TON`);
        return {
          success: true,
          data: {
            balance: balance?.balance,
            usd: price?.usd,
          },
        };
      } catch (err) {
        return { success: false, error: String(err.message || err).slice(0, 500) };
      }
    },
  },
];

// Optional lifecycle hooks
export async function start(ctx) { /* ctx.bridge, ctx.db, ctx.config, ctx.pluginConfig, ctx.log */ }
export async function stop() { /* cleanup timers, connections */ }

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

Two manifests

Plugins have two manifest sources with different roles:

| File | Purpose | Required | |------|---------|----------| | manifest.json | Registry & marketplace (discovery, listing, metadata) | Yes | | export const manifest in index.js | Runtime config (SDK version, defaults, secrets, bot) | Only for Pattern B |

manifest.json (for registry):

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "description": "One-line description",
  "author": { "name": "your-name", "url": "https://github.com/your-name" },
  "license": "MIT",
  "entry": "index.js",
  "teleton": ">=1.0.0",
  "tools": [{ "name": "myplugin_balance", "description": "Check TON balance" }],
  "permissions": [],
  "tags": ["defi", "ton"]
}

Add "sdkVersion": ">=1.0.0" for P

Teleton Plugins

Install / Use

README