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

# B2B API

> B2B API endpoints for market suggestions, people, gaps, and webhooks

<Note>
  All B2B endpoints require an API key via the `X-API-Key` header. Some endpoints require Pro tier access.
</Note>

## Suggestions

<ParamField path="GET" method="/api/b2b/suggestions">
  Get market suggestions based on entity signals and attribute changes.
</ParamField>

### Query Parameters

<ParamField query="category" type="string">
  Filter by category
</ParamField>

<ParamField query="limit" type="number">
  Maximum results
</ParamField>

<ParamField query="offset" type="number">
  Pagination offset
</ParamField>

<ParamField query="hours" type="number">
  Lookback window in hours
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "suggestions": [
    {
      "id": "suggestion-uuid",
      "entity": {
        "slug": "patrick-mahomes",
        "displayName": "Patrick Mahomes"
      },
      "signal": "injury_status changed to questionable",
      "market": {
        "title": "Chiefs to win Super Bowl",
        "venue": "polymarket",
        "price": 0.35
      },
      "confidence": 0.85,
      "createdAt": "2025-01-28T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 50,
    "limit": 20,
    "offset": 0
  }
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "X-API-Key: your_api_key" \
    "https://api.marketmotion.xyz/api/b2b/suggestions?category=sports&limit=10"
  ```
</CodeGroup>

***

## Trending Suggestions

<ParamField path="GET" method="/api/b2b/suggestions/trending">
  Get currently trending market suggestions.
</ParamField>

### Query Parameters

<ParamField query="limit" type="number">
  Maximum results
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "suggestions": [...]
}
```

***

## List People

<ParamField path="GET" method="/api/b2b/people">
  Get people entities with market exposure and alert activity.
</ParamField>

### Query Parameters

<ParamField query="q" type="string">
  Search by name
</ParamField>

<ParamField query="category" type="string">
  Filter by category
</ParamField>

<ParamField query="subcategory" type="string">
  Filter by subcategory
</ParamField>

<ParamField query="limit" type="number">
  Maximum results
</ParamField>

<ParamField query="offset" type="number">
  Pagination offset
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "people": [
    {
      "slug": "patrick-mahomes",
      "displayName": "Patrick Mahomes",
      "entityType": "person",
      "category": "sports",
      "marketCount": 12,
      "alertCount7d": 3
    }
  ],
  "pagination": {
    "total": 500,
    "limit": 20,
    "offset": 0
  }
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "X-API-Key: your_api_key" \
    "https://api.marketmotion.xyz/api/b2b/people?category=sports&subcategory=nfl&limit=20"
  ```
</CodeGroup>

***

## Get Person

<ParamField path="GET" method="/api/b2b/people/:slug">
  Get detailed person information with attributes, relationships, markets, and recent alerts.
</ParamField>

### Path Parameters

<ParamField path="slug" type="string" required>
  Person slug
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "person": {
    "slug": "patrick-mahomes",
    "displayName": "Patrick Mahomes",
    "attributes": [
      { "key": "injury_status", "value": "questionable", "source": "ESPN" }
    ],
    "relationships": [...],
    "markets": [...],
    "recentAlerts": [...]
  }
}
```

***

## Person Markets

<ParamField path="GET" method="/api/b2b/people/:slug/markets">
  Get markets for a person with cross-venue spread data.
</ParamField>

### Path Parameters

<ParamField path="slug" type="string" required>
  Person slug
</ParamField>

### Query Parameters

<ParamField query="venue" type="string">
  Filter by venue
</ParamField>

<ParamField query="limit" type="number">
  Maximum results
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "markets": [
    {
      "title": "Chiefs to win Super Bowl",
      "venue": "polymarket",
      "price": 0.35
    }
  ],
  "crossVenue": [
    {
      "outcomeLabel": "Chiefs to win",
      "spread": 0.03,
      "signalType": "mispricing"
    }
  ]
}
```

***

## Market Gaps

<ParamField path="GET" method="/api/b2b/gaps">
  Get detected market gaps — entities with strong signals but no corresponding market.
</ParamField>

<Warning>
  Requires Pro tier API key.
</Warning>

### Query Parameters

<ParamField query="category" type="string">
  Filter by category
</ParamField>

<ParamField query="limit" type="number">
  Maximum results
</ParamField>

<ParamField query="minSignals" type="number">
  Minimum signal count threshold
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "gaps": [
    {
      "entity": {
        "slug": "some-entity",
        "displayName": "Entity Name"
      },
      "signalCount": 15,
      "category": "sports",
      "reason": "High activity with no prediction market coverage"
    }
  ],
  "total": 25
}
```

