Telegram SDK - Positronic Blockchain

How It Works

Your Telegram Mini App game connects to Positronic via a simple JavaScript SDK. Players automatically get a blockchain wallet when they first play. Game events are validated by AI, and legitimate play earns ASF coins.

1

Player opens your Mini App in Telegram

2

SDK auto-detects Telegram user & creates wallet

3

Player plays your game, events are tracked

4

Session submitted → AI validates for cheating

5

Legitimate play earns ASF coins to player's wallet

Quick Start

Register Your Game

Call positronic_registerGame to register your game on the blockchain. You'll receive a game_id and api_key. Your game enters a review queue (AI + governance council).

Add the SDK

Include the Positronic Telegram SDK in your Mini App HTML:

<script src="https://cdn.positronic-ai.network/sdk/positronic-telegram.js"></script>

Initialize

const game = new PositronicTelegram({
  rpcUrl: 'https://rpc.positronic-ai.network',
  gameId: 'your-game-id',
  apiKey: 'gk_your_api_key'
});

// Auto-detects Telegram user, creates wallet
const { wallet, isNew } = await game.init();

Track Gameplay & Earn

// Start a session when player begins playing
const session = await game.startSession();

// Track game events as they happen
session.trackEvent('kill_enemy', { enemy: 'boss', score: 500 });
session.trackEvent('collect_item', { item: 'gem', value: 100 });
session.trackEvent('complete_level', { level: 3 });

// Submit when round/level ends — AI validates and calculates reward
const result = await session.submit({ score: 15000, level: 3 });

// Show reward using Telegram's native popup
game.showReward(result.reward);

SDK Methods

PositronicTelegram

Method	Returns	Description
`init()`	`Promise<{wallet, isNew}>`	Initialize SDK, detect Telegram user, create/get wallet
`startSession(proofType?)`	`Promise<Session>`	Start a new game session for current player
`showReward(reward)`	`void`	Show reward popup via Telegram WebApp API
`showPopup(title, msg)`	`void`	Show popup via Telegram WebApp API
`getGameInfo()`	`Promise<GameInfo>`	Get your game's blockchain info
`getMiningRate()`	`Promise<MiningRate>`	Current mining rate and daily cap
`getPlayerHistory(limit?)`	`Promise<Session[]>`	Player's past sessions
`getWalletInfo()`	`Promise<UserInfo>`	Telegram user's wallet info and stats

TelegramGameSession

Method	Returns	Description
`trackEvent(type, data?)`	`void`	Track a game event (auto-batched every 10 events)
`submit(metrics)`	`Promise<Result>`	Submit session for AI validation and reward
`getStatus()`	`Promise<Status>`	Check current session status
`.elapsed`	`number`	Seconds since session started

Event Types

Track these events during gameplay for accurate AI validation and reward calculation:

Event	Description	Example Data
`kill_enemy`	Player defeated an enemy	`{ enemy: 'dragon', score: 500 }`
`collect_item`	Item collected	`{ item: 'gem', value: 100 }`
`complete_level`	Level completed	`{ level: 3, time: 120 }`
`take_damage`	Player took damage	`{ amount: 25 }`
`use_skill`	Skill/ability used	`{ skill: 'fireball' }`
`craft_item`	Item crafted	`{ item: 'sword', materials: 3 }`
`trade`	Player traded	`{ gave: 'gold', got: 'potion' }`
`achievement`	Achievement unlocked	`{ name: 'First Blood' }`

Reward System

🪙

Player Daily Cap

Each player can earn up to 50 ASF/day per game. Resets every 24 hours.

🎮

Game Daily Cap

Each game has a total daily emission cap (default 10,000 ASF/day). Customizable when registering.

🤖

AI Validation

Every session is validated by AI anti-cheat. Suspicious play gets 50% reduced reward. Detected cheating gets 0.

⭐

Trust Score

Games start at trust score 100. Low cheat rates increase your multiplier up to 2x. Cheating drops it fast.

Reward Formula

