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

{
  "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:

{
  "injury_status": "questionable",
  "injury_status_source": "ESPN",
  "injury_status_updated": "2025-01-28T10:00:00Z",
  "injury_status_confidence": 0.95
}

Common Attributes by Type

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

Person (Politician)

Attribute	Type	Description
party	string	Political party
office	string	Current office held
state	string	State represented
approval_rating	number	Latest approval %

Team

Attribute	Type	Description
conference	string	League conference
division	string	League division
stadium_slug	string	Home venue reference
record	string	Current season record

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

GET /api/entities/:slug

Returns complete entity with relationships and market exposures.

List Entities

GET /api/entities?category=sports&type=person&limit=50

Filter by category, subcategory, and type.

Search Entities

GET /api/entities?q=mahomes

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

Why Entities Matter

Machine-Readable

AI systems can directly consume entity data without parsing text or risking hallucinations.

Relationship Context

Understand how entities connect—a player to a team to a stadium to a city.

Market Mapping

Every entity links to relevant prediction markets, showing exposure.

Attributed Data

Every attribute includes source, timestamp, and confidence—full provenance.