> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mouth.app/llms.txt
> Use this file to discover all available pages before exploring further.

# X (Twitter) Integration

> How Mouth integrates with X for challenge creation, notifications, and social engagement.

## 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**

## 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