# Market Motion API — LLM Context File

> Structured entity intelligence for prediction markets. 17,000+ typed entities, 18,400+ relationship edges, cross-venue arbitrage detection, and real-time alerts — the context layer for AI trading systems.

## Quick Reference

- Base URL: `https://api.marketmotion.xyz/api`
- Auth: `X-API-Key: mt_live_...` header (optional for public endpoints, required for B2B)
- Rate limits: 30/min (no key), 300/min (developer key), 1,000/min (pro key)
- Response format: `{ "success": true, "data": { ... } }` or `{ "success": false, "error": "..." }`
- Venues: Polymarket, Kalshi, Hyperliquid
- Get API keys: https://motiontrade.xyz/developer
- Full docs: https://motiontrade.mintlify.app/api/introduction

---

## Entity System

Entities are canonical representations of real-world things that affect prediction markets. Each entity has a slug (URL-safe identifier), typed attributes with provenance, explicit relationships to other entities, and links to affected markets across venues.

### Entity Types

| Type   | Description                        | Examples                              |
|--------|------------------------------------|---------------------------------------|
| person | Individual humans                  | Patrick Mahomes, Donald Trump         |
| team   | Sports teams, political parties    | Kansas City Chiefs, Democratic Party  |
| org    | Companies, agencies, institutions  | Federal Reserve, OpenAI, SEC          |
| place  | Locations                          | Arrowhead Stadium, Iowa, Washington   |
| league | Sports leagues                     | NFL, NBA, MLB, NHL                    |
| asset  | Financial instruments              | Bitcoin, Ethereum, NVIDIA             |

### Categories

| Category   | Subcategories                                                                        |
|------------|--------------------------------------------------------------------------------------|
| politics   | us-government, us-elections, governors, + 104 international (uk-politics, france-politics, china-politics, etc.) |
| sports     | nfl, nba, mlb, nhl, ncaa-mens-basketball, ncaa-womens-basketball, soccer            |
| finance    | fed, macro, equities, earnings, central-banks                                        |
| crypto     | layer-1, defi, memecoins, nft, regulation                                            |
| culture    | entertainment, awards, media                                                         |
| science    | space, climate, health, physics                                                      |
| technology | ai, software, hardware, semiconductors                                               |

### Relationship Types

| Relationship    | From   → To     | Example                                |
|-----------------|-----------------|----------------------------------------|
| plays_for       | person → team   | Mahomes plays_for Chiefs               |
| member_of       | person → org    | Biden member_of Democratic Party       |
| leads           | person → org    | Starmer leads Labour Party             |
| colleague_of    | person → person | Cabinet member colleague_of PM         |
| plays_at        | team → place    | Chiefs plays_at Arrowhead Stadium      |
| located_in      | place → place   | Arrowhead located_in Kansas City       |
| competes_in     | team → league   | Chiefs competes_in NFL                 |
| governs         | person → place  | Governor governs State                 |
| affiliated_with | entity → entity | General-purpose connection             |
| parent_of       | org → org       | Parent company → subsidiary            |

### Typed Attributes

Entities have key-value attributes with provenance tracking:
- `injury_status`: healthy | questionable | doubtful | out (source: ESPN)
- `party`: Republican | Democrat | Labour | etc. (source: official records)
- `state`: US state abbreviation (source: congress data)
- `approval_rating`: numeric (source: polls)
- `team_record`: win-loss string (source: ESPN)
- `weather`: { conditions, temperature, windSpeed, bettingImpact } (source: weather API)

Attribute changes trigger market impact detection — when an entity's attributes change, the system identifies which connected markets may be affected.

---

## API Endpoints

### Entities

**GET /api/entities**
Search and browse entities.
```
Params: q (search text), category, subcategory, group, type (person|team|org|place|league|asset), tag (comma-separated), limit (default 50, max 200), cursor
Response: { success, items: [{ id, slug, displayName, entityType, category, subcategory, group, tags, snapshot }], nextCursor }
```

