# List Trades

> Lists whale trades from the last 30 days, newest or biggest first, with each trader's record and what other whales did.

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

`GET /v2/trades`

Scope: `read`

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.

> **Note:** 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](https://rivo.markets/docs/rate-limits).

## Example request

curl:

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

Python:

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

TypeScript:

```typescript
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

- `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.
- `trader` (trader ref, optional): 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.
- `market` (market ref, optional): 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.
- `outcome` (string, optional): Returns rows for one side of the market. Pass the side's `name` (`Yes`, `No`, `Lakers`, `Up`) or its `label` from [Get Market](https://rivo.markets/docs/reference/get-market), such as `Milwaukee`. The match ignores case. You must also pass exactly one `market`.
- `action` (string, optional, default `buy`): Which trades to return: `buy`, `sell` or `all`. `buy` leaves out trims and closes, because those are exits.
- `entry` (string, optional, default `all`): Which buys to return. `open` returns new positions only, `add` returns buys that add to a position, and `all` returns both.
- `minUsd` (number, optional): Returns trades of at least this many dollars.
- `maxUsd` (number, optional): Returns trades of at most this many dollars.
- `priceMin` (number, optional): Returns trades at or above this price paid, from 0 to 1.
- `priceMax` (number, optional): Returns trades at or below this price paid, from 0 to 1.
- `named` (boolean, optional): Set to `true` to return only trades by a named trader. This leaves out venues that do not name their traders.
- `minWinRate` (number, optional): 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.
- `minSettled` (integer, optional): 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.
- `result` (string, optional): Returns trades with this result: `open`, `win` or `loss`.
- `q` (string, optional): 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.
- `since` (string, optional): Returns trades at or after this time, in ISO 8601 with an offset. A time older than 30 days reads as 30 days ago.
- `until` (string, optional): Returns trades at or before this time, in ISO 8601 with an offset.
- `sort` (string, optional, default `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`.
- `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": [
    {
      "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

- `data` (object[]): The trades on this page.
  - `id` (string): The trade's id. It never changes, so the same trade has the same id in every listing and on the stream.
  - `time` (string): When the trade happened on the venue, in ISO 8601 UTC.
  - `market` (object): The market this row is about.
    - `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.
  - `outcome` (string): 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`.
  - `action` (string): Whether the trader bought or sold: `buy` or `sell`.
  - `entry` (string 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.
  - `price` (number or null): The price paid for each contract, from 0 to 1.
  - `usd` (number or null): The dollars traded.
  - `contracts` (number or null): The number of contracts traded.
  - `trader` (object 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`.
    - `ref` (trader ref): The trader's ref. You can pass it to any `trader` filter or to [Get Trader](https://rivo.markets/docs/reference/get-trader).
    - `name` (string or null): The trader's public name, or `null` when they have none. The API never returns a wallet address as a name.
    - `winRate` (number 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.
    - `profit` (number or null): The trader's profit in USD, over the same bets as `winRate`.
    - `settled` (integer): The number of settled bets behind `winRate` and `profit`.
  - `agreement` (object): The other whale trades on this market in the 24 hours before this one.
    - `sameSide` (object): Trades that bought the same side.
      - `trades` (integer): The number of whale trades.
      - `usd` (number): The dollars those trades spent.
    - `otherSide` (object): Trades that bought the other side.
      - `trades` (integer): The number of whale trades.
      - `usd` (number): The dollars those trades spent.
  - `result` (string): The trade's result. It is `open` until the market settles, then `win`, `loss` or `void`.
  - `profit` (number or null): What the trade made in USD, if held to settlement at the price paid. It is `null` while the market is open.
- `nextCursor` (string 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. |