GET/v2/tradesread scope

List Trades

This route returns whale trades from every venue over the last 30 days, newest first. Each row includes the trader's record in that kind of market and what other whales did on the same market in the 24 hours before it.

You can filter by who traded, what they paid and the trader's record. minWinRate and minSettled test the same record that the row returns under trader. For example, ?minWinRate=0.6&minSettled=50 returns trades by traders who win 60% of their bets and have 50 or more settled bets in that kind of market.

Every row the API returns counts toward your key's daily allowance of 50,000 trades. Rows that a filter leaves out do not count. See Rate limits.

Example request

GET /v2/trades

curl "https://api.rivo.markets/v2/trades?venue=kalshi&named=true&minWinRate=0.6&minSettled=50&limit=2" \
  -H "Authorization: Bearer rivo_live_..."

import requests

url = "https://api.rivo.markets/v2/trades"
headers = {
    "Authorization": "Bearer rivo_live_...",
}
params = [
    ("venue", "kalshi"),
    ("named", "true"),
    ("minWinRate", "0.6"),
    ("minSettled", "50"),
    ("limit", "2"),
]

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

const params = new URLSearchParams([
  ["venue", "kalshi"],
  ["named", "true"],
  ["minWinRate", "0.6"],
  ["minSettled", "50"],
  ["limit", "2"],
]);

