# RISEx Telegram Bot (/docs/cookbook/risex-telegram-bot)

import { Cards, Card } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';

## Introduction

Trading perpetual futures usually means navigating complex UIs with order books, charts, and confusing terminology. What if you could just text "buy 0.02 BTC" to a bot and have it execute the trade instantly? That's exactly what this tutorial builds: an AI-powered Telegram bot that trades on RISEx, RISE's perpetual futures exchange.

The bot combines RISE Wallet's session keys for secure delegation, GPT-4o-mini for natural language understanding, and RISEx's REST API for trading. Users never expose their private keys. Instead, they grant limited permissions to a P256 session key that the bot uses for trading.

### What You'll Build

A complete trading bot with two parts:

**Telegram Bot Backend:**

* Natural language command processing ("buy 0.02 BTC", "check my balance")
* Slash commands for quick actions (`/balance`, `/deposit`, `/positions`)
* EIP-712 signature generation for authenticated API calls
* Encrypted signer key storage
* Integration with RISEx REST API

**Registration Frontend:**

* RISE Wallet connection UI
* One-click session key registration
* Telegram account linking
* Permission grant interface

### What You'll Learn

* Building Telegram bots with Telegraf framework
* Integrating GPT-4o-mini for natural language processing
* Using RISE Wallet's P256 session keys for delegation
* EIP-712 typed data signing for API authentication
* Trading perpetual futures programmatically
* Secure key management with AES-256-GCM encryption
* Account abstraction patterns for web3 apps

### Prerequisites

* Node.js 18+ installed
* A Telegram account (to create and test the bot)
* Basic understanding of React and Next.js
* Familiarity with TypeScript
* An OpenRouter API key (for GPT access - get one at [openrouter.ai/keys](https://openrouter.ai/keys))

<Callout type="info">
  This tutorial uses RISE Testnet and testnet USDC. The bot includes a `/deposit` command that gives you free testnet funds instantly!
</Callout>

### Source Code

The complete source code for this project is available on GitHub: [awesamarth/risex-tg-bot](https://github.com/awesamarth/risex-tg-bot)

***

## Architecture Overview

Before diving into code, let's understand how the system works.

### Component Diagram

<Mermaid
  chart="graph TD
    A[User in Telegram] -->|&#x22;buy 0.02 BTC&#x22;| B[Telegram Bot]
    B -->|Parse Intent| C[GPT-4o-mini via OpenRouter]
    C -->|&#x22;place_order tool&#x22;| B
    B -->|Load Encrypted Key| D[Signers Store]
    B -->|Sign EIP-712 Message| E[Viem]
    E -->|POST /v1/orders/place| F[RISEx API]
    F -->|Execute Trade| G[RISE Testnet]
    G -->|Transaction Hash| B
    B -->|Order Confirmation| A

    H[Frontend UI] -->|Register Signer| I[RISE Wallet]
    I -->|Sign Permission| J[Smart Contract]
    J -->|Store Encrypted| D"
/>

### How It Works

**Setup Phase (One-Time):**

1. User opens the registration frontend and connects RISE Wallet
2. User enters their Telegram ID
3. User signs an EIP-712 message granting trading permissions to a P256 session key
4. The session key is encrypted and stored securely on the backend
5. The Telegram ID is linked to the wallet address

**Trading Phase (Ongoing):**

1. User sends a message to the Telegram bot ("buy 0.02 BTC")
2. Bot verifies the user has a registered signer
3. Bot sends message to GPT-4o-mini to parse intent
4. GPT returns structured tool call (`place_order` with params)
5. Bot decrypts the user's session key
6. Bot signs an EIP-712 `VerifySignature` message
7. Bot calls RISEx API with the signature
8. RISEx verifies signature and executes the trade
9. Bot replies with order confirmation and transaction hash

This architecture ensures users never expose their main private keys while still enabling automated trading.

## Quick Links

<Cards>
  <Card title="Setup" href="/docs/cookbook/risex-telegram-bot/setup" description="Project setup, backend and frontend initialization" />

  <Card title="Backend" href="/docs/cookbook/risex-telegram-bot/backend" description="Build the Telegram bot with AI integration" />

  <Card title="Frontend" href="/docs/cookbook/risex-telegram-bot/frontend" description="Create the registration UI" />

  <Card title="Testing & Production" href="/docs/cookbook/risex-telegram-bot/testing" description="Run, test, and deploy your bot" />
</Cards>