> ## 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.
# Create a Bet
> How to create a new PvP bet on Mouth.
## Overview
There are two ways to create a bet on Mouth: via X (Twitter) or directly on the web app.
## Via X (Twitter)
### Flow
```mermaid theme={null}
sequenceDiagram
participant C as Challenger
participant X as X (Twitter)
participant Bot as Mouth Bot
participant BE as Backend
participant App as Mouth Web App
participant SC as Smart Contract
C->>X: Tweets or replies to a tweet, tags @Mouth_App
Bot->>BE: Creates Draft bet in DB
BE-->>Bot: Returns bet URL (pvp.mouth.app/challenge/{id})
Bot->>X: Replies with bet URL
C->>App: Clicks link, sees pre-filled form
C->>App: Completes details, confirms deposit
App->>BE: POST /bets (bet details + amount)
BE->>SC: Deploys bet contract via Factory + deposits USDC (gasless, server-side)
SC-->>BE: Bet live on-chain (Draft → Pending)
BE-->>App: Returns bet details
Note over C,X: Same URL now shows bet details to opponent
```
### Step by Step
1. **User tweets or replies to a tweet tagging `@Mouth_App`** — e.g., *"@Mouth\_App I'll put \$500 that ETH hits \$10k by EOY"* or replies to someone else's prediction with *"@Mouth\_App I'll put \$500 against this"*
2. **Mouth bot detects the tag** and:
* Creates a **Draft** bet in the backend database
* Replies with the bet URL: `pvp.mouth.app/challenge/{id}`
* The URL is pre-filled with the tweet URL and opponent's X handle (if any)
3. **User clicks the link** and sees the bet creation form with:
* Tweet URL already linked
* Opponent's X handle pre-filled (if any)
* Fields to edit/confirm: title, description, amount, expiration, odds
4. **User confirms the deposit** — the backend handles everything on-chain: approves USDC to the factory (if needed), deploys the bet contract via the Factory, and deposits the Challenger's USDC — all as a gasless server-side transaction via Privy
5. Bet goes from Draft to **Pending** on-chain
6. **The same URL** (`pvp.mouth.app/challenge/{id}`) now shows the finalized bet details to anyone who visits — including the opponent, who can accept directly from this page
If the opponent hasn't signed up on Mouth yet, the backend automatically pre-generates an embedded wallet for them via Privy's server SDK. When they eventually log in with X, they'll get the same wallet and can interact with the bet immediately. See [Identity & Wallets](/architecture/identity-and-wallets) for details.
## Via Web App
### Flow
```mermaid theme={null}
sequenceDiagram
participant C as Challenger
participant App as Mouth Web App
participant BE as Backend
participant SC as Smart Contract
participant Bot as Mouth Bot
participant X as X (Twitter)
C->>App: Navigates to pvp.mouth.app
C->>App: Clicks "Create Bet"
C->>App: Fills bet details, confirms deposit
App->>BE: POST /bets (bet details + amount)
BE->>SC: Deploys bet contract via Factory + deposits USDC (gasless, server-side)
SC-->>BE: Bet created on-chain (Pending)
BE-->>App: Returns bet details
App-->>C: Bet page live at pvp.mouth.app/challenge/{id}
C->>X: Shares link on X (optional)
Bot->>X: Optionally tags opponent with same link
```
### Step by Step
1. **User navigates to pvp.mouth.app**
2. **Logs in with X** (via Privy) — this creates/accesses their embedded wallet
3. **Clicks "Create Bet"** and fills in:
* **Title**: Short, clear prediction statement
* **Description**: Detailed terms, resolution criteria, data sources
* **Amount**: Bet size in USDC
* **Expiration date**: When the prediction should be evaluated
* **Opponent** (optional): X handle of the person being challenged
* **Category**: Crypto, Sports, Politics, Tech, Other
4. **Confirms the deposit** — the backend deploys the smart contract on-chain and deposits the Challenger's USDC via a gasless server-side transaction. Bet is now **Pending**
5. **Bet page is live** at `pvp.mouth.app/challenge/{id}` — can share on X, send in DMs, etc.
6. If an opponent was specified, the **Mouth bot tags them on X** with the same bet link
## Bet Parameters
### Required
| Parameter | Type | Description |
| ---------------- | ------- | ------------------------------------------------- |
| `title` | string | Short prediction statement (max 140 chars) |
| `amount` | uint256 | Bet amount in USDC (min total pot: \$10 USDC) |
| `expirationDate` | uint256 | Unix timestamp — when the prediction is evaluated |
### Optional
| Parameter | Type | Description | Default |
| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------- |
| `description` | string | Detailed terms and resolution criteria | empty |
| `opponent` | string | X handle of the challenged user | none (Open PvP Bet) |
| `odds` | uint8 | Challenger's perceived probability for their side (10-90). Determines the deposit ratio between challenger and opponent. | 50 |
| `category` | string | Bet category | "Other" |
| `acceptanceDeadline` | uint256 | Deadline for opponent to accept. **Mandatory for all bets.** | 72 hours |
| `disputeable` | bool | If `true`, 48h dispute window after resolution. If `false`, immediately finalized. | `false` |
| `tweetUrl` | string | URL of the original tweet (context) | none |
The acceptance deadline is **mandatory** for all bet types (default: 72 hours). It ensures that 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-moment sniping when the outcome may already be predictable.
## PvP vs Open PvP Bets
When creating a bet, the Challenger chooses one of two modes:
### PvP Bet (1v1)
* A specific opponent is named (X handle)
* Only that person can accept
* The opponent must deposit the **full matching amount**
* Acceptance deadline applies (default 72 hours) — opponent must accept before it passes
### Open PvP Bet (Partially Fillable)
* No specific opponent — anyone can take the other side
* **Multiple opponents** can each deposit a portion of the total amount
* Acceptance deadline applies (default 72 hours)
* The bet activates when fully filled OR when the acceptance deadline passes (whichever comes first)
* If only partially filled at the deadline, the bet activates with the filled amount and the unfilled portion is returned to the Challenger
See [Accept a Bet](/flows/accept-bet) for detailed acceptance flows.
## Single URL Lifecycle
Every bet has a **single, permanent URL** (`pvp.mouth.app/challenge/{id}`) that adapts its content based on who's viewing and the current state:
| Viewer | Bet State | What They See |
| ---------- | --------- | ---------------------------------------- |
| Challenger | Draft | Form to finalize bet details and deposit |
| Challenger | Pending | Bet details, withdraw option |
| Opponent | Pending | Bet details, "Accept Bet" button |
| Anyone | Active | Live bet, countdown to expiration |
| Anyone | Resolved | Result, winner, payout details |
For bets created via X, the bot posts **one reply** with this URL. The Challenger uses it to finalize, and the opponent uses the same link to accept — no second tweet or link needed.
## After Creation
Once the bet is created (on-chain):
* The bet appears on the Challenger's profile on pvp.mouth.app
* If directed at someone, the opponent receives a notification (X reply + web app notification)
* Open PvP Bets are visible on the Mouth explore page
* Funds are in the smart contract but **withdrawable** by the Challenger until accepted (directed) or until any opponent deposits (open)