> ## 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.
# How It Works
> The complete lifecycle of a Mouth bet, from creation to resolution.
## Bet Lifecycle
Every Mouth bet goes through a clear lifecycle with well-defined states:
**PvP bet (1v1) — Disputeable:**
```mermaid theme={null}
stateDiagram-v2
[*] --> Draft: Bot detects tag on X
[*] --> Pending: Challenger creates bet (web app)
Draft --> Pending: Challenger finalizes & deposits (on-chain)
Draft --> Abandoned: Challenger never finalizes
Pending --> Cancelled: Challenger withdraws
Pending --> Expired: Deadline passes (challenger or resolver withdraws)
Pending --> Active: Opponent accepts & deposits full amount
Active --> Resolved: Outcome determined (48h dispute window)
Resolved --> Finalized: Dispute window expires
Finalized --> Claimed: Winner claims funds
```
**PvP bet (1v1) — Non-Disputeable:**
```mermaid theme={null}
stateDiagram-v2
[*] --> Draft: Bot detects tag on X
[*] --> Pending: Challenger creates bet (web app)
Draft --> Pending: Challenger finalizes & deposits (on-chain)
Draft --> Abandoned: Challenger never finalizes
Pending --> Cancelled: Challenger withdraws
Pending --> Expired: Deadline passes (challenger or resolver withdraws)
Pending --> Active: Opponent accepts & deposits full amount
Active --> Finalized: Outcome determined (immediate)
Finalized --> Claimed: Resolver distributes funds automatically
```
**Open PvP Bet (partially fillable):**
```mermaid theme={null}
stateDiagram-v2
[*] --> Draft: Bot detects tag on X
[*] --> Pending: Challenger creates bet (web app)
Draft --> Abandoned: Challenger never finalizes
Draft --> Pending: Challenger finalizes & deposits (on-chain)
Pending --> Cancelled: Challenger withdraws (no fills yet)
Pending --> Expired: Deadline passes, no fills (challenger or resolver withdraws)
Pending --> Filling: First opponent deposits
Filling --> Filling: More opponents deposit
Filling --> Active: Fully filled OR acceptance deadline passes
Active --> Resolved: Outcome determined (disputeable: 48h window)
Active --> Finalized: Outcome determined (non-disputeable: immediate)
Resolved --> Finalized: Dispute window expires
Finalized --> Claimed: Winner(s) claim funds
```
The **Draft** state is backend-only (not on-chain). The smart contract is deployed only when the Challenger finalizes the bet and deposits USDC, transitioning from Draft to Pending.
## Step by Step
### 1. Create a Bet (Challenger)
A user (the **Challenger**) sees a prediction on X — or makes one himself — and creates a prediction.
**Via X:**
* User tweets (or replies to a tweet) tagging `@Mouth_App` with the prediction details and amount
* The Mouth bot detects the tag, creates a **Draft** in the backend, and replies with the bet URL (`pvp.mouth.app/challenge/{id}`)
* The user clicks the link and sees the bet form pre-filled with the tweet URL and opponent's handle
* The user completes the form, deposits USDC, and the bet is deployed on-chain (Draft → Pending)
* The **same URL** is now used by the opponent to view and accept the bet — no second link needed
**Via Web App:**
* User navigates to pvp.mouth.app and clicks "Create Bet"
* Fills in the prediction details
**Bet parameters:**
| Parameter | Description | Example |
| ---------------- | ----------------------------------------------------------------- | -------------------------------------------------------- |
| **Title** | Short description of the prediction | "Monad FDV under \$1B" |
| **Description** | Detailed terms and conditions | "Fully diluted valuation of \$MON token on CoinGecko..." |
| **Tweet link** | A link containing the tweet that originated the challenge | x.com/tweet |
| **Amount** | Bet size in USDC | \$500 |
| **Odds** | Challenger's perceived probability (10-90, default 50) | 50 |
| **Deadline** | Date before the prediction should be accepted (default: 72 hours) | June 15, 2025 |
| **Expiration** | When the prediction should be evaluated | June 30, 2025 |
| **Challenger** | X handle of the user | @user1 |
| **Opponent** | X handle of the challenged user (optional) | @user2 |
| **Open PvP Bet** | If no opponent is specified, anyone can take the other side | true/false |
The **Odds** parameter (default 50) sets the deposit ratio between the two sides. At 50, both sides deposit the same amount. At other values, the deposits are asymmetric: a Challenger who sets odds to 20 is saying their scenario has a 20% probability, so the opponent must deposit proportionally more to match. The opponent's required deposit is calculated as `challenger_amount * ((100 - odds) / odds)`.
The Challenger **confirms the deposit** — the backend deposits their USDC into the bet's smart contract via a gasless server-side transaction at creation time.
Funds are **NOT locked** at this stage. The Challenger can ALWAYS withdraw at any time before the opponent accepts and deposits their stake.
### 2. Accept a Bet (Opponent)
The opponent (either the specific challenged user or anyone, if the bet is open) sees the bet and decides to take the other side.
**Via X:**
* If the opponent has no balance on Mouth, they must click the **link** from the bot's reply and deposit USDC to accept the challenge
* If the opponent already has a balance on Mouth, they can just reply on X tagging @Mouth\_App and accept the challenge with natural language
**Via Web App:**
* User sees the bet on pvp.mouth.app (via direct link, explore page, or profile page)
* Clicks "Accept Challenge" — the backend deposits the matching USDC via a gasless server-side transaction
#### PvP Bets (1v1)
Once the opponent deposits the full matching amount, the bet becomes **Active**:
* Both deposits are locked in the smart contract
* The **2% protocol fee** is collected immediately and sent to the Mouth treasury
* Neither party can withdraw
* The bet will be resolved at the expiration date
#### Open PvP Bets (Partially Fillable)
Open PvP Bets (no specific opponent) can be filled by **multiple opponents**, each depositing a portion of the total amount:
* Any Mouth user can deposit any amount up to the remaining unfilled portion
* Multiple opponents can fill the bet over time
* The **2% protocol fee** is collected proportionally as each opponent deposits
* When the acceptance deadline passes, the bet becomes **Active** with whatever amount has been filled (via `activatePartial`)
* The Challenger can also trigger `activatePartial` at any time during filling to activate the bet early with the current filled amount — the unfilled portion is returned automatically
**Example:**
* Challenger creates an Open PvP Bet for \$1,000
* User A deposits \$600
* User B deposits \$400
* Bet is now fully filled → becomes Active immediately
* OR: acceptance deadline passes with \$600 filled → bet activates for \$600, \$400 returned to Challenger
* OR: Challenger triggers early activation with \$600 filled → same result, no need to wait for deadline
The acceptance deadline is **mandatory** for all bet types (default: 72 hours). It ensures every bet has a clear cutoff — if no one accepts by the deadline, the Challenger can reclaim their funds. For Open PvP Bets, it also prevents last-second sniping when the outcome may already be predictable.
### 3. Resolution
When the expiration date is reached, the bet enters the resolution phase.
The Mouth resolution engine determines the outcome:
1. **Automatic resolution** — For bets tied to verifiable on-chain data (token price, FDV, TVL), the protocol can resolve automatically using oracle data
2. **Manual resolution** — For subjective or off-chain bets, the Mouth team resolves the outcome
Each bet has a `disputeable` flag set at creation:
* **`disputeable = true`**: After resolution, a 48-hour dispute window opens. Either party can dispute the outcome. After the window expires (or a dispute is resolved), the bet is finalized and winners can claim.
* **`disputeable = false`**: Resolution immediately finalizes the bet — no dispute window, no waiting. For PvP 1v1 bets, the backend distributes funds automatically via `resolverClaim()`.
See [Resolution Engine](/architecture/resolution-engine) for the full resolution mechanism.
### 4. Claim Winnings
Once the bet is finalized:
* For **non-disputeable PvP 1v1 bets**: the backend distributes funds automatically right after resolution — no manual claim needed
* For **disputeable bets** or **Open PvP**: the **winner** claims the remaining pot from the web app (the 2% fee was already collected at deposit time)
* Funds are sent to the winner's embedded wallet as USDC
* The winner can then withdraw to any external wallet
**Example (PvP 1v1):**
* Challenger deposits \$500, Opponent deposits \$500
* Total pot: \$1,000
* Protocol fee (2%): \$20 (collected at deposit time)
* Winner receives: \$980
**Example (Open PvP Bet, 2 opponents):**
* Challenger deposits \$1,000, Opponents deposit \$600 + \$400
* Total pot: \$2,000
* Protocol fee (2%): \$40 (collected as each opponent deposits)
* If Challenger wins: receives \$1,960
* If Opponents win: each gets their proportional share of the remaining pot based on their deposit ratio. User A (\$600/\$1,000 = 60%) gets \$1,176, User B (\$400/\$1,000 = 40%) gets \$784
### 5. Edge Cases
The Challenger can withdraw their deposit at ANY time before acceptance. After the acceptance deadline, both the Challenger and the Resolver can withdraw (deserted bet cleanup).
If neither party has an interest in continuing, both can agree to cancel. Each party reclaims their remaining deposit (the 2% protocol fee was already collected at deposit time and is not refunded).
Only applies to disputeable bets. If a party disagrees with the resolution outcome, they can open a dispute within 48 hours. The resolver can re-resolve the bet during this window. See [Resolution Engine](/architecture/resolution-engine) for the dispute process.