> ## Documentation Index
> Fetch the complete documentation index at: https://motiontrade.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={null}
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)

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

### Success (single item)

```json theme={null}
{
  "success": true,
  "entity": { ... }
}
```

### Error

```json theme={null}
{
  "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` |

```json theme={null}
{
  "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](https://marketmotion.xyz/entities) — Browse entities visually