Skip to main content

​
Overview

X integration is a distribution and engagement layer on top of the Mouth protocol. The web app is the core product; X makes it viral.

​
The Mouth Bot (@Mouth_App)

The Mouth bot is an automated X account that:
  • Monitors mentions of @Mouth_App in tweets and replies
  • Posts challenge links when a challenge is created from a tweet
  • Notifies opponents when they’re challenged
  • Announces results when challenges are resolved

​
Interaction Flows

​
Creating a Challenge from X

@cryptoguru: "Monad FDV will be under $1B in 3 months, I'm calling it"
    │
    └── @user: "@Mouth_App I'll bet $500 against this"
            │
            └── @Mouth_App: "New challenge on Mouth!

                            'Monad FDV under $1B in 3 months'
                            $500 USDC

                            @user finalize it
                            @cryptoguru accept once it's live

                            pvp.mouth.app/challenge/abc123"
At this point, the bot has created a Draft in the draft_challenges table and assigned a permanent URL. Both the Challenger and the opponent use the same link:
  • @user clicks it → sees the form to finalize the challenge (edit details, deposit USDC)
  • @cryptoguru clicks it later → sees the challenge details and “Accept Challenge” button
No second tweet or link is needed. The bot posts one reply addressing both parties.

​
Challenge Accepted

Once both sides have deposited, the challenge is live. The same URL (pvp.mouth.app/challenge/{id}) now shows the active challenge with both parties locked in.

​
Challenge Resolved

@Mouth_App: "Challenge settled!

            @user wins against @cryptoguru
            Monad FDV under $1B in 3 months
            Payout: $980 USDC

            pvp.mouth.app/challenge/abc123"

​
Bot Behavior Rules

TriggerBot Action
User tags @Mouth_App in a tweetCreate Draft, reply with challenge URL (pvp.mouth.app/challenge/{id})
Challenge finalized by ChallengerSame URL now shows challenge details to opponent (no new tweet needed)
Opponent accepts challengeChallenge goes active, visible on the same page
Challenge resolvedPost result, tag both parties, show payout
Challenge cancelled/expiredPost cancellation notice

​
What the Bot Does NOT Do

  • Does not handle any funds or wallet operations
  • Does not resolve challenges (that’s the resolution engine)
  • Does not create smart contracts directly (that happens when the challenger finalizes on the web app)
  • Is purely a notification and engagement layer

​
Social Features

​
Shareable Challenge Cards

Every challenge has a unique URL (e.g., pvp.mouth.app/challenge/{id}) that generates a rich Open Graph card when shared on X:
  • Challenge title
  • Amount
  • Both parties’ X handles and avatars
  • Current status (Draft / Pending / Active / Resolved)
  • Countdown to expiration

​
Profile Pages

Every Mouth user has a public profile at pvp.mouth.app/profile/{handle} showing:
  • Win/loss record
  • Total volume bet
  • Active challenges
  • Challenge history
  • Win streak

​
Leaderboard

A public leaderboard at pvp.mouth.app/leaderboard showing:
  • Top winners (by profit)
  • Most active challengers
  • Longest win streaks
  • Highest volume