# Market Motion API > Structured entity intelligence for prediction markets. 17,000+ typed entities, 18,400+ relationships, cross-venue arbitrage, real-time alerts. ## Quick Start - Base URL: `https://api.marketmotion.xyz/api` - Auth: Optional `X-API-Key` header. Most endpoints work at 30 req/min without a key. - Response: `{ "success": true, "data": { ... } }` or `{ "success": false, "error": "..." }` - Venues: Polymarket, Kalshi, Hyperliquid - Full llms.txt: https://motiontrade.xyz/llms.txt ## Core Concepts **Entities** are canonical representations (person, team, org, place, league, asset) with typed attributes, explicit relationships, and links to prediction markets. When entity attributes change (injury, polling data, weather), connected markets are affected. **Graph** enables second-order reasoning: Player injury → team impact → league outcomes → market price movements. Traverse with depth parameter (1-3). **Cross-venue arbitrage**: Same markets on Polymarket and Kalshi may have different prices. The `/graph/mispricings` endpoint detects and scores these automatically. **Alerts** fire on market-moving events: injury status changes, crowding spikes, arbitrage, political changes, finance shifts, rumors. Each alert includes whyThisFired reasons, entity context, and related markets. ## Entity Types person, team, org, place, league, asset ## Categories politics (us-government, us-elections, governors, + 104 international), sports (nfl, nba, mlb, nhl, ncaa, soccer), finance (fed, macro, equities, earnings, central-banks), crypto (layer-1, defi, memecoins), culture (entertainment, awards, media), science (space, climate, health), technology (ai, software, hardware, semiconductors) ## Relationship Types plays_for, member_of, leads, colleague_of, plays_at, located_in, competes_in, governs, affiliated_with, parent_of ## Endpoints ### Entities ``` GET /api/entities Search: ?q=&category=&type=&limit=&cursor= GET /api/entities/:slug Entity + markets + news GET /api/entities/:slug/full Entity + all relationships expanded GET /api/entities/:slug/markets Linked prediction markets GET /api/entities/:slug/news Related news items GET /api/entities/:slug/relationships Entity relationships GET /api/entities/:slug/related Related entities via graph GET /api/entities/:slug/completeness Data completeness score GET /api/entities/by-market/:marketId Entities linked to a market GET /api/entities/subcategories ?category= → subcategory list ``` ### Taxonomy ``` GET /api/taxonomy/stats Category counts, totals GET /api/taxonomy/:cat/:sub/groups Groups in subcategory GET /api/taxonomy/:cat/:sub/:group/entities Entities in group ``` ### Markets ``` GET /api/markets/search ?q=&venue=&limit= (cross-venue search) GET /api/markets/predictions ?venue=&category=&sort=&limit=&offset= (Polymarket + Kalshi) GET /api/markets/predictions/categories Category list with counts GET /api/markets/curated Hyperliquid trending/top/new/featured GET /api/markets/filter ?type=&category=&sort=&search=&limit= GET /api/markets/detail/:symbol Full market data GET /api/markets/candles/:symbol ?interval=&period= (OHLCV) GET /api/markets/:venue/:marketId Market by venue + ID GET /api/markets/cross-venue Matched markets across venues with spread GET /api/markets/entity-connected Entity-linked markets with arb signals POST /api/markets/cross-venue/match Trigger cross-venue matching ``` ### Graph & Arbitrage ``` GET /api/graph/mispricings ?minSpread=&actionableOnly=&category=&limit= (PRIMARY ARB ENDPOINT) GET /api/graph/mispricings/top Top opportunities by spread GET /api/graph/mispricings/check/:id Check if outcome is mispriced GET /api/graph/mispricings/stats Aggregate mispricing stats GET /api/graph/cross-venue/:outcomeId Cross-venue prices for outcome GET /api/graph/movers ?window=&limit= (top price movers) GET /api/graph/entity/:id/neighborhood ?depth=&includeMarkets= (relationship graph) GET /api/graph/entity/:id/markets Market exposure with drivers + spread GET /api/graph/entity/:id/events Timestamped events (changes, news, moves) GET /api/graph/entity/:id/fact/:key/history Attribute version history with provenance GET /api/graph/entity/:id/timeline Event timeline GET /api/graph/outcome/:id/context Entities + events affecting an outcome GET /api/graph/outcome/:id/prices Cross-venue prices GET /api/graph/outcome/:id/history Price history GET /api/graph/topic/:topic Topic exploration GET /api/graph/event/:id/impact Event impact analysis GET /api/graph/view ?type= (generic graph builder) GET /api/graph/stats System-wide graph statistics ``` ### Alerts ``` GET /api/alerts/inbox ?type=&limit=&offset= (auth required) GET /api/alerts/:id Full alert + entity + related markets GET /api/alerts/recent Recent alpha alerts (public) GET /api/alerts/stream SSE real-time stream GET /api/alerts/outcomes/stats ?days=&type= (effectiveness analytics) GET /api/alerts/outcomes/top Top performing alerts GET /api/alerts/:id/outcome Outcome tracking for specific alert POST /api/alerts/:id/read Mark read POST /api/alerts/:id/dismiss Dismiss POST /api/alerts/:id/acted Mark traded ``` Alert types: injury, crowding_spike, crowding_rotation, weather, copy_trade, arbitrage, rumor, political_change, finance_change ### B2B API (requires API key) ``` GET /api/b2b/suggestions Recent alerts as trading opportunities (?category=&limit=&hours=) GET /api/b2b/suggestions/trending Top-ranked suggestions (last 6h) GET /api/b2b/people Browse person entities (?q=&category=&subcategory=&limit=) GET /api/b2b/people/:slug Full person profile + relationships + markets GET /api/b2b/people/:slug/markets Person's markets with cross-venue prices GET /api/b2b/entities/:slug/market-map Categorized market map: exact/team/props/related + cross-venue flags GET /api/b2b/cross-venue-matches Normalized cross-venue pairs with compareFlag + spread GET /api/b2b/gaps Market gap analysis — entities with high signals, low coverage (Pro tier) GET /api/b2b/gaps/:slug Detailed gap analysis for one entity (Pro tier) ``` #### Entity Market Map (`/api/b2b/entities/:slug/market-map`) Returns all prediction markets linked to an entity, categorized by taxonomy: - `exact_entity`: Direct entity-market link (confidence >= 0.7) - `team_market`: Market found via plays_for/member_of/leads relationship - `player_prop`: Market containing prop/over/under patterns - `related_indirect`: Graph-expanded markets from related entities Each market includes: - Live prices from Polymarket and/or Kalshi - Cross-venue `compareFlag`: `exact_match` (safe to arb), `near_match` (similar but verify), `do_not_compare` - Confidence score and linked relationship path Query: `?includeRelated=true&limit=50` #### Cross-Venue Matches (`/api/b2b/cross-venue-matches`) Normalized pair objects for every Polymarket/Kalshi match with: - `compareFlag`: `exact_match` or `near_match` (only reviewed pairs returned) - Live prices from both venues + spread + spreadPct - `signalType`: `arbitrage` (>=10%), `mispricing` (>=5%), `aligned` (<5%) - Linked entities from the knowledge graph Query: `?category=&minSpread=0.05&limit=50` ### WebSocket (Socket.IO) ``` Connect: io('https://api.marketmotion.xyz', { transports: ['websocket'] }) Channels: subscribe:arb / unsubscribe:arb → arb:update (cross-venue spread changes) subscribe:portfolio / unsubscribe:portfolio → portfolio:update (live PnL + positions) subscribe:feed / unsubscribe:feed → feed:activity (trader actions) subscribe:leaderboard / unsubscribe:leaderboard → leaderboard:update (rankings) join:tournament / leave:tournament → tournament:update, tournament:liquidation arb:update payload: { outcomeId, outcomeSlug, outcomeLabel, category, venues: [{ venue, price, volume }], spread, spreadPct, maxVenue, minVenue, signalType, timestamp } signalType: arbitrage (>=10%), mispricing (>=5%), aligned (<5%) ``` ### Webhooks (Pro tier, requires API key) ``` GET /api/b2b/webhooks List webhook endpoints POST /api/b2b/webhooks Create endpoint (url, events[], description) PUT /api/b2b/webhooks/:id Update endpoint DELETE /api/b2b/webhooks/:id Deactivate endpoint POST /api/b2b/webhooks/:id/test Send test event GET /api/b2b/webhooks/:id/deliveries Delivery history ``` Webhook events: alert.injury, alert.arbitrage, alert.crowding, alert.political, alert.finance, alert.rumor, gap.detected Signature: HMAC-SHA256 in X-Webhook-Signature header. Retry: exponential backoff (1m→6h), auto-disable after 50 failures. ### Billing & Subscription ``` GET /api/billing/status Subscription status + monetizationEnabled flag POST /api/billing/checkout Create Stripe Checkout session ({ tier: "developer"|"pro" }) POST /api/billing/portal Stripe Customer Portal session POST /api/billing/webhook Stripe webhook (internal) ``` Tiers: Free (30 req/min, public only) | Developer $49/mo (300 req/min, + B2B) | Pro $199/mo (1,000 req/min, + webhooks + gaps) | Enterprise (custom) Note: When monetizationEnabled=false (beta), all features are free for authenticated users. ### Developer ``` GET /api/developer/info API metadata GET /api/developer/endpoints Machine-readable endpoint list POST /api/developer/keys Create API key (auth required) GET /api/developer/keys List keys (auth required) DELETE /api/developer/keys/:keyId Revoke key GET /api/developer/keys/:keyId/stats API key usage stats ``` ### News ``` GET /api/news News feed GET /api/news/by-asset/:symbol News for asset GET /api/news/trending Trending news ``` ## AI Workflows 1. **Entity context**: `GET /api/entities/:slug/full` → attributes + relationships + markets + news 2. **Arbitrage scan**: `GET /api/graph/mispricings?minSpread=0.03&actionableOnly=true` 3. **Second-order effects**: `GET /api/graph/entity/:id/neighborhood?depth=2&includeMarkets=true` 4. **Attribute tracking**: `GET /api/graph/entity/:id/fact/:key/history` → version history with provenance 5. **Market context**: `GET /api/graph/outcome/:id/context` → entities + events + cross-venue prices 6. **Alert trading**: `GET /api/alerts/:id` → whyThisFired + relatedMarkets + priceAtAlert 7. **B2B suggestions**: `GET /api/b2b/suggestions?category=sports&hours=6` → alerts as trading opportunities 8. **Market gaps**: `GET /api/b2b/gaps?category=politics` → entities with high signals, low market coverage 9. **Person intel**: `GET /api/b2b/people/donald-trump` → full profile + relationships + markets 10. **Cross-venue monitoring**: `GET /api/markets/cross-venue` → matched pairs with spread data 11. **Entity market map**: `GET /api/b2b/entities/lebron-james/market-map` → categorized markets (exact/team/props/related) with cross-venue flags 12. **Safe arbitrage pairs**: `GET /api/b2b/cross-venue-matches?minSpread=0.05` → reviewed pairs with compareFlag safety labels ## AI Agent Integration ### MCP Server (Claude, GPT, etc.) ```bash npx @market-motion/mcp # or configure in claude_desktop_config.json ``` 10 tools: research_entity, research_scenario, search_entities, get_entity_detail, get_isq_signals, get_sentiment, get_arbitrage, get_markets, get_entity_market_map, get_cross_venue_matches ### OpenAI Function Calling Download: `https://docs.marketmotion.xyz/api/openai-tools.json` Compatible with GPT-4, GPT-4o, and any OpenAI-compatible API. ### Compare Flags (for safe arbitrage) - `exact_match`: Verified identical markets across venues — safe to compare prices and trade - `near_match`: Similar but not identical — verify resolution criteria before trading - `do_not_compare`: Unreviewed or rejected — do not use for arbitrage ### Taxonomy Labels (for entity market maps) - `exact_entity`: Direct market link with high confidence - `team_market`: Market linked via team/org relationship (plays_for, member_of, leads) - `player_prop`: Player prop market (points, yards, assists, over/under) - `related_indirect`: Market from a related entity in the graph ## 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