API Overview

Market Motion API reference

Base URL

All API requests should be made to:

https://api.marketmotion.xyz/api

Authentication

Include your API key in the X-API-Key header:

curl -H "X-API-Key: your_api_key" https://api.marketmotion.xyz/api/entities

Most endpoints work without authentication at reduced rate limits.

Rate Limits

Tier	Limit	Authentication
Anonymous	30 req/min	None
Test Key	100 req/min	X-API-Key header
Live Key	300 req/min	X-API-Key header

Response Format

All responses follow this structure:

Success (list)

{
  "success": true,
  "items": [...],
  "nextCursor": "cursor-string-or-null"
}

Success (single item)

{
  "success": true,
  "entity": { ... }
}

Error

{
  "success": false,
  "error": "Error message describing what went wrong"
}

HTTP Status Codes

Code	Description
200	Success
400	Bad request — invalid parameters
401	Unauthorized — invalid API key
404	Not found — entity or market doesn’t exist
429	Rate limit exceeded
500	Internal server error

Pagination

Entities — cursor-based

Entity list endpoints use cursor-based pagination:

Parameter	Type	Default	Description
limit	number	50	Results per page
cursor	string	—	Cursor from previous response’s nextCursor

{
  "success": true,
  "items": [...],
  "nextCursor": "eyJpZCI6Imxhc3QtaWQifQ"
}

Pass nextCursor as the cursor query parameter to fetch the next page. When nextCursor is null, there are no more results.

Markets — offset-based

Market prediction endpoints use offset-based pagination:

Parameter	Type	Default	Description
limit	number	50	Results per page (max: 100)
offset	number	0	Number of results to skip

Endpoints

Entities

Method	Endpoint	Description
GET	/entities	List and search entities (use ?q= for search)
GET	/entities/:slug	Get entity details
GET	/entities/:slug/full	Get entity with all related data
GET	/entities/:slug/markets	Get markets for an entity
GET	/entities/:slug/news	Get news for an entity
GET	/entities/:slug/relationships	Get entity relationships
GET	/entities/:slug/related	Get related entities by graph traversal
GET	/entities/subcategories	Get subcategories for a category
GET	/entities/by-market/:marketId	Get entities linked to a market

Taxonomy

Method	Endpoint	Description
GET	/taxonomy/stats	Category and subcategory counts
GET	/taxonomy/:category/:subcategory/entities	Entities in a subcategory
GET	/taxonomy/:category/:subcategory/groups	Groups within a subcategory
GET	/taxonomy/:category/:subcategory/:group/entities	Entities in a group
GET	/schemas	Snapshot and attribute schemas

Markets

Method	Endpoint	Description
GET	/markets/predictions	List prediction markets (includes bid/ask)
GET	/markets/search	Search markets by title
GET	/markets/categories	Market categories and product types
GET	/markets/detail/:symbol	Market detail by symbol
GET	/markets/candles/:symbol	OHLCV candle data
GET	/markets/cross-venue	Cross-venue matched markets (includes bid/ask)
GET	/markets/entity-connected	Cross-venue markets via entity links
GET	/markets/predictions/categories	Prediction market categories
GET	/markets/:symbol/orderbook	Hyperliquid L2 orderbook
GET	/markets/polymarket/:tokenId/orderbook	Polymarket orderbook

Graph Intelligence

Method	Endpoint	Description
GET	/entities/:slug/graph	Entity relationship graph
GET	/graph/view	Configurable graph view builder
GET	/graph/entity/:id/neighborhood	Entity neighborhood subgraph
GET	/graph/entity/:id/markets	Entity market exposures with drivers
GET	/graph/entity/:id/timeline	Entity event timeline
GET	/graph/entity/:id/events	Entity events with impact scores
GET	/graph/entity/:id/fact/:key/history	Fact version history
GET	/graph/outcome/:id/context	Market outcome context graph
GET	/graph/outcome/:id/prices	Cross-venue prices for an outcome
GET	/graph/outcome/:id/history	Outcome price history
GET	/graph/topic/:topic	Discover entities/markets by topic
GET	/graph/event/:id/impact	Event impact chain
GET	/graph/movers	Top entity movers
GET	/graph/mispricings	Cross-venue mispricings
GET	/graph/mispricings/top	Top mispricing opportunities
GET	/graph/mispricings/check/:outcomeId	Check if outcome is mispriced
GET	/graph/mispricings/stats	Mispricing aggregate stats
GET	/graph/cross-venue/:outcomeId	Cross-venue data for outcome
GET	/graph/kalshi/overlapping	Kalshi/Polymarket overlapping markets
GET	/graph/stats	Graph database stats

Intelligence Signals

Method	Endpoint	Description
GET	/intelligence/entity/:slug/impact	Entity impact coefficients across markets
GET	/intelligence/entity/:slug/sentiment	Multi-window entity sentiment scores
GET	/intelligence/market/:id/signals	ISQ-scored signals for a market

Attribution

Method	Endpoint	Description
GET	/attribution/entity/:slug	Entity impact coefficients
GET	/attribution/market/:venue/:marketId	Market entity attributions
GET	/attribution/top-movers	Top-moving entities
GET	/attribution/predict	Predict market impact of attribute change
GET	/attribution/causality/:slug	Entity causal relationships
GET	/attribution/top-causal	Top causal entities

Alerts

Method	Endpoint	Description
GET	/alerts/inbox	Alert inbox with filtering
GET	/alerts/:id	Alert detail with entity and market context
GET	/alerts/:id/outcome	Alert outcome tracking
GET	/alerts/outcomes/stats	Alert performance statistics
GET	/alerts/outcomes/top	Top-performing alerts

Conflicts

Method	Endpoint	Description
GET	/conflicts	Active geopolitical conflicts
GET	/conflicts/:slug	Conflict detail with threat level
GET	/conflicts/:slug/signals	Intelligence signals for a conflict
GET	/conflicts/:slug/markets	Markets affected by a conflict

Source Analytics

Method	Endpoint	Description
GET	/analytics/source-scores	Source signal quality scores
GET	/analytics/source-scores/:author	Detailed source analytics
GET	/analytics/source-scores/:author/predict	Predict source reliability

B2B API

Method	Endpoint	Description
GET	/b2b/suggestions	Market suggestions
GET	/b2b/suggestions/trending	Trending suggestions
GET	/b2b/people	People with market exposure
GET	/b2b/people/:slug	Person detail with markets and alerts
GET	/b2b/people/:slug/markets	Person’s markets with cross-venue data
GET	/b2b/gaps	Detected market gaps (Pro)
GET	/b2b/gaps/:slug	Gap detail (Pro)
CRUD	/b2b/webhooks	Webhook management (Pro)

Portfolio

Method	Endpoint	Description
GET	/portfolio/pnl-history	PnL chart data (1h, 24h, 7d, 30d, all)
GET	/portfolio/positions	Current positions from snapshots
GET	/portfolio/summary	Account value, margin, daily PnL
GET	/portfolio/orders	Open Hyperliquid orders
GET	/portfolio/fills	Hyperliquid trade fill history
POST	/portfolio/refresh	Trigger manual position snapshot

LLM Context

For AI systems, we provide a machine-readable documentation file:

https://marketmotion.xyz/llms.txt

This contains all endpoints, schemas, and examples optimized for LLM consumption.

SDKs

• CLI: npm install -g @marketmotion/cli (v0.4.0)
• TypeScript SDK — coming soon
• Python SDK — coming soon

Support

• Entity Explorer — Browse entities visually