> ## 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.

# Entities

> Structured representations of real-world things

## What is an Entity?

An **entity** is a structured representation of a real-world thing that's relevant to prediction markets. Unlike raw text or search results, entities have:

* **Typed attributes** (not just key-value strings)
* **Explicit relationships** to other entities
* **Market connections** showing which markets they affect

## Entity Types

| Type     | Description       | Examples                                  |
| -------- | ----------------- | ----------------------------------------- |
| `person` | Individual humans | Patrick Mahomes, Joe Biden, Elon Musk     |
| `team`   | Sports teams      | Kansas City Chiefs, Los Angeles Lakers    |
| `org`    | Organizations     | Federal Reserve, OpenAI, Democratic Party |
| `place`  | Locations         | Arrowhead Stadium, Iowa, New York City    |
| `league` | Sports leagues    | NFL, NBA, MLB                             |
| `asset`  | Financial assets  | Bitcoin, Ethereum, NVIDIA                 |

## Entity Structure

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "patrick-mahomes",
  "displayName": "Patrick Mahomes",
  "entityType": "person",
  "category": "sports",
  "subcategory": "nfl",
  "description": "NFL quarterback for Kansas City Chiefs",
  "attributes": {
    "position": "Quarterback",
    "jersey_number": "15",
    "injury_status": "healthy",
    "source": "ESPN",
    "updated_at": "2025-01-28T10:00:00Z"
  },
  "relationships": [...],
  "marketExposures": [...]
}
```

## Attributes

Attributes are typed key-value pairs attached to entities. Every attribute includes provenance:

```json theme={null}
{
  "injury_status": "questionable",
  "injury_status_source": "ESPN",
  "injury_status_updated": "2025-01-28T10:00:00Z",
  "injury_status_confidence": 0.95
}
```

### Common Attributes by Type

<Tabs>
  <Tab title="Person (Athlete)">
    | Attribute       | Type   | Description                |
    | --------------- | ------ | -------------------------- |
    | `position`      | string | Playing position           |
    | `jersey_number` | number | Jersey number              |
    | `injury_status` | enum   | healthy, questionable, out |
    | `team_slug`     | string | Current team reference     |
  </Tab>

  <Tab title="Person (Politician)">
    | Attribute         | Type   | Description         |
    | ----------------- | ------ | ------------------- |
    | `party`           | string | Political party     |
    | `office`          | string | Current office held |
    | `state`           | string | State represented   |
    | `approval_rating` | number | Latest approval %   |
  </Tab>

  <Tab title="Team">
    | Attribute      | Type   | Description           |
    | -------------- | ------ | --------------------- |
    | `conference`   | string | League conference     |
    | `division`     | string | League division       |
    | `stadium_slug` | string | Home venue reference  |
    | `record`       | string | Current season record |
  </Tab>
</Tabs>

## Slugs

Every entity has a unique `slug` used in API paths:

* URL-safe (lowercase, hyphens)
* Human-readable
* Stable (won't change)

Examples:

* `patrick-mahomes`
* `kansas-city-chiefs`
* `joe-biden`
* `bitcoin`

## Categories

Entities are organized into categories and subcategories:

```
sports/
  ├── nfl/
  ├── nba/
  ├── mlb/
  └── nhl/
politics/
  ├── us-congress/
  ├── governors/
  └── presidential/
crypto/
  ├── layer-1/
  ├── defi/
  └── memecoins/
finance/
  ├── equities/
  └── macro/
```

## Fetching Entities

### Get Single Entity

```bash theme={null}
GET /api/entities/:slug
```

Returns complete entity with relationships and market exposures.

### List Entities

```bash theme={null}
GET /api/entities?category=sports&type=person&limit=50
```

Filter by category, subcategory, and type.

### Search Entities

```bash theme={null}
GET /api/entities?q=mahomes
```

Full-text search across names and descriptions using the `q` parameter on the list endpoint.

## Why Entities Matter

<CardGroup cols={2}>
  <Card title="Machine-Readable">
    AI systems can directly consume entity data without parsing text or risking hallucinations.
  </Card>

  <Card title="Relationship Context">
    Understand how entities connect—a player to a team to a stadium to a city.
  </Card>

  <Card title="Market Mapping">
    Every entity links to relevant prediction markets, showing exposure.
  </Card>

  <Card title="Attributed Data">
    Every attribute includes source, timestamp, and confidence—full provenance.
  </Card>
</CardGroup>