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

# Graph

> Entity relationship graph and intelligence endpoints

## Get Entity Graph

<ParamField path="GET" method="/api/entities/:slug/graph">
  Get the relationship graph for an entity, including connected entities and edges.
</ParamField>

### Path Parameters

<ParamField path="slug" type="string" required>
  Entity slug (e.g., `patrick-mahomes`)
</ParamField>

### Query Parameters

<ParamField query="depth" type="number" default="1">
  How many relationship levels to traverse (max: 3)
</ParamField>

<ParamField query="includeMarkets" type="boolean">
  Include market nodes in the graph
</ParamField>

<ParamField query="maxNodes" type="number">
  Maximum number of nodes to return
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "graph": {
    "nodes": [
      {
        "id": "patrick-mahomes",
        "label": "Patrick Mahomes",
        "type": "person",
        "category": "sports"
      },
      {
        "id": "kansas-city-chiefs",
        "label": "Kansas City Chiefs",
        "type": "team",
        "category": "sports"
      }
    ],
    "edges": [
      {
        "source": "patrick-mahomes",
        "target": "kansas-city-chiefs",
        "label": "plays_for"
      }
    ],
    "centerNodeId": "patrick-mahomes"
  },
  "stats": {
    "totalNodes": 12,
    "totalEdges": 15
  }
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/entities/patrick-mahomes/graph?depth=2&includeMarkets=true"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.marketmotion.xyz/api/entities/patrick-mahomes/graph?depth=2'
  );
  const { graph, stats } = await response.json();
  console.log(`Nodes: ${stats.totalNodes}, Edges: ${stats.totalEdges}`);
  ```

  ```python Python theme={null}
  response = requests.get(
      'https://api.marketmotion.xyz/api/entities/patrick-mahomes/graph',
      params={'depth': 2}
  )
  data = response.json()
  graph = data['graph']
  ```
</CodeGroup>

### Graph Depth

| Depth | Description               | Use Case              |
| ----- | ------------------------- | --------------------- |
| 1     | Direct relationships only | Simple entity context |
| 2     | Two degrees of separation | Team → Stadium → City |
| 3     | Three degrees             | Full network analysis |

<Warning>
  Higher depth values return exponentially more data. Use depth 3 sparingly.
</Warning>

***

## Graph View Builder

<ParamField path="GET" method="/api/graph/view">
  Configurable graph view that supports multiple visualization types.
</ParamField>

### Query Parameters

<ParamField query="type" type="string" required>
  View type: `neighborhood`, `movers`, `entity_markets`, `market_context`, `timeline`, `explain_fact`, `topic`, `cross_venue`, `impact_chain`
</ParamField>

<ParamField query="entity" type="string">
  Entity ID (required for entity-centric views)
</ParamField>

<ParamField query="outcome" type="string">
  Outcome ID (for market views)
</ParamField>

<ParamField query="scope" type="string">
  Scope filter
</ParamField>

<ParamField query="window" type="number">
  Time window in hours
</ParamField>

<ParamField query="depth" type="number">
  Traversal depth
</ParamField>

<ParamField query="limit" type="number">
  Maximum results
</ParamField>

<ParamField query="topic" type="string">
  Topic string (for topic view)
</ParamField>

<ParamField query="factKey" type="string">
  Fact key (for explain\_fact view)
</ParamField>

### Response

Returns a graph structure with view-specific additional data depending on the `type` parameter.

<CodeGroup>
  ```bash cURL theme={null}
  # Entity neighborhood
  curl "https://api.marketmotion.xyz/api/graph/view?type=neighborhood&entity=entity-uuid&depth=2"

  # Top movers
  curl "https://api.marketmotion.xyz/api/graph/view?type=movers&window=24&limit=10"

  # Topic discovery
  curl "https://api.marketmotion.xyz/api/graph/view?type=topic&topic=artificial-intelligence&limit=20"
  ```
</CodeGroup>

***

## Entity Neighborhood

<ParamField path="GET" method="/api/graph/entity/:id/neighborhood">
  Get the neighborhood subgraph around an entity.
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  Entity ID
</ParamField>

### Query Parameters

<ParamField query="depth" type="number">
  Traversal depth
</ParamField>

<ParamField query="includeFacts" type="boolean">
  Include fact nodes
</ParamField>

<ParamField query="includeEvents" type="boolean">
  Include event nodes
</ParamField>

<ParamField query="limit" type="number">
  Maximum nodes
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "graph": {
    "nodes": [...],
    "edges": [...]
  }
}
```

