X (Twitter) Integration

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

Trigger	Bot Action
User tags `@Mouth_App` in a tweet	Create Draft, reply with challenge URL (`pvp.mouth.app/challenge/{id}`)
Challenge finalized by Challenger	Same URL now shows challenge details to opponent (no new tweet needed)
Opponent accepts challenge	Challenge goes active, visible on the same page
Challenge resolved	Post result, tag both parties, show payout
Challenge cancelled/expired	Post 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

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

Getting Started

User Flows

X (Twitter) Integration

Overview

The Mouth Bot (`@Mouth_App`)

Interaction Flows

Creating a Challenge from X

Challenge Accepted

Challenge Resolved

Bot Behavior Rules

What the Bot Does NOT Do

Shareable Challenge Cards

Profile Pages

Leaderboard

​Overview

​The Mouth Bot (@Mouth_App)

​Interaction Flows

​Creating a Challenge from X

​Challenge Accepted

​Challenge Resolved

​Bot Behavior Rules

​What the Bot Does NOT Do

​Social Features

​Shareable Challenge Cards

​Profile Pages

​Leaderboard

Overview

The Mouth Bot (`@Mouth_App`)

Interaction Flows

Creating a Challenge from X

Challenge Accepted

Challenge Resolved

Bot Behavior Rules

What the Bot Does NOT Do

Social Features

Shareable Challenge Cards

Profile Pages

Leaderboard