Router & screen flow

How the bot routes between screens and which handlers/keyboards are used. UX is aligned with PolyGun.

---

Screens overview

Screen	Description	Router
Home	Welcome, balance, wallet address, main menu reply keyboard	start_router
Markets menu	“Market Search” + category inline buttons	start_router
Market list	List of markets (Yes/No trade buttons) + Main Menu inline	markets_router
Wallet	Wallet address + USDC.e balance	wallet_router
Withdrawal flow	3 steps: address → amount → confirm	withdrawal_router
Trade result	“Order sent” after Yes/No on a market	trading_router

---

Flow diagram

flowchart TD
    Start["/start"] --> NewUser{User exists?}
    NewUser -->|No| CreateWallet["Create wallet\nShow home keyboard"]
    NewUser -->|Yes| Home["Home screen\n(balance + reply keyboard)"]

    CreateWallet --> Home

    Home --> Markets["📊 Markets\nor الأسواق"]
    Home --> Wallet["👛 Wallet\nor محفظتي"]
    Home --> Withdraw["💸 Withdraw\nor سحب"]
    Home --> MainMenu["🏠 Main Menu"]

    Markets --> MarketsMenu["Market Search\n+ category inline keyboard"]
    MarketsMenu --> CatTag["Category by tag\ncallback: markets:tag:<id>"]
    MarketsMenu --> CatSearch["Search\ncallback: markets:search:<query>"]
    CatTag --> MarketList["Market list\n(Yes/No per market)"]
    CatSearch --> MarketList
    MarketList --> Trade["trade:<market>:<token>:buy"]
    MarketList --> MainMenu
    Trade --> TradeResult["✅ Order sent"]
    MainMenu --> Home

    Wallet --> WalletScreen["Wallet address\n+ USDC.e balance"]
    WalletScreen --> Home

    Withdraw --> W1["State: waiting_address"]
    W1 --> W2["State: waiting_amount"]
    W2 --> W3["State: waiting_confirm"]
    W3 --> WithdrawDone["✅ Withdrawal tx sent"]
    WithdrawDone --> Home

---

Triggers → screen

Commands

Trigger	Screen / action	Handler
/start	Home (or create wallet then home)	start_handler

Reply keyboard (main menu, PolyGun-style)

Button text	Screen / action	Handler
🔍 Markets / 📊 Markets / الأسواق	Markets menu (category inline)	markets_menu_handler
📊 Portfolio	Portfolio (positions, PnL)	portfolio_handler
📋 Limit Orders	Limit orders list	limit_orders_handler
👛 Wallet / محفظتي	Wallet (address, balance, Withdraw)	wallet_handler
🔄 Refresh	Re-send home dashboard	refresh_handler
⚙️ Settings	Settings menu	settings_handler
🔗 Referrals	Referrals placeholder	referrals_handler
❓ Help	Help & FAQs	help_handler
🏠 Main Menu	Home	main_menu_handler
💸 Withdraw / سحب	Start withdrawal (ask address)	start_withdrawal

Inline callbacks

callback_data	Screen / action	Handler
main_menu	Home	main_menu_callback_handler
markets:tag:<tag_id>	Fetch by tag → market list	markets_callback_handler
markets:search:<query>	Search → market list	markets_callback_handler
trade:<market_id>:<token_id>:buy	Execute market order → “Order sent”	trade_callback_handler

Withdrawal FSM (message-driven)

State	User input	Next
—	Tap “💸 Withdraw” / “سحب”	waiting_address
waiting_address	Valid 0x address	waiting_amount
waiting_amount	Number > 0	waiting_confirm
waiting_confirm	“نعم” / “yes” / “y”	Execute tx, clear state, show tx hash

---

Router registration order (main.py)

1. start_router — /start, Main Menu, Markets menu
2. wallet_router — Wallet
3. markets_router — Market categories & list, trade callbacks
4. trading_router — trade:* callbacks
5. withdrawal_router — Withdraw + FSM steps

---

Keyboards

Keyboard	Type	Used on
home_keyboard()	Reply	Home
market_categories_keyboard()	Inline	Markets menu
main_menu_inline_keyboard()	Inline	After market list
Per-market Yes/No	Inline	Market list (built in markets.py)

---

File reference

File	Responsibility
app/keyboards.py	Reply + inline keyboard builders
app/handlers/start.py	Home, Main Menu, Markets menu
app/handlers/wallet.py	Wallet screen
app/handlers/markets.py	Market categories, market list, fetch by tag/search
app/trading.py	Trade execution (trade:*)
app/withdrawal.py	Withdrawal FSM