GET/v2/positionsread scope

List Positions

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

GET /v2/positions

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

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

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

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
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.
kindstring
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. To pass several values, repeat the key, up to 50 times. A row matches if it matches any of them.
tradertrader ref
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.
marketmarket ref
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.
outcomestring
Returns rows for one side of the market. Pass the side's name (Yes, No, Lakers, Up) or its label from Get Market, such as Milwaukee. The match ignores case. You must also pass exactly one market.
priceMinnumber
Returns sides that trade at or above this price now, from 0 to 1. Rows with no recent price drop out.
priceMaxnumber
Returns sides that trade at or below this price now, from 0 to 1. Rows with no recent price drop out.
minUsdnumber
Returns sides that hold at least this many dollars.
minTradersinteger
Returns sides that at least this many winning traders hold, from 1 to 100.
backedboolean
Set to true to return only positions with a measured record of how bets like them paid. On those rows record is not null.
sortstringdefault 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.
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": [
    {
      "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

dataobject[]
The positions on this page.
Show 14 data fields
- marketobject
  The market this row is about.
  Show 6 market fields
  - refmarket ref
    The market's ref. You can pass it to any market filter or to Get Market. On a market of several outcomes, it names the whole event.
  - contractmarket 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 or a market bot.
  - titlestring
    The market's title, as the venue writes it.
  - venuestring
    The venue that lists the market: one of kalshi, polymarket, polymarket_us or gemini.
  - categorystring or null
    The market's category: one of sports, politics, crypto, finance, culture. It is null when Rivo has not classified the market.
  - kindstring or null
    The kind of market, such as nfl or bitcoin. It is null when Rivo has not classified the market yet.
- outcomestring
  The side the traders hold: Yes, No, or a named outcome.
- outcomeLabelstring or null
  The name the market gives this side, when Yes or No alone says too little.
- entryPricenumber or null
  The average price every holder paid, from 0 to 1. Rivo divides their dollars by their contracts.
- pricenumber or null
  The price the side trades at now. It is null when nothing traded recently.
- priceAtstring or null
  When Rivo read price, in ISO 8601 UTC.
- usdnumber
  The dollars on this side. On a venue that does not name its traders, this is the sum of the large buys.
- openedAtstring
  When the first buy happened, in ISO 8601 UTC.
- lastBoughtAtstring
  When the latest buy happened, in ISO 8601 UTC.
- leadobject 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.
  Show 7 lead fields
  - reftrader ref
    The trader's ref. You can pass it to any trader filter or to Get Trader.
  - namestring or null
    The trader's public name, or null when they have none. The API never returns a wallet address as a name.
  - winRatenumber 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.
  - profitnumber or null
    The trader's profit in USD, over the same bets as winRate.
  - settledinteger
    The number of settled bets behind winRate and profit.
  - usdnumber
    The dollars this trader has put on this side.
  - entryPricenumber or null
    The average price this trader paid, from 0 to 1.
- othersobject[]
  The other winning holders. Each has the same fields as lead.
  Show 7 others fields
  - reftrader ref
    The trader's ref. You can pass it to any trader filter or to Get Trader.
  - namestring or null
    The trader's public name, or null when they have none. The API never returns a wallet address as a name.
  - winRatenumber 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.
  - profitnumber or null
    The trader's profit in USD, over the same bets as winRate.
  - settledinteger
    The number of settled bets behind winRate and profit.
  - usdnumber
    The dollars this trader has put on this side.
  - entryPricenumber or null
    The average price this trader paid, from 0 to 1.
- splitobject
  How the winning traders' money splits between this side and the other sides of the market.
  Show 3 split fields
  - sameSideUsdnumber
    The dollars on this side.
  - otherSideUsdnumber
    The dollars on the other sides.
  - otherSideTradersinteger
    The number of winning traders on the other sides.
- activityobject or null
  What this side did over the last hour. It is null when Rivo has no reading for the hour.
  Show 2 activity fields
  - move1hnumber or null
    The price change over the hour.
  - volume1hnumber or null
    The dollars traded over the hour.
- recordobject or null
  How settled bets like this one did at this price. It is null when Rivo has no measured record.
  Show 3 record fields
  - settledinteger
    The number of settled bets in the record.
  - winRatenumber
    The share of those bets that won, from 0 to 1.
  - maxPricenumber
    The highest price at which the record says this bet was worth buying, from 0 to 1.
nextCursorstring 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.

Example request

GET /v2/positions

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

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

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

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

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.

kindstring

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. To pass several values, repeat the key, up to 50 times. A row matches if it matches any of them.

tradertrader ref

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.

marketmarket ref

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.

outcomestring

Returns rows for one side of the market. Pass the side's name (Yes, No, Lakers, Up) or its label from Get Market, such as Milwaukee. The match ignores case. You must also pass exactly one market.

priceMinnumber

Returns sides that trade at or above this price now, from 0 to 1. Rows with no recent price drop out.

priceMaxnumber

Returns sides that trade at or below this price now, from 0 to 1. Rows with no recent price drop out.

minUsdnumber

Returns sides that hold at least this many dollars.

minTradersinteger

Returns sides that at least this many winning traders hold, from 1 to 100.

backedboolean

Set to true to return only positions with a measured record of how bets like them paid. On those rows record is not null.

sortstringdefault 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.

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": [
    {
      "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

dataobject[]

The positions on this page.

Show 14 data fields

marketobject
The market this row is about.
Show 6 market fields
- refmarket ref
  The market's ref. You can pass it to any market filter or to Get Market. On a market of several outcomes, it names the whole event.
- contractmarket 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 or a market bot.
- titlestring
  The market's title, as the venue writes it.
- venuestring
  The venue that lists the market: one of kalshi, polymarket, polymarket_us or gemini.
- categorystring or null
  The market's category: one of sports, politics, crypto, finance, culture. It is null when Rivo has not classified the market.
- kindstring or null
  The kind of market, such as nfl or bitcoin. It is null when Rivo has not classified the market yet.
outcomestring
The side the traders hold: Yes, No, or a named outcome.
outcomeLabelstring or null
The name the market gives this side, when Yes or No alone says too little.
entryPricenumber or null
The average price every holder paid, from 0 to 1. Rivo divides their dollars by their contracts.
pricenumber or null
The price the side trades at now. It is null when nothing traded recently.
priceAtstring or null
When Rivo read price, in ISO 8601 UTC.
usdnumber
The dollars on this side. On a venue that does not name its traders, this is the sum of the large buys.
openedAtstring
When the first buy happened, in ISO 8601 UTC.
lastBoughtAtstring
When the latest buy happened, in ISO 8601 UTC.
leadobject 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.
Show 7 lead fields
- reftrader ref
  The trader's ref. You can pass it to any trader filter or to Get Trader.
- namestring or null
  The trader's public name, or null when they have none. The API never returns a wallet address as a name.
- winRatenumber 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.
- profitnumber or null
  The trader's profit in USD, over the same bets as winRate.
- settledinteger
  The number of settled bets behind winRate and profit.
- usdnumber
  The dollars this trader has put on this side.
- entryPricenumber or null
  The average price this trader paid, from 0 to 1.
othersobject[]
The other winning holders. Each has the same fields as lead.
Show 7 others fields
- reftrader ref
  The trader's ref. You can pass it to any trader filter or to Get Trader.
- namestring or null
  The trader's public name, or null when they have none. The API never returns a wallet address as a name.
- winRatenumber 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.
- profitnumber or null
  The trader's profit in USD, over the same bets as winRate.
- settledinteger
  The number of settled bets behind winRate and profit.
- usdnumber
  The dollars this trader has put on this side.
- entryPricenumber or null
  The average price this trader paid, from 0 to 1.
splitobject
How the winning traders' money splits between this side and the other sides of the market.
Show 3 split fields
- sameSideUsdnumber
  The dollars on this side.
- otherSideUsdnumber
  The dollars on the other sides.
- otherSideTradersinteger
  The number of winning traders on the other sides.
activityobject or null
What this side did over the last hour. It is null when Rivo has no reading for the hour.
Show 2 activity fields
- move1hnumber or null
  The price change over the hour.
- volume1hnumber or null
  The dollars traded over the hour.
recordobject or null
How settled bets like this one did at this price. It is null when Rivo has no measured record.
Show 3 record fields
- settledinteger
  The number of settled bets in the record.
- winRatenumber
  The share of those bets that won, from 0 to 1.
- maxPricenumber
  The highest price at which the record says this bet was worth buying, from 0 to 1.

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. You sent outcome without exactly one market. Or the cursor came from another listing.