**GET /api/entities/:slug**
Get entity by slug with markets and news.
```
Params: slug (e.g., "patrick-mahomes", "donald-trump", "keir-starmer")
Response: { success, entity: { id, slug, displayName, entityType, category, subcategory, bio, avatarUrl, tags, snapshot: { party, state, role, chamber, ... } }, markets: [{ marketId, question, volume, outcomes: [{ tokenId, outcomeName, price }], link: { confidence, reason } }], news: { count24h, items: [{ id, source, title, content, sentiment, publishedAt }] } }
```

**GET /api/entities/:slug/full**
Entity with all relationships expanded.
```
Response: { success, entity: { ...full entity }, relationships: { from: [{ id, type, role, relatedEntity: { id, slug, displayName, entityType } }], to: [...] }, markets: [...], news: { count24h, items: [...] } }
```

**GET /api/entities/:slug/markets**
All prediction markets linked to this entity.

**GET /api/entities/:slug/news**
News items related to entity.

**GET /api/entities/:slug/relationships**
Entity relationships only.

**GET /api/entities/:slug/related**
Related entities (via relationship graph).

**GET /api/entities/:slug/completeness**
Entity data completeness score.

**GET /api/entities/by-market/:marketId**
Find entities linked to a specific market.

**GET /api/entities/subcategories**
Get subcategories for a category.
```
Params: category
Response: { success, category, subcategories: [{ subcategory, count }] }
```

### Taxonomy Navigation

**GET /api/taxonomy/stats**
Full taxonomy statistics.
```
Response: { success, totalEntities, totalLinkedMarkets, totalCategories, totalRelationshipTypes, byCategory: { politics: 1632, sports: 12500, ... } }
```

**GET /api/taxonomy/:category/:subcategory/groups**
Groups within a subcategory.
```
Response: { success, category, subcategory, groups: [{ group, count }] }
```

**GET /api/taxonomy/:category/:subcategory/:group/entities**
Entities in a specific group.
```
Params: type, tag, q, limit, cursor
Response: { success, category, subcategory, group, items: [...], nextCursor }
```

### Markets

**GET /api/markets/search**
Search markets across all venues by keyword.
```
Params: q (required), limit (max 20, default 10), venue (all|polymarket|hyperliquid)
Response: { success, query, data: [{ id, symbol, title/question, venue, price, volume, outcomes }] }
```

**GET /api/markets/predictions**
Browse prediction markets (Polymarket + Kalshi) with filters.
```
Params: venue (polymarket|kalshi|all, default all), category (comma-separated), sort (volume|liquidity|ending_soon|new|activity), volumeMin, endingWithin (days), search, limit (default 50), offset
Response: { markets: [{ id, venue, question, category, volume, liquidity, yesPrice, noPrice, outcomes: [{ name, price, tokenId }], endDate, image }], total, limit, offset, hasMore }
```

**GET /api/markets/predictions/categories**
All prediction market categories with counts.
```
Response: { success, categories: [{ name, count, slug }] }
```

**GET /api/markets/curated**
Homepage curated markets (Hyperliquid perps/spot).
```
Response: { trending: [...], topVolume: [...], newMarkets: [...], featured: [...] }
Market fields: { id, symbol, name, price, priceChange24h, volume24h, openInterest, fundingRate, maxLeverage, productType, category }
```

**GET /api/markets/filter**
Filter Hyperliquid markets.
```
Params: type (all|perps|spot|stocks), category, sort (volume|change|name|new), order (asc|desc), search, limit, offset
Response: { markets: [...], total, limit, offset }
```

**GET /api/markets/detail/:symbol**
Detailed market data for a symbol.
```
Response: { market: { id, symbol, name, price, priceChange24h, volume24h, openInterest, fundingRate, maxLeverage, markPrice, indexPrice, productType } }
```

**GET /api/markets/candles/:symbol**
OHLCV candle data.
```
Params: interval (default '15m'), period (LIVE|1H|1D|1W|1M)
Response: { symbol, interval, period, candles: [{ timestamp, open, high, low, close, volume }] }
```

**GET /api/markets/:venue/:marketId**
Get market details by venue and ID.

**GET /api/markets/categories**
Hyperliquid market categories.
```
Response: { productTypes: { all, perps, spot, stocks }, categories: [{ name, count }] }
```

