# Get Trader

> Reads one trader's record overall, by category and by kind of market. On request it adds their positions, profit curve, habits and similar traders.

Source: https://rivo.markets/docs/reference/get-trader

`GET /v2/traders/{ref}`

Scope: `read`

This route returns one trader's record overall, in each category and in each kind of market. It also returns their average entry price and their place on the venue's profit ranking.

`include` adds extra sections to the response. Each include counts as a request of its own against your 120 requests a minute, so `?include=positions,curve` uses 3.

| include | Adds |
| --- | --- |
| `positions` | Adds the trader's open and recent positions. Each row folds every buy and sell on one side of one market into a single position. |
| `curve` | Adds the trader's profit over time and by month. |
| `habits` | Adds the trader's results by bet size and by price paid, how their trades change their positions, when they trade by weekday and hour in US Eastern time, and their streaks. |
| `similar` | Adds traders who trade the same kinds of market. |

## Example request

curl:

```bash
curl "https://api.rivo.markets/v2/traders/kalshi%3Arepanzuliog?include=positions%2Ccurve%2Chabits%2Csimilar" \
  -H "Authorization: Bearer rivo_live_..."
```

Python:

```python
import requests

url = "https://api.rivo.markets/v2/traders/kalshi%3Arepanzuliog"
headers = {
    "Authorization": "Bearer rivo_live_...",
}
params = [
    ("include", "positions,curve,habits,similar"),
]

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

TypeScript:

```typescript
const params = new URLSearchParams([
  ["include", "positions,curve,habits,similar"],
]);