reward = base_reward * scarcity_factor * trust_multiplier * skill_factor

  base_reward      — Set per game (depends on game type and daily cap)
  scarcity_factor  — 1.0x when supply available, decreasing as pool empties
  trust_multiplier — Game's trust score (100 = 1.0x, max 2.0x)
  skill_factor     — Player's score-based multiplier (max 3.0x)

Telegram RPC Methods

These methods are available in addition to the 24 Game Bridge methods. See full API docs for all methods.

Method	Access	Description
`positronic_telegramAuth`	Public	Authenticate Telegram user, get/create wallet
`positronic_telegramGetWallet`	Public	Get wallet info for Telegram user
`positronic_telegramGetStats`	Public	Get Telegram bridge statistics
`positronic_telegramRegisterBot`	Admin	Register Telegram bot token for a game

positronic_telegramAuth

// Request
{
  "jsonrpc": "2.0",
  "method": "positronic_telegramAuth",
  "params": [12345678, "username", "First Name"],
  "id": 1
}

// Response
{
  "result": {
    "success": true,
    "wallet_address": "0x1a2b3c...",
    "is_new": true,
    "telegram_id": 12345678
  }
}

positronic_telegramGetWallet

// Request
{
  "jsonrpc": "2.0",
  "method": "positronic_telegramGetWallet",
  "params": [12345678],
  "id": 1
}

// Response
{
  "result": {
    "telegram_id": 12345678,
    "username": "player1",
    "wallet_address": "0x1a2b3c...",
    "total_sessions": 42,
    "total_earned": 1500000000000000000000
  }
}

Full Example: Telegram Clicker Game

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My ASF Clicker</title>
  <script src="https://telegram.org/js/telegram-web-app.js"></script>
  <script src="https://cdn.positronic-ai.network/sdk/positronic-telegram.js"></script>
</head>
<body>
  <h1>Tap to Mine ASF!</h1>
  <p>Score: <span id="score">0</span></p>
  <button id="tap" style="font-size:48px;padding:40px">🪙</button>
  <p id="status">Loading...</p>

  <script>
  (async function() {
    // 1. Initialize SDK
    const game = new PositronicTelegram({
      rpcUrl: 'https://rpc.positronic-ai.network',
      gameId: 'my-clicker-v1',
      apiKey: 'gk_your_api_key_here'
    });

    const { wallet, isNew } = await game.init();
    document.getElementById('status').textContent =
      isNew ? 'New wallet created!' : 'Welcome back!';

    // 2. Start session
    const session = await game.startSession();
    let score = 0;

    // 3. Track taps
    document.getElementById('tap').onclick = function() {
      score += 10;
      document.getElementById('score').textContent = score;
      session.trackEvent('collect_item', { item: 'coin', value: 10 });
    };

    // 4. Submit after 60 seconds
    setTimeout(async function() {
      const result = await session.submit({ score: score, level: 1 });
      game.showReward(result.reward);
    }, 60000);
  })();
  </script>
</body>
</html>

Game Registration Flow

Register

Call positronic_registerGame with your game name, type (SDK_INTEGRATED for Telegram), and description. You receive a game_id and api_key.

AI Review

Your game is automatically reviewed by 4 AI models for risk assessment. Low-risk games pass quickly.

Council Vote

Governance council members vote on your game. Requires 3+ votes with 60% approval.

Activation

Once approved, your game goes ACTIVE. Players can now start earning ASF.

FAQ

Do players need a crypto wallet?

No. The SDK automatically creates a Positronic wallet for each Telegram user when they first play. Zero setup needed.

How do players withdraw their ASF?

Players can connect their auto-created wallet to the Positronic Web Wallet to manage their tokens.

What happens if players cheat?

AI validates every session. Suspicious patterns get 50% reduced rewards. Detected cheating gets zero. Games with high cheat rates lose trust score and may be suspended.

How much can players earn?

Default: up to 50 ASF per player per day per game. The reward depends on play quality, game trust score, and overall scarcity.

Is there a cost to integrate?

No. Registration is free. There are no fees for using the Game Bridge or Telegram SDK.

Can I use the SDK outside Telegram?

Yes. The SDK works in any browser. Outside Telegram, it runs in development mode with a test user ID.

Telegram Game SDK