const res = await fetch(`https://api.rivo.markets/v2/trades?${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.
tradertrader ref
Returns rows for this trader. Take the trader's ref from any row that names them. To pass several values, repeat the key, up to 50 times. A row matches if it matches any of them.
marketmarket ref
Returns rows for this market. The ref can name one contract or a market with several outcomes. To pass several values, repeat the key, up to 50 times. A row matches if it matches any of them.
outcomestring
Returns rows for one side of the market. Pass the side's name (Yes, No, Lakers, Up) or its label from Get Market, such as Milwaukee. The match ignores case. You must also pass exactly one market.
actionstringdefault buy
Which trades to return: buy, sell or all. buy leaves out trims and closes, because those are exits.
entrystringdefault all
Which buys to return. open returns new positions only, add returns buys that add to a position, and all returns both.
minUsdnumber
Returns trades of at least this many dollars.
maxUsdnumber
Returns trades of at most this many dollars.
priceMinnumber
Returns trades at or above this price paid, from 0 to 1.
priceMaxnumber
Returns trades at or below this price paid, from 0 to 1.
namedboolean
Set to true to return only trades by a named trader. This leaves out venues that do not name their traders.
minWinRatenumber
Returns trades by traders whose win rate in that kind of market is at least this, from 0 to 1. The trader also needs at least 10 settled bets there. Trades with no named trader drop out.
minSettledinteger
Returns trades by traders with at least this many settled bets in that kind of market, from 1 to 100,000. Trades with no named trader drop out.
resultstring
Returns trades with this result: open, win or loss.
qstring
Returns trades whose market title or outcome contains every one of these words, up to five words and 200 characters. Search covers the full 30 days.
sincestring
Returns trades at or after this time, in ISO 8601 with an offset. A time older than 30 days reads as 30 days ago.
untilstring
Returns trades at or before this time, in ISO 8601 with an offset.
sortstringdefault newest
How to order the trades. newest puts the latest first and size puts the biggest first. With size, the API reads only the last 24 hours unless you set trader or market.
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": [
    {
      "id": "f1c6b941-64bf-5911-88ef-1b5de17e9d76",
      "time": "2026-10-15T02:25:20.514Z",
      "market": {
        "ref": "a2Fsc2hpOm1hcmtldDpLWEJUQzE1TS0yNk9DVDE0MjIzMC0zMA",
        "contract": "a2Fsc2hpOm1hcmtldDpLWEJUQzE1TS0yNk9DVDE0MjIzMC0zMA",
        "title": "BTC price up in next 15 mins?",
        "venue": "kalshi",
        "category": "crypto",
        "kind": "bitcoin"
      },
      "outcome": "No",
      "action": "buy",
      "entry": null,
      "price": 0.992,
      "usd": 1008.86,
      "contracts": 1017,
      "trader": {
        "ref": "kalshi:prokingpriest",
        "name": "prokingpriest",
        "winRate": 0.974,
        "profit": 14118.88,
        "settled": 16521
      },
      "agreement": {
        "sameSide": { "trades": 9, "usd": 13130.67 },
        "otherSide": { "trades": 2, "usd": 2501.92 }
      },
      "result": "open",
      "profit": null
    },
    {
      "id": "1ce3724a-941e-5b4a-8e84-f2e50ae89bb8",
      "time": "2026-10-15T02:24:53.011Z",
      "market": {
        "ref": "a2Fsc2hpOm1hcmtldDpLWE1MQkdBTUUtMjZPQ1QxNDIwMDBNSUxMQUQtTUlM",
        "contract": "a2Fsc2hpOm1hcmtldDpLWE1MQkdBTUUtMjZPQ1QxNDIwMDBNSUxMQUQtTUlM",
        "title": "Milwaukee wins",
        "venue": "kalshi",
        "category": "sports",
        "kind": "mlb"
      },
      "outcome": "Yes",
      "action": "buy",
      "entry": null,
      "price": 0.88,
      "usd": 7933.36,
      "contracts": 9015.18,
      "trader": {
        "ref": "kalshi:scottramirez",
        "name": "scottramirez",
        "winRate": 0.8269,
        "profit": 5122.43,
        "settled": 52
      },
      "agreement": {
        "sameSide": { "trades": 37, "usd": 95502.12 },
        "otherSide": { "trades": 0, "usd": 0 }
      },
      "result": "open",
      "profit": null
    }
  ],
  "nextCursor": "eyJ0IjoiMjAyNi0xMC0xNSAwMjoyNDo1My4wMTErMDAiLCJpZCI6IjFjZTM3MjRhLTk0MWUtNWI0YS04ZTg0LWYyZTUwYWU4OWJiOCJ9"
}

Response fields

dataobject[]
The trades on this page.
Show 13 data fields
- idstring
  The trade's id. It never changes, so the same trade has the same id in every listing and on the stream.
- timestring
  When the trade happened on the venue, in ISO 8601 UTC.
- marketobject
  The market this row is about.
  Show 6 market 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.
- outcomestring
  The side the trader bought or sold, by its name. On Polymarket it is the outcome's own name, such as Lakers. On every other venue it is Yes or No.
- actionstring
  Whether the trader bought or sold: buy or sell.
- entrystring or null
  What the trade did to the trader's position: open, add, flip, trim or close. It is null when the venue does not say.
- pricenumber or null
  The price paid for each contract, from 0 to 1.
- usdnumber or null
  The dollars traded.
- contractsnumber or null
  The number of contracts traded.
- traderobject or null
  The trader who made the trade, with their record in this kind of market, or their whole record when Rivo has none for that kind. Only kalshi or polymarket name their traders. On every other venue this is null.
  Show 5 trader fields
  - reftrader ref
    The trader's ref. You can pass it to any trader filter or to Get Trader.
  - namestring or null
    The trader's public name, or null when they have none. The API never returns a wallet address as a name.
  - winRatenumber or null
    The share of their settled bets the trader won, from 0 to 1. It covers the kind of market this row is about, or their whole record when Rivo has none for that kind. It is null until they have 10 settled bets.
  - profitnumber or null
    The trader's profit in USD, over the same bets as winRate.
  - settledinteger
    The number of settled bets behind winRate and profit.
- agreementobject
  The other whale trades on this market in the 24 hours before this one.
  Show 2 agreement fields
  - sameSideobject
    Trades that bought the same side.
    Show 2 sameSide fields
    tradesinteger
    The number of whale trades.
    usdnumber
    The dollars those trades spent.
  - otherSideobject
    Trades that bought the other side.
    Show 2 otherSide fields
    tradesinteger
    The number of whale trades.
    usdnumber
    The dollars those trades spent.
- resultstring
  The trade's result. It is open until the market settles, then win, loss or void.
- profitnumber or null
  What the trade made in USD, if held to settlement at the price paid. It is null while the market is open.
nextCursorstring or null
Pass this as cursor to read the next page. It is null on the last page.

Headers

Every route sends the x-ratelimit-* headers. This route also sends x-trades-limit, x-trades-remaining and x-trades-reset for the daily trade allowance. x-trades-reset counts the seconds until midnight UTC.

Errors

Code	When
`VALIDATION`	A parameter is out of range or unknown. You sent `outcome` without exactly one `market`. You asked for `sort=size` with a `since` older than 24 hours and no `trader` or `market`. Or the cursor came from another listing.
`QUOTA_EXCEEDED`	You used up this minute's requests or today's trade allowance. The `retry-after` header says when to try again.

Example request

GET /v2/trades

curl "https://api.rivo.markets/v2/trades?venue=kalshi&named=true&minWinRate=0.6&minSettled=50&limit=2" \
  -H "Authorization: Bearer rivo_live_..."

import requests

url = "https://api.rivo.markets/v2/trades"
headers = {
    "Authorization": "Bearer rivo_live_...",
}
params = [
    ("venue", "kalshi"),
    ("named", "true"),
    ("minWinRate", "0.6"),
    ("minSettled", "50"),
    ("limit", "2"),
]

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

const params = new URLSearchParams([
  ["venue", "kalshi"],
  ["named", "true"],
  ["minWinRate", "0.6"],
  ["minSettled", "50"],
  ["limit", "2"],
]);

const res = await fetch(`https://api.rivo.markets/v2/trades?${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.

tradertrader ref

Returns rows for this trader. Take the trader's ref from any row that names them. To pass several values, repeat the key, up to 50 times. A row matches if it matches any of them.

marketmarket ref

Returns rows for this market. The ref can name one contract or a market with several outcomes. To pass several values, repeat the key, up to 50 times. A row matches if it matches any of them.

outcomestring

Returns rows for one side of the market. Pass the side's name (Yes, No, Lakers, Up) or its label from Get Market, such as Milwaukee. The match ignores case. You must also pass exactly one market.

actionstringdefault buy

Which trades to return: buy, sell or all. buy leaves out trims and closes, because those are exits.

entrystringdefault all

Which buys to return. open returns new positions only, add returns buys that add to a position, and all returns both.

minUsdnumber

Returns trades of at least this many dollars.

maxUsdnumber

Returns trades of at most this many dollars.

priceMinnumber

Returns trades at or above this price paid, from 0 to 1.

priceMaxnumber

Returns trades at or below this price paid, from 0 to 1.

namedboolean

Set to true to return only trades by a named trader. This leaves out venues that do not name their traders.

minWinRatenumber

Returns trades by traders whose win rate in that kind of market is at least this, from 0 to 1. The trader also needs at least 10 settled bets there. Trades with no named trader drop out.

minSettledinteger

Returns trades by traders with at least this many settled bets in that kind of market, from 1 to 100,000. Trades with no named trader drop out.

resultstring

Returns trades with this result: open, win or loss.

qstring

Returns trades whose market title or outcome contains every one of these words, up to five words and 200 characters. Search covers the full 30 days.

sincestring

Returns trades at or after this time, in ISO 8601 with an offset. A time older than 30 days reads as 30 days ago.

untilstring

Returns trades at or before this time, in ISO 8601 with an offset.

sortstringdefault newest

How to order the trades. newest puts the latest first and size puts the biggest first. With size, the API reads only the last 24 hours unless you set trader or market.

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": [
    {
      "id": "f1c6b941-64bf-5911-88ef-1b5de17e9d76",
      "time": "2026-10-15T02:25:20.514Z",
      "market": {
        "ref": "a2Fsc2hpOm1hcmtldDpLWEJUQzE1TS0yNk9DVDE0MjIzMC0zMA",
        "contract": "a2Fsc2hpOm1hcmtldDpLWEJUQzE1TS0yNk9DVDE0MjIzMC0zMA",
        "title": "BTC price up in next 15 mins?",
        "venue": "kalshi",
        "category": "crypto",
        "kind": "bitcoin"
      },
      "outcome": "No",
      "action": "buy",
      "entry": null,
      "price": 0.992,
      "usd": 1008.86,
      "contracts": 1017,
      "trader": {
        "ref": "kalshi:prokingpriest",
        "name": "prokingpriest",
        "winRate": 0.974,
        "profit": 14118.88,
        "settled": 16521
      },
      "agreement": {
        "sameSide": { "trades": 9, "usd": 13130.67 },
        "otherSide": { "trades": 2, "usd": 2501.92 }
      },
      "result": "open",
      "profit": null
    },
    {
      "id": "1ce3724a-941e-5b4a-8e84-f2e50ae89bb8",
      "time": "2026-10-15T02:24:53.011Z",
      "market": {
        "ref": "a2Fsc2hpOm1hcmtldDpLWE1MQkdBTUUtMjZPQ1QxNDIwMDBNSUxMQUQtTUlM",
        "contract": "a2Fsc2hpOm1hcmtldDpLWE1MQkdBTUUtMjZPQ1QxNDIwMDBNSUxMQUQtTUlM",
        "title": "Milwaukee wins",
        "venue": "kalshi",
        "category": "sports",
        "kind": "mlb"
      },
      "outcome": "Yes",
      "action": "buy",
      "entry": null,
      "price": 0.88,
      "usd": 7933.36,
      "contracts": 9015.18,
      "trader": {
        "ref": "kalshi:scottramirez",
        "name": "scottramirez",
        "winRate": 0.8269,
        "profit": 5122.43,
        "settled": 52
      },
      "agreement": {
        "sameSide": { "trades": 37, "usd": 95502.12 },
        "otherSide": { "trades": 0, "usd": 0 }
      },
      "result": "open",
      "profit": null
    }
  ],
  "nextCursor": "eyJ0IjoiMjAyNi0xMC0xNSAwMjoyNDo1My4wMTErMDAiLCJpZCI6IjFjZTM3MjRhLTk0MWUtNWI0YS04ZTg0LWYyZTUwYWU4OWJiOCJ9"
}