### Cross-Venue Matching & Arbitrage

**GET /api/markets/cross-venue**
Find same markets listed on multiple venues (Polymarket + Kalshi).
```
Params: limit (default 20, max 50)
Response: { success, markets: [{ outcomeId, label, category, venues: [{ venue, marketId, price, volume }], spread, arbitrageOpportunity }], stats: { total, withArbitrage } }
```

**GET /api/markets/entity-connected**
Markets connected to entities with cross-venue data.
```
Params: limit, category, minSpread
Response: { success, crossVenueMarkets, directEntityLinks, stats: { totalCrossVenue, totalDirectLinks, withArbitrageSignal } }
```

**POST /api/markets/cross-venue/match**
Trigger cross-venue matching (Polymarket ↔ Kalshi).
```
Response: { success, matches: [{ polymarket, kalshi, similarity, matchType }], stats }
```

### Graph & Intelligence

**GET /api/graph/mispricings**
Find cross-venue arbitrage opportunities with spread analysis. This is the primary arbitrage detection endpoint.
```
Params: minSpread (default 0.05), category, limit, actionableOnly (boolean)
Response: {
  success, count,
  mispricings: [{
    question, spread,
    venues: [{ venue, marketId, yesPrice, noPrice, volume }],
    category, actionable
  }],
  summary: { totalFound, actionable, arbitrage, avgSpread }
}
```

**GET /api/graph/mispricings/top**
Top mispricing opportunities ranked by spread.
```
Params: limit (default 10)
Response: { success, opportunities, count }
```

**GET /api/graph/mispricings/check/:outcomeId**
Check if a specific outcome is mispriced across venues.
```
Response: { success, mispriced: boolean, signal (if mispriced), message }
```

**GET /api/graph/mispricings/stats**
Aggregate mispricing statistics.

**GET /api/graph/cross-venue/:outcomeId**
Cross-venue price data for a specific outcome.
```
Response: { success, outcomeId, venues: [{ venue, price, volume }], mispricing }
```

**GET /api/graph/movers**
Top price movers in recent window.
```
Params: scope, window (hours, default 24), limit (default 20)
Response: Graph view with nodes/edges showing price movement
```

**GET /api/graph/entity/:id/neighborhood**
Entity relationship graph — traverse connections.
```
Params: depth (1-3), includeFacts (boolean), includeEvents (boolean), limit
Response: Graph view { nodes: [...], edges: [...] }
```

**GET /api/graph/entity/:id/markets**
Entity market exposure — all markets affected by this entity.
```
Params: includeFacts, limit
Response: { ...graphData, exposures: [{ outcomeId, outcomeSlug, outcomeLabel, category, subcategory, exposureType, strength, reasons, drivers, venuePrices, spread }] }
```

**GET /api/graph/entity/:id/timeline**
Entity event timeline.
```
Params: window (hours, default 168), limit (default 30)
```

**GET /api/graph/entity/:id/events**
Entity events (attribute changes, news, market moves).
```
Params: limit (default 20), since (ISO date)
Response: { success, entityId, events: [{ id, eventType, title, happenedAt, impactScore, source, changes }] }
```

**GET /api/graph/entity/:id/fact/:key/history**
Attribute version history with provenance.
```
Params: limit (default 10)
Response: { success, fact: { id, key, factType, currentValue }, versions: [{ id, value, validFrom, validTo, source, eventType, eventTitle }] }
```

**GET /api/graph/outcome/:id/context**
Market context — entities and events affecting an outcome.
```
Params: window (hours), limit
```

**GET /api/graph/outcome/:id/prices**
Cross-venue prices for an outcome.
```
Response: { success, outcomeId, venues: [{ venue, price, volume }] }
```

**GET /api/graph/outcome/:id/history**
Outcome price history.
```
Params: hours (default 24)
```

**GET /api/graph/topic/:topic**
Explore a topic across entities and markets.
```
Params: category, limit, includeMarkets (default true)
```

**GET /api/graph/event/:id/impact**
Event impact analysis — which markets moved.
```
Params: includeMarkets (default true)
```

