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

# Markets

> Market API endpoints

## List Prediction Markets

<ParamField path="GET" method="/api/markets/predictions">
  List prediction markets with optional filtering.
</ParamField>

### Query Parameters

<ParamField query="venue" type="string">
  Filter by venue: `polymarket`, `kalshi`
</ParamField>

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

<ParamField query="sort" type="string">
  Sort order: `volume`, `liquidity`, `ending_soon`, `new`, `activity`, `trending`
</ParamField>

<ParamField query="volumeMin" type="number">
  Minimum volume threshold
</ParamField>

<ParamField query="endingWithin" type="string">
  Filter markets ending within a time window (e.g., `24h`, `7d`)
</ParamField>

<ParamField query="search" type="string">
  Filter by title text
</ParamField>

<ParamField query="limit" type="number" default="50">
  Results per page (max: 100)
</ParamField>

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

### Response

```json theme={null}
{
  "success": true,
  "markets": [
    {
      "id": "market-uuid",
      "externalId": "polymarket-condition-id",
      "title": "Will the Chiefs win Super Bowl LIX?",
      "venue": "polymarket",
      "category": "sports",
      "subcategory": "nfl",
      "active": true,
      "outcomes": [
        { "label": "Yes", "price": 0.35 },
        { "label": "No", "price": 0.65 }
      ],
      "volume": 1500000,
      "endDate": "2025-02-09T23:59:59Z"
    }
  ],
  "total": 500
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/markets/predictions?venue=polymarket&category=sports&sort=volume&limit=20"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.marketmotion.xyz/api/markets/predictions?venue=polymarket&category=sports&limit=20'
  );
  const { markets, total } = await response.json();
  ```

  ```python Python theme={null}
  response = requests.get(
      'https://api.marketmotion.xyz/api/markets/predictions',
      params={'venue': 'polymarket', 'category': 'sports', 'limit': 20}
  )
  data = response.json()
  ```
</CodeGroup>

***

## Search Markets

<ParamField path="GET" method="/api/markets/search">
  Search markets by title.
</ParamField>

### Query Parameters

<ParamField query="q" type="string" required>
  Search query
</ParamField>

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

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

### Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "market-uuid",
      "title": "Chiefs to win Super Bowl LIX",
      "venue": "polymarket",
      "price": 0.35,
      "volume": 1500000
    }
  ]
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/markets/search?q=super%20bowl&venue=polymarket"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.marketmotion.xyz/api/markets/search?q=super%20bowl&venue=polymarket'
  );
  const { data } = await response.json();
  ```

  ```python Python theme={null}
  response = requests.get(
      'https://api.marketmotion.xyz/api/markets/search',
      params={'q': 'super bowl', 'venue': 'polymarket'}
  )
  markets = response.json()['data']
  ```
</CodeGroup>

***

## Get Market Detail

<ParamField path="GET" method="/api/markets/detail/:symbol">
  Get detailed market data for a specific symbol.
</ParamField>

### Path Parameters

<ParamField path="symbol" type="string" required>
  Market symbol (e.g., `BTC`, `ETH`)
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "market": {
    "id": "market-uuid",
    "symbol": "BTC",
    "price": 65000,
    "volume24h": 1200000000,
    "fundingRate": 0.0001,
    "productType": "perp"
  }
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/markets/detail/BTC"
  ```
</CodeGroup>

***

## Get Candles

<ParamField path="GET" method="/api/markets/candles/:symbol">
  Get OHLCV candle data for a symbol.
</ParamField>

### Path Parameters

<ParamField path="symbol" type="string" required>
  Market symbol
</ParamField>

### Query Parameters

<ParamField query="interval" type="string">
  Candle interval (e.g., `1m`, `5m`, `1h`, `1d`)
</ParamField>

