# List Positions

> Lists what winning traders hold right now on markets that are still trading, biggest first.

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

`GET /v2/positions`

Scope: `read`

This route returns the open positions of traders who have a winning record in that kind of market, on markets that are still trading. Each row covers one side of one market. It shows the biggest holder, the other holders, what they paid and what the side costs now.

Some venues do not name their traders. On those venues a row shows the side that large buys went to, and `lead` is `null`. Rivo refreshes prices from the market activity it already holds and rebuilds the list every few minutes.

Each holder on a row, `lead` and every one of `others`, counts as one trade toward your account's 5,000 trades a day.

## Example request

curl:

```bash
curl "https://api.rivo.markets/v2/positions?venue=kalshi&category=sports&limit=1" \
  -H "Authorization: Bearer rivo_live_..."
```

Python:

```python
import requests

url = "https://api.rivo.markets/v2/positions"
headers = {
    "Authorization": "Bearer rivo_live_...",
}
params = [
    ("venue", "kalshi"),
    ("category", "sports"),
    ("limit", "1"),
]

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

TypeScript:

```typescript
const params = new URLSearchParams([
  ["venue", "kalshi"],
  ["category", "sports"],
  ["limit", "1"],
]);

const res = await fetch(`https://api.rivo.markets/v2/positions?${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 positions this trader holds. 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`.
- `priceMin` (number, optional): Returns sides that trade at or above this price now, from 0 to 1. Rows with no recent price drop out.
- `priceMax` (number, optional): Returns sides that trade at or below this price now, from 0 to 1. Rows with no recent price drop out.
- `minUsd` (number, optional): Returns sides that hold at least this many dollars.
- `minTraders` (integer, optional): Returns sides that at least this many winning traders hold, from 1 to 100.
- `backed` (boolean, optional): Set to `true` to return only positions with a measured record of how bets like them paid. On those rows `record` is not `null`.
- `sort` (string, optional, default `size`): How to order the positions. `size` sorts by dollars held, `newest` puts the latest buy first, and `move` puts the biggest price move of the last hour first, in either direction.
- `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": [
    {
      "market": {
        "ref": "a2Fsc2hpOm1hcmtldDpLWE5GTE5GQ05PUlRILTI3LUNISQ",
        "contract": "a2Fsc2hpOm1hcmtldDpLWE5GTE5GQ05PUlRILTI3LUNISQ",
        "title": "Will Chicago win the Pro Football NFC North Division?",
        "venue": "kalshi",
        "category": "sports",
        "kind": "nfl"
      },
      "outcome": "Yes",
      "outcomeLabel": null,
      "entryPrice": 0.2005,
      "price": 0.2,
      "priceAt": "2026-10-15T02:28:27.319Z",
      "usd": 42770.17,
      "openedAt": "2026-10-04T08:40:39.804Z",
      "lastBoughtAt": "2026-10-12T05:13:29.103Z",
      "lead": {
        "ref": "kalshi:avidsmores",
        "name": "avidsmores",
        "winRate": 0.6973,
        "profit": 15681.48,
        "settled": 935,
        "usd": 42770.17,
        "entryPrice": 0.2005
      },
      "others": [],
      "split": { "sameSideUsd": 42770.17, "otherSideUsd": 0, "otherSideTraders": 0 },
      "activity": null,
      "record": null
    }
  ],
  "nextCursor": "eyJvIjoxfQ"
}
```

## Response fields

- `data` (object[]): The positions on this page.
  - `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 traders hold: `Yes`, `No`, or a named outcome.
  - `outcomeLabel` (string or null): The name the market gives this side, when `Yes` or `No` alone says too little.
  - `entryPrice` (number or null): The average price every holder paid, from 0 to 1. Rivo divides their dollars by their contracts.
  - `price` (number or null): The price the side trades at now. It is `null` when nothing traded recently.
  - `priceAt` (string or null): When Rivo read `price`, in ISO 8601 UTC.
  - `usd` (number): The dollars on this side. On a venue that does not name its traders, this is the sum of the large buys.
  - `openedAt` (string): When the first buy happened, in ISO 8601 UTC.
  - `lastBoughtAt` (string): When the latest buy happened, in ISO 8601 UTC.
  - `lead` (object or null): The biggest holder, with their record in this kind of market. It is `null` on a venue that does not name its traders.
    - `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`.
    - `usd` (number): The dollars this trader has put on this side.
    - `entryPrice` (number or null): The average price this trader paid, from 0 to 1.
  - `others` (object[]): The other winning holders. Each has the same fields as `lead`.
    - `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`.
    - `usd` (number): The dollars this trader has put on this side.
    - `entryPrice` (number or null): The average price this trader paid, from 0 to 1.
  - `split` (object): How the winning traders' money splits between this side and the other sides of the market.
    - `sameSideUsd` (number): The dollars on this side.
    - `otherSideUsd` (number): The dollars on the other sides.
    - `otherSideTraders` (integer): The number of winning traders on the other sides.
  - `activity` (object or null): What this side did over the last hour. It is `null` when Rivo has no reading for the hour.
    - `move1h` (number or null): The price change over the hour.
    - `volume1h` (number or null): The dollars traded over the hour.
  - `record` (object or null): How settled bets like this one did at this price. It is `null` when Rivo has no measured record.
    - `settled` (integer): The number of settled bets in the record.
    - `winRate` (number): The share of those bets that won, from 0 to 1.
    - `maxPrice` (number): The highest price at which the record says this bet was worth buying, from 0 to 1.
- `nextCursor` (string or null): Pass this as `cursor` to read the next page. It is `null` on the last page.

The cursor marks a place in the sorted list. If Rivo rebuilds the list between two pages, a row can shift by one place.

## Errors

| Code | When |
| --- | --- |
| `VALIDATION` | A parameter is out of range or unknown. You sent `outcome` without exactly one `market`. Or the cursor came from another listing. |