**GET /api/graph/view**
Generic graph view builder.
```
Params: type (required: neighborhood|movers|entity_markets|market_context|timeline|explain_fact|topic|cross_venue|impact_chain), entity, outcome, scope, window, depth, includeFacts, includeEvents, includeMarkets, limit, factKey, topic, category, eventId
```

**GET /api/graph/stats**
System-wide graph statistics.
```
Response: { success, stats: { sources, events, facts, factVersions, outcomes, marketExposures, marketSnapshots, marketMoves }, factsByType, recentEventsByType }
```

### Alerts

Real-time alerts for market-moving events.

Alert types: `injury`, `crowding_spike`, `crowding_rotation`, `weather`, `copy_trade`, `arbitrage`, `rumor`, `political_change`, `finance_change`

**GET /api/alerts/inbox**
User's alert inbox (requires auth).
```
Params: type (alert type filter), limit (default 50, max 100), offset
Response: {
  success,
  data: {
    alerts: [{
      id, type, subtype, asset, entitySlug,
      headline, details,
      metrics: { ... type-specific metrics },
      sentAt, read, readAt, dismissed, actedOn
    }],
    pagination: { limit, offset, total },
    unreadCount
  }
}
```

**GET /api/alerts/:id**
Full alert with context, entity data, and related markets.
```
Response: {
  success,
  data: {
    id, type, subtype, asset, marketId, entitySlug,
    headline, details,
    whyThisFired: ["Reason 1", "Reason 2"],
    priceAtAlert, currentPrice,
    entity: { slug, displayName, entityType, subcategory },
    humanStats: { "Team": "...", "Position": "...", "Player Tier": "..." },
    relatedMarkets: [{ venue, marketId, question, outcomeName, yesPrice, volume }],
    metrics: { ... },
    engagement: { tradesWithin1m, tradesWithin5m, tradesWithin15m }
  }
}
```

**POST /api/alerts/:id/read** — Mark alert as read
**POST /api/alerts/:id/dismiss** — Dismiss alert
**POST /api/alerts/:id/acted** — Mark that user traded on this alert

**GET /api/alerts/outcomes/stats**
Alert effectiveness analytics.
```
Params: days (default 30), type, entity
```

**GET /api/alerts/outcomes/top**
Top performing alerts by outcome score.

**GET /api/alerts/:id/outcome**
Outcome tracking for a specific alert.

**GET /api/alerts/recent**
Recent alpha alerts (public, from discovery service).

**GET /api/alerts/stream**
Server-Sent Events stream for real-time alerts.

### Alert Metrics by Type

**Injury alerts:**
```json
{ "oldStatus": "Active", "newStatus": "Out", "team": "Denver Nuggets", "position": "C" }
```

**Crowding alerts:**
```json
{ "longShare": 0.82, "traderCount": 47 }
```

**Arbitrage alerts:**
```json
{ "spread": 0.08, "venues": ["polymarket", "kalshi"], "direction": "buy_kalshi_sell_poly" }
```

**Political change alerts:**
```json
{ "changeType": "appointment", "entity": "marco-rubio", "role": "Secretary of State" }
```

**Finance change alerts:**
```json
{ "indicator": "fed_rate", "previousValue": 5.25, "newValue": 5.00 }
```

---

## B2B API (requires API key)

Enterprise endpoints for prediction market platforms. All require `X-API-Key` header.

### Market Suggestions

**GET /api/b2b/suggestions**
Recent alerts surfaced as trading opportunities with linked prediction markets.
```
Auth: X-API-Key + read permission
Params: category, limit (max 50, default 20), offset, hours (max 168, default 24)
Response: {
  success,
  data: [{
    entity: { slug, displayName, category, avatarUrl },
    alertType, headline, sentAt,
    markets: [{ venue, marketId, question, outcomeId, outcomeName, currentPrice, volume, confidence }],
    signal: { strength, reasons, priceAtAlert, direction },
    engagement: { tradesWithin1m, tradesWithin5m, tradesWithin15m }
  }],
  pagination: { limit, offset, total }
}
```