***

## Get Gap

<ParamField path="GET" method="/api/b2b/gaps/:slug">
  Get detailed gap information for a specific entity.
</ParamField>

<Warning>
  Requires Pro tier API key.
</Warning>

### Path Parameters

<ParamField path="slug" type="string" required>
  Entity slug
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "gap": {
    "entity": { ... },
    "signals": [...],
    "markets": [...]
  }
}
```

***

## Webhooks

Webhook endpoints allow you to receive real-time notifications when events occur.

<Warning>
  Requires Pro tier API key.
</Warning>

### List Webhooks

<ParamField path="GET" method="/api/b2b/webhooks">
  List your configured webhook endpoints.
</ParamField>

```json theme={null}
{
  "success": true,
  "endpoints": [
    {
      "id": "webhook-uuid",
      "url": "https://your-server.com/webhook",
      "events": ["alert.injury", "alert.arbitrage"],
      "isActive": true,
      "description": "Production webhook"
    }
  ]
}
```

### Create Webhook

<ParamField path="POST" method="/api/b2b/webhooks">
  Register a new webhook endpoint.
</ParamField>

**Body:**

```json theme={null}
{
  "url": "https://your-server.com/webhook",
  "events": ["alert.injury", "alert.arbitrage", "gap.detected"],
  "description": "My webhook"
}
```

**Response:**

```json theme={null}
{
  "success": true,
  "id": "webhook-uuid",
  "secret": "whsec_..."
}
```

### Update Webhook

<ParamField path="PUT" method="/api/b2b/webhooks/:id">
  Update a webhook endpoint.
</ParamField>

**Body:**

```json theme={null}
{
  "url": "https://your-server.com/webhook-v2",
  "events": ["alert.injury"],
  "isActive": true,
  "description": "Updated webhook"
}
```

### Delete Webhook

<ParamField path="DELETE" method="/api/b2b/webhooks/:id">
  Delete a webhook endpoint.
</ParamField>

### Test Webhook

<ParamField path="POST" method="/api/b2b/webhooks/:id/test">
  Send a test payload to your webhook endpoint.
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "statusCode": 200
}
```

### Webhook Deliveries

<ParamField path="GET" method="/api/b2b/webhooks/:id/deliveries">
  Get delivery history for a webhook endpoint.
</ParamField>

**Query Parameters:**

<ParamField query="limit" type="number">
  Maximum results
</ParamField>

<ParamField query="offset" type="number">
  Pagination offset
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "deliveries": [
    {
      "id": "delivery-uuid",
      "event": "alert.injury",
      "statusCode": 200,
      "deliveredAt": "2025-01-28T10:00:00Z",
      "payload": { ... }
    }
  ],
  "pagination": {
    "total": 100,
    "limit": 20,
    "offset": 0
  }
}
```

### Webhook Events

| Event             | Description                     |
| ----------------- | ------------------------------- |
| `alert.injury`    | Injury status change detected   |
| `alert.arbitrage` | Cross-venue mispricing detected |
| `alert.crowding`  | Position crowding detected      |
| `alert.political` | Political change detected       |
| `alert.finance`   | Financial indicator change      |
| `alert.rumor`     | Unconfirmed rumor detected      |
| `gap.detected`    | Market gap identified           |