Documentation

Overview

StakerHQ gives your staking syndicate a complete back-office. You get a private Telegram bot that your stakers interact with, and a web dashboard where you track every bet, balance, and game outcome in real time.

🤖

Telegram Bot

Your stakers receive game tips, subscribe, and log bets — all inside Telegram. No app download needed.

📊

Web Dashboard

Real-time P&L, staker balances, full bet ledger, Game Analytics widget, and transaction history.

🖼️

Auto OCR & Watermark

Game photos are read by AI (league, teams, odds extracted automatically) and watermarked with your brand.

Getting Set Up

1
Create a Telegram bot — Open Telegram, message @BotFather, send /newbot, follow the prompts. Copy the bot token it gives you.
2
Find your Telegram User ID — Message @userinfobot and it will reply with your numeric ID (e.g. 123456789).
3
Sign up & complete the wizard — Create your account at /signup then paste your bot token, one primary Telegram user ID (no commas), and optional brand name in the Setup Wizard. Add other admins later in the bot via Manage additional admins. Your bot starts automatically.
4
Open your bot in Telegram — Search for your bot's username and send /start. You'll see the admin panel with buttons to send games, manage users, check balances, and more.
5
Recommended: add /dashboard to Telegram’s menu — Message @BotFather with /setcommands, choose your bot, then paste this single line (no leading slash): dashboard - Open your dashboard That exposes /dashboard in the / command picker next to the input for both admins and stakers. See Slash menu for details.

Sending Games

As an admin you send games directly from your Telegram chat with the bot. Every approved staker who is online receives the game card instantly with Subscribe and Enter Bet buttons.

📸 Photo game

Send any bet slip or odds screenshot as an image. The bot reads it with AI OCR — extracting sport, league, teams, and odds — then watermarks it with your brand name. Stakers receive the photo with Subscribe and Enter Bet buttons.

✏️ Text game

Send a text message describing the game. Stakers receive it as a formatted card. Useful when you have a tip but no screenshot.

📢 Admin replies / broadcasts

After sending a game, open the Game Analytics widget and tap Manage → Manage Replies to broadcast an update to all subscribers (e.g. "game starts in 10 min").

⏹ Stopping / cancelling a game

Stop hides the game from new online stakers but keeps it for existing subscribers. Cancel marks the game as cancelled and notifies all subscribers.

🔄 Reactivating a game

Use Ready to re-send a stopped game to all online stakers. Even stakers who previously deleted the game card receive a fresh copy instantly.

Managing Stakers

➕ Adding a staker (recommended)

Prefer the clean approach — they find your bot and request access:

Share your bot link (e.g. t.me/YourBotUsername)
They tap Start, then Request to join
You get a New join request — Approve or Reject
Or review anytime: /dashboard → Manage users → Pending Requests
Tell them to send /start again after approval to go online

This avoids collecting Telegram IDs and bypasses Forward Privacy issues.

Fallback (manual): Manage users → Manage all users → Add user — paste their numeric ID from @userinfobot, or forward a message from them (fails if Forward Privacy is on).

Once approved/added they get a welcome message. Username is the default nickname — edit anytime.

➖ Removing a staker

Tap Remove in the users panel. All their game messages are deleted from Telegram automatically.

✏️ Nicknames

Inside Manage all users, tap a staker's name to edit their display nickname. Nicknames appear in the Game Analytics widget, balance reports, and the web dashboard.

⭐ Superusers

Superusers receive all game cards automatically without needing to Subscribe first. Use this for trusted VIP stakers. Manage via Manage Superusers in the bot.

👑 Additional admins

The setup wizard only saves one primary admin ID. To add teammates, use Manage additional admins here. Extra admins receive the Game Analytics widget and can use admin commands in the bot. They do not have platform dashboard access (only the account owner can log into the web dashboard).

Bets & Balances

📝 Entering a bet (staker side)

After subscribing, tap Enter Bet. Send stake and odds:

400 4

Or send just the amount (e.g. 400) — the bot asks for odds next.

You can also reply to the game with /b 400 4. Odds are always required. Market / match is not asked. Multiple bets on the same game are allowed.

Confirmation includes Win ✅ / Lose ❌ so the staker (or you) can settle later.

💰 Balance

The staker's balance represents the running total they owe to you (the admin). It increases when bets win and decreases when they lose — based on the stake formula assigned to that staker.

You can manually deposit (add) or withdraw (subtract) from a staker's balance at any time from the web dashboard. All changes are logged with full history.

📋 Reports

Stakers: /reports — shows all their bets and outcomes.
Admins: visit the Bets tab in the web dashboard for a complete filterable ledger.
On the staker's detail page you can also edit individual bet fields and see the full edit audit trail.

Stake totals (pool tracking)

Optional live pool for a game. Available on all tenants.

🎯 Set a target when sending

Put /t 1000 anywhere in the photo caption. Stakers see a live bar (e.g. 400/1000€). You always see contributors.

No target (instant pick)

Skip /t. Stakers still Enter Bet. You see “staked so far” on the Game Analytics widget; stakers do not see a running total until you set one.

Change target anytime

Set Total / Edit Total on the Game Analytics widget (first row next to Send Reply), or reply /t 2000. Overshoot past the target is allowed.

Quick buttons

Ready · Waiting · Stop · Cancel · Enough · Skip broadcast short status lines to subscribers. Use Enough when the pool is full enough.

Job aids (two guides)

Separate printable guides for stakers and admins.

Staker guide → Admin guide →

Marking Results

Open the Game Analytics widget for the game (via /dashboard or the widget message in your admin chat). Tap 🏁 Finish Game and then select Win or Lose.

