# Market discovery

> Source: https://implyra.com/docs/market-discovery
> Implyra API docs · API reference · Market discovery

Query Polymarket markets with selected metrics, historical deltas, composable filters, and cursor pagination.

Transport: POST

## Request

`POST /markets/discover`

Send a JSON body. Select the metrics you intend to display, then add filters, deltas, and sorting as needed.

**Market discovery**

```sh
curl --fail-with-body \
  -X POST "$IMPLYRA_API_URL/markets/discover" \
  -H "Content-Type: application/json" \
  -d '{
  "metrics": [
    "volume",
    "liquidity",
    "price"
  ],
  "deltas": [
    {
      "metric": "price",
      "window": "24h",
      "compare": "delta_abs"
    }
  ],
  "sort": {
    "metric": "volume",
    "direction": "desc"
  },
  "pagination": {
    "limit": 20
  }
}'
```

```ts
const baseUrl = process.env.IMPLYRA_API_URL;
if (!baseUrl) throw new Error("Set IMPLYRA_API_URL");

const response = await fetch(
  new URL("markets/discover", baseUrl.replace(/\/?$/, "/")),
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      metrics: ["volume", "liquidity", "price"],
      deltas: [
        { metric: "price", window: "24h", compare: "delta_abs" }
      ],
      sort: { metric: "volume", direction: "desc" },
      pagination: { limit: 20 }
    })
  }
);

if (!response.ok) {
  throw new Error(
    `Implyra ${response.status}: ${await response.text()}`
  );
}

const { markets, pagination } = await response.json();
console.log(markets, pagination.has_more);
```

```python
import json
import os
from urllib.request import Request, urlopen

base_url = os.environ["IMPLYRA_API_URL"].rstrip("/")
payload = {
    "metrics": ["volume", "liquidity", "price"],
    "deltas": [
        {"metric": "price", "window": "24h", "compare": "delta_abs"}
    ],
    "sort": {"metric": "volume", "direction": "desc"},
    "pagination": {"limit": 20}
}

request = Request(
    f"{base_url}/markets/discover",
    data=json.dumps(payload).encode(),
    headers={"Content-Type": "application/json"},
    method="POST"
)

with urlopen(request, timeout=30) as response:
    result = json.load(response)
    print(result["markets"])
```

## Body parameters

| Name | Type | Description |
| --- | --- | --- |
| `metrics` | string[] · optional | Fields to return. Volume is cumulative USD trading volume; liquidity is in USD; price is on the 0–1 scale. Holder fields require availability to be enabled. |
| `deltas` | object[] · optional | Each entry has metric, compare (delta_abs or delta_pct), and exactly one of window or since. |
| `filters` | object · optional | An AND / OR group containing numeric metric conditions and optional nested groups. |
| `sort` | object · optional | metric and direction (asc or desc; default desc). Add window and compare together for delta sorting. Also accepts primary and fallback sort objects. |
| `pagination` | object · optional | limit (default 20, maximum 100) and an optional opaque cursor from the previous response. |
| `search` | string · optional | Search market text. Maximum 200 characters. |
| `tags_any / tags_all / tags_none` | string[] · optional | Filter by lowercase tag slugs; maximum 50 per array. |
| `price_min / price_max` | number · optional | Price bounds on the 0–1 scale. |
| `stages` | string[] · optional | One or more of new, building, peak, settling, and resolving. |
| `nulls` | string · optional | How to sort unavailable deltas: last, exclude, or zero. Zero is limited to absolute delta comparisons. |

## Response

A successful request returns a markets array and pagination metadata. The example below uses illustrative values.

For 24-hour trading volume, request an absolute volume delta over 24h and read volume_24h.abs when its status is ok. The current metrics.volume field is cumulative volume.

**200 · Example response**

```json
{
  "markets": [
    {
      "market_id": "example-market-id",
      "condition_id": "example-condition-id",
      "slug": "example-market",
      "question": "Will the example event happen?",
      "category": "Crypto",
      "active": true,
      "closed": false,
      "age_seconds": 2592000,
      "available_windows": [
        "5m",
        "15m",
        "30m",
        "1h",
        "4h",
        "24h",
        "7d",
        "30d"
      ],
      "stage": "peak",
      "price": 0.64,
      "metrics": {
        "volume": 1284512.33,
        "liquidity": 391204.5,
        "price": 0.64
      },
      "deltas": {
        "price_24h": {
          "abs": 0.04,
          "status": "ok"
        }
      }
    }
  ],
  "pagination": {
    "has_more": false
  }
}
```

## Read delta status before values

Delta keys use the metric and requested window, such as price_24h. The status is one of ok, too_new, missing_history, or div0. An unavailable delta is not a zero change; preserve that distinction in your interface.