# Crosswalk XP Bot ## Crosswalk XP Bot Documentation The Crosswalk Telegram Bot is designed to enhance community engagement by rewarding meaningful participation and recognizing achievements within the Crosswalk ecosystem. This bot transforms everyday interactions into measurable progress, allowing users to track and celebrate their journey — and gives admins fair, powerful tools to keep chats lively without chaos. *** ### Key Features **XP System**\ Each eligible message earns XP (Experience Points). Levels increase with accumulated XP, and higher levels require progressively more points. This nudges steady, meaningful engagement over time. **Daily Bonus (+ WebApp Countdown)**\ Users can claim a daily XP bonus with **/dailybonus**. Inside **/statsui**, a live **HH:MM:SS** countdown shows exactly when the next claim is ready. **Achievements**\ Milestones reward consistent activity — first message, 7-day streaks, XP thresholds, level targets, and more. They give members something to aim for beyond raw XP. **Leaderboards (Weekly & All-time)**\ See who’s leading today, this week, or overall. Weekly resets keep the race fresh; all-time boards honor the veterans. **Stats WebApp (/statsui)**\ A beautiful, in-Telegram dashboard: progress bar, 30-day XP chart, 7-day heatmap, badges, teams, events, leaderboards, active boosters, tickets, and the daily bonus countdown — all in one place. **Teams (with Approvals)**\ Anyone can found a team with an emoji + name. Players request to join; captains (and master admins) approve via inline buttons in DM. Team leaderboards (all-time & weekly) turn solo grind into squad play. **Events (Mini-Seasons)**\ Admins launch time-boxed missions with custom points. Award event points with a reply + inline picker, and track both **individual** and **team** event leaderboards. Reset or delete events safely when they end. **Boosters & Store (Telegram Stars)**\ Strategize your climb: * **Quick Charge** — x2 XP for **1h** (selected chat) * **XP Surge** — x2 XP for **5 days** (selected chat) * **King of the Week** — x2 XP for **7 days** across **all chats** * **Lucky Draw Ticket** — lottery entry with unique code in stats * **Jackpot Boost** — three rolls; each “6” = **+300 XP** (up to +900) Multipliers **don’t stack**; a new one **replaces** the current in the same scope (local/global). Purchases are native Telegram **Stars**. **Custom Hourly Bonuses (by Hashtag)**\ Each group can define exact-match hashtags that trigger a **small hourly XP bonus** during scheduled windows (first valid message in the round wins). It’s a fun, brand-tuned spark every hour. **Rewards & Fair Tools for Admins** * **/rain** to reward random **weekly contributors** * **/give** / **/penalize** (reply-based) to correct XP * **/tagall** mentions **recently active** users only (cooldowns & caps) **Affiliate Program**\ Bring groups or users to Crosswalk XP and earn **20%** of referred revenue for **6 months**. Group owners can remove the bot and **re-add via an affiliate link** to attach attribution (latest referral wins from that moment onward). *** ### How It Works #### Earning XP Every eligible message awards XP with a short cooldown to discourage spam and reward meaningful chat. XP rolls into **levels** and **weekly totals** (used for weekly boards and fair giveaways like **/rain**). #### Leveling Up Levels use a quadratic curve so higher tiers feel earned. (Typical form: `XP(level) = a·level² + b·level + c`.)\ **Examples:** * Level 1 ≈ **25 XP** * Level 2 ≈ **65 XP** * Level 10 ≈ **1105 XP** #### Daily Bonus Users claim once per 24h with **/dailybonus**. The **/statsui** WebApp shows a live **HH:MM:SS** countdown to the next claim (and “READY” when it’s available). #### Achievements The bot records milestones (streaks, XP thresholds, level targets, special moments) and surfaces them in **/statsui**. Achievements add direction and bragging rights. #### Teams & Events * **Teams:** create, request, approve, kick, delete; plus team boards (weekly, all-time, and “my team” views). * **Events:** create a named mission, award points via inline UI, and track **individual** and **team** standings. Reset or delete when finished. #### Boosters & Store Boosters are **tactical power-ups** purchased with Telegram Stars in the **/statsui** store. Multipliers are scope-aware (local chat vs global) and **replace** existing multipliers instead of stacking. #### Leaderboards * **Daily/Weekly/All-time** personal boards * **Team** boards (weekly & all-time) * **Event** boards (users & teams)\ Admins can post official boards in group; everyone can browse comfortably from DM (with group pickers). *** ### Technical Overview **Real-Time Processing**\ Messages are processed live; XP is recorded with anti-spam cooldowns. Achievements and weekly rollups are kept in sync for instant leaderboards. **Database Architecture**\ A lightweight SQLite database stores users, XP, daily/weekly aggregates, achievements, teams, events, boosts, tickets, referrals, and scheduler artifacts (e.g., hashtag rounds). **Error Handling**\ Command and callback flows validate actor identity (“not your button”), admin roles, and expiry windows (e.g., 48h join-request TTL). Failures are logged and surfaced gracefully. **Backup & Recovery**\ DB snapshots protect user progress. After a restart or update, state is restored so communities don’t lose momentum. **Payments (Stars)**\ Booster purchases are handled via Telegram Stars invoices. After payment, the bot records the item (and `expires_at` for multipliers) and the **/statsui** snapshot refreshes. *** ### Commands Summary > *Admin-only in group* means the command requires chat admin rights if run in a group. In DMs, most boards are viewable via a clean group picker. **General**\ `/start` — welcome & quick actions\ `/help` — command help\ `/privacy` — data handling & policy\ `/statsui` — open Stats WebApp (charts, heatmap, badges, store, tickets, daily countdown) **Daily & Puzzles**\ `/dailybonus` — claim daily XP (24h cooldown)\ `/decrypt ` — answer the current group puzzle (one winner per challenge) **Boosters**\ `/myboosts` — show your active boosters (local + global)\ \&#xNAN;*(Dev/Test: `/testboost`, `/buytest` — disabled in production)* **Teams — players & captains**\ `/team_create ` — create a team (you become captain)\ `/team_list` — list teams in this group\ `/team_join` — request to join (captain/master admin approves in DM)\ `/team_leave` — leave your team (captains can delete via flow)\ `/team_kick` — captain removes a member **Teams — admin**\ `/delete_team` — delete any team via confirm flow\ `/set_admin` — appoint a master admin for this chat\ `/unset_admin` — remove a master admin\ `/list_admins` — list master admins **Team leaderboards**\ `/team_leaderboard` — all-time team ranking\ `/team_weekly` — weekly team ranking\ `/team_myboard` — ranking inside your team (all-time)\ `/team_myweekly` — weekly ranking inside your team **Events**\ `/event_new ` — create event in this group\ `/event_list` — list events\ `/event_points ` — **reply** to a user to award points (inline event picker)\ `/event_score` — your own event points\ `/event_leaderboard` — top users in an event\ `/event_team_leaderboard` — team totals in an event\ `/event_myteam` — your team’s breakdown in an event\ `/event_reset` — **admin:** reset an event’s points\ `/event_delete` — **admin:** delete event **Leaderboards & admin tools**\ `/leaderboard [topN]` — *admin-only in group*; DM viewer available\ `/topdaily` — *admin-only in group*; today’s ranking\ `/topweek` — *admin-only in group*; current week ranking\ `/topdate YYYY-MM-DD` — *admin-only in group*; specific date ranking\ `/weeklyleaderboard` — weekly board (alt entry; DM viewer available) **Rewards & moderation (admin)**\ `/rain ` — reward random **weekly contributors**\ `/give ` (reply) — grant XP\ `/penalize ` (reply) — remove XP\ `/tagall` — mention recently active members (cooldowns & caps) *** ### Why It Matters The Crosswalk Telegram Bot is more than a tool; it’s a framework for building a meaningful, engaged community. By turning every interaction into progress, we make participation visible and rewarding. With teams, events, boosters, achievements, and fair admin controls, every conversation counts — and every week tells a story worth showing up for. *** ### Links **Medium (full product story):**\ **Bitget listing of the application:**\ --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://crosswalk-ecosystem.gitbook.io/crosswalk-ecosystem-docs/current-releases/crosswalk-xp-bot.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.