GET/v2/markets/{ref}read scope

Get Market

This route returns one market with its status, its rule, and every outcome's price, bid and ask. For a market with several contracts, it lists both sides of each contract, and each side carries its contract's own ref.

include adds extra sections to the response. Each include counts as a request of its own against your 120 requests a minute, so ?include=book,whales uses 3. trades also counts its rows against the 50,000 trades a day.

include	Adds
`book`	Adds the bids and asks for each side, up to 20 levels. Rivo reads them from the venue and caches them for 5 seconds. It works on a single contract only and returns `null` for a market with several contracts.
`whales`	Adds the whale dollars on each side and lists each whale on the market. For each whale it shows what they bought and sold, their prices, their record and whether they still hold.
`call`	Adds the side with the most behind it, with a headline and up to four reasons. It is `null` when there is no call, or when the call was not ready within half a second. In that case, ask again shortly.
`history`	Adds the price and volume over `range`. For a repeating market it also adds the last 15 windows and how often each side won them. It works on a single contract only.
`trades`	Adds the newest 40 whale buys on the market, with the same fields as a List Trades row.

To trade one side on paper, call Place Paper Order. Pass the outcome's ref as market and its name as outcome.

Example request

GET /v2/markets/{ref}

curl "https://api.rivo.markets/v2/markets/a2Fsc2hpOm1hcmtldDpLWE1MQkdBTUUtMjZPQ1QxNDIwMDBNSUxMQUQtTUlM?include=book%2Cwhales%2Ccall%2Chistory%2Ctrades" \
  -H "Authorization: Bearer rivo_live_..."

import requests

url = "https://api.rivo.markets/v2/markets/a2Fsc2hpOm1hcmtldDpLWE1MQkdBTUUtMjZPQ1QxNDIwMDBNSUxMQUQtTUlM"
headers = {
    "Authorization": "Bearer rivo_live_...",
}
params = [
    ("include", "book,whales,call,history,trades"),
]

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

const params = new URLSearchParams([
  ["include", "book,whales,call,history,trades"],
]);

