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

# Markets

> Prediction markets across venues

## Market Data

Market Motion indexes prediction markets from multiple venues and links them to entities. This gives you:

* **Cross-venue coverage**: Polymarket, Kalshi, and more
* **Entity connections**: Which entities affect which markets
* **Structured data**: Prices, volumes, outcomes

## Supported Venues

| Venue          | Type           | Coverage                                |
| -------------- | -------------- | --------------------------------------- |
| **Polymarket** | Crypto/Web3    | Politics, Sports, Crypto, Entertainment |
| **Kalshi**     | CFTC-regulated | Politics, Economics, Weather, Sports    |

## Market Structure

```json theme={null}
{
  "id": "market-uuid",
  "externalId": "polymarket-condition-id",
  "title": "Will the Chiefs win Super Bowl LIX?",
  "venue": "polymarket",
  "category": "sports",
  "subcategory": "nfl",
  "active": true,
  "outcomes": [
    { "label": "Yes", "price": 0.35 },
    { "label": "No", "price": 0.65 }
  ],
  "volume": 1500000,
  "liquidity": 250000,
  "endDate": "2025-02-09T23:59:59Z"
}
```

## Entity-Market Links

Markets connect to entities through **market exposures**:

```json theme={null}
{
  "role": "subject",
  "market": {
    "id": "market-id",
    "title": "Chiefs to win Super Bowl LIX",
    "venue": "polymarket"
  },
  "outcome": {
    "label": "Yes"
  }
}
```

### Exposure Roles

| Role          | Description                          | Example                     |
| ------------- | ------------------------------------ | --------------------------- |
| `subject`     | Market is directly about this entity | "Will Biden win?" for Biden |
| `participant` | Entity participates in market event  | Team in a game market       |
| `affected`    | Entity is indirectly affected        | Stadium for a game market   |

## Fetching Markets

### List Markets

```bash theme={null}
GET /api/markets/predictions?venue=polymarket&category=sports&limit=20
```

**Parameters:**

* `venue`: polymarket, kalshi
* `category`: politics, sports, crypto, finance
* `subcategory`: nfl, presidential, etc.
* `active`: true/false
* `limit`, `offset`: pagination

### Search Markets

```bash theme={null}
GET /api/markets/search?q=super%20bowl&venue=polymarket
```

### Get Categories

```bash theme={null}
GET /api/markets/predictions/categories
```

Returns category breakdown with counts.

## Markets for an Entity

The most powerful query: get all markets affecting an entity.

```bash theme={null}
GET /api/entities/patrick-mahomes
```

The `marketExposures` array contains all relevant markets:

```json theme={null}
{
  "entity": {
    "slug": "patrick-mahomes",
    "marketExposures": [
      {
        "role": "subject",
        "market": { "title": "Mahomes MVP", "venue": "polymarket" }
      },
      {
        "role": "participant",
        "market": { "title": "Chiefs vs Ravens", "venue": "kalshi" }
      }
    ]
  }
}
```

## Cross-Venue Arbitrage

Find the same market across venues:

```javascript theme={null}
// Search both venues
const [polymarket, kalshi] = await Promise.all([
  fetch('/api/markets/search?q=chiefs%20super%20bowl&venue=polymarket'),
  fetch('/api/markets/search?q=chiefs%20super%20bowl&venue=kalshi')
]);

// Compare prices for arbitrage
const polyPrice = polymarket.markets[0].outcomes[0].price;
const kalshiPrice = kalshi.markets[0].outcomes[0].price;

if (Math.abs(polyPrice - kalshiPrice) > 0.03) {
  console.log('Potential arbitrage opportunity!');
}
```

## Market Categories

Markets are categorized using AI classification:

```
politics/
  ├── presidential/
  ├── congress/
  └── international/
sports/
  ├── nfl/
  ├── nba/
  └── soccer/
crypto/
  ├── prices/
  ├── launches/
  └── regulation/
finance/
  ├── fed/
  ├── inflation/
  └── earnings/
```

## Real-Time Data

<Note>
  Market prices are cached and updated periodically. For real-time trading, use venue APIs directly. Market Motion is optimized for entity context, not tick data.
</Note>

Use Market Motion to:

1. **Discover** which markets relate to an entity
2. **Understand** entity relationships affecting markets
3. **Monitor** attribute changes that signal market moves

Then execute trades directly on Polymarket or Kalshi.