**GET /api/b2b/suggestions/trending**
Top-ranked suggestions from the last 6 hours.
```
Auth: X-API-Key + read permission
Params: limit (max 20, default 10)
Response: { success, data: [...same shape as suggestions...] }
```

### Person Intelligence

**GET /api/b2b/people**
Browse and search person entities with market counts and alert activity.
```
Auth: X-API-Key + read permission
Params: q (search), category, subcategory, limit (max 100, default 50), offset
Response: {
  success,
  data: [{
    slug, displayName, category, subcategory, entityType, avatarUrl, tags,
    snapshot: { party, state, role, ... },
    marketCount, recentAlertCount
  }],
  pagination: { limit, offset, total }
}
```

**GET /api/b2b/people/:slug**
Full person profile with attributes, relationships, recent alerts, and all affected markets.
```
Auth: X-API-Key + read permission
Response: {
  success,
  data: {
    entity: { slug, displayName, category, subcategory, bio, avatarUrl, tags, snapshot },
    relationships: [{ type, role, relatedEntity: { slug, displayName, entityType } }],
    recentAlerts: [{ type, headline, sentAt }],
    markets: [{ venue, marketId, question, currentPrice, volume, confidence }],
    stats: { totalMarkets, totalAlerts7d, topAlertTypes }
  }
}
```

**GET /api/b2b/people/:slug/markets**
Markets for a person with cross-venue price comparison.
```
Auth: X-API-Key + read permission
Params: venue, limit, offset
Response: {
  success,
  data: [{
    venue, marketId, question, outcomeId, outcomeName,
    currentPrice, volume, confidence,
    crossVenue: [{ venue, price, volume }] // same market on other venues
  }]
}
```

### Market Gap Analysis (Pro tier)

Data-driven detection of entities with high signal activity but low market coverage.

**GET /api/b2b/gaps**
Top market gaps across all entities. Requires Pro tier when monetization is enabled.
```
Auth: X-API-Key + read permission + Pro tier
Params: category, limit (max 50, default 20), minSignals (default 1)
Response: {
  success,
  data: [{
    entity: { slug, displayName, category, subcategory, avatarUrl },
    gapScore: 0.82,  // 0-1, higher = bigger opportunity
    signals: {
      alertCount7d, newsMentions7d,
      topAlertTypes: ["injury", "rumor"]
    },
    coverage: {
      linkedMarkets, categoryAverage, deficit
    },
    recentAlerts: [{ headline, alertType, sentAt }],
    suggestedCategories: ["game_outcomes", "mvp"]
  }]
}
```

**GET /api/b2b/gaps/:slug**
Detailed gap analysis for a single entity.
```
Auth: X-API-Key + read permission + Pro tier
Response: { success, data: { ...same shape with expanded detail... } }
```

### Webhooks (Pro tier)

Push delivery for alerts and market gaps. HMAC-SHA256 signed payloads.

**GET /api/b2b/webhooks**
List webhook endpoints.
```
Auth: X-API-Key
Response: { success, data: [{ id, url, events, isActive, description, failureCount, lastSuccessAt, createdAt }] }
```

**POST /api/b2b/webhooks**
Create webhook endpoint.
```
Auth: X-API-Key + write permission
Body: { url: "https://your-server.com/webhooks", events: ["alert.injury", "alert.arbitrage"], description?: "..." }
Response: { success, data: { id, url, secret, events, isActive, createdAt } }
```
The `secret` is returned once on creation. Use it to verify HMAC-SHA256 signatures in the `X-Webhook-Signature` header.

**PUT /api/b2b/webhooks/:id**
Update webhook endpoint (URL, events, active status).
```
Auth: X-API-Key + write permission
Body: { url?, events?, isActive?, description? }
```

**DELETE /api/b2b/webhooks/:id**
Deactivate webhook endpoint (soft delete).
```
Auth: X-API-Key + write permission
```

**POST /api/b2b/webhooks/:id/test**
Send a test event to the webhook endpoint.
```
Auth: X-API-Key + write permission
Response: { success, data: { statusCode, responseMs } }
```

