# List Markets

> Searches and browses markets on every venue. It returns open markets by default, or the markets that settled in the last 30 days.

Source: https://rivo.markets/docs/reference/list-markets

`GET /v2/markets`

Scope: `read`

This route returns markets. Without `q`, it browses: it lists the markets that traded in the last hour, then each venue's most traded open markets. With `q`, it searches the title and outcomes of every open market.

`status=settled` lists markets that settled in the last 30 days and had whale trades, with the most recently settled first. `status=all` lists the open markets first and the settled ones after them.

A market with several outcomes, such as a game between two teams or an election with many candidates, appears as one row. Its `outcomes` show the two sides of its most traded contract, and `outcomeCount` says how many contracts it has. [Get Market](https://rivo.markets/docs/reference/get-market) lists every contract.

## Example request

curl:

```bash
curl "https://api.rivo.markets/v2/markets?category=sports&sort=whale_money&limit=2" \
  -H "Authorization: Bearer rivo_live_..."
```

Python:

```python
import requests

url = "https://api.rivo.markets/v2/markets"
headers = {
    "Authorization": "Bearer rivo_live_...",
}
params = [
    ("category", "sports"),
    ("sort", "whale_money"),
    ("limit", "2"),
]

res = requests.get(url, headers=headers, params=params)
res.raise_for_status()
print(res.json())
```

TypeScript:

```typescript
const params = new URLSearchParams([
  ["category", "sports"],
  ["sort", "whale_money"],
  ["limit", "2"],
]);

const res = await fetch(`https://api.rivo.markets/v2/markets?${params}`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.RIVO_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`Rivo API ${res.status}`);
const { data } = await res.json();
```

## Query parameters

- `venue` (string, optional): Returns rows from these venues: `kalshi`, `polymarket`, `polymarket_us` or `gemini`. To pass several values, repeat the key, up to 50 times. A row matches if it matches any of them.
- `category` (string, optional): Returns rows in these categories: `sports`, `politics`, `crypto`, `finance`, `culture`. To pass several values, repeat the key, up to 50 times. A row matches if it matches any of them.
- `kind` (string, optional): Returns rows in these kinds of market. Each kind belongs to one category: `nfl`, `college_football`, `nba`, `wnba`, `college_basketball`, `basketball`, `mlb`, `nhl`, `soccer`, `tennis`, `golf`, `mma`, `boxing`, `motorsport`, `cricket`, `esports`, `chess`, `rugby`, `olympics`, `parlay`, `other_sports`, `us_elections`, `us_politics`, `world_politics`, `other_politics`, `bitcoin`, `ethereum`, `solana`, `xrp`, `other_crypto`, `fed_rates`, `economic_data`, `stocks_indices`, `companies`, `commodities`, `fx`, `other_finance`, `mentions`, `weather`, `entertainment`, `tech_ai`, `health`, `other_culture`. See [Kinds of market](https://rivo.markets/docs/concepts#kinds-of-market). To pass several values, repeat the key, up to 50 times. A row matches if it matches any of them.
- `status` (string, optional, default `open`): Which markets to return: `open`, `settled` or `all`.
- `q` (string, optional): Returns markets whose title or outcomes contain these words, up to 200 characters.
- `priceMin` (number, optional): Returns open markets whose leading side trades at or above this price, from 0 to 1. It works on open markets only.
- `priceMax` (number, optional): Returns open markets whose leading side trades at or below this price, from 0 to 1. It works on open markets only.
- `series` (boolean, optional): Set to `true` to return only repeating markets. These markets reopen on a clock, such as Bitcoin up or down in the next 15 minutes.
- `sort` (string, optional, default `whale_money`): How to order open markets. `whale_money` sorts by whale dollars in the last hour, `volume` by dollars traded in the last hour, `move` by the biggest price move of the last hour in either direction, and `newest` by the latest trade. Markets with no reading for the sort come last. Settled markets always come newest settled first.
- `limit` (integer, optional, default `50`): The number of rows on each page, from 1 to 200.
- `cursor` (string, optional): Pass the `nextCursor` from the previous page to read the next one. A cursor works only on the listing that made it. See [Paging](https://rivo.markets/docs/concepts#paging).

## Example response

```json
{
  "data": [
    {
      "ref": "cG9seW1hcmtldDptYXJrZXQ6d3RhLW11Y2hvdmEtc2huYWlkZS0yMDI2LTEwLTE0",
      "title": "Wuhan Tennis Open: Karolina Muchova vs Diana Shnaider",
      "venue": "polymarket",
      "category": "sports",
      "kind": "tennis",
      "status": "open",
      "outcomes": [
        {
          "name": "Karolina Muchova",
          "label": "Karolina Muchova",
          "price": 0.6
        },
        {
          "name": "Diana Shnaider",
          "label": "Diana Shnaider",
          "price": 0.4
        }
      ],
      "outcomeCount": 16,
      "volume1h": 197247.96,
      "move1h": 0.02,
      "whaleMoney": 339469.91,
      "result": null,
      "settledAt": null
    },
    {
      "ref": "cG9seW1hcmtldDptYXJrZXQ6Y2ZiLWNvbHN0LXR4c3QtMjAyNi0xMC0xNS10b3RhbC02OXB0NQ",
      "title": "Colorado State vs. Texas State: O/U 69.5",
      "venue": "polymarket",
      "category": "sports",
      "kind": "college_football",
      "status": "open",
      "outcomes": [
        {
          "name": "Yes",
          "label": "Yes",
          "price": 0.505
        },
        {
          "name": "No",
          "label": "No",
          "price": 0.495
        }
      ],
      "outcomeCount": 228,
      "volume1h": null,
      "move1h": null,
      "whaleMoney": 91079.31,
      "result": null,
      "settledAt": null
    }
  ],
  "nextCursor": "eyJwIjoib3BlbiIsIm8iOjJ9"
}
```

## Response fields

- `data` (object[]): The markets on this page.
  - `ref` (market ref): The market's ref. You can pass it to any `market` filter or to [Get Market](https://rivo.markets/docs/reference/get-market). On a market of several outcomes, it names the whole event.
  - `contract` (market ref or null): The ref of the exact contract. It is the same as `ref` on a market with one contract. On a market of several outcomes, such as a game with a moneyline and a spread, it tells the contracts apart. Pass it to [Place Paper Order](https://rivo.markets/docs/reference/place-paper-order) or a market bot.
  - `title` (string): The market's title, as the venue writes it.
  - `venue` (string): The venue that lists the market: one of `kalshi`, `polymarket`, `polymarket_us` or `gemini`.
  - `category` (string or null): The market's category: one of `sports`, `politics`, `crypto`, `finance`, `culture`. It is `null` when Rivo has not classified the market.
  - `kind` (string or null): The kind of market, such as `nfl` or `bitcoin`. It is `null` when Rivo has not classified the market yet.
  - `status` (string): The market's status: `open`, `settled` or `void`.
  - `outcomes` (object[]): On an open market, the two sides, or the two sides of its most traded contract. The list is empty on a settled market.
    - `name` (string): The side's name, the same on every route. On Polymarket it is the outcome's own name, such as `Lakers` or `Up`. On every other venue it is `Yes` or `No`.
    - `label` (string): What the venue calls the side, such as `Milwaukee` or `Not Milwaukee`. It equals `name` where the two agree.
    - `price` (number or null): The side's price now, from 0 to 1.
  - `outcomeCount` (integer): The number of contracts the market has.
  - `volume1h` (number or null): The dollars traded on the market in the last hour, counting every trade Rivo's market reader saw. It is `null` when Rivo has not seen the market trade. It comes from a different read than `whaleMoney`, so on a busy market `whaleMoney` can be larger.
  - `move1h` (number or null): How much the Yes price changed over the last hour.
  - `whaleMoney` (number or null): The dollars whales spent buying into the market in the last hour, from Rivo's whale trades. It is `null` when no whale bought in the last hour.
  - `result` (string or null): On a settled market, the name of the outcome that won. It is `null` while the market is open and when it is void.
  - `settledAt` (string or null): On a settled market, when it settled, in ISO 8601 UTC.
- `nextCursor` (string or null): Pass this as `cursor` to read the next page. It is `null` on the last page.

## Errors

| Code | When |
| --- | --- |
| `VALIDATION` | A parameter is out of range or unknown. You sent `priceMin` or `priceMax` without `status=open`. You sent a `sort` other than `newest` with `status=settled`. Or the cursor came from another listing. |