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

# GET /api/v1/discover — Browse Prediction Markets

> List canonical questions with volume-weighted index prices, cross-platform divergence scores, and the cheapest buy price available across all integrated venues.

The discover endpoint is your primary entry point for browsing prediction markets on Predexy. It returns a paginated list of canonical questions — each one representing a single real-world question aggregated across all platforms that list it. Every item in the response includes a volume-weighted index price, a divergence category indicating how much platforms disagree, and the best buy price available right now.

## Endpoint

```
GET https://api.predexy.com/api/v1/discover
```

## Authentication

A session JWT is required. Pass it as a bearer token or let the browser send the `pdx_access` cookie automatically:

```
Authorization: Bearer <your_jwt>
```

## Query parameters

<ParamField query="category" type="string">
  Filter by market category. Common values: `crypto`, `politics`, `sports`, `science`, `entertainment`. Omit to return all categories.
</ParamField>

<ParamField query="limit" type="number" default="50">
  Maximum items to return. Range 1–200.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of items to skip. Use for pagination.
</ParamField>

## Example request

```bash cURL theme={null}
curl https://api.predexy.com/api/v1/discover \
  -H "Authorization: Bearer <your_jwt>" \
  -G \
  --data-urlencode "category=crypto" \
  --data-urlencode "limit=5"
```

## Response

The response wraps an array of `DiscoverItem` objects in `data` and includes pagination state in `meta`.

### DiscoverItem fields

<ResponseField name="id" type="string" required>
  Canonical question UUID. Use this to fetch full details from `GET /api/v1/questions/{id}`.
</ResponseField>

<ResponseField name="title" type="string" required>
  Human-readable canonical question text, e.g. `"Will BTC reach $100k by 2026?"`.
</ResponseField>

<ResponseField name="slug" type="string" required>
  URL-safe identifier for the question.
</ResponseField>

<ResponseField name="category" type="string" required>
  Market category label.
</ResponseField>

<ResponseField name="end_time" type="string">
  ISO 8601 timestamp when the market resolves. `null` for perpetual markets.
</ResponseField>

<ResponseField name="market_count" type="number" required>
  Number of platforms currently listing this question. A value of `3` means three separate platform markets are linked to this canonical question.
</ResponseField>

<ResponseField name="platform_slugs" type="string[]" required>
  Slugs of every platform listing this question, e.g. `["polymarket", "limitless", "predictfun"]`.
</ResponseField>

<ResponseField name="index_price" type="number">
  Volume-weighted consensus probability, expressed as a decimal from 0 to 1. `null` if no pricing data is available.
</ResponseField>

<ResponseField name="divergence" type="number">
  Weighted standard deviation of Yes prices across platforms. Higher values mean platforms disagree more. `null` if fewer than two platforms have pricing data.
</ResponseField>

<ResponseField name="divergence_category" type="string">
  Categorized divergence level: `low` (under 2%), `medium` (2–5%), or `high` (over 5%). `null` if divergence cannot be computed.
</ResponseField>

<ResponseField name="best_buy_price" type="number">
  The cheapest Yes price available across all linked platforms. `null` if no pricing data exists.
</ResponseField>

<ResponseField name="best_buy_platform" type="string">
  Slug of the platform offering the cheapest price, e.g. `"limitless"`. `null` if unavailable.
</ResponseField>

<ResponseField name="spread_bps" type="number">
  Spread between the cheapest and most expensive Yes price, expressed in basis points (1 bps = 0.01%). A value of `400` means a 4% spread. `null` if fewer than two prices are available.
</ResponseField>

### meta fields

<ResponseField name="meta.count" type="number">
  Items returned in this response.
</ResponseField>

<ResponseField name="meta.total" type="number">
  Total items matching the query.
</ResponseField>

<ResponseField name="meta.offset" type="number">
  Offset applied to this page.
</ResponseField>

<ResponseField name="meta.limit" type="number">
  Limit applied to this page.
</ResponseField>

## Sample response

```json theme={null}
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "title": "Will BTC reach $100k by 2026?",
      "slug": "will-btc-reach-100k-by-2026",
      "category": "crypto",
      "end_time": "2026-01-01T00:00:00Z",
      "market_count": 3,
      "platform_slugs": ["polymarket", "limitless", "predictfun"],
      "index_price": 0.62,
      "divergence": 0.034,
      "divergence_category": "medium",
      "best_buy_price": 0.58,
      "best_buy_platform": "limitless",
      "spread_bps": 400
    },
    {
      "id": "8e1e4c9d-1234-4abc-9abc-000000000001",
      "title": "Will the Fed cut rates in Q1 2026?",
      "slug": "fed-rate-cut-q1-2026",
      "category": "economics",
      "end_time": "2026-03-31T23:59:59Z",
      "market_count": 2,
      "platform_slugs": ["polymarket", "manifold"],
      "index_price": 0.41,
      "divergence": 0.015,
      "divergence_category": "low",
      "best_buy_price": 0.40,
      "best_buy_platform": "manifold",
      "spread_bps": 200
    }
  ],
  "meta": {
    "count": 2,
    "total": 847,
    "offset": 0,
    "limit": 5
  }
}
```

<Note>
  Use `market_count` to quickly identify questions listed on multiple platforms — these are the most likely candidates for arbitrage. Any question with `market_count >= 2` and `divergence_category` of `medium` or `high` is worth inspecting further with `GET /api/v1/questions/{id}`.
</Note>