Graph - Market Motion

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

# 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

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

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

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

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

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

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

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

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

Response

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

Event Impact

GET

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

Path Parameters

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

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

​Get Entity Graph

​Path Parameters

​Query Parameters

​Response

​Graph Depth

​Graph View Builder

​Query Parameters

​Response

​Entity Neighborhood

​Path Parameters

​Query Parameters

​Response

​Entity Market Exposures

​Path Parameters

​Query Parameters

​Response

​Entity Timeline

​Path Parameters

​Query Parameters

​Response

​Entity Events

​Path Parameters

​Query Parameters

​Response

​Fact History

​Path Parameters

​Query Parameters

​Response

​Outcome Context

​Path Parameters

​Query Parameters

​Outcome Prices

​Path Parameters

​Response

​Outcome History

​Path Parameters

​Query Parameters

​Response

​Topic Discovery

​Path Parameters

​Query Parameters

​Response

​Event Impact

​Path Parameters

​Query Parameters

​Response

​Top Movers

​Query Parameters

​Response

​Mispricings

​Query Parameters

​Response

​Top Mispricings

​Query Parameters

​Response

​Check Mispricing

​Path Parameters

​Response

​Mispricing Stats

​Response

​Cross-Venue Outcome

​Path Parameters

​Response

​Kalshi Overlapping

​Response

​Graph Stats

​Response

​Visualization

​D3.js Example

​Cytoscape.js Example

Get Entity Graph

Path Parameters

Query Parameters

Response

Graph Depth

Graph View Builder

Query Parameters

Response

Entity Neighborhood

Path Parameters

Query Parameters

Response

Entity Market Exposures

Path Parameters

Query Parameters

Response

Entity Timeline

Path Parameters

Query Parameters

Response

Entity Events

Path Parameters

Query Parameters

Response

Fact History

Path Parameters

Query Parameters

Response

Outcome Context

Path Parameters

Query Parameters

Outcome Prices

Path Parameters

Response

Outcome History

Path Parameters

Query Parameters

Response

Topic Discovery

Path Parameters

Query Parameters

Response

Event Impact

Path Parameters

Query Parameters

Response

Top Movers

Query Parameters

Response

Mispricings

Query Parameters

Response

Top Mispricings

Query Parameters

Response

Check Mispricing

Path Parameters

Response

Mispricing Stats

Response

Cross-Venue Outcome

Path Parameters

Response

Kalshi Overlapping

Response

Graph Stats

Response

Visualization

D3.js Example

Cytoscape.js Example