SDK Overview

@tma.sh/sdk provides everything you need to build authenticated, payment-ready Telegram Mini Apps. Install one package and get auth validation, signed JWTs, TON and Stars payments, and key-value storage — all wired to your TMA.sh project automatically.

Installation

bun add @tma.sh/sdk

Quick start

import { createTMA } from '@tma.sh/sdk';

const tma = createTMA({ projectId: 'your-project-id' });

// Authenticate the user
const { user, jwt } = await tma.auth.validate(
  window.Telegram.WebApp.initData,
  'your-project-id'
);

// Use KV storage
await tma.kv.set('key', { value: 'data' });
const data = await tma.kv.get('key');

// Auto-authenticated fetch (injects JWT Authorization header)
const response = await tma.fetch('/api/profile');

createTMA() takes a config object with your projectId. On any *.tma.sh deployment, the SDK uses this to connect to the correct project backend.

Package exports

The SDK ships multiple entry points so you only import what you need:

Import	Purpose
@tma.sh/sdk	Core client — auth, payments, KV storage
@tma.sh/sdk/react	React hooks and providers
@tma.sh/sdk/svelte	Svelte reactive stores
@tma.sh/sdk/bot	Bot handler utilities (defineBot, session middleware)
@tma.sh/sdk/server	Server-side helpers for API routes

The core package is framework-agnostic. Use it directly in any JavaScript project. The framework-specific entry points (/react, /svelte) provide idiomatic bindings that handle loading states, reactivity, and error handling for you. The /bot entry point provides utilities for building Telegram bot handlers with session middleware.

The /server entry point is designed for API routes — Hono handlers that run on the edge. It includes auth middleware, a typed KV wrapper, and initData validation utilities.

What’s inside

Authentication

Validate Telegram users with a single call. The SDK verifies initData via HMAC-SHA256 and returns a signed JWT that works with any backend — Supabase, Firebase, Turso, or your own.

See Authentication for details.

Payments

Accept Telegram Stars payments with a single call via tma.payments.stars.pay(). The SDK handles invoice creation through the platform (no bot token needed client-side) and opens the native Telegram payment sheet. TON Connect cryptocurrency payments are also supported via @tonconnect/ui.

See Payments for details.

KV Storage

Simple key-value storage scoped to your project. Store JSON-serializable values up to 128 KB per key. No database setup, no connection strings.

See KV Storage for details.

Server Helpers

Auth middleware, typed KV bindings, and initData validation for your Hono API routes. Everything you need to build authenticated server-side logic.

See Server Helpers for details.