***

## Entity Market Exposures

<ParamField path="GET" method="/api/graph/entity/:id/markets">
  Get market exposures for an entity with drivers and cross-venue pricing.
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  Entity ID
</ParamField>

### Query Parameters

<ParamField query="includeFacts" type="boolean">
  Include fact data
</ParamField>

<ParamField query="limit" type="number">
  Maximum results
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "graph": { ... },
  "exposures": [
    {
      "outcomeId": "outcome-uuid",
      "outcomeSlug": "chiefs-super-bowl-yes",
      "outcomeLabel": "Yes",
      "category": "sports",
      "subcategory": "nfl",
      "exposureType": "subject",
      "strength": 0.85,
      "reasons": ["Direct market subject"],
      "drivers": [...],
      "venuePrices": [
        { "venue": "polymarket", "price": 0.35 },
        { "venue": "kalshi", "price": 0.38 }
      ],
      "spread": 0.03
    }
  ]
}
```

***

## Entity Timeline

<ParamField path="GET" method="/api/graph/entity/:id/timeline">
  Get event timeline for an entity.
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  Entity ID
</ParamField>

### Query Parameters

<ParamField query="window" type="number">
  Time window in hours
</ParamField>

<ParamField query="limit" type="number">
  Maximum events
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "events": [
    {
      "id": "event-uuid",
      "eventType": "injury_update",
      "title": "Mahomes listed as questionable",
      "happenedAt": "2025-01-28T10:00:00Z",
      "impactScore": 0.8,
      "source": "ESPN"
    }
  ]
}
```

***

## Entity Events

<ParamField path="GET" method="/api/graph/entity/:id/events">
  Get entity events with impact scores and attribute changes.
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  Entity ID
</ParamField>

### Query Parameters

<ParamField query="limit" type="number">
  Maximum events
</ParamField>

<ParamField query="since" type="string">
  ISO date string — only return events after this time
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "entityId": "entity-uuid",
  "events": [
    {
      "id": "event-uuid",
      "eventType": "injury_update",
      "title": "Status changed to questionable",
      "happenedAt": "2025-01-28T10:00:00Z",
      "impactScore": 0.8,
      "source": "ESPN",
      "changes": [
        { "attribute": "injury_status", "from": "healthy", "to": "questionable" }
      ]
    }
  ]
}
```

***

## Fact History

<ParamField path="GET" method="/api/graph/entity/:id/fact/:key/history">
  Get version history for a specific entity fact/attribute.
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  Entity ID
</ParamField>

<ParamField path="key" type="string" required>
  Fact key (e.g., `injury_status`)
</ParamField>

### Query Parameters

<ParamField query="limit" type="number">
  Maximum versions
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "fact": {
    "key": "injury_status",
    "currentValue": "questionable"
  },
  "versions": [
    {
      "id": "version-uuid",
      "value": "questionable",
      "validFrom": "2025-01-28T10:00:00Z",
      "validTo": null,
      "versionHash": "abc123",
      "source": "ESPN",
      "eventType": "injury_update",
      "eventTitle": "Status changed"
    },
    {
      "id": "version-uuid-2",
      "value": "healthy",
      "validFrom": "2025-01-20T10:00:00Z",
      "validTo": "2025-01-28T10:00:00Z",
      "source": "ESPN"
    }
  ]
}
```

