JavaScript · Cryptocurrencies · Cryptography
Overview
Hello everyone! I guess you already know that for about a year now there’s been a boom of mini apps in Telegram everyone tapped on the hamster. Most of these mini apps are related to crypto. Many developers want to provide their users with a wallet inside the app (EVM, TON, Solana, etc.)—basically a virtual account that can be topped up, can withdraw funds, and most importantly, can call smart contracts.
A simple but unsafe solution is to store all the keys on your server and make transactions on behalf of the user. If someone hacks your server, all client funds are lost. It’s hard to earn people’s trust in that scenario.
A complex but inconvenient solution is a wallet that the user must write down on a piece of paper and manage by themselves. In that case, you might as well just use WalletConnect or not build a mini app at all. The problem is that your mini app’s UI could become painful: the user would have to confirm every action in an external app.
We looked for an option for our mini app that offers the security of a non-custodial wallet with the smoothest possible UX/UI. And we found it.
In this article, I’ll review TMA Wallet (npm package, website, GitHub)—an open-source, non-custodial, multi-party wallet suitable for any chain, which works using the recently introduced Telegram Cloud Storage API.
Let’s go!
Very Brief Explanation of Terms
Wallet = Private Key. This private key is used to sign transactions and grants its owner the right to control the funds at a specific blockchain address.
Custodial Wallet = Some organization owns your private key and can act on your behalf. A classic example is a crypto exchange like Binance. It’s convenient but requires great trust in the organization.
Non-custodial Wallet = You alone have your private key. It’s stored on your device, and all actions with your funds are done by you or with your confirmation. The main issue is that it’s easy to lose. If you lose your private key, you lose your funds.
MPC (multi-party computation) = An attempt to solve the “lost wallet” issue: the key is split into several parts, stored in different places, and all parts are needed to form a signature on a transaction. In this scenario, hacking one party doesn’t let you access the user’s funds. Meanwhile, the user doesn’t need to store the key entirely on their own.
So, a non-custodial MPC wallet is a wallet where the private key is split into parts stored in different locations and never fully assembled by any single party.
What Exactly Is TMA Wallet?
TMA Wallet is a non-custodial, multi-party (MPC) wallet that uses Telegram Cloud Storage for secure key storage. Everything is linked to the user’s Telegram account, so they don’t have to remember any seed phrases or set up external wallets. The flow is so smooth that your user might not even realize there’s a crypto wallet under the hood—you can build a completely friendly UI and hide the blockchain magic from the user.
Here are some of the main advantages:
Easy Integration: Just install the npm package, plug it into your code, and that’s it. Every user of your mini app now has a wallet.
No TON Connect or WalletConnect Workarounds: The user stays entirely in Telegram; all transactions are signed “under the hood.”
MPC Technology: The private key isn’t available to anyone—not Telegram, not your server, not TMA Wallet’s servers. It’s only put together on the user’s device for a few nanoseconds (while signing a transaction) and then disappears.
Easy Recovery: Lost your phone? No problem—get a new one, log into Telegram, and the wallet is automatically restored.
Access from Multiple Devices: If the user opens the mini app from a desktop client with the same Telegram account, they’ll get access to the same wallet as on their phone.
Open-Source: Everything is on GitHub. You can review and verify security yourself or commission an audit.
Viem/Wagmi/Ethers.js Support: If you’re working on any EVM-compatible chain (Ethereum, BSC, Polygon, etc.), you can use standard libraries.
Supports Any Chain: EVM chains are supported out of the box, but TMA Wallet is basically a system for separate storage of any secret. So you could store a private key for TON, Solana, or any other chain.
How Does It Work “Under the Hood”?
As I’ve mentioned, TMA Wallet is based on MPC principles, where the private key is effectively shared between multiple parties and only reassembled briefly on the client side to sign transactions. Here’s a short summary:
When the user first opens your mini app, the user’s device generates a ClientPublicKey and ClientSecretKey. The ClientSecretKey is saved in Telegram Cloud Storage.
The ClientPublicKey and
WebApp.initData(signed by Telegram) are sent to the server.The server checks that Telegram’s signature is valid and (optionally) asks the user for extra authentication (2FA). It’s optional, and you don’t have to if you don’t want to.
The server then generates an IntermediaryKey by signing (ClientPublicKey + telegramUserId) with its own ServerSecretKey. Then it encrypts this IntermediaryKey before sending it back to the client.
The IntermediaryKey returns to the client and is decrypted there.
Finally, the client signs the IntermediaryKey with ClientSecretKey, resulting in the WalletPrivateKey (the actual private key of the wallet).
This key is used to sign the transaction and is never saved anywhere long term. For each new action, that chain of steps (except step 1) is repeated.
In the end, the app’s UX looks perfect: login is seamless thanks to auto-auth in mini apps, and transactions are seamless because there’s an in-app wallet.
How to Add It to Your Mini App?
- Install the SDK:
npm install --save @tmawallet/sdk
- Initialize the key in your code:
import { TMAWalletClient } from '@tmawallet/sdk';
import { ethers } from 'ethers';
// Don't forget to sign up at dash.tmawallet.com
const myApiKey = '1234567812345678'; // Your API key
const client = new TMAWalletClient(myApiKey);
// Authorize the user and create/load their wallet
await client.authenticate();
console.log('Your wallet address: ', client.walletAddress);
- Example of making a transaction (here using Ethers.js):
// Use TMA Wallet as the "signer" for ethers
const provider = new ethers.JsonRpcProvider();
const signer = client.getEthersSigner(provider);
const tx = await signer.sendTransaction({
to: '0x...',
value: ethers.parseEther('1.0'),
});
console.log('Transaction hash:', tx.hash);
And that’s it.
FAQ
Below are questions (slightly edited) from TMA Wallet’s README, with their answers:
Is this definitely secure?
Yes, that’s the core idea. Thanks to the MPC protocol, neither TMA Wallet’s servers, Telegram, nor you have full access to the private key—only the user does.
Do I have to give you access to my bot’s token?
No. We’re one of the first to support Telegram’s new asymmetric signature scheme. We only need your bot’s ID, which is already public.
Which blockchain can be supported?
Any. EVM blockchains (Ethereum, etc.) work out of the box with ethers.js. For something custom, you can use the accessPrivateKey method.
What if the user loses their device?
As long as they have access to their Telegram account, they just log in on a new device, and the wallet is restored automatically. No seed phrase is required.
Can I back up the key?
Technically yes, but you probably don’t need to. The wallet can already be restored through Telegram. If you want, you can let the user back it up, but that’s at your own risk.
Conclusion
We used TMA Wallet in two of our own apps. One is already in production (I was a bit shy to post the link at the start, but I think it’s okay to mention here in the footer: Only100x).
It’s a great option for anyone building Telegram mini apps who wants to give users a secure wallet without messing up the UX with external connectors.
Feel free to try it and explore the documentation. All the project’s code is open on GitHub. Good luck!
Tags:
telegram mini app · crypto · non-custodial wallet · tma wallet
Top comments (0)