✓ All unsettled staker bets are updated to the result in one click.
✓ Balances adjust automatically based on each staker's stake formula.
✓ A settlement notification is sent to every subscriber.
✓ Stakers can also settle their own individual bets with the Win/Lose buttons on their bet card.
✓ The game result (Won / Lost) is shown on the web dashboard games table.

Stake Formulas

Each staker can have a different formula that determines how winnings and losses are shared between you (the admin) and the staker.

% Profit Share

Admin fronts 100% of the stake. Staker keeps a fixed % of the profit when the bet wins. On a loss, admin bears the full stake.

Example — 20% profit share, stake 100, odds 3.0:

Win: total return 300, profit 200

Staker keeps: 200 × 20% = 40

Admin receives: 300 − 40 = 260

Balance change: +260

Loss: balance change: −100

⚖ Split Stake

Admin and staker each contribute a fixed % of every bet. Winnings and losses split by the same ratio.

Example — 50/50 split, stake 100, odds 3.0:

Win: total return 300, profit 200

Staker keeps: 200 × 50% = 100

Admin profit: 200 × 50% = 100

Balance change: +100

Loss: admin loses admin's 50 of stake, balance: −50

Set or change a staker's formula via Manage Users → Stake Config in the bot admin panel. The current formula is always visible on the staker's detail page in the dashboard.

Web Dashboard

Log in at /login to access your dashboard. The dashboard is accessible from any device.

🏠 Overview

Key stats: total stakers, total staked, win/loss counts, win rate, unsettled bets, and bot status.

👥 Stakers

Full table — balance, total staked, bets placed, W/L record, win rate, online status. Click any staker for their full profile.

👤 Staker Detail

Per-staker profile: stake config, balance with deposit/withdraw controls, full transaction ledger, and editable bet history with audit trail.

📋 Bets

Complete bet ledger — filter by staker, result, date range. Export to CSV. Click staker names to jump to their profile.

🎮 Games

All games sent — OCR-extracted match event, league, country, sport; status; staked/winnings/profit; result. Date range filter and CSV export.

🎮 Game Detail

Full game view: image, subscribers, bets, replies, result, financials. Editable match metadata. Mark Won/Lost inline.

📜 Bot Logs

Live output from your bot process — useful for debugging. Sensitive server paths are automatically hidden.

⚙️ Bot Controls

Restart or stop your bot directly from the dashboard without needing SSH access.

Slash menu: expose `/dashboard`

We recommend registering at least /dashboard with BotFather so admins and stakers get a persistent entry in Telegram’s built-in command list (tap / next to the message field). It’s optional but we find it much more convenient than typing the command from scratch.

Steps

Open @BotFather in Telegram.
Send /setcommands as a message to BotFather (that is normal — you are not “running” the command in your own bot).
Pick your bot from the list BotFather shows.
Paste your command list as plain text. Use the pattern commandname - Short description. Do not put a / in front of the command name when talking to BotFather.

Minimal example (only dashboard)

dashboard - Open your dashboard

After saving, open a chat with your bot — the menu will show /dashboard. Admins get the admin dashboard; stakers get their status, balance, and stake info. You can add more commands to the same list later if you want.

Bot Commands

👤 Staker commands

/startGo online — receive active games and pending notifications

/dashboardYour personal dashboard — online status, balance, stake setup; we recommend adding this via BotFather (see above)

/stopGo offline — pause incoming game cards

/statusCheck your current online/offline status

/balanceView your current balance

/reportsView all your bets and outcomes

/helpShow the full command list

🔑 Admin commands

/dashboardAdmin panel; same as /start for admins — register it in BotFather’s menu (instructions)

/usersShortcut to manage stakers

/set_balance <id> <n>Set a staker's balance

/set_nickname <id> <name>Set display name for a staker

/reports <user_id>View a staker's full bet history

/infoBot info and runtime stats

/help_adminFull admin command reference

/cancelCancel any pending input action

Job aids

Two official printable guides. Share the staker link with your team; keep the admin guide for operators (photo-only send, green/red status, extra admins, split-stake defaults, Game Analytics widget).

Staker job aid → Admin operations guide →

FAQ

How should I add new stakers? ▾

Preferred: share your bot link → they tap Start → Request to join → you Approve (or use Pending Requests). Manual Add user by ID / forward is only a fallback. Forwarding fails when Telegram Forward Privacy is on — Request to join avoids that entirely. See the admin onboarding guide.

Stakers aren't receiving game cards even though they're online. ▾

Make sure they have sent /start to the bot to go online. Also verify they're registered: check Manage all users in the admin panel. Superusers receive all games automatically; regular stakers must Subscribe per game.

A staker's balance looks wrong. ▾

Visit the staker's detail page in the dashboard. You can see the full transaction history (showing exactly when and how the balance changed) and use Deposit / Withdraw to manually adjust. All adjustments are logged with timestamp and note.

Can I have multiple admins? ▾

Yes. The website setup asks for one primary admin Telegram ID only. After that, go to Manage Users → Manage additional admins in the bot and add their Telegram ID. Extra admins receive the Game Analytics widget and can use admin commands, but they cannot log into the web dashboard (that's reserved for the account owner).

How do I change the watermark on game photos? ▾

Set it during the Setup Wizard (Brand watermark text field). You can update it later directly from the dashboard settings or by contacting support.

Where does the OCR data (match event, league, sport) come from? ▾

When you send a photo game, the platform reads the image with OpenAI's vision model and extracts sport, country, league, team names, odds, and bet type. This data populates the Games table automatically. You can always edit it manually on the game detail page.

What happens when I reactivate a game? ▾

The game is instantly re-sent to all online stakers — including those who previously deleted the game card. Offline stakers will receive it the next time they send /start.