ChainHawkXBot
A solo-built, production Telegram bot that lets anyone create a custodial crypto wallet, check balances, send real signed transactions, and view an aggregated portfolio — across three live blockchains — entirely through chat. Built and documented phase by phase as a professional engineering case study, not just a finished demo.
What ChainHawkXBot Actually Does
@ChainHawkXBot is a modular, conversational Telegram assistant that lets a user do all of the following entirely through chat — no app to install, no browser extension, no seed phrase to write down themselves.
/walletCreate or view a custodial wallet — the private key is generated, encrypted, and stored server-side, never exposed in chat./balance [chain]Check real balances across Ethereum Sepolia, BSC Testnet, and Flow EVM Testnet./send <address> <amount>Send a real, signed, on-chain transaction on any supported chain./history [chain]View recent transaction history via Etherscan's V2 API./statusLive network status — gas price and block number — across all three chains at once./exportExport the private key, gated behind a two-step confirmation with auto-delete from chat./portfolioTotal holdings aggregated across all three chains, converted to real-time USD.Crypto Onboarding Is Still Too Complicated
Managing a crypto wallet normally means juggling a separate app or browser extension, writing down a seed phrase, understanding gas on multiple networks, and switching between chains manually just to see where your funds actually are. That friction is the real barrier for a lot of people who are curious about crypto but not willing to learn a new toolchain first.
The opportunity here wasn't "build a wallet" — wallets exist. It was proving that a genuinely secure, multi-chain wallet could live inside a chat interface people already use every day, with the hard parts (custody, signing, chain-switching, pricing) handled invisibly on the backend. That's the broader positioning behind this project: turning a complicated technical process into something usable.
The Interesting Part Isn't the Feature List
Plenty of tutorials walk through building a wallet bot. What makes this one worth documenting is how it was built:
Architecture-first discipline. A ChainAdapter interface was designed before a single blockchain integration existed in the code. When the second chain was added, it took a fraction of the original effort and touched zero other files. The third chain proved it again — a measurable payoff of a design decision, not a claim.
Security treated as non-negotiable, even under pressure. Two real secret-exposure incidents happened during testing. Both were handled the way real production incidents are handled — not glossed over.
A five-layer debugging saga, solved with method, not luck. A database migration surfaced five separate, compounding failures. Each was isolated with a narrower test than the last — the actual, unglamorous shape of real engineering work.
Honest engineering over impressive-sounding engineering. Error messages were deliberately written to never overclaim — the bot tells a user when it can't be certain something landed, instead of offering false reassurance.
Designed as Independent Modules, Each With One Job
The system is organized into modules with a single responsibility each — Telegram Interface, Command Processing, User Management, Wallet Management, Blockchain Services, Database Layer, Security, Pricing, Configuration, and Logging.
The ChainAdapter interface is the centerpiece: a single contract that every blockchain implementation satisfies. It was written in the foundations phase, before any chain was wired up — a bet that paid off twice when BSC and Flow EVM were added later with minimal new code and zero changes to the rest of the system.
Three Chains, One Adapter Pattern
Each chain was added as a new implementation of the same ChainAdapter interface, in the order the architecture was proven:
Ethereum Sepolia
The original chain — first live RPC call, first real balance check, first signed transaction.
BSC Testnet
Added to prove the architecture. Took a fraction of the original effort, touched zero other files.
Flow EVM Testnet
Proved it a second time — by this point, adding a chain was routine, not risky.
On top of that, /portfolio aggregates holdings across all three chains into a single figure, converted to real-time USD via CoinGecko pricing — the first feature that treats the three chains as one unified account rather than three separate ones.
Custody Handled Like It's Real Money — Because It Is
Every wallet is custodial: the private key is generated server-side and encrypted at rest with AES-256-GCM. It is never displayed or logged in plaintext. Exporting it is gated behind a two-step confirmation, and the exported message auto-deletes from the chat shortly after.
Two real secret-exposure incidents happened during testing — a bot token, and more seriously, a real private key pasted into chat. Both were treated the way an actual production incident is treated: the secret was burned and rotated (or abandoned entirely), and the lesson was documented rather than quietly fixed and forgotten.
The Five-Layer Production Bug
Migrating the database from SQLite to Postgres, for real persistent hosting, surfaced five separate, compounding failures — not one bug, five, stacked on top of each other. Each was isolated with a narrower test than the last:
- 01
An IPv6-only connection issue — the database was reachable, but only over a connection path the environment wasn't configured for.
- 02
A duplicated environment variable silently overriding a fix that had already been applied correctly elsewhere.
- 03
An editor reverting code back to an old pattern without an obvious trigger.
- 04
A corrupted password copy — a credential that looked correct but wasn't, byte for byte.
- 05
A Windows C: drive at exactly zero bytes free, silently breaking package installs with no obvious error pointing at disk space.
Separately, integrating Etherscan's V2 API for transaction history meant a real 22-hour wait for a flaky third-party API key to start working — a reminder that not every delay is a bug in your own code.
From Local Script to Always-On Service
Two architectural changes turned this from a local project into a real, always-on service. First, the database moved from SQLite to Postgres via Supabase, using Prisma ORM, to support real persistent hosting. Second, when a paid hosting tier wasn't affordable, Telegram's long-polling was swapped for webhooks — not to cut a corner, but to make a free hosting tier's sleep behavior work correctly. That constraint was solved architecturally and explained honestly, not hidden.
The bot is deployed on Render as a web service, running in webhook mode in production.
Genuinely Live, Genuinely Deployed
The strongest proof point: the bot was tested and confirmed responsive on Telegram with the development laptop completely powered off — independent, always-on infrastructure, not a demo tied to one machine.
What This Build Actually Taught
Everything Under the Hood
From Empty Folder to Live Deployment
Empty Folder
Just an idea and a blank repository.
Foundations
Node.js, TypeScript, and a modular architecture designed before any feature existed.
Wallet
Real key generation with viem, encrypted at rest with AES-256-GCM.
Blockchain
First live RPC call and real balance check on Ethereum Sepolia.
Transactions
First real, signed, on-chain transaction — verified independently on Etherscan.
Multi-Chain
BSC Testnet added as a second chain, proving the ChainAdapter architecture.
Security
A real private-key exposure incident, handled the way a production incident is handled.
Database Migration
SQLite to PostgreSQL via Supabase, chasing down five compounding production bugs.
Production
Long-polling swapped for Telegram webhooks to make free-tier hosting behave correctly.
Live Deployment
Deployed on Render — and verified live with the development laptop powered off.
Live Project & Source
Message the Bot
It's genuinely deployed — talk to it directly on Telegram right now.
Open @ChainHawkXBot →Read the Source
Full codebase, phase-by-phase build docs, and the original case-study brief.
View on GitHub →Founder Insight Posts
Alongside the build, a series of Founder Insight posts documented the engineering journey in real time — architecture decisions, debugging, and honest lessons as they happened.