A fast, enterprise-grade TON wallet connector for the browser.
TBridge is a pure TypeScript SDK for discovering wallets, establishing encrypted sessions, and requesting transfers / signatures on TON. It is framework-agnostic (React, Vue, Svelte, or vanilla), ships an optional vanilla UI, and is built for production dApps and Telegram Mini Apps.
| Package | @tbridge/sdk |
| Runtime | Browser only |
| Language | TypeScript → ESM |
| Crypto | NaCl box via tweetnacl (overridable) |
| License | MIT |
- Protocol-complete — injected JS bridge and remote HTTP/SSE bridge; connect, restore, disconnect,
sendTransaction,signData - Secure by default — safe JSON parse, HTTPS manifest policy, origin-bound sessions, rate-limited RPC, AES-GCM at-rest storage for persisted data
- TMA-aware —
web_app_open_link/web_app_open_tg_linkfor real Mini Apps; safe fallbacks for Telegram in-app browser and mobile web - Smart open policy — auto-open on mobile; on desktop auto-open only for Telegram Wallet inside Telegram; otherwise QR + Open in wallet
- UI included — modal, wallet grid, always-on QR, i18n (EN/RU), light/dark theme, branding, inline CSS
- Framework-agnostic — no React/Vue runtime dependency
pnpm add @tbridge/sdk
# or: npm install @tbridge/sdk
# or: yarn add @tbridge/sdkRequires a modern browser with fetch, EventSource, and Web Crypto (crypto.subtle / getRandomValues).
Not a Node.js runtime library.
Host a TON Connect–compatible manifest at a public HTTPS URL:
{
"url": "https://your-app.example",
"name": "Your App",
"iconUrl": "https://your-app.example/icon-180.png",
"termsOfUseUrl": "https://your-app.example/terms",
"privacyPolicyUrl": "https://your-app.example/privacy"
}Pass that URL as manifestUrl when creating the client.
import { createTBridge, connectWithUi } from '@tbridge/sdk';
const bridge = createTBridge({
manifestUrl: 'https://your-app.example/tonconnect-manifest.json',
// walletsRegistry: 'https://config.ton.org/wallets-v2.json', // optional override
locale: 'en', // 'en' | 'ru'
theme: 'dark', // 'dark' | 'light'
// sessionPersistence: 'local', // default — survives Mini App / tab close
});
// Restore previous HTTP session when possible
await bridge.restoreConnection();
if (!bridge.isConnected) {
await connectWithUi(bridge);
// tonProofPayload is optional param
// await connectWithUi(bridge, { tonProofPayload });
}
bridge.on('statusChange', (status) => {
console.log(status);
});
await bridge.sendTransaction({
validUntil: Math.floor(Date.now() / 1000) + 300,
messages: [{ address: 'EQ...', amount: '100000000' }],
});
await bridge.disconnect();const wallets = await bridge.getWallets();
const wallet = wallets.find((w) => w.app_name === 'tonkeeper');
await bridge.connect({
appName: wallet!.app_name,
onConnectLink: (link) => {
// Show your own QR / open logic
window.open(link, '_blank', 'noopener,noreferrer');
},
});No extra Telegram SDK is required. TBridge detects a real Mini App (initData / tgWebApp* params) and opens:
t.melinks viaweb_app_open_tg_link- external wallet HTTPS links via
web_app_open_link/Telegram.WebApp.openLink
Telegram in-app browser (not a Mini App) uses normal navigation helpers so the dApp page and SSE stay alive.
await connectWithUi(bridge, {
locale: 'ru',
theme: 'dark',
});bridge.setTheme('light');
bridge.setLocale('ru');| Environment | Auto-open wallet link | Waiting UI |
|---|---|---|
| Mobile browser / Telegram in-app browser / mobile Mini App | Yes | QR + Open + Copy |
| Desktop (browser) | No (use Open in wallet or scan QR) | QR + Open + Copy |
| Desktop Telegram + Telegram Wallet | Yes | QR + Open + Copy |
Force QR-only (never auto-open):
await connectWithUi(bridge, { preferQr: true });Wallet icons are prefetched in the background after registry load (HTTP cache warm-up). Modal icons use loading="eager".
| Option | Required | Description |
|---|---|---|
manifestUrl |
yes | HTTPS URL of your app manifest |
walletsRegistry |
no | Custom wallets JSON URL (strict-parsed). Default: official TON list |
storage |
no | Custom StorageAdapter (default: encrypted localStorage) |
crypto |
no | Custom CryptoProvider (default: tweetnacl) |
network |
no | 'mainnet' | 'testnet' |
requestTimeoutMs |
no | RPC timeout |
sessionMaxAgeMs |
no | Max age for restore (default 7 days) |
sessionPersistence |
no | 'local' (default, durable) | 'session' (tab-scoped secret) |
theme |
no | 'light' | 'dark' |
locale |
no | 'en' | 'ru' |
debug |
no | Safe debug logs (never secrets) |
allowInsecureManifest |
no | Dev only — allow non-HTTPS manifest |
| Method | Description |
|---|---|
restoreConnection() |
Restore HTTP session if persisted secret is available |
connect({ appName, onConnectLink?, tonProofPayload? }) |
Connect to a wallet |
disconnect() |
End session and clear persisted data |
destroy() |
Release listeners / in-memory session (does not clear storage) |
getWallets() |
Parsed registry list (triggers icon prefetch) |
detectInjected() |
Injected provider, if any |
sendTransaction(tx) |
Request transfer |
signData(payload) |
Request data signature |
on / once |
Events |
setTheme / setLocale |
UI preferences |
getTheme / getLocale |
Current UI preferences |
High-level UI:
import { connectWithUi, openWalletModal } from '@tbridge/sdk';bridge.on('statusChange', (status) => {
/* disconnected | connecting | connected */
});
bridge.on('bridgeHealth', (health) => {
/* connected | reconnecting | offline */
});
bridge.on('disconnect', ({ reason }) => {
/* wallet | local | session_expired | user_cancel */
});- Session persistence (default
local) — HTTP session material is stored via the storage adapter so Mini App / tab relaunch can restore. UsesessionPersistence: 'session'for stricter tab-scoped secrets (worse UX on close). - At-rest encryption — default
LocalStorageAdapterstores values as AES-GCM blobs (enc:v1:…). Optional host secret:globalThis.__TBRIDGE_STORAGE_SECRET__(strong random string at bootstrap). Without it, the key is derived from the page origin — this obfuscates storage, it does not protect against same-origin XSS. - Threat model — treat XSS on the dApp origin as full session compromise. Enforce a strict CSP on the host app.
- Manifest URL must be HTTPS outside localhost.
- Wallet icons —
httpsonly (http allowed on localhost). - RPC is rate-limited; bridge
fetchusescredentials: 'omit'. - Call
disconnect()on logout;destroy()only tears down the instance.
pnpm add @tbridge/sdkimport { createTBridge, connectWithUi } from '@tbridge/sdk';Repository: advanceddev/tbridge-sdk
MIT © Ivan Lomovtcev