StakrrBot

A Telegram bot for tracking Printr staking positions across Solana and EVM chains. Get real-time reward alerts, claim Solana rewards in one tap, and explore trending tokens — all without leaving Telegram.

Built with TypeScript, Telegraf, and the @printr/sdk.

---

Features

• Real-time reward alerts — get notified when claimable rewards change, with configurable thresholds and cooldowns
• Position snapshots — view all open and closed staking positions grouped by token, with staked amounts, unlock dates, and rewards
• One-tap claiming — claim Solana staking rewards directly from Telegram; the bot signs and submits the transaction as a gas relayer (no private key needed from the user)
• Multi-chain support — track wallets on Solana, Ethereum, Base, Polygon, and Arbitrum
• Trending tokens — live feed of the most active tokens on Printr
• Buyback & burn stats — see protocol buyback and burn activity per token
• Wallet tags — label wallets with custom names for easy identification
• Persistent storage — subscriptions survive restarts via PostgreSQL (or local JSON fallback)

---

Bot commands

Command	Description
/watch [address]	Add a wallet to track
/unwatch	Remove a wallet
/list	View all tracked wallets
/positions	Fetch latest position snapshot
/refresh	Force an immediate poll
/alerts [value]	View or set minimum reward delta for alerts
/cooldown [seconds]	View or set time between alerts
/burns	Buyback & burn stats for your staked tokens
/trending	Live feed of hot tokens on Printr
/ca	Show your token's contract address (if BOT_TOKEN_CA is set)
/stats	Bot usage stats (owner only)

Keyboard buttons mirror the most-used commands for quick access.

---

Setup

1. Clone and install

git clone https://github.com/perturpe/Stakrr.git
cd Stakrr
npm install

2. Configure environment

Copy the example and fill in your values:

cp .env.example .env

Required variables:

Variable	Description
TELEGRAM_BOT_TOKEN	Bot token from @BotFather
TELEGRAM_BOT_USERNAME	Bot username without @
BOT_SOLANA_PRIVATE_KEY	Base58 private key for the relayer wallet (pays gas for claims)

Optional branding:

Variable	Description
BOT_NAME	Display name in bot messages (default: StakingBot)
BOT_TOKEN_TICKER	Your token ticker, e.g. $MYTOKEN
BOT_TOKEN_CA	Solana contract address — enables /ca command
COMMUNITY_URL	Telegram community link shown to new users
LAUNCHER_BOT_URL	Telegram launcher bot link — enables 🚀 Launch button
OWNER_TELEGRAM_ID	Your Telegram user ID — gates /stats and /diag_claim

See .env.example for the full list.

3. Fund the relayer wallet

The bot uses a dedicated Solana wallet to pay gas fees when claiming rewards on behalf of users. Generate a fresh keypair, export it as base58, and set it as BOT_SOLANA_PRIVATE_KEY. Fund it with a small amount of SOL (~0.1 SOL is plenty to start).

Rewards always land in the user's wallet — the relayer wallet only pays the transaction fee.

4. Run locally

# Development (TypeScript directly via tsx)
npm run dev:bot

# Production (compile first)
npm run build
npm run start:bot

---

Deploying to DigitalOcean App Platform

This repo includes a pre-configured Dockerfile and App Platform spec.

Steps

1. Fork or push this repo to your GitHub account
2. In DigitalOcean App Platform, create a new app from your repo
3. Choose the Worker component type (not a web service)
4. Set instance count to 1 to avoid duplicate alert sends
5. Add environment variables in the App Platform dashboard
6. Provision a Managed PostgreSQL database and set DATABASE_URL

When DATABASE_URL is set the bot uses Postgres automatically. Without it, subscriptions fall back to a local JSON file (fine for local dev, not recommended for production).

Required env vars on App Platform

• TELEGRAM_BOT_TOKEN
• TELEGRAM_BOT_USERNAME
• BOT_SOLANA_PRIVATE_KEY
• DATABASE_URL
• OWNER_TELEGRAM_ID (recommended)
• Any branding vars you want

---

Storage

Mode	When used
PostgreSQL	DATABASE_URL is set
Local JSON file	No DATABASE_URL (dev/testing only)

Subscriptions, wallet tags, and alert settings are all persisted.

---

Wallet address formats

The bot accepts wallets in any of these formats:

• CAIP-10 — solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:<address> or eip155:8453:<address>
• Solana base58 — auto-detected and prefixed with Solana mainnet chain ID
• EVM 0x address — uses DEFAULT_EVM_CHAIN_ID (default: Base / eip155:8453)

---

Tech stack

• TypeScript
• Telegraf v4
• @printr/sdk — staking positions, reward claiming
• @solana/web3.js — transaction signing & submission
• PostgreSQL via pg — subscription storage
• Express — optional web interface

---

License

ISC