**GET /api/b2b/webhooks/:id/deliveries**
Delivery history for a webhook endpoint.
```
Auth: X-API-Key
Params: limit (max 100, default 50), offset
Response: { success, data: [{ id, event, status, statusCode, responseMs, attempts, createdAt, deliveredAt }] }
```

**Webhook Event Types:**
```
alert.injury          — Player injury detected
alert.arbitrage       — Cross-venue arbitrage detected
alert.crowding        — Crowding spike/rotation
alert.political       — Political change detected
alert.finance         — Finance change detected
alert.rumor           — Rumor classified
gap.detected          — New high-scoring market gap found
```

**Webhook Payload Shape:**
```json
{
  "id": "delivery-uuid",
  "event": "alert.injury",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "headline": "LeBron James — OUT (knee)",
    "entity": { "slug": "lebron-james", "displayName": "LeBron James" },
    "alertType": "injury",
    "markets": [{ "venue": "polymarket", "marketId": "...", "question": "...", "price": 0.45 }]
  }
}
```

**Retry Policy:** Exponential backoff — 1m, 5m, 15m, 1h, 6h. Auto-disabled after 50 consecutive failures. Delivery timeout: 10 seconds.

**Signature Verification:**
```
signature = HMAC-SHA256(secret, JSON.stringify(payload))
// Compare with X-Webhook-Signature header
```

---

## Billing & Subscription

**GET /api/billing/status**
Current subscription status and monetization flag. Works for both authenticated and unauthenticated users.
```
Response: { success, data: { monetizationEnabled, tier, subscriptionStatus, stripeConfigured } }
```

**POST /api/billing/checkout**
Create Stripe Checkout session. Requires auth. Returns 400 when monetization is disabled.
```
Body: { tier: "developer" | "pro" }
Response: { success, data: { url } }  // Redirect user to this URL
```

**POST /api/billing/portal**
Create Stripe Customer Portal session for managing subscription.
```
Response: { success, data: { url } }
```

**POST /api/billing/webhook**
Stripe webhook endpoint (raw body, signature verification). Not for external use.

### Subscription Tiers

| | Free | Developer ($49/mo) | Pro ($199/mo) | Enterprise (custom) |
|---|---|---|---|---|
| Rate limit | 30 req/min | 300 req/min | 1,000 req/min | Unlimited |
| Public endpoints | Yes | Yes | Yes | Yes |
| B2B endpoints | — | Yes | Yes | Yes |
| Webhooks | — | — | Yes (10 endpoints) | Unlimited |
| Market Gap Analysis | — | — | Yes | Yes |

Note: When `monetizationEnabled` is false (beta mode), all features are available to authenticated users regardless of tier.

---

### Developer

**GET /api/developer/info**
API metadata and documentation links.
```
Response: { success, api: { version, baseUrl, documentation }, authentication, rateLimits, permissions, sdks }
```

**GET /api/developer/endpoints**
Machine-readable list of all public endpoints.
```
Response: { success, endpoints: { markets: [...], entities: [...], graph: [...], taxonomy: [...], b2b: [...] } }
```

**POST /api/developer/keys** — Create API key (requires auth)
**GET /api/developer/keys** — List API keys (requires auth)
**DELETE /api/developer/keys/:keyId** — Revoke API key
**GET /api/developer/keys/:keyId/stats** — API key usage stats

### News

**GET /api/news** — Get news feed
**GET /api/news/by-asset/:symbol** — News for specific asset
**GET /api/news/trending** — Trending news

---

## Common AI Workflows

### 1. Get full context for an entity before reasoning about market impact

```
GET /api/entities/patrick-mahomes/full
→ Returns entity with attributes (injury_status, position), relationships (plays_for Chiefs, competes_in NFL), affected markets (Super Bowl odds, MVP odds, game lines), and recent news (24h count + items with sentiment).
```

### 2. Find arbitrage opportunities

```
GET /api/graph/mispricings?minSpread=0.03&actionableOnly=true&limit=20
→ Returns markets listed on both Polymarket and Kalshi where prices diverge. Each result includes both venue prices, the spread, and whether it's actionable.
```

### 3. Trace second-order effects from an event

