Compatibility policy

The target SDK version and plugin status are declared once in compatibility.json. Only supported marketplace plugins are generated into registry.json.

Legacy source remains available for migration and audit history, but quarantined plugins are not offered through the WebUI marketplace. This prevents SDK v2 from installing plugins that depend on removed raw Telegram access or direct wallet mnemonic access.

Status	Plugins	Meaning
SDK v2 supported	24	Loads against SDK v2; 22 marketplace plugins plus 2 examples
Quarantined	2	Preserved in source, rejected by SDK v2 and excluded from the marketplace
Total	26	193 tools

SDK v2 marketplace

Plugin	Tools	Description
boards	9	Browse and participate in the boards.ton decentralized forum using x402 TON micropayments
casino	4	Slot machine and dice games with TON payments and auto-payout
crypto-prices	2	Real-time cryptocurrency prices and comparison via CryptoCompare API
dedust	8	Swap tokens, browse pools, and trade on DeDust -- TON's #2 DEX
deezer	1	Search and send music tracks via Telegram's @DeezerMusicBot inline bot (Deezer)
dyor	11	TON token analytics from DYOR.io -- search, price, trust score, metrics, DEX trades, holders, pools
fragment	6	Search and browse Telegram's NFT marketplace — usernames, numbers, collectible gifts, auction history
geckoterminal	10	TON DEX pool and token data -- trending, new, and top pools, trades, OHLCV, token info, batch prices
giftindex	6	GiftIndex ODROB trading with workflow guardrails - monitor, analyze and trade the Telegram Gifts index on TON. Owner-only, corridor-enforced, post-trade verified.
giftstat	11	Telegram gift market data -- collections, floor prices, models, stats, history
multisend	5	Batch send TON and jettons to up to 254 recipients through Teleton's protected Highload Wallet v3 broker
pic	1	Search and send images via Telegram's @pic inline bot (Yandex Image Search)
sbt	2	Deploy and mint Soulbound Tokens (TEP-85) on TON
stonfi	8	Swap tokens, browse pools, and farm on StonFi DEX -- the largest DEX on TON
stormtrade	13	Trade perpetual futures on Storm Trade DEX — crypto, stocks, forex, commodities
swapcoffee	6	Swap tokens on TON via swap.coffee aggregator - best rates across all DEXes
tonapi	20	TON blockchain data from TONAPI -- accounts, jettons, NFTs, prices, transactions, traces, DNS, staking
twitter	24	X/Twitter API v2 — read (search, lookup, trends) + write (post, like, retweet, follow) with OAuth 1.0a
uranus	13	Inspect, quote, trade and launch Uranus Meme tokens on TON through the protected Teleton SDK transaction broker.
vid	1	Search and send YouTube videos via Telegram's @vid inline bot
weather	2	Current weather and 7-day forecast via Open-Meteo API
webdom	11	Buy, sell, auction, and manage .ton domains and Telegram usernames on webdom.market

Development examples are available in plugins/example and plugins/example-sdk, but are intentionally not marketplace entries.

Quarantined legacy plugins

Plugin	Blocker
gaspump	Legacy SDK v1 plugin retained for older Teleton agents; raw bridge and wallet access are incompatible with SDK v2.
voice-notes	Legacy SDK v1 plugin retained for older Teleton agents; raw Telegram client access is incompatible with SDK v2.

Plugins listed in this section declare an incompatible SDK range, so the runtime rejects them before registering tools. They return to the marketplace only after migration to public SDK capabilities.

Install

Use the Teleton WebUI marketplace for supported plugins:

teleton start --webui

For local development, copy a supported plugin into the agent data directory and restart Teleton:

cp -R plugins/weather ~/.teleton/plugins/
teleton start

Do not manually install quarantined plugins into an SDK v2 runtime.

Build a plugin

A plugin is an ESM directory with three required files:

plugins/my-plugin/
├── index.js
├── manifest.json
└── README.md

Use a static tools array for pure local logic or external API reads. Use tools(sdk) when the plugin needs public TON, Telegram, storage, secrets or logging capabilities.

export const manifest = {
  name: "my-plugin",
  version: "1.0.0",
  sdkVersion: "^2.0.0",
  description: "Example SDK v2 plugin",
};

export const tools = (sdk) => [
  {
    name: "my_plugin_balance",
    description: "Read the configured TON wallet balance",
    scope: "admin-only",
    category: "data-bearing",
    parameters: { type: "object", properties: {} },
    async execute() {
      const balance = await sdk.ton.getBalance();
      return { success: true, data: balance };
    },
  },
];

The following are forbidden in SDK v2 plugins:

• sdk.telegram.getRawClient();
• context.bridge or ctx.bridge;
• reading wallet.json or a mnemonic;
• undeclared secrets or environment-variable scraping;
• dependencies without a committed lockfile.

See CONTRIBUTING.md for the complete contribution contract and the SDK README for the public API.

Validate the complete catalog

Node 22.22.2, 24.15.0, or a supported newer release is required.

npm ci --ignore-scripts
npm run install:plugins
npm run validate
npm test
npm --prefix ../teleton-agent run build:sdk
npm run validate:runtime
npm run audit:plugins

Runtime validation imports every plugin against the sibling ../teleton-agent SDK checkout, compares runtime tools with manifests, and rejects duplicate or malformed tools. CI runs the same checks on Node 22 and Node 24.

Security model

• Plugins receive sanitized configuration and an isolated database.
• Secrets must be declared and accessed through sdk.secrets.
• Marketplace actions are treated as external actions by Teleton and require explicit approval.
• SDK v2 capability boundaries are mandatory; manifest permissions cannot restore removed raw APIs.
• npm lifecycle scripts are disabled when plugin dependencies are installed.
• HIGH and CRITICAL dependency vulnerabilities fail CI.

License

MIT