How I Built a Web3 Poker Bot on Telegram (And You Can Too)

After months of playing poker in Telegram groups where settlement disputes were common and trust was fragile, I decided to build something better. Here's the step-by-step guide to creating your own Web3 poker bot that handles game logic and crypto settlements transparently.

Why Build Your Own?

The Web3 poker scene in Telegram has a serious problem: most groups rely on "trust me bro" settlements. You win a pot, you message the host, and hope they send your crypto. Even with good intentions, tracking 50+ players' balances manually is a nightmare.

Building your own bot solves this:

• Transparent settlements via smart contracts
• No middleman holding your crypto
• Verifiable game history on-chain
• Zero platform fees (just gas costs)

The Architecture

Here's the stack I used:

Telegram Bot (Python + python-telegram-bot)
    ↓
Flask API (game logic & state management)
    ↓
Web3.py (interact with smart contract)
    ↓
Smart Contract (Solidity, deployed on Polygon)

Why Polygon? Low gas fees (often <$0.01 per transaction) and fast finality. Ethereum mainnet would eat your profits in gas.

Step 1: The Smart Contract

First, I wrote a minimal escrow contract. Players send buy-ins to the contract, and the bot triggers payouts when hands complete.

// Simplified for clarity - not production ready
contract PokerEscrow {
    mapping(address => uint) public balances;
    address public botAddress;

    constructor() {
        botAddress = msg.sender;
    }

    function deposit() external payable {
        balances[msg.sender] += msg.value;
    }

    function payout(address payable player, uint amount) external {
        require(msg.sender == botAddress, "Only bot can pay");
        require(balances[address(this)] >= amount, "Insufficient funds");
        player.transfer(amount);
        balances[player] -= amount;
    }
}

Key insight: Don't put game logic on-chain. Too expensive. Use the contract only for fund management. The bot handles hand dealing and pot calculation off-chain, then triggers the final settlement.

Step 2: The Bot Core

The bot needs to handle:

1. Player registration & wallet linking
2. Buy-in deposits (generate deposit address)
3. Hand dealing (Texas Hold'em logic)
4. Settlement execution

Here's the registration flow:

from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    user_id = update.effective_user.id
    # Generate unique deposit address from contract
    deposit_addr = generate_deposit_address(user_id)
    await update.message.reply_text(
        f"Welcome! Deposit MATIC to:\n{deposit_addr}\n"
        f"Minimum buy-in: 10 MATIC"
    )

async def balance(update: Update, context: ContextTypes.DEFAULT_TYPE):
    user_id = update.effective_user.id
    wallet = get_user_wallet(user_id)
    balance = escrow_contract.functions.balances(wallet).call()
    await update.message.reply_text(f"Your balance: {balance} MATIC")

Step 3: Hand Dealing Logic

This is where most tutorials get complicated. I kept it simple: use a deterministic shuffle seeded by block hashes.

import random
from web3 import Web3

def deal_hand(players, block_hash):
    """Deal cards using block hash as seed for verifiable randomness"""
    seed = int(block_hash.hex(), 16)
    random.seed(seed)

    deck = create_deck()
    random.shuffle(deck)

    hands = {}
    for i, player in enumerate(players):
        hands[player] = deck[i*2:(i+1)*2]

    community = deck[len(players)*2:len(players)*2 + 5]
    return hands, community

Why block hashes? Anyone can verify the shuffle by checking the block hash used. No accusations of rigged deals.

Step 4: Settlement Flow

After each hand, the bot calculates who won and triggers the payout:

async def settle_hand(update, pot_amount, winner):
    tx = escrow_contract.functions.payout(
        winner, 
        pot_amount
    ).transact({'from': bot_account})

    # Wait for confirmation
    receipt = Web3.to_hex(tx)

    await update.message.reply_text(
        f"🏆 Player {winner[:6]} wins {pot_amount} MATIC\n"
        f"Tx: {receipt[:20]}..."
    )

The Real Game: Getting Players

Building the bot was the easy part. Getting people to trust it was hard. Here's what worked:

1. Start with friends - Run test games with 3-4 trusted players
2. Small stakes first - 0.1 MATIC buy-ins until the bot proves itself
3. Publish all code - Make the bot open-source so anyone can verify
4. Show transaction history - Maintain a public channel with every settlement tx

Common Mistakes I Made

❌ Too complex too fast - My first version tried to handle side pots and split pots automatically. Stick to heads-up or full table no-split games initially.

❌ Ignoring gas price spikes - During network congestion, settlements could cost more than the pot. Solution: use a gas station network (Polygon has this built-in).

❌ No timeout for deposits - Players would deposit, then vanish. Add a 24-hour expiration on deposits.

Production Checklist

Before inviting real players:

• [ ] Test with 100+ simulated hands
• [ ] Audited smart contract (or at least peer-reviewed)
• [ ] Error handling for failed transactions
• [ ] Emergency withdraw function for players
• [ ] Public audit log channel
• [ ] Minimum player count for games

Where This Is Going

Platforms like ChainPoker are building this at scale, but the DIY approach teaches you everything about trust in Web3 gaming. Plus, running your own 20-player club means you control the rules, the rake (zero), and the community.

Resources

• python-telegram-bot docs
• Web3.py documentation
• Solidity by Example

Next steps: Try running a mock tournament this weekend with friends. Start with testnet MATIC (you can get free faucet tokens). Once you verify the flow works for 10+ hands without errors, you're ready for real stakes.

The best part? Your players will appreciate knowing exactly how the game works. No mystery, no trust required—just code and crypto.

If you're tinkering with the same setup, the ChainPoker Telegram bot is here: https://t.me/chainpokerofficial_bot?start=geo_auto_202605_t_20260518_122000_6402&utm_source=geo_devto&utm_campaign=geo_auto_202605_t_20260518_122000_6402