***

## Outcome Context

<ParamField path="GET" method="/api/graph/outcome/:id/context">
  Get the context graph for a market outcome — entities, events, and facts that influence it.
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  Outcome ID
</ParamField>

### Query Parameters

<ParamField query="window" type="number">
  Time window in hours
</ParamField>

<ParamField query="limit" type="number">
  Maximum nodes
</ParamField>

***

## Outcome Prices

<ParamField path="GET" method="/api/graph/outcome/:id/prices">
  Get cross-venue prices for a specific outcome.
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  Outcome ID
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "outcomeId": "outcome-uuid",
  "venues": [
    { "venue": "polymarket", "price": 0.35, "volume": 1500000 },
    { "venue": "kalshi", "price": 0.38, "volume": 800000 }
  ]
}
```

***

## Outcome History

<ParamField path="GET" method="/api/graph/outcome/:id/history">
  Get price history for an outcome.
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  Outcome ID
</ParamField>

### Query Parameters

<ParamField query="hours" type="number">
  Hours of history to return
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "outcomeId": "outcome-uuid",
  "history": [
    {
      "timestamp": "2025-01-28T10:00:00Z",
      "price": 0.35,
      "volume": 50000
    }
  ]
}
```

***

## Topic Discovery

<ParamField path="GET" method="/api/graph/topic/:topic">
  Discover entities and markets related to a topic.
</ParamField>

### Path Parameters

<ParamField path="topic" type="string" required>
  Topic string (e.g., `artificial-intelligence`, `nfl-playoffs`)
</ParamField>

### Query Parameters

<ParamField query="category" type="string">
  Filter by category
</ParamField>

<ParamField query="limit" type="number">
  Maximum results
</ParamField>

<ParamField query="includeMarkets" type="boolean">
  Include related markets
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "entities": [...],
  "markets": [...]
}
```

***

## Event Impact

<ParamField path="GET" method="/api/graph/event/:id/impact">
  Get the impact chain for an event — which entities and markets were affected.
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  Event ID
</ParamField>

### Query Parameters

<ParamField query="includeMarkets" type="boolean">
  Include market impact data
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "graph": { ... },
  "impact": [
    {
      "entityId": "entity-uuid",
      "entityName": "Patrick Mahomes",
      "impactScore": 0.8,
      "affectedMarkets": 5
    }
  ]
}
```

***

## Top Movers

<ParamField path="GET" method="/api/graph/movers">
  Get entities with the largest recent attribute or market changes.
</ParamField>

### Query Parameters

<ParamField query="scope" type="string">
  Scope filter
</ParamField>

<ParamField query="window" type="number">
  Time window in hours
</ParamField>

<ParamField query="limit" type="number">
  Maximum results
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "movers": [
    {
      "entityId": "entity-uuid",
      "entityName": "Patrick Mahomes",
      "changeType": "injury_status",
      "magnitude": 0.8,
      "affectedMarkets": 5
    }
  ]
}
```

***

## Mispricings

<ParamField path="GET" method="/api/graph/mispricings">
  Get cross-venue mispricing opportunities.
</ParamField>

### Query Parameters

<ParamField query="minSpread" type="number">
  Minimum spread to include
</ParamField>

<ParamField query="category" type="string">
  Filter by category
</ParamField>

<ParamField query="limit" type="number">
  Maximum results
</ParamField>

<ParamField query="actionableOnly" type="boolean">
  Only return actionable mispricings
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "mispricings": [
    {
      "outcomeId": "outcome-uuid",
      "label": "Chiefs to win Super Bowl",
      "venues": [
        { "venue": "polymarket", "price": 0.35 },
        { "venue": "kalshi", "price": 0.42 }
      ],
      "spread": 0.07,
      "category": "sports"
    }
  ],
  "count": 25,
  "summary": { ... }
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/graph/mispricings?minSpread=0.05&category=sports&limit=10"
  ```