Response fields

dataobject[]

The trades on this page.

Show 13 data fields

idstring
The trade's id. It never changes, so the same trade has the same id in every listing and on the stream.
timestring
When the trade happened on the venue, in ISO 8601 UTC.
marketobject
The market this row is about.
Show 6 market 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.
outcomestring
The side the trader bought or sold, by its name. On Polymarket it is the outcome's own name, such as Lakers. On every other venue it is Yes or No.
actionstring
Whether the trader bought or sold: buy or sell.
entrystring or null
What the trade did to the trader's position: open, add, flip, trim or close. It is null when the venue does not say.
pricenumber or null
The price paid for each contract, from 0 to 1.
usdnumber or null
The dollars traded.
contractsnumber or null
The number of contracts traded.
traderobject or null
The trader who made the trade, with their record in this kind of market, or their whole record when Rivo has none for that kind. Only kalshi or polymarket name their traders. On every other venue this is null.
Show 5 trader fields
- reftrader ref
  The trader's ref. You can pass it to any trader filter or to Get Trader.
- namestring or null
  The trader's public name, or null when they have none. The API never returns a wallet address as a name.
- winRatenumber or null
  The share of their settled bets the trader won, from 0 to 1. It covers the kind of market this row is about, or their whole record when Rivo has none for that kind. It is null until they have 10 settled bets.
- profitnumber or null
  The trader's profit in USD, over the same bets as winRate.
- settledinteger
  The number of settled bets behind winRate and profit.
agreementobject
The other whale trades on this market in the 24 hours before this one.
Show 2 agreement fields
- sameSideobject
  Trades that bought the same side.
  Show 2 sameSide fields
  - tradesinteger
    The number of whale trades.
  - usdnumber
    The dollars those trades spent.
- otherSideobject
  Trades that bought the other side.
  Show 2 otherSide fields
  - tradesinteger
    The number of whale trades.
  - usdnumber
    The dollars those trades spent.
resultstring
The trade's result. It is open until the market settles, then win, loss or void.
profitnumber or null
What the trade made in USD, if held to settlement at the price paid. It is null while the market is open.

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 `outcome` without exactly one `market`. You asked for `sort=size` with a `since` older than 24 hours and no `trader` or `market`. Or the cursor came from another listing.
`QUOTA_EXCEEDED`	You used up this minute's requests or today's trade allowance. The `retry-after` header says when to try again.