> For the complete documentation index, see [llms.txt](https://serotolabs.gitbook.io/tradeclash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://serotolabs.gitbook.io/tradeclash/game-design/core-mechanics.md).

# Core Mechanics: Streets, Bids & Reveals

The complete auction ruleset. Everything here is public — no hidden mechanics.

***

## The Auction Loop

One lot. Three streets. One reveal. Roughly three minutes. Then the next lot deals.

```
Street 1 (30s) → Bids revealed → Street 2 (30s) → Bids revealed → Street 3 (30s) → Reveal → ~10s cooldown → Next lot
```

Rooms seat 2-4 players. Open seating — join or leave between lots. Rooms persist.

***

## Lot Composition

Every lot contains exactly **7 prediction market positions**. How they're distributed depends on the table size:

| Players | Private (1 each) | Shared (Streets 2+3) | Burn (hidden) |
| ------- | ---------------- | -------------------- | ------------- |
| 2       | 2                | 2                    | 3             |
| 3       | 3                | 2                    | 2             |
| 4       | 4                | 2                    | 1             |

There is always at least one burn card — a position nobody sees until the reveal. This prevents the lot from being fully solvable.

***

## Street 1 — "The Peek"

**Shared information** (visible to all players):

* Category (e.g., Politics, Macro, Tech)
* Payout range (e.g., $180–$420)
* Position count (always 7)

**Private information** (unique per player):

* One fully revealed position: market name, side (YES/NO), entry price, current price, size

This is dealt at the start. You have your hole card from the beginning.

**Action**: Sealed bid or $0 (pass). 30-second timer. Server-authoritative — timeout defaults to $0.

**After timer**: All bids revealed to all players.

**First-place win check**: If the highest bid exceeds the second-highest by **50% or more**, the high bidder wins the lot immediately. Skip to the reveal.

***

## Street 2 — "The Flip"

**New shared information**: One position revealed to all players. This is not dealt from the private pool — it's a new card flipped for the table.

**Known at this point**:

* Your private position
* 1 shared position
* All Street 1 bids

**Action**: Sealed bid. 30 seconds. Independent of previous bid — go up, down, or pass.

**After timer**: All bids revealed.

**First-place win check**: **20% gap** wins it early.

***

## Street 3 — "The River"

**New shared information**: One more position revealed to all players.

**Known at this point**:

* Your private position
* 2 shared positions
* All bids from Streets 1 and 2

**Action**: Final sealed bid. 30 seconds.

**No first-place win check.** Highest bid wins. Ties broken by earliest timestamp.

***

## The Reveal

All seven positions are exposed, including every burn card. The narrative plays out:

1. **trueValue calculated**: `sum of (currentPrice - entry) × size` across all 7 positions
2. **All bid history shown** — every player's bids from all 3 streets, visible as a bid evolution
3. **Winner announced** — highest final-street bid
4. **Profit calculated**: `trueValue - winningBid`
   * Positive = the winner got a deal
   * Negative = winner's curse (overbid)
   * Zero = the winner paid exact value
5. **Non-winners score 0** for that lot

If a lot was won via first-place win (Streets 1 or 2), the reveal shows a "FIRST PLACE WIN" badge.

If all players bid $0 on the final street, the lot goes unclaimed. No winner. Next lot deals.

***

## Bidding Rules

| Rule             | Detail                                                           |
| ---------------- | ---------------------------------------------------------------- |
| **Independence** | Bids are independent each street. Go up, down, or pass freely.   |
| **Visibility**   | All bids revealed between streets. You see what everyone thinks. |
| **Pass**         | $0 = pass. Not a permanent fold — you can bid on later streets.  |
| **Range**        | Non-negative, unbounded. Bid any amount ≥ $0.                    |
| **Currency**     | Game dollars (sandbox). $SIM or USDC in future real-money rooms. |
| **Timer**        | 30 seconds per street. Server-authoritative. Timeout = $0.       |

***

## First-Place Win Mechanic

Aggressive bidding is rewarded with early victory — and early risk.

| Street   | Gap Required | Rationale                             |
| -------- | ------------ | ------------------------------------- |
| Street 1 | ≥ 50%        | Bold play on minimal information      |
| Street 2 | ≥ 20%        | Achievable with private + shared info |
| Street 3 | None         | Standard auction — highest bid wins   |

A first-place win on overbid is dramatic. You gapped the table, won the lot, and the reveal shows you paid $340 for a $220 lot. The spectacle is part of the game.

***

## Between Lots

* \~10 seconds cooldown after reveal
* Next lot auto-deals
* Players can leave (no penalty) or stay
* New players can join if the room has space
* Cumulative leaderboard tracks session profit

***

## Scoring

Profit accumulates across lots. The leaderboard ranks by cumulative P\&L.

* Win a lot at a discount → positive profit
* Win a lot at a premium → negative profit (winner's curse)
* Don't win → 0 for that lot

Consistency matters more than swings. A player who profits $20 on ten lots outranks a player who profits $300 on one lot and loses $290 on nine.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://serotolabs.gitbook.io/tradeclash/game-design/core-mechanics.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.