Entities

Entity API endpoints

List Entities

GET

List all entities with optional filtering. Also supports search via the q parameter.

Query Parameters

category · string

Filter by category: politics, sports, crypto, finance

subcategory · string

Filter by subcategory: nfl, presidential, etc.

group · string

Filter by group within a subcategory

type · string

Filter by entity type: person, team, org, place, league, asset, event

tag · string

Filter by tag

q · string

Search entities by name (minimum 2 characters)

limit · number · default: "50"

Results per page

cursor · string

Cursor for pagination (from previous response’s nextCursor)

Response

{
  "success": true,
  "items": [
    {
      "id": "uuid",
      "slug": "patrick-mahomes",
      "displayName": "Patrick Mahomes",
      "entityType": "person",
      "category": "sports",
      "subcategory": "nfl",
      "description": "NFL quarterback for Kansas City Chiefs"
    }
  ],
  "nextCursor": "eyJpZCI6Imxhc3QtaWQifQ"
}

cURL

curl "https://api.marketmotion.xyz/api/entities?category=sports&type=person&limit=10"

Search Example

Search is done via the q parameter on the same list endpoint:

cURL

curl "https://api.marketmotion.xyz/api/entities?q=mahomes"

---

Get Entity

GET

Get entity details including relationships, markets, and news.

Path Parameters

slug · string · required

Entity slug (e.g., patrick-mahomes)

Response

{
  "success": true,
  "entity": {
    "id": "uuid",
    "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"
    },
    "relationships": [
      {
        "role": "plays_for",
        "entity": {
          "id": "uuid",
          "slug": "kansas-city-chiefs",
          "displayName": "Kansas City Chiefs",
          "entityType": "team"
        }
      }
    ],
    "marketExposures": [
      {
        "role": "subject",
        "market": {
          "id": "market-id",
          "title": "Chiefs to win Super Bowl LIX",
          "venue": "polymarket"
        },
        "outcome": {
          "label": "Yes"
        }
      }
    ]
  },
  "markets": [...],
  "news": [...]
}

cURL

curl "https://api.marketmotion.xyz/api/entities/patrick-mahomes"

---

Get Entity (Full)

GET

Get entity with all related data including relationships, primary and secondary markets, and news.

Path Parameters

slug · string · required

Entity slug

Query Parameters

marketLimit · number

Maximum number of markets to return

newsLimit · number

Maximum number of news items to return

Response

{
  "success": true,
  "entity": { ... },
  "relationships": [...],
  "markets": [...],
  "secondaryMarkets": [...],
  "news": [...]
}

cURL

curl "https://api.marketmotion.xyz/api/entities/patrick-mahomes/full?marketLimit=10&newsLimit=5"

---

Get Entity Markets

GET

Get prediction markets connected to an entity.

Path Parameters

slug · string · required

Entity slug

Query Parameters

venue · string

Filter by venue: polymarket, kalshi

limit · number

Maximum results

Response

{
  "success": true,
  "markets": [
    {
      "id": "market-uuid",
      "title": "Chiefs to win Super Bowl LIX",
      "venue": "polymarket",
      "price": 0.35,
      "volume": 1500000
    }
  ]
}

cURL

curl "https://api.marketmotion.xyz/api/entities/patrick-mahomes/markets?venue=polymarket"

---

Get Entity News

GET

Get news items related to an entity.

Path Parameters

slug · string · required

Entity slug

Query Parameters

limit · number

Maximum results

Response

{
  "success": true,
  "news": [
    {
      "id": "news-uuid",
      "title": "Mahomes expected to play Sunday",
      "source": "ESPN",
      "publishedAt": "2025-01-28T10:00:00Z"
    }
  ]
}

---

Get Entity Relationships

GET

Get all relationships for an entity, organized by direction.

Path Parameters

slug · string · required

Entity slug

Response

{
  "success": true,
  "entity": {
    "slug": "patrick-mahomes",
    "displayName": "Patrick Mahomes"
  },
  "relationships": {
    "from": [
      {
        "relationshipType": "plays_for",
        "entity": {
          "slug": "kansas-city-chiefs",
          "displayName": "Kansas City Chiefs",
          "entityType": "team"
        }
      }
    ],
    "to": [...]
  }
}

cURL

curl "https://api.marketmotion.xyz/api/entities/patrick-mahomes/relationships"

---

Get Related Entities

GET

Get entities related by graph traversal, with path and distance information.

Path Parameters

slug · string · required

Entity slug

Query Parameters

depth · number · default: "2"

How many relationship hops to traverse

types · string

Comma-separated entity types to include

Response

{
  "success": true,
  "entity": { "slug": "patrick-mahomes" },
  "relatedEntities": [
    {
      "entity": {
        "slug": "kansas-city-chiefs",
        "displayName": "Kansas City Chiefs",
        "entityType": "team"
      },
      "path": ["plays_for"],
      "distance": 1
    }
  ]
}

---

Get Subcategories

GET

Get available subcategories, optionally filtered by category.

Query Parameters

category · string

Filter subcategories by parent category

Response

{
  "success": true,
  "subcategories": [
    { "name": "nfl", "count": 200 },
    { "name": "nba", "count": 150 },
    { "name": "mlb", "count": 100 }
  ]
}

cURL

curl "https://api.marketmotion.xyz/api/entities/subcategories?category=sports"

---

Get Entities by Market

GET

Get all entities linked to a specific market.

Path Parameters

marketId · string · required

Market ID

Response

{
  "success": true,
  "entities": [
    {
      "slug": "patrick-mahomes",
      "displayName": "Patrick Mahomes",
      "entityType": "person",
      "role": "subject"
    }
  ]
}

cURL

curl "https://api.marketmotion.xyz/api/entities/by-market/market-uuid"