Graph

Entity relationship graph and intelligence endpoints

Get Entity Graph

GET

Get the relationship graph for an entity, including connected entities and edges.

Path Parameters

slug · string · required

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

Query Parameters

depth · number · default: "1"

How many relationship levels to traverse (max: 3)

includeMarkets · boolean

Include market nodes in the graph

maxNodes · number

Maximum number of nodes to return

Response

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

cURL

curl "https://api.marketmotion.xyz/api/entities/patrick-mahomes/graph?depth=2&includeMarkets=true"

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

Higher depth values return exponentially more data. Use depth 3 sparingly.

---

Graph View Builder

GET

Configurable graph view that supports multiple visualization types.

Query Parameters

type · string · required

View type: neighborhood, movers, entity_markets, market_context, timeline, explain_fact, topic, cross_venue, impact_chain

entity · string

Entity ID (required for entity-centric views)

outcome · string

Outcome ID (for market views)

scope · string

Scope filter

window · number

Time window in hours

depth · number

Traversal depth

limit · number

Maximum results

topic · string

Topic string (for topic view)

factKey · string

Fact key (for explain_fact view)

Response

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

cURL

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

---

Entity Neighborhood

GET

Get the neighborhood subgraph around an entity.

Path Parameters

id · string · required

Entity ID

Query Parameters

depth · number

Traversal depth

includeFacts · boolean

Include fact nodes

includeEvents · boolean

Include event nodes

limit · number

Maximum nodes

Response

{
  "success": true,
  "graph": {
    "nodes": [...],
    "edges": [...]
  }
}

---

Entity Market Exposures

GET

Get market exposures for an entity with drivers and cross-venue pricing.

Path Parameters

id · string · required

Entity ID

Query Parameters

includeFacts · boolean

Include fact data

limit · number

Maximum results

Response

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

GET

Get event timeline for an entity.

Path Parameters

id · string · required

Entity ID

Query Parameters

window · number

Time window in hours

limit · number

Maximum events

Response

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

GET

Get entity events with impact scores and attribute changes.

Path Parameters

id · string · required

Entity ID

Query Parameters

limit · number

Maximum events

since · string

ISO date string — only return events after this time

Response

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

GET

Get version history for a specific entity fact/attribute.

Path Parameters

id · string · required

Entity ID

key · string · required

Fact key (e.g., injury_status)

Query Parameters

limit · number

Maximum versions

Response

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

GET

Get the context graph for a market outcome — entities, events, and facts that influence it.

Path Parameters

id · string · required

Outcome ID

Query Parameters

window · number

Time window in hours

limit · number

Maximum nodes

---

Outcome Prices

GET

Get cross-venue prices for a specific outcome.

Path Parameters

id · string · required

Outcome ID

Response

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

---

Outcome History

GET

Get price history for an outcome.

Path Parameters

id · string · required

Outcome ID

Query Parameters

hours · number

Hours of history to return

Response

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

---

Topic Discovery

GET

Discover entities and markets related to a topic.

Path Parameters

topic · string · required

Topic string (e.g., artificial-intelligence, nfl-playoffs)

Query Parameters

category · string

Filter by category

limit · number

Maximum results

includeMarkets · boolean

Include related markets

Response

{
  "success": true,
  "entities": [...],
  "markets": [...]
}

---

Event Impact

GET

Get the impact chain for an event — which entities and markets were affected.

Path Parameters

id · string · required

Event ID

Query Parameters

includeMarkets · boolean

Include market impact data

Response

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

---

Top Movers

GET

Get entities with the largest recent attribute or market changes.

Query Parameters

scope · string

Scope filter

window · number

Time window in hours

limit · number

Maximum results

Response

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

---

Mispricings

GET

Get cross-venue mispricing opportunities.

Query Parameters

minSpread · number

Minimum spread to include

category · string

Filter by category

limit · number

Maximum results

actionableOnly · boolean

Only return actionable mispricings

Response

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

cURL

curl "https://api.marketmotion.xyz/api/graph/mispricings?minSpread=0.05&category=sports&limit=10"

---

Top Mispricings

GET

Get the highest-spread mispricing opportunities.

Query Parameters

limit · number

Maximum results

Response

{
  "success": true,
  "opportunities": [...],
  "count": 10
}

---

Check Mispricing

GET

Check if a specific outcome is mispriced across venues.

Path Parameters

outcomeId · string · required

Outcome ID to check

Response

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

---

Mispricing Stats

GET

Get aggregate mispricing statistics.

Response

{
  "success": true,
  "stats": {
    "totalMispricings": 150,
    "averageSpread": 0.04,
    "maxSpread": 0.15,
    "byCategory": { ... }
  }
}

---

Cross-Venue Outcome

GET

Get cross-venue pricing data for a specific outcome.

Path Parameters

outcomeId · string · required

Outcome ID

Response

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

GET

Get markets that overlap between Kalshi and Polymarket.

Response

{
  "success": true,
  "markets": [...],
  "count": 50
}

---

Graph Stats

GET

Get aggregate statistics for the graph database.

Response

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

cURL

curl "https://api.marketmotion.xyz/api/graph/stats"

---

Visualization

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

D3.js Example

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

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)' } }
    ]
  });
}