# List Traders

> Searches and ranks traders who were active in the last 30 days, over all time or over today, this week or this month.

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

`GET /v2/traders`

Scope: `read`

This route returns traders who traded in the last 30 days, ranked by `sort`. Only `kalshi` or `polymarket` name their traders. Venues whose public trades name nobody have no traders here.

`period` ranks traders by the bets they placed in that window instead of their whole record. `category` or `kind` ranks them by their record in those markets only.

Win rate and return need at least 10 settled bets. Until a trader has 10, both are `null`, and the trader sorts after everyone who has them.

## Example request

curl:

```bash
curl "https://api.rivo.markets/v2/traders?venue=kalshi&period=month&sort=profit&limit=2" \
  -H "Authorization: Bearer rivo_live_..."
```

Python:

```python
import requests

url = "https://api.rivo.markets/v2/traders"
headers = {
    "Authorization": "Bearer rivo_live_...",
}
params = [
    ("venue", "kalshi"),
    ("period", "month"),
    ("sort", "profit"),
    ("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"],
  ["period", "month"],
  ["sort", "profit"],
  ["limit", "2"],
]);

const res = await fetch(`https://api.rivo.markets/v2/traders?${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): Ranks traders by their record in one category: `sports`, `politics`, `crypto`, `finance`, `culture`. Pass one value.
- `kind` (string, optional): Ranks traders by their record in one kind of market: `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`. Pass one value. If you also send `category`, the kind must belong to that category.
- `q` (string, optional): Finds traders by name, handle or address, up to 100 characters.
- `period` (string, optional, default `all`): The window to rank over. `today` covers the last 24 hours, `week` 7 days, `month` 30 days, and `all` the whole record.
- `minSettled` (integer, optional): Returns only traders with at least this many settled bets in the chosen markets and window, from 1 to 100,000.
- `sort` (string, optional, default `profit`): How to rank traders: `profit`, `win_rate`, `return`, `volume`, `trades` or `recent`. `recent` puts the latest trade 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": "kalshi:repanzuliog",
      "name": "RepanzulioG",
      "venue": "kalshi",
      "winRate": 0.8423,
      "return": 0.1091,
      "profit": 191467.44,
      "volume": 1755478.24,
      "trades": 1171,
      "settled": 1097,
      "bestKind": "parlay",
      "lastTradeAt": "2026-09-30T03:14:23.912Z"
    },
    {
      "ref": "kalshi:apexnyc",
      "name": "apexnyc",
      "venue": "kalshi",
      "winRate": 0.4142,
      "return": 0.1026,
      "profit": 178785.16,
      "volume": 1742912.01,
      "trades": 4654,
      "settled": 4604,
      "bestKind": "tennis",
      "lastTradeAt": "2026-10-15T01:18:49.469Z"
    }
  ],
  "nextCursor": "eyJvIjoyfQ"
}
```

## Response fields

- `data` (object[]): The traders on this page.
  - `ref` (trader ref): The trader's ref.
  - `name` (string or null): The trader's public name. The API never returns a wallet address as a name.
  - `venue` (string): The venue the trader trades on.
  - `winRate` (number or null): The share of settled bets the trader won in the chosen markets and window, from 0 to 1. It is `null` until they have 10 settled bets.
  - `return` (number or null): The trader's profit divided by the money they traded, in the same markets and window. It is `null` until they have 10 settled bets.
  - `profit` (number or null): The trader's profit in USD, in the same markets and window.
  - `volume` (number or null): The dollars the trader traded, in the same markets and window.
  - `trades` (integer): The number of trades in the same markets and window.
  - `settled` (integer): The number of settled bets in the same markets and window.
  - `bestKind` (string or null): The kind of market where the trader makes the most, once they have enough settled bets there.
  - `lastTradeAt` (string or null): When the trader last traded, in ISO 8601 UTC.
- `nextCursor` (string or null): Pass this as `cursor` to read the next page. It is `null` on the last page.

To read a trader's individual trades, call [List Trades](https://rivo.markets/docs/reference/list-trades) with `trader` set to their ref.

## Errors

| Code | When |
| --- | --- |
| `VALIDATION` | A parameter is out of range or unknown, `kind` does not belong to `category`, or the cursor came from another listing. |