Telegram Mini-App Quickstart

Quickstart: Implementing Particle Auth within Telegram Mini-Apps

Particle Network’s Smart Wallet-as-a-Service (MPC-based wallets alongside account abstraction) natively supports integration within Telegram Mini-apps, using a users Telegram account to create and use an embedded wallet.

Getting up and running with Particle Network’s Smart Wallet-as-a-Service within your Telegram Mini-app takes less than 5-minutes.

This guide provides a step-by-step walkthrough on setting up Particle Auth in a Telegram Mini-app, enabling you to leverage features like social logins, smart accounts, and gasless transactions.

Note that due to limitations of Telegram’s in-app browser (WebView), only email login, SMS login, and embedded wallets are supported within Telegram mini-apps.

For detailed documentation on Particle’s various SDKs, refer to the “SDKs and APIs” pages.

Guide 1: Using the starter repository

This is the fastest and recommended way to start.

Set up a Telegram Bot and Mini-app

Before you begin, you must create a Telegram Bot and Mini-app.

Follow this comprehensive guide to set them up. You can pause at the step where a URL is required, as you’ll need to deploy your app first.

Clone and set up the TG Mini-app starter

The fastest way to set up a Telegram Mini-app with Particle is to use the starter repository. This repository provides a pre-configured Telegram Mini-app that already includes the Particle Wallet and Account Abstraction functionality, providing a straightforward foundation for building your own Mini-app.

To get started, clone the repository:

git clone https://github.com/Particle-Network/tg-miniapp-particle-starter.git

Then install the dependencies:

Terminal

yarn

This will initialize a Telegram Mini-app with the following features:

Technology Stack:
- @telegram-apps/create-mini-app
- Next.js
- TypeScript
- Tailwind CSS
- Particle Auth SDK
- Particle AA SDK
- ethers.js
Main Features:
- User Authentication: Seamless login using Telegram through Particle Auth.
- Wallet Information Display: Wallet information is loaded and displayed in-app.
- Gasless Transactions: To exemplify the possible functionality here between Particle Auth and its AA SDK, users can send gasless transactions of native tokens to any address.

Mini-app development

To start developing your Telegram Mini-app, it’s essential to understand the key files in the project. These files form the backbone of the app’s structure and are where you will make customizations and add new features:

/src/components/Root/index.tsx: The Root component establishes the main environment for the app by configuring Particle Auth, binding theme and viewport CSS variables, and managing application states through nested providers and hooks.
Edit this file to customize the Particle Auth configuration and modify global app settings.
/src/app/layout.tsx: This file defines the root layout of the Telegram Mini-app, setting global metadata, applying styles, and ensuring a responsive design by wrapping the app’s content in the Root component with proper viewport configuration.
/src/components/Home/index.tsx: The Home component manages the user interface, handling wallet connections, initializing smart accounts, and navigating through tabs.
This is where you configure the Smart Account settings (such as the type of account contract, the supported chains, and so on), customize the app’s header, and manage interactive components within the tabs.
/src/components/EVMDemo/index.tsx: In this demo, the EVMDemo component enables users to interact with EVM-compatible blockchains via a smart account, making gasless native token transfers (Solana is also supported, just not by default within this starter).
Modify this file to add new features or change how blockchain interactions are displayed, as it is imported into the Home component’s tabs.

Configuring Particle Auth

Particle Auth requires three key values to be initiated: projectId, clientKey, and appId. These values link your Telegram Mini-app with the Particle dashboard.

To retrieve these values for configuration within your application, follow these steps:

For more information on the Particle dashboard, take a look at this video or visit the dashboard quickstart

Once you have retrieved your projectId, clientKey, and appId, add them to a .env file located in the root of your project with the following content:

.env

NEXT_PUBLIC_PROJECT_ID='PROJECT_ID'
NEXT_PUBLIC_CLIENT_KEY='CLIENT_KEY'
NEXT_PUBLIC_APP_ID='APP_ID'

Run the Mini-app

Although it is possible to run the application outside of Telegram, it is recommended to develop it within Telegram for the most accurate representation of its real-world functionality.

To run the application inside Telegram, @BotFather requires an exposed link. Deploy the app in Vercel or expose your HTTP development server using Ngrok.

If you use Ngrok, run the application locally with:

yarn dev

Now you can use the URL of your app to complete the configuration from @BotFather (as a reminder, you can now return to this step from the Telegram documentation).

Guide 2: Start from scratch

This section provides guidance on how to start building your own Telegram Mini-app from scratch.

Create a Mini-app

To create a new Mini-app, use the @telegram-apps/create-mini-app package. This starter project is built with the default options along with Next.js integration.

Install Additional Packages

Install the required packages using Yarn:

