GET/v2/tradersread scope

List Traders

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

GET /v2/traders

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

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

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

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
Ranks traders by their record in one category: sports, politics, crypto, finance, culture. Pass one value.
kindstring
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.
qstring
Finds traders by name, handle or address, up to 100 characters.
periodstringdefault all
The window to rank over. today covers the last 24 hours, week 7 days, month 30 days, and all the whole record.
minSettledinteger
Returns only traders with at least this many settled bets in the chosen markets and window, from 1 to 100,000.
sortstringdefault profit
How to rank traders: profit, win_rate, return, volume, trades or recent. recent puts the latest trade 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": "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

dataobject[]
The traders on this page.
Show 11 data fields
- reftrader ref
  The trader's ref.
- namestring or null
  The trader's public name. The API never returns a wallet address as a name.
- venuestring
  The venue the trader trades on.
- winRatenumber 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.
- returnnumber 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.
- profitnumber or null
  The trader's profit in USD, in the same markets and window.
- volumenumber or null
  The dollars the trader traded, in the same markets and window.
- tradesinteger
  The number of trades in the same markets and window.
- settledinteger
  The number of settled bets in the same markets and window.
- bestKindstring or null
  The kind of market where the trader makes the most, once they have enough settled bets there.
- lastTradeAtstring or null
  When the trader last traded, in ISO 8601 UTC.
nextCursorstring 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 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.

Example request

GET /v2/traders

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

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

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

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

Ranks traders by their record in one category: sports, politics, crypto, finance, culture. Pass one value.

kindstring

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.

qstring

Finds traders by name, handle or address, up to 100 characters.

periodstringdefault all

The window to rank over. today covers the last 24 hours, week 7 days, month 30 days, and all the whole record.

minSettledinteger

Returns only traders with at least this many settled bets in the chosen markets and window, from 1 to 100,000.

sortstringdefault profit

How to rank traders: profit, win_rate, return, volume, trades or recent. recent puts the latest trade 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": "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

dataobject[]

The traders on this page.

Show 11 data fields

reftrader ref
The trader's ref.
namestring or null
The trader's public name. The API never returns a wallet address as a name.
venuestring
The venue the trader trades on.
winRatenumber 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.
returnnumber 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.
profitnumber or null
The trader's profit in USD, in the same markets and window.
volumenumber or null
The dollars the trader traded, in the same markets and window.
tradesinteger
The number of trades in the same markets and window.
settledinteger
The number of settled bets in the same markets and window.
bestKindstring or null
The kind of market where the trader makes the most, once they have enough settled bets there.
lastTradeAtstring or null
When the trader last traded, 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, kind does not belong to category, or the cursor came from another listing.