GET/v2/marketsread scope

List Markets

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 lists every contract.

Example request

GET /v2/markets

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

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())

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

venuestring
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.
categorystring
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.
kindstring
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. To pass several values, repeat the key, up to 50 times. A row matches if it matches any of them.
statusstringdefault open
Which markets to return: open, settled or all.
qstring
Returns markets whose title or outcomes contain these words, up to 200 characters.
priceMinnumber
Returns open markets whose leading side trades at or above this price, from 0 to 1. It works on open markets only.
priceMaxnumber
Returns open markets whose leading side trades at or below this price, from 0 to 1. It works on open markets only.
seriesboolean
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.
sortstringdefault 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.
limitintegerdefault 50
The number of rows on each page, from 1 to 200.
cursorstring
Pass the nextCursor from the previous page to read the next one. A cursor works only on the listing that made it. See Paging.

Example response

Response

{
  "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

dataobject[]
The markets on this page.
Show 14 data fields
- refmarket ref
  The market's ref. You can pass it to any market filter or to Get Market. On a market of several outcomes, it names the whole event.
- contractmarket 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 or a market bot.
- titlestring
  The market's title, as the venue writes it.
- venuestring
  The venue that lists the market: one of kalshi, polymarket, polymarket_us or gemini.
- categorystring or null
  The market's category: one of sports, politics, crypto, finance, culture. It is null when Rivo has not classified the market.
- kindstring or null
  The kind of market, such as nfl or bitcoin. It is null when Rivo has not classified the market yet.
- statusstring
  The market's status: open, settled or void.
- outcomesobject[]
  On an open market, the two sides, or the two sides of its most traded contract. The list is empty on a settled market.
  Show 3 outcomes fields
  - namestring
    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.
  - labelstring
    What the venue calls the side, such as Milwaukee or Not Milwaukee. It equals name where the two agree.
  - pricenumber or null
    The side's price now, from 0 to 1.
- outcomeCountinteger
  The number of contracts the market has.
- volume1hnumber 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.
- move1hnumber or null
  How much the Yes price changed over the last hour.
- whaleMoneynumber 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.
- resultstring 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.
- settledAtstring or null
  On a settled market, when it settled, in ISO 8601 UTC.
nextCursorstring 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.

Example request

GET /v2/markets

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

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())

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

venuestring

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.

categorystring

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.

kindstring

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. To pass several values, repeat the key, up to 50 times. A row matches if it matches any of them.

statusstringdefault open

Which markets to return: open, settled or all.

qstring

Returns markets whose title or outcomes contain these words, up to 200 characters.

priceMinnumber

Returns open markets whose leading side trades at or above this price, from 0 to 1. It works on open markets only.

priceMaxnumber

Returns open markets whose leading side trades at or below this price, from 0 to 1. It works on open markets only.

seriesboolean

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.

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

limitintegerdefault 50

The number of rows on each page, from 1 to 200.

cursorstring

Pass the nextCursor from the previous page to read the next one. A cursor works only on the listing that made it. See Paging.

Example response

Response

{
  "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

dataobject[]

The markets on this page.

Show 14 data fields

refmarket ref
The market's ref. You can pass it to any market filter or to Get Market. On a market of several outcomes, it names the whole event.
contractmarket 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 or a market bot.
titlestring
The market's title, as the venue writes it.
venuestring
The venue that lists the market: one of kalshi, polymarket, polymarket_us or gemini.
categorystring or null
The market's category: one of sports, politics, crypto, finance, culture. It is null when Rivo has not classified the market.
kindstring or null
The kind of market, such as nfl or bitcoin. It is null when Rivo has not classified the market yet.
statusstring
The market's status: open, settled or void.
outcomesobject[]
On an open market, the two sides, or the two sides of its most traded contract. The list is empty on a settled market.
Show 3 outcomes fields
- namestring
  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.
- labelstring
  What the venue calls the side, such as Milwaukee or Not Milwaukee. It equals name where the two agree.
- pricenumber or null
  The side's price now, from 0 to 1.
outcomeCountinteger
The number of contracts the market has.
volume1hnumber 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.
move1hnumber or null
How much the Yes price changed over the last hour.
whaleMoneynumber 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.
resultstring 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.
settledAtstring or null
On a settled market, when it settled, in ISO 8601 UTC.

nextCursorstring or null

Pass this as cursor to read the next page. It is null on the last page.

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.