yarn add @particle-network/aa @particle-network/auth-core-modal blo ethers framer-motion sonner eruda

Add Context Directory

Create a context directory in the src folder and add an index.tsx file. You can find the code for this file in the starter repository.

Configure Particle Auth

In the components/Root directory, rename your main component file to index.tsx. Configure the AuthCoreContextProvider to wrap the AppProvider as follows:

<AuthCoreContextProvider
  options={{
    projectId: process.env.NEXT_PUBLIC_PROJECT_ID as string,
    clientKey: process.env.NEXT_PUBLIC_CLIENT_KEY as string,
    appId: process.env.NEXT_PUBLIC_APP_ID as string,
    themeType: "dark",
    // Define UI elements for the smart account
    erc4337: {
      name: "SIMPLE",
      version: "2.0.0",
    },
    wallet: {
      themeType: "dark",
      customStyle: {
        // Locks the chain selector to IoTeX mainnet and testnet
        supportChains: [EthereumSepolia, BaseSepolia],
        dark: {
          colorAccent: "#7DD5F9",
          colorPrimary: "#21213a",
          colorOnPrimary: "#171728",
          primaryButtonBackgroundColors: ["#5ED7FF", "#E89DE7"],
          primaryIconButtonBackgroundColors: ["#5ED7FF", "#E89DE7"],
          primaryIconTextColor: "#FFFFFF",
          primaryButtonTextColor: "#0A1161",
          cancelButtonBackgroundColor: "#666666",
          backgroundColors: [
            "#14152e",
            [
              ["#e6b1f766", "#e6b1f700"],
              ["#7dd5f94d", "#7dd5f900"],
            ],
          ],
          messageColors: ["#7DD5F9", "#ed5d51"],
          borderGlowColors: ["#7bd5f940", "#323233"],
          modalMaskBackgroundColor: "#141430b3",
        },
      },
    },
  }}
>
  <Toaster
    /* This component displays notifications. */
    richColors
    position="top-left"
    expand={false}
    closeButton
    duration={2000}
  />
  <AppProvider>
    <div className="box-border w-screen">{props.children}</div>
  </AppProvider>
</AuthCoreContextProvider>

You can find the complete implementation of the Root component in the starter repository.

Build the Mini-app

Edit the layout.tsx and page.tsx files in the src/app directory to reflect the reference files in the starter repository.

Once configured, create a Home component to implement your Mini-app.

Example Implementation (AA)

The Particle Network AA SDK allows you to set up and configure smart accounts. Here’s an example:

import { SmartAccount } from '@particle-network/aa';
import { useEthereum } from "@particle-network/auth-core-modal";
import { BaseSepolia } from '@particle-network/chains';

const { provider } = useEthereum();

// Set up and configure the smart account
const smartAccount = new SmartAccount(provider, {
  projectId: process.env.NEXT_PUBLIC_PROJECT_ID!,
  clientKey: process.env.NEXT_PUBLIC_CLIENT_KEY!,
  appId: process.env.NEXT_PUBLIC_APP_ID!,
  aaOptions: {
    accountContracts: {
      SIMPLE: [
        {
          version: '2.0.0',
          chainIds: [BaseSepolia.id],
        },
      ],
    },
  },
});

In this setup:

SmartAccount: This class is used to create a smart account utilizing an instance of SimpleAccount.
aaOptions: This field specifies the version and chain IDs for the account contracts, allowing you to configure the smart account with specific blockchain settings. Here, we’re using version 2.0.0 of SimpleAccount and targeting the Base testnet (Sepolia) chain.

Find the full implementation of the Home component and set up in the starter repository.

GETTING STARTED

WALLET-AS-A-SERVICE

ACCOUNT ABSTRACTION

CONFIGURATION

Quickstart: Implementing Particle Auth within Telegram Mini-Apps

Guide 1: Using the starter repository

Guide 2: Start from scratch

Create a Mini-app

Install Additional Packages

Add Context Directory

Configure Particle Auth

Build the Mini-app

Example Implementation (AA)

GETTING STARTED

WALLET-AS-A-SERVICE

ACCOUNT ABSTRACTION

CONFIGURATION

​Quickstart: Implementing Particle Auth within Telegram Mini-Apps

​Guide 1: Using the starter repository

​Guide 2: Start from scratch

​Create a Mini-app

​Install Additional Packages

​Add Context Directory

​Configure Particle Auth

​Build the Mini-app

​Example Implementation (AA)

Quickstart: Implementing Particle Auth within Telegram Mini-Apps

Guide 1: Using the starter repository

Guide 2: Start from scratch

Create a Mini-app

Install Additional Packages

Add Context Directory

Configure Particle Auth

Build the Mini-app

Example Implementation (AA)