> 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/technical-documentation/polymarket-integration.md).

# Polymarket Integration

Trade Clash lots are built from real Polymarket positions. This page explains how live prediction market data becomes a playable auction.

***

## What We Pull

The Polymarket API provides:

* **Active markets** — the prediction market question (e.g., "Will X happen by Y date?")
* **Current prices** — what YES and NO sides are trading at right now
* **Volume** — how much activity a market is generating
* **Resolution timers** — when the market resolves

We use this data in two places:

1. **Lot curation** — selecting positions and calculating trueValue
2. **Dashboard** — displaying live market intelligence on the globe

***

## From Market to Position

A Polymarket market becomes a position in a lot when an admin selects it during curation:

```
Polymarket market → Select side (YES or NO) → Set entry price → Record current price → Set size → Position ready
```

| Field          | Source                                               |
| -------------- | ---------------------------------------------------- |
| `market`       | Market question from Polymarket                      |
| `side`         | Admin selects YES or NO                              |
| `entry`        | Price at which the hypothetical position was entered |
| `currentPrice` | Live Polymarket price at curation time               |
| `size`         | Dollar size assigned by admin                        |

The difference between `entry` and `currentPrice` — scaled by `size` — determines the position's contribution to the lot's trueValue.

***

## Snapshot Timing

Positions are frozen at curation time. Once a lot is created, its trueValue is fixed — even if Polymarket prices move afterward.

This is intentional. The auction tests players' ability to evaluate a portfolio based on incomplete information, not their ability to track real-time price feeds. The lot is a static puzzle.

**Freshness**: Lots are curated from recent market data to stay relevant. Stale lots (where underlying markets have resolved or prices have shifted dramatically) are rotated out of the active pool.

***

## Lot Assembly

Seven positions are bundled into a lot:

1. **Category assignment** — based on the dominant theme of the selected markets (Politics, Macro, Tech, etc.)
2. **Payout range** — set to be 2-3x wider than the trueValue's actual position within it
3. **trueValue calculation** — `sum of (currentPrice - entry) × size` across all 7 positions
4. **Position ordering** — randomized for dealing (which becomes private, shared, or burn)

The admin tool pulls trending markets, so lots naturally reflect what's happening on Polymarket right now.

***

## Dashboard Feed

The globe dashboard displays Polymarket data independently of the auction:

* **Trending markets** by region/category
* **Price movements** — significant changes in the last 24 hours
* **Resolution calendar** — markets approaching their resolution date
* **Volume heatmap** — which regions/categories are most active

This serves as both a standalone market intelligence tool and a warm-up for auctions — players who browse the dashboard arrive at the table with category context.

***

## Phase 2: Deeper Integration

When player-created lots launch:

* **Direct Polymarket selection** — players browse live markets and pick positions for their lots
* **Auto-pricing** — trueValue calculated automatically from live prices
* **Market diversity scoring** — system encourages lots with positions from different markets (not 7 positions from the same question)
* **Auto-generated lots** — algorithmic lot creation from trending markets for continuous supply


---

# 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/technical-documentation/polymarket-integration.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.