<ParamField query="period" type="string">
  Time period to fetch (e.g., `24h`, `7d`, `30d`)
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "symbol": "BTC",
  "candles": [
    {
      "timestamp": "2025-01-28T10:00:00Z",
      "open": 64500,
      "high": 65200,
      "low": 64100,
      "close": 65000,
      "volume": 50000000
    }
  ]
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/markets/candles/BTC?interval=1h&period=24h"
  ```
</CodeGroup>

***

## Get Categories

<ParamField path="GET" method="/api/markets/categories">
  Get market categories and product types.
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "productTypes": {
    "all": 1200,
    "perps": 500,
    "spot": 400,
    "stocks": 300
  },
  "categories": [
    { "category": "politics", "count": 500 },
    { "category": "sports", "count": 300 },
    { "category": "crypto", "count": 150 }
  ]
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/markets/categories"
  ```
</CodeGroup>

***

## Prediction Categories

<ParamField path="GET" method="/api/markets/predictions/categories">
  Get prediction market categories with counts.
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "categories": [
    { "name": "politics", "count": 500, "slug": "politics" },
    { "name": "sports", "count": 300, "slug": "sports" }
  ]
}
```

***

## Cross-Venue Markets

<ParamField path="GET" method="/api/markets/cross-venue">
  Get markets matched across multiple venues with spread data. Includes bid/ask pricing.
</ParamField>

### Query Parameters

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

### Response

```json theme={null}
{
  "success": true,
  "markets": [
    {
      "outcomeId": "outcome-uuid",
      "label": "Chiefs to win Super Bowl",
      "venues": [
        {
          "venue": "polymarket",
          "price": 0.35,
          "bestBid": 0.34,
          "bestAsk": 0.36,
          "volume": 1500000,
          "liquidity": 250000,
          "url": "https://polymarket.com/event/..."
        },
        {
          "venue": "kalshi",
          "price": 0.38,
          "yesBid": 0.37,
          "yesAsk": 0.39,
          "noBid": 0.61,
          "noAsk": 0.63,
          "volume": 500000,
          "url": "https://kalshi.com/markets/..."
        }
      ],
      "spread": 0.03
    }
  ]
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/markets/cross-venue?limit=20"
  ```
</CodeGroup>

***

## Orderbook (Hyperliquid)

<ParamField path="GET" method="/api/markets/:symbol/orderbook">
  Get L2 orderbook for a Hyperliquid perpetual.
</ParamField>

### Path Parameters

<ParamField path="symbol" type="string" required>
  Market symbol (e.g., `BTC`, `ETH`)
</ParamField>

### Query Parameters

<ParamField query="depth" type="number" default="20">
  Number of price levels per side (max: 100)
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "symbol": "BTC",
  "bids": [
    { "price": 64990, "size": 1.5 },
    { "price": 64985, "size": 3.2 }
  ],
  "asks": [
    { "price": 65010, "size": 0.8 },
    { "price": 65015, "size": 2.1 }
  ],
  "spread": 20,
  "midPrice": 65000,
  "depth": 20
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/markets/BTC/orderbook?depth=10"
  ```
</CodeGroup>

***

## Orderbook (Polymarket)

<ParamField path="GET" method="/api/markets/polymarket/:tokenId/orderbook">
  Get orderbook for a Polymarket outcome token.
</ParamField>

### Path Parameters

<ParamField path="tokenId" type="string" required>
  Polymarket outcome token ID
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "tokenId": "12345...",
  "bids": [
    { "price": 0.54, "size": 500 },
    { "price": 0.53, "size": 1200 }
  ],
  "asks": [
    { "price": 0.56, "size": 300 },
    { "price": 0.57, "size": 800 }
  ],
  "spread": 0.02,
  "midPrice": 0.55
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/markets/polymarket/12345.../orderbook"
  ```
</CodeGroup>

***

## Entity-Connected Markets

<ParamField path="GET" method="/api/markets/entity-connected">
  Get cross-venue markets discovered through entity connections.
</ParamField>

### Query Parameters

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

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

<ParamField query="minSpread" type="number">
  Minimum spread threshold
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "crossVenueMarkets": [...],
  "stats": {
    "totalMatches": 150,
    "averageSpread": 0.025
  }
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/markets/entity-connected?minSpread=0.03&limit=10"
  ```
</CodeGroup>