</CodeGroup>

***

## Top Mispricings

<ParamField path="GET" method="/api/graph/mispricings/top">
  Get the highest-spread mispricing opportunities.
</ParamField>

### Query Parameters

<ParamField query="limit" type="number">
  Maximum results
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "opportunities": [...],
  "count": 10
}
```

***

## Check Mispricing

<ParamField path="GET" method="/api/graph/mispricings/check/:outcomeId">
  Check if a specific outcome is mispriced across venues.
</ParamField>

### Path Parameters

<ParamField path="outcomeId" type="string" required>
  Outcome ID to check
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "mispriced": true,
  "signal": {
    "spread": 0.07,
    "venues": [
      { "venue": "polymarket", "price": 0.35 },
      { "venue": "kalshi", "price": 0.42 }
    ]
  }
}
```

***

## Mispricing Stats

<ParamField path="GET" method="/api/graph/mispricings/stats">
  Get aggregate mispricing statistics.
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "stats": {
    "totalMispricings": 150,
    "averageSpread": 0.04,
    "maxSpread": 0.15,
    "byCategory": { ... }
  }
}
```

***

## Cross-Venue Outcome

<ParamField path="GET" method="/api/graph/cross-venue/:outcomeId">
  Get cross-venue pricing data for a specific outcome.
</ParamField>

### Path Parameters

<ParamField path="outcomeId" type="string" required>
  Outcome ID
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "outcomeId": "outcome-uuid",
  "venues": [
    { "venue": "polymarket", "price": 0.35, "volume": 1500000 },
    { "venue": "kalshi", "price": 0.38, "volume": 800000 }
  ],
  "mispricing": {
    "spread": 0.03,
    "direction": "kalshi_higher"
  }
}
```

***

## Kalshi Overlapping

<ParamField path="GET" method="/api/graph/kalshi/overlapping">
  Get markets that overlap between Kalshi and Polymarket.
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "markets": [...],
  "count": 50
}
```

***

## Graph Stats

<ParamField path="GET" method="/api/graph/stats">
  Get aggregate statistics for the graph database.
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "stats": {
    "sources": 22,
    "events": 15000,
    "facts": 85000,
    "factVersions": 250000,
    "outcomes": 5000,
    "marketExposures": 12000,
    "marketSnapshots": 1000000,
    "marketMoves": 50000
  },
  "factsByType": { ... },
  "recentEventsByType": { ... }
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/graph/stats"
  ```
</CodeGroup>

***

## Visualization

The graph responses are designed for direct use with visualization libraries:

### D3.js Example

```javascript theme={null}
import * as d3 from 'd3';

async function renderGraph(entitySlug) {
  const response = await fetch(`/api/entities/${entitySlug}/graph?depth=2`);
  const { graph } = await response.json();

  const simulation = d3.forceSimulation(graph.nodes)
    .force('link', d3.forceLink(graph.edges).id(d => d.id))
    .force('charge', d3.forceManyBody().strength(-300))
    .force('center', d3.forceCenter(width / 2, height / 2));

  // ... render nodes and edges
}
```

### Cytoscape.js Example

```javascript theme={null}
import cytoscape from 'cytoscape';

async function renderGraph(entitySlug) {
  const response = await fetch(`/api/entities/${entitySlug}/graph?depth=2`);
  const { graph } = await response.json();

  const cy = cytoscape({
    container: document.getElementById('graph'),
    elements: [
      ...graph.nodes.map(n => ({ data: { id: n.id, label: n.label } })),
      ...graph.edges.map(e => ({
        data: { source: e.source, target: e.target, label: e.label }
      }))
    ],
    style: [
      { selector: 'node', style: { 'label': 'data(label)' } },
      { selector: 'edge', style: { 'label': 'data(label)' } }
    ]
  });
}
```