```
Step 1: GET /api/entities/patrick-mahomes → check injury_status attribute
Step 2: GET /api/graph/entity/{id}/neighborhood?depth=2&includeMarkets=true
→ Traverses: Mahomes → Chiefs → NFL → Super Bowl markets, AFC Championship markets, MVP markets
→ All connected markets that could be affected by this entity's attribute change
```

### 4. Monitor entity changes over time

```
GET /api/graph/entity/{id}/events?limit=20
→ Returns timestamped events: attribute changes, news, market moves
GET /api/graph/entity/{id}/fact/injury_status/history
→ Returns version history: Active → Questionable → Out, each with timestamp and source
```

### 5. Build market context for a prediction

```
GET /api/graph/outcome/{id}/context?window=48
→ Returns all entities connected to this market outcome, recent events affecting it, and cross-venue price data
GET /api/graph/outcome/{id}/prices
→ Returns prices across Polymarket, Kalshi for the same outcome
```

### 6. Understand alert context and trade on it

```
GET /api/alerts/{id}
→ Returns: headline, whyThisFired (human-readable reasons), entity context (humanStats), related markets with current prices, price at time of alert vs current price
→ The relatedMarkets array gives you exactly which markets to consider trading
```

### 7. B2B: Get trading suggestions from recent signals

```
GET /api/b2b/suggestions?category=sports&hours=6&limit=20
→ Returns recent alerts packaged as trading opportunities with linked markets, signal strength, and engagement metrics
GET /api/b2b/suggestions/trending
→ Top suggestions ranked by signal strength from the last 6 hours
```

### 8. B2B: Find market listing opportunities

```
GET /api/b2b/gaps?category=politics&limit=20
→ Returns entities with high signal activity but low market coverage — opportunities to list new markets
→ Each result includes gap score, recent signals, and suggested market categories
```

### 9. B2B: Person intelligence for research

```
GET /api/b2b/people?category=politics&subcategory=us-government&q=senator
→ Browse politicians with market counts and alert activity
GET /api/b2b/people/donald-trump
→ Full profile with relationships, recent alerts, and all affected markets across venues
```

### 10. Cross-venue price monitoring

```
GET /api/markets/cross-venue?limit=50
→ Returns matched market pairs across venues with spread data
GET /api/graph/mispricings/stats
→ Aggregate statistics on current mispricing landscape
```

---

## Key Design Principles

1. **Entity-centric**: Markets are connected TO entities, not the other way around. Start with entities, traverse to markets.
2. **Provenance-tracked**: Every attribute has a source, timestamp, and confidence. Fact history preserves the full audit trail.
3. **Cross-venue**: The same underlying event may have markets on Polymarket, Kalshi, and (for perps) Hyperliquid. The system matches and compares them.
4. **Graph-native**: Relationships enable second-order reasoning. Player injury → team impact → league outcomes → market prices.
5. **Real-time signals**: Alerts fire on entity attribute changes (injuries, weather, crowding, arbitrage, political changes) with pre-computed market impact.
6. **Global coverage**: 17,000+ entities across 104 countries, 7 categories, and all major prediction market venues.

---

## Authentication

Most read endpoints work without authentication at 30 req/min. For higher limits:

```
curl -H "X-API-Key: mt_live_your_key_here" \
  https://api.marketmotion.xyz/api/entities/donald-trump
```

Rate limit headers on every response:
- `X-RateLimit-Limit`: Your limit
- `X-RateLimit-Remaining`: Requests remaining
- `X-RateLimit-Reset`: Unix timestamp when limit resets

## Error Handling

```json
{ "success": false, "error": "Error message" }
```

HTTP codes: 200 (success), 400 (bad params), 401 (auth required), 403 (insufficient tier), 404 (not found), 429 (rate limited), 500 (server error)

---

## Links

- Entity Explorer: https://motiontrade.xyz/entities
- Developer Portal: https://motiontrade.xyz/developer
- Platform (B2B): https://motiontrade.xyz/platform
- Pricing: https://motiontrade.xyz/pricing
- Alerts Dashboard: https://motiontrade.xyz/alerts
- Full Documentation: https://motiontrade.mintlify.app/api/introduction