const res = await fetch(`https://api.rivo.markets/v2/markets/a2Fsc2hpOm1hcmtldDpLWE1MQkdBTUUtMjZPQ1QxNDIwMDBNSUxMQUQtTUlM?${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

refmarket refrequired
The market's ref. You can take it from any row that names the market.

Query parameters

includestring
The extra sections to add: book, whales, call, history or trades. Separate them with commas, or repeat the key.
rangestringdefault 1d
The period that include=history covers: 1h, 1d or 7d.

Example response

Response

{
  "data": {
    "ref": "a2Fsc2hpOm1hcmtldDpLWE1MQkdBTUUtMjZPQ1QxNDIwMDBNSUxMQUQtTUlM",
    "title": "Milwaukee wins",
    "venue": "kalshi",
    "category": "sports",
    "kind": "mlb",
    "status": "open",
    "result": null,
    "settledAt": null,
    "rule": "If Milwaukee wins the Milwaukee vs Los Angeles D professional baseball game originally scheduled for Oct 14, 2026, then the market resolves to Yes.",
    "outcomes": [
      {
        "ref": "a2Fsc2hpOm1hcmtldDpLWE1MQkdBTUUtMjZPQ1QxNDIwMDBNSUxMQUQtTUlM",
        "contract": "Milwaukee wins",
        "name": "Yes",
        "label": "Milwaukee",
        "price": 0.87,
        "bid": 0.86,
        "ask": 0.87
      },
      {
        "ref": "a2Fsc2hpOm1hcmtldDpLWE1MQkdBTUUtMjZPQ1QxNDIwMDBNSUxMQUQtTUlM",
        "contract": "Milwaukee wins",
        "name": "No",
        "label": "Not Milwaukee",
        "price": 0.13,
        "bid": 0.13,
        "ask": 0.14
      }
    ],
    "otherVenues": [],
    "book": [
      {
        "outcome": "Yes",
        "bids": [
          { "price": 0.86, "size": 194965.3 },
          { "price": 0.85, "size": 262306.1 }
        ],
        "asks": [
          { "price": 0.87, "size": 163419.21 },
          { "price": 0.88, "size": 111676.84 }
        ]
      },
      {
        "outcome": "No",
        "bids": [
          { "price": 0.13, "size": 163419.21 },
          { "price": 0.12, "size": 111676.84 }
        ],
        "asks": [
          { "price": 0.14, "size": 194965.3 },
          { "price": 0.15, "size": 262306.1 }
        ]
      }
    ],
    "whales": {
      "sides": [
        { "outcome": "Yes", "usd": 77068.91, "trades": 28 }
      ],
      "traders": [
        {
          "ref": "kalshi:pentasir",
          "name": "pentasir",
          "winRate": 0.7791,
          "profit": 10958.34,
          "settled": 163,
          "outcome": "Yes",
          "boughtUsd": 9835.02,
          "soldUsd": 0,
          "entryPrice": 0.39,
          "exitPrice": null,
          "status": "holding",
          "lastTradeAt": "2026-10-14T22:49:09.451Z"
        }
      ]
    },
    "call": null,
    "history": {
      "range": "1d",
      "prices": [
        { "time": "2026-10-14T03:00:00.000Z", "price": 0.38, "volume": 8804.29 },
        { "time": "2026-10-14T04:00:00.000Z", "price": 0.39, "volume": 25974.21 }
      ],
      "series": null
    },
    "trades": [
      {
        "id": "1ce3724a-941e-5b4a-8e84-f2e50ae89bb8",
        "time": "2026-10-15T02:24:53.011Z",
        "market": {
          "ref": "a2Fsc2hpOm1hcmtldDpLWE1MQkdBTUUtMjZPQ1QxNDIwMDBNSUxMQUQtTUlM",
          "contract": "a2Fsc2hpOm1hcmtldDpLWE1MQkdBTUUtMjZPQ1QxNDIwMDBNSUxMQUQtTUlM",
          "title": "Milwaukee wins",
          "venue": "kalshi",
          "category": "sports",
          "kind": "mlb"
        },
        "outcome": "Yes",
        "action": "buy",
        "entry": null,
        "price": 0.88,
        "usd": 7933.36,
        "contracts": 9015.18,
        "trader": {
          "ref": "kalshi:scottramirez",
          "name": "scottramirez",
          "winRate": 0.8269,
          "profit": 5122.43,
          "settled": 52
        },
        "agreement": {
          "sameSide": { "trades": 37, "usd": 95502.12 },
          "otherSide": { "trades": 0, "usd": 0 }
        },
        "result": "open",
        "profit": null
      }
    ]
  }
}

Response fields

dataobject
The market you asked for.
Show 17 data 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.
- statusstring
  The market's status: open, closed, settled or void. closed means trading has stopped but no result is in yet.
- resultstring or null
  The name of the outcome that won. It is null until the market settles, and when it is void.
- settledAtstring or null
  When the market settled, in ISO 8601 UTC.
- rulestring or null
  How the venue settles the market, in the venue's own words.
- outcomesobject[]
  Both sides of each contract in the market.
  Show 7 outcomes fields
  - refmarket ref
    The contract this side trades on. Pass it as market to a paper order or a market bot.
  - contractstring
    The contract's own title. On a market with several contracts, it tells you which contract this side belongs to.
  - namestring
    The side's name, the same name trades, whales and positions use. On Polymarket it is the outcome's own name. On every other venue it is Yes or No. Pass it as outcome to a paper order.
  - labelstring
    What the venue calls the side, such as Milwaukee or Not Milwaukee. Every route that takes an outcome accepts the label too.
  - pricenumber or null
    The side's price now, from 0 to 1.
  - bidnumber or null
    The best bid, from 0 to 1. It is null when the venue has no book.
  - asknumber or null
    The best ask, from 0 to 1. It is null when the venue has no book.
- otherVenuesobject[]
  The same outcome on other venues. Rivo pairs only some markets across venues, and this list is empty for every other market.
  Show 2 otherVenues fields
  - venuestring
    The other venue that lists this outcome.
  - refmarket ref
    The contract on that venue.
- bookobject[] or null
  The order book, when you ask for include=book. Each side lists its best price first.
  Show 3 book fields
  - outcomestring
    The side this entry is about.
  - bidsobject[]
    The bids, with the best first.
    Show 2 bids fields
    pricenumber
    The price at this level, from 0 to 1.
    sizenumber
    The number of contracts offered at this price.
  - asksobject[]
    The asks, with the best first.
    Show 2 asks fields
    pricenumber
    The price at this level, from 0 to 1.
    sizenumber
    The number of contracts offered at this price.
- whalesobject
  The whales, when you ask for include=whales. It covers the last 30 days on a single contract and the last 24 hours on a market with several contracts.
  Show 2 whales fields
  - sidesobject[]
    The whale buys on each side.
    Show 3 sides fields
    outcomestring
    The side this entry is about.
    usdnumber
    The dollars whales spent buying this side.
    tradesinteger
    The number of whale buys on this side.
  - tradersobject[]
    One row for each named whale on each side, with the biggest buyers first.
    Show 12 traders 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.
    outcomestring
    The side this whale bought.
    boughtUsdnumber
    The dollars this whale spent buying.
    soldUsdnumber
    The dollars this whale received from selling.
    entryPricenumber or null
    The average price this whale paid.
    exitPricenumber or null
    The average price this whale sold at.
    statusstring
    Whether the whale still holds: holding, reduced or exited.
    lastTradeAtstring
    When this whale last traded this market, in ISO 8601 UTC.
- callobject or null
  The call, when you ask for include=call.
  Show 7 call fields
  - outcomestring or null
    The side with the most money and the strongest records behind it.
  - actionstring
    What the call suggests: buy or watch.
  - headlinestring
    The call, in one line.
  - detailstring
    One sentence that explains the call.
  - pricenumber or null
    The side's price now, from 0 to 1.
  - maxPricenumber or null
    The highest price worth paying, when a measured record supports one.
  - reasonsstring[]
    Up to four reasons behind the call.
- historyobject or null
  The price history, when you ask for include=history.
  Show 3 history fields
  - rangestring
    The period the history covers: 1h, 1d or 7d.
  - pricesobject[]
    The data points, oldest first.
    Show 3 prices fields
    timestring
    The time of this point, in ISO 8601 UTC.
    pricenumber
    The Yes price at this point.
    volumenumber
    The dollars traded in this interval.
  - seriesobject or null
    The past windows. Only repeating markets have them.
    Show 3 series fields
    windowsobject[]
    The last 15 windows, with the newest first.
    Show 3 windows fields
    opensAtstring
    When the window opened, in ISO 8601 UTC.
    closesAtstring
    When the window closed, in ISO 8601 UTC.
    resultstring
    The side that won the window: yes or no.
    yesWoninteger
    The number of windows that Yes won.
    noWoninteger
    The number of windows that No won.
- tradesobject[]
  The newest 40 whale buys, when you ask for include=trades.
  Show 13 trades fields
  - idstring
    The trade's id. It never changes, so the same trade has the same id in every listing and on the stream.
  - timestring
    When the trade happened on the venue, in ISO 8601 UTC.
  - 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 trader bought or sold, by its name. On Polymarket it is the outcome's own name, such as Lakers. On every other venue it is Yes or No.
  - actionstring
    Whether the trader bought or sold: buy or sell.
  - entrystring or null
    What the trade did to the trader's position: open, add, flip, trim or close. It is null when the venue does not say.
  - pricenumber or null
    The price paid for each contract, from 0 to 1.
  - usdnumber or null
    The dollars traded.
  - contractsnumber or null
    The number of contracts traded.
  - traderobject or null
    The trader who made the trade, with their record in this kind of market, or their whole record when Rivo has none for that kind. Only kalshi or polymarket name their traders. On every other venue this is null.
    Show 5 trader 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.
  - agreementobject
    The other whale trades on this market in the 24 hours before this one.
    Show 2 agreement fields
    sameSideobject
    Trades that bought the same side.
    Show 2 sameSide fields
    tradesinteger
    The number of whale trades.
    usdnumber
    The dollars those trades spent.
    otherSideobject
    Trades that bought the other side.
    Show 2 otherSide fields
    tradesinteger
    The number of whale trades.
    usdnumber
    The dollars those trades spent.
  - resultstring
    The trade's result. It is open until the market settles, then win, loss or void.
  - profitnumber or null
    What the trade made in USD, if held to settlement at the price paid. It is null while the market is open.

When you do not ask for an include, the response leaves out the fields that include would add.

Errors

Code	When
`VALIDATION`	`ref` is not a market ref, or a parameter is unknown or out of range.
`NOT_FOUND`	No market has that ref.
`QUOTA_EXCEEDED`	The includes would take the key past its per-minute limit, or you asked for `include=trades` after using up today's trade allowance.

include

Adds

book

Adds the bids and asks for each side, up to 20 levels. Rivo reads them from the venue and caches them for 5 seconds. It works on a single contract only and returns null for a market with several contracts.

whales

Adds the whale dollars on each side and lists each whale on the market. For each whale it shows what they bought and sold, their prices, their record and whether they still hold.

call

Adds the side with the most behind it, with a headline and up to four reasons. It is null when there is no call, or when the call was not ready within half a second. In that case, ask again shortly.

history

Adds the price and volume over range. For a repeating market it also adds the last 15 windows and how often each side won them. It works on a single contract only.

trades

Adds the newest 40 whale buys on the market, with the same fields as a List Trades row.

Example request

GET /v2/markets/{ref}

curl "https://api.rivo.markets/v2/markets/a2Fsc2hpOm1hcmtldDpLWE1MQkdBTUUtMjZPQ1QxNDIwMDBNSUxMQUQtTUlM?include=book%2Cwhales%2Ccall%2Chistory%2Ctrades" \
  -H "Authorization: Bearer rivo_live_..."

import requests

url = "https://api.rivo.markets/v2/markets/a2Fsc2hpOm1hcmtldDpLWE1MQkdBTUUtMjZPQ1QxNDIwMDBNSUxMQUQtTUlM"
headers = {
    "Authorization": "Bearer rivo_live_...",
}
params = [
    ("include", "book,whales,call,history,trades"),
]

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

const params = new URLSearchParams([
  ["include", "book,whales,call,history,trades"],
]);

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

Example response

Response

{
  "data": {
    "ref": "a2Fsc2hpOm1hcmtldDpLWE1MQkdBTUUtMjZPQ1QxNDIwMDBNSUxMQUQtTUlM",
    "title": "Milwaukee wins",
    "venue": "kalshi",
    "category": "sports",
    "kind": "mlb",
    "status": "open",
    "result": null,
    "settledAt": null,
    "rule": "If Milwaukee wins the Milwaukee vs Los Angeles D professional baseball game originally scheduled for Oct 14, 2026, then the market resolves to Yes.",
    "outcomes": [
      {
        "ref": "a2Fsc2hpOm1hcmtldDpLWE1MQkdBTUUtMjZPQ1QxNDIwMDBNSUxMQUQtTUlM",
        "contract": "Milwaukee wins",
        "name": "Yes",
        "label": "Milwaukee",
        "price": 0.87,
        "bid": 0.86,
        "ask": 0.87
      },
      {
        "ref": "a2Fsc2hpOm1hcmtldDpLWE1MQkdBTUUtMjZPQ1QxNDIwMDBNSUxMQUQtTUlM",
        "contract": "Milwaukee wins",
        "name": "No",
        "label": "Not Milwaukee",
        "price": 0.13,
        "bid": 0.13,
        "ask": 0.14
      }
    ],
    "otherVenues": [],
    "book": [
      {
        "outcome": "Yes",
        "bids": [
          { "price": 0.86, "size": 194965.3 },
          { "price": 0.85, "size": 262306.1 }
        ],
        "asks": [
          { "price": 0.87, "size": 163419.21 },
          { "price": 0.88, "size": 111676.84 }
        ]
      },
      {
        "outcome": "No",
        "bids": [
          { "price": 0.13, "size": 163419.21 },
          { "price": 0.12, "size": 111676.84 }
        ],
        "asks": [
          { "price": 0.14, "size": 194965.3 },
          { "price": 0.15, "size": 262306.1 }
        ]
      }
    ],
    "whales": {
      "sides": [
        { "outcome": "Yes", "usd": 77068.91, "trades": 28 }
      ],
      "traders": [
        {
          "ref": "kalshi:pentasir",
          "name": "pentasir",
          "winRate": 0.7791,
          "profit": 10958.34,
          "settled": 163,
          "outcome": "Yes",
          "boughtUsd": 9835.02,
          "soldUsd": 0,
          "entryPrice": 0.39,
          "exitPrice": null,
          "status": "holding",
          "lastTradeAt": "2026-10-14T22:49:09.451Z"
        }
      ]
    },
    "call": null,
    "history": {
      "range": "1d",
      "prices": [
        { "time": "2026-10-14T03:00:00.000Z", "price": 0.38, "volume": 8804.29 },
        { "time": "2026-10-14T04:00:00.000Z", "price": 0.39, "volume": 25974.21 }
      ],
      "series": null
    },
    "trades": [
      {
        "id": "1ce3724a-941e-5b4a-8e84-f2e50ae89bb8",
        "time": "2026-10-15T02:24:53.011Z",
        "market": {
          "ref": "a2Fsc2hpOm1hcmtldDpLWE1MQkdBTUUtMjZPQ1QxNDIwMDBNSUxMQUQtTUlM",
          "contract": "a2Fsc2hpOm1hcmtldDpLWE1MQkdBTUUtMjZPQ1QxNDIwMDBNSUxMQUQtTUlM",
          "title": "Milwaukee wins",
          "venue": "kalshi",
          "category": "sports",
          "kind": "mlb"
        },
        "outcome": "Yes",
        "action": "buy",
        "entry": null,
        "price": 0.88,
        "usd": 7933.36,
        "contracts": 9015.18,
        "trader": {
          "ref": "kalshi:scottramirez",
          "name": "scottramirez",
          "winRate": 0.8269,
          "profit": 5122.43,
          "settled": 52
        },
        "agreement": {
          "sameSide": { "trades": 37, "usd": 95502.12 },
          "otherSide": { "trades": 0, "usd": 0 }
        },
        "result": "open",
        "profit": null
      }
    ]
  }
}

Response fields

dataobject

The market you asked for.

Show 17 data 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.
statusstring
The market's status: open, closed, settled or void. closed means trading has stopped but no result is in yet.
resultstring or null
The name of the outcome that won. It is null until the market settles, and when it is void.
settledAtstring or null
When the market settled, in ISO 8601 UTC.
rulestring or null
How the venue settles the market, in the venue's own words.
outcomesobject[]
Both sides of each contract in the market.
Show 7 outcomes fields
- refmarket ref
  The contract this side trades on. Pass it as market to a paper order or a market bot.
- contractstring
  The contract's own title. On a market with several contracts, it tells you which contract this side belongs to.
- namestring
  The side's name, the same name trades, whales and positions use. On Polymarket it is the outcome's own name. On every other venue it is Yes or No. Pass it as outcome to a paper order.
- labelstring
  What the venue calls the side, such as Milwaukee or Not Milwaukee. Every route that takes an outcome accepts the label too.
- pricenumber or null
  The side's price now, from 0 to 1.
- bidnumber or null
  The best bid, from 0 to 1. It is null when the venue has no book.
- asknumber or null
  The best ask, from 0 to 1. It is null when the venue has no book.
otherVenuesobject[]
The same outcome on other venues. Rivo pairs only some markets across venues, and this list is empty for every other market.
Show 2 otherVenues fields
- venuestring
  The other venue that lists this outcome.
- refmarket ref
  The contract on that venue.
bookobject[] or null
The order book, when you ask for include=book. Each side lists its best price first.
Show 3 book fields
- outcomestring
  The side this entry is about.
- bidsobject[]
  The bids, with the best first.
  Show 2 bids fields
  - pricenumber
    The price at this level, from 0 to 1.
  - sizenumber
    The number of contracts offered at this price.
- asksobject[]
  The asks, with the best first.
  Show 2 asks fields
  - pricenumber
    The price at this level, from 0 to 1.
  - sizenumber
    The number of contracts offered at this price.
whalesobject
The whales, when you ask for include=whales. It covers the last 30 days on a single contract and the last 24 hours on a market with several contracts.
Show 2 whales fields
- sidesobject[]
  The whale buys on each side.
  Show 3 sides fields
  - outcomestring
    The side this entry is about.
  - usdnumber
    The dollars whales spent buying this side.
  - tradesinteger
    The number of whale buys on this side.
- tradersobject[]
  One row for each named whale on each side, with the biggest buyers first.
  Show 12 traders 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.
  - outcomestring
    The side this whale bought.
  - boughtUsdnumber
    The dollars this whale spent buying.
  - soldUsdnumber
    The dollars this whale received from selling.
  - entryPricenumber or null
    The average price this whale paid.
  - exitPricenumber or null
    The average price this whale sold at.
  - statusstring
    Whether the whale still holds: holding, reduced or exited.
  - lastTradeAtstring
    When this whale last traded this market, in ISO 8601 UTC.
callobject or null
The call, when you ask for include=call.
Show 7 call fields
- outcomestring or null
  The side with the most money and the strongest records behind it.
- actionstring
  What the call suggests: buy or watch.
- headlinestring
  The call, in one line.
- detailstring
  One sentence that explains the call.
- pricenumber or null
  The side's price now, from 0 to 1.
- maxPricenumber or null
  The highest price worth paying, when a measured record supports one.
- reasonsstring[]
  Up to four reasons behind the call.
historyobject or null
The price history, when you ask for include=history.
Show 3 history fields
- rangestring
  The period the history covers: 1h, 1d or 7d.
- pricesobject[]
  The data points, oldest first.
  Show 3 prices fields
  - timestring
    The time of this point, in ISO 8601 UTC.
  - pricenumber
    The Yes price at this point.
  - volumenumber
    The dollars traded in this interval.
- seriesobject or null
  The past windows. Only repeating markets have them.
  Show 3 series fields
  - windowsobject[]
    The last 15 windows, with the newest first.
    Show 3 windows fields
    opensAtstring
    When the window opened, in ISO 8601 UTC.
    closesAtstring
    When the window closed, in ISO 8601 UTC.
    resultstring
    The side that won the window: yes or no.
  - yesWoninteger
    The number of windows that Yes won.
  - noWoninteger
    The number of windows that No won.
tradesobject[]
The newest 40 whale buys, when you ask for include=trades.
Show 13 trades fields
- idstring
  The trade's id. It never changes, so the same trade has the same id in every listing and on the stream.
- timestring
  When the trade happened on the venue, in ISO 8601 UTC.
- 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 trader bought or sold, by its name. On Polymarket it is the outcome's own name, such as Lakers. On every other venue it is Yes or No.
- actionstring
  Whether the trader bought or sold: buy or sell.
- entrystring or null
  What the trade did to the trader's position: open, add, flip, trim or close. It is null when the venue does not say.
- pricenumber or null
  The price paid for each contract, from 0 to 1.
- usdnumber or null
  The dollars traded.
- contractsnumber or null
  The number of contracts traded.
- traderobject or null
  The trader who made the trade, with their record in this kind of market, or their whole record when Rivo has none for that kind. Only kalshi or polymarket name their traders. On every other venue this is null.
  Show 5 trader 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.
- agreementobject
  The other whale trades on this market in the 24 hours before this one.
  Show 2 agreement fields
  - sameSideobject
    Trades that bought the same side.
    Show 2 sameSide fields
    tradesinteger
    The number of whale trades.
    usdnumber
    The dollars those trades spent.
  - otherSideobject
    Trades that bought the other side.
    Show 2 otherSide fields
    tradesinteger
    The number of whale trades.
    usdnumber
    The dollars those trades spent.
- resultstring
  The trade's result. It is open until the market settles, then win, loss or void.
- profitnumber or null
  What the trade made in USD, if held to settlement at the price paid. It is null while the market is open.

Code

When

VALIDATION

ref is not a market ref, or a parameter is unknown or out of range.

NOT_FOUND

No market has that ref.

QUOTA_EXCEEDED

The includes would take the key past its per-minute limit, or you asked for include=trades after using up today's trade allowance.