const res = await fetch(`https://api.rivo.markets/v2/traders/kalshi%3Arepanzuliog?${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();
```

## Path parameters

- `ref` (trader ref, required): The trader's `ref`. You can take it from any row that names the trader.

## Query parameters

- `include` (string, optional): The extra sections to add: `positions`, `curve`, `habits` or `similar`. Separate them with commas, or repeat the key.

## Example response

```json
{
  "data": {
    "ref": "kalshi:repanzuliog",
    "name": "RepanzulioG",
    "venue": "kalshi",
    "record": {
      "trades": 1404,
      "settled": 1097,
      "winRate": 0.8423,
      "return": 0.0646,
      "profit": 191467.44,
      "volume": 2965383.35
    },
    "byCategory": [
      {
        "category": "sports",
        "kind": null,
        "trades": 1157,
        "settled": 1083,
        "winRate": 0.8532,
        "return": 0.1097,
        "profit": 192432.31,
        "volume": 1754513.37,
        "avgEntry": 0.795,
        "lastTradeAt": "2026-09-30T03:14:23.912Z"
      }
    ],
    "byKind": [
      {
        "category": "sports",
        "kind": "tennis",
        "trades": 28,
        "settled": 28,
        "winRate": 1,
        "return": 0.5344,
        "profit": 33026.16,
        "volume": 61795.96,
        "avgEntry": 0.6775,
        "lastTradeAt": "2026-09-28T15:25:09.900Z"
      }
    ],
    "avgEntry": 0.329,
    "rank": { "position": 2, "outOf": 6335 },
    "lastTradeAt": "2026-09-30T03:14:23.912Z",
    "positions": {
      "open": [
        {
          "market": {
            "ref": "a2Fsc2hpOm1hcmtldDpLWE1WRUNST1NTQ0FURUdPUlktUzIwMjYwNTUyMkIwMTUxQy0xMjI1RDQxMzY5Rg",
            "contract": "a2Fsc2hpOm1hcmtldDpLWE1WRUNST1NTQ0FURUdPUlktUzIwMjYwNTUyMkIwMTUxQy0xMjI1RDQxMzY5Rg",
            "title": "no Over 3.5 goals scored,no Over 2.5 goals scored",
            "venue": "kalshi",
            "category": "culture",
            "kind": null
          },
          "outcome": "Yes",
          "entryPrice": 0.919,
          "exitPrice": null,
          "usd": 24845.01,
          "soldUsd": null,
          "status": "open",
          "result": null,
          "profit": null,
          "openedAt": "2026-09-20T14:25:15.268Z",
          "lastTradeAt": "2026-09-20T14:25:15.268Z"
        }
      ],
      "recent": [
        {
          "market": {
            "ref": "a2Fsc2hpOm1hcmtldDpLWE1WRUNST1NTQ0FURUdPUlktUzIwMjY5M0Q2MkRCQzVFNy03NzFBODYxQkUwQQ",
            "contract": "a2Fsc2hpOm1hcmtldDpLWE1WRUNST1NTQ0FURUdPUlktUzIwMjY5M0Q2MkRCQzVFNy03NzFBODYxQkUwQQ",
            "title": "yes HOU Texans,yes SF 49ers,yes Atlanta wins by over 12.5 points",
            "venue": "kalshi",
            "category": "sports",
            "kind": null
          },
          "outcome": "Yes",
          "entryPrice": 0.362,
          "exitPrice": null,
          "usd": 42597.12,
          "soldUsd": null,
          "status": "settled",
          "result": "win",
          "profit": 75074.48,
          "openedAt": "2026-09-30T03:14:23.912Z",
          "lastTradeAt": "2026-09-30T03:14:23.912Z"
        }
      ]
    },
    "curve": {
      "points": [
        { "time": "2026-09-17T15:10:24.005Z", "profit": 86, "trades": 7 }
      ],
      "months": [
        { "month": "2026-09", "trades": 1097, "profit": 191467.44 }
      ]
    },
    "habits": {
      "bySize": [
        { "label": "$0 to $14", "trades": 351, "settled": 251, "winRate": 0.9124, "return": 0.0595, "profit": 90.91, "volume": 1527.17 }
      ],
      "byPrice": [
        { "label": "Under 20¢", "avgEntry": 0.0454, "trades": 90, "settled": 28, "winRate": 0.3571, "return": 1.2214, "profit": 168476.68, "volume": 137938.89 }
      ],
      "behaviour": [],
      "hours": [
        { "weekday": 0, "hour": 1, "trades": 76 }
      ],
      "streaks": { "current": 1, "currentKind": "win", "longestWin": 13, "longestLoss": 14 }
    },
    "similar": [
      { "ref": "kalshi:thebigdon", "name": "thebigdon", "profit": 189605.38 }
    ]
  }
}
```

## Response fields

- `data` (object): The trader you asked for.
  - `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.
  - `record` (object): The trader's whole record.
    - `trades` (integer): The number of trades Rivo has on record.
    - `settled` (integer): The number of settled bets.
    - `winRate` (number or null): The share of settled bets won, from 0 to 1. It is `null` until there are 10 settled bets.
    - `profit` (number or null): The profit in USD.
    - `volume` (number or null): The dollars traded.
    - `return` (number or null): The profit divided by the dollars traded. It is `null` until there are 10 settled bets.
  - `byCategory` (object[]): The trader's record in each category.
    - `category` (string): The category this row covers.
    - `kind` (string or null): The kind of market this row covers. It is `null` on a row for a whole category.
    - `trades` (integer): The number of trades Rivo has on record.
    - `settled` (integer): The number of settled bets.
    - `winRate` (number or null): The share of settled bets won, from 0 to 1. It is `null` until there are 10 settled bets.
    - `profit` (number or null): The profit in USD.
    - `volume` (number or null): The dollars traded.
    - `return` (number or null): The profit divided by the dollars traded. It is `null` until there are 10 settled bets.
    - `avgEntry` (number or null): The average price paid, from 0 to 1.
    - `lastTradeAt` (string or null): When the trader last traded in this category or kind, in ISO 8601 UTC.
  - `byKind` (object[]): The trader's record in each kind of market.
    - `category` (string): The category this row covers.
    - `kind` (string or null): The kind of market this row covers. It is `null` on a row for a whole category.
    - `trades` (integer): The number of trades Rivo has on record.
    - `settled` (integer): The number of settled bets.
    - `winRate` (number or null): The share of settled bets won, from 0 to 1. It is `null` until there are 10 settled bets.
    - `profit` (number or null): The profit in USD.
    - `volume` (number or null): The dollars traded.
    - `return` (number or null): The profit divided by the dollars traded. It is `null` until there are 10 settled bets.
    - `avgEntry` (number or null): The average price paid, from 0 to 1.
    - `lastTradeAt` (string or null): When the trader last traded in this category or kind, in ISO 8601 UTC.
  - `avgEntry` (number or null): The average price paid, from 0 to 1.
  - `rank` (object or null): The trader's place on the venue's profit ranking. It is `null` when the trader is not ranked.
    - `position` (integer): The trader's place, where 1 is the top.
    - `outOf` (integer): The number of traders in the ranking.
  - `lastTradeAt` (string or null): When the trader last traded, in ISO 8601 UTC.
  - `positions` (object): The trader's positions, when you ask for `include=positions`.
    - `open` (object[]): The positions the trader still holds.
      - `market` (object or null): The market this position is on. It is `null` on the rare position whose market Rivo cannot name. Here `kind` is always `null`.
        - `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 holds.
      - `entryPrice` (number or null): The average price paid, from 0 to 1.
      - `exitPrice` (number or null): The average price the trader sold at, from 0 to 1.
      - `usd` (number): The dollars the trader spent buying.
      - `soldUsd` (number or null): The dollars the trader received from selling.
      - `status` (string or null): The position's status: `open`, `reduced`, `exited` or `settled`. A position stops counting as open once the trader sells 95% of it.
      - `result` (string or null): The result once the market settles: `win`, `loss` or `void`.
      - `profit` (number or null): The profit in USD, once Rivo knows it.
      - `openedAt` (string): When the trader first bought, in ISO 8601 UTC.
      - `lastTradeAt` (string): When the trader last bought or sold, in ISO 8601 UTC.
    - `recent` (object[]): Recent positions the trader has left or that have settled.
      - `market` (object or null): The market this position is on. It is `null` on the rare position whose market Rivo cannot name. Here `kind` is always `null`.
        - `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 holds.
      - `entryPrice` (number or null): The average price paid, from 0 to 1.
      - `exitPrice` (number or null): The average price the trader sold at, from 0 to 1.
      - `usd` (number): The dollars the trader spent buying.
      - `soldUsd` (number or null): The dollars the trader received from selling.
      - `status` (string or null): The position's status: `open`, `reduced`, `exited` or `settled`. A position stops counting as open once the trader sells 95% of it.
      - `result` (string or null): The result once the market settles: `win`, `loss` or `void`.
      - `profit` (number or null): The profit in USD, once Rivo knows it.
      - `openedAt` (string): When the trader first bought, in ISO 8601 UTC.
      - `lastTradeAt` (string): When the trader last bought or sold, in ISO 8601 UTC.
  - `curve` (object): The profit curve, when you ask for `include=curve`.
    - `points` (object[]): The running total of profit, oldest first.
      - `time` (string): The time of this point, in ISO 8601 UTC.
      - `profit` (number): The total profit up to this point, in USD.
      - `trades` (integer): The number of settled bets counted up to this point.
    - `months` (object[]): The results for each month.
      - `month` (string): The month, written as `YYYY-MM`.
      - `trades` (integer): The number of bets that settled that month.
      - `profit` (number): The profit that month, in USD.
  - `habits` (object): The trader's habits, when you ask for `include=habits`.
    - `bySize` (object[]): The trader's results by bet size, split into four bands with the same number of trades in each.
      - `label` (string): The band this row covers, such as `$0 to $14` or `Under 20¢`.
      - `trades` (integer): The number of trades Rivo has on record.
      - `settled` (integer): The number of settled bets.
      - `winRate` (number or null): The share of settled bets won, from 0 to 1. It is `null` until there are 10 settled bets.
      - `profit` (number or null): The profit in USD.
      - `volume` (number or null): The dollars traded.
      - `return` (number or null): The profit divided by the dollars traded. It is `null` until there are 10 settled bets.
    - `byPrice` (object[]): The trader's results by price paid, with `avgEntry` for each band.
      - `label` (string): The band this row covers, such as `$0 to $14` or `Under 20¢`.
      - `trades` (integer): The number of trades Rivo has on record.
      - `settled` (integer): The number of settled bets.
      - `winRate` (number or null): The share of settled bets won, from 0 to 1. It is `null` until there are 10 settled bets.
      - `profit` (number or null): The profit in USD.
      - `volume` (number or null): The dollars traded.
      - `return` (number or null): The profit divided by the dollars traded. It is `null` until there are 10 settled bets.
      - `avgEntry` (number or null): The average price paid in this band.
    - `behaviour` (object[]): How the trader's trades changed their positions, such as opening, adding, trimming or closing, with the most common first.
      - `label` (string): What this row counts.
      - `trades` (integer): The number of trades.
    - `hours` (object[]): The trader's trades by weekday and hour, in US Eastern time.
      - `weekday` (integer): The day of the week, where 0 is Sunday.
      - `hour` (integer): The hour of the day, from 0 to 23.
      - `trades` (integer): The number of trades.
    - `streaks` (object): The trader's win and loss streaks over settled bets.
      - `current` (integer): The length of the current streak.
      - `currentKind` (string or null): Whether the current streak is wins or losses: `win` or `loss`.
      - `longestWin` (integer): The longest run of wins.
      - `longestLoss` (integer): The longest run of losses.
  - `similar` (object[]): Similar traders, when you ask for `include=similar`.
    - `ref` (trader ref): The trader's ref.
    - `name` (string or null): The trader's public name.
    - `profit` (number or null): The trader's profit in USD.

Rivo hides traders with a losing record from its lists, but you can still read them by ref. The API answers `NOT_FOUND` for a trader removed from the product.

## Errors

| Code | When |
| --- | --- |
| `VALIDATION` | `ref` is not a trader ref, or a parameter is unknown. |
| `NOT_FOUND` | No trader has that ref. |
| `QUOTA_EXCEEDED` | The includes would take the key past its per-minute limit. |