# Get Market

> Reads one market with every outcome's price, bid and ask. On request it adds the order book, the whales, the price history and the newest whale trades.

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

`GET /v2/markets/{ref}`

Scope: `read`

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](https://rivo.markets/docs/reference/list-trades) row. |

To trade one side on paper, call [Place Paper Order](https://rivo.markets/docs/reference/place-paper-order). Pass the outcome's `ref` as `market` and its `name` as `outcome`.

## Example request

curl:

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

Python:

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

TypeScript:

```typescript
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

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

## Query parameters

- `include` (string, optional): The extra sections to add: `book`, `whales`, `call`, `history` or `trades`. Separate them with commas, or repeat the key.
- `range` (string, optional, default `1d`): The period that `include=history` covers: `1h`, `1d` or `7d`.

## Example response

```json
{
  "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

- `data` (object): The market you asked for.
  - `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.
  - `status` (string): The market's status: `open`, `closed`, `settled` or `void`. `closed` means trading has stopped but no result is in yet.
  - `result` (string or null): The name of the outcome that won. It is `null` until the market settles, and when it is void.
  - `settledAt` (string or null): When the market settled, in ISO 8601 UTC.
  - `rule` (string or null): How the venue settles the market, in the venue's own words.
  - `outcomes` (object[]): Both sides of each contract in the market.
    - `ref` (market ref): The contract this side trades on. Pass it as `market` to a paper order or a market bot.
    - `contract` (string): The contract's own title. On a market with several contracts, it tells you which contract this side belongs to.
    - `name` (string): 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.
    - `label` (string): What the venue calls the side, such as `Milwaukee` or `Not Milwaukee`. Every route that takes an `outcome` accepts the label too.
    - `price` (number or null): The side's price now, from 0 to 1.
    - `bid` (number or null): The best bid, from 0 to 1. It is `null` when the venue has no book.
    - `ask` (number or null): The best ask, from 0 to 1. It is `null` when the venue has no book.
  - `otherVenues` (object[]): The same outcome on other venues. Rivo pairs only some markets across venues, and this list is empty for every other market.
    - `venue` (string): The other venue that lists this outcome.
    - `ref` (market ref): The contract on that venue.
  - `book` (object[] or null): The order book, when you ask for `include=book`. Each side lists its best price first.
    - `outcome` (string): The side this entry is about.
    - `bids` (object[]): The bids, with the best first.
      - `price` (number): The price at this level, from 0 to 1.
      - `size` (number): The number of contracts offered at this price.
    - `asks` (object[]): The asks, with the best first.
      - `price` (number): The price at this level, from 0 to 1.
      - `size` (number): The number of contracts offered at this price.
  - `whales` (object): 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.
    - `sides` (object[]): The whale buys on each side.
      - `outcome` (string): The side this entry is about.
      - `usd` (number): The dollars whales spent buying this side.
      - `trades` (integer): The number of whale buys on this side.
    - `traders` (object[]): One row for each named whale on each side, with the biggest buyers first.
      - `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`.
      - `outcome` (string): The side this whale bought.
      - `boughtUsd` (number): The dollars this whale spent buying.
      - `soldUsd` (number): The dollars this whale received from selling.
      - `entryPrice` (number or null): The average price this whale paid.
      - `exitPrice` (number or null): The average price this whale sold at.
      - `status` (string): Whether the whale still holds: `holding`, `reduced` or `exited`.
      - `lastTradeAt` (string): When this whale last traded this market, in ISO 8601 UTC.
  - `call` (object or null): The call, when you ask for `include=call`.
    - `outcome` (string or null): The side with the most money and the strongest records behind it.
    - `action` (string): What the call suggests: `buy` or `watch`.
    - `headline` (string): The call, in one line.
    - `detail` (string): One sentence that explains the call.
    - `price` (number or null): The side's price now, from 0 to 1.
    - `maxPrice` (number or null): The highest price worth paying, when a measured record supports one.
    - `reasons` (string[]): Up to four reasons behind the call.
  - `history` (object or null): The price history, when you ask for `include=history`.
    - `range` (string): The period the history covers: `1h`, `1d` or `7d`.
    - `prices` (object[]): The data points, oldest first.
      - `time` (string): The time of this point, in ISO 8601 UTC.
      - `price` (number): The Yes price at this point.
      - `volume` (number): The dollars traded in this interval.
    - `series` (object or null): The past windows. Only repeating markets have them.
      - `windows` (object[]): The last 15 windows, with the newest first.
        - `opensAt` (string): When the window opened, in ISO 8601 UTC.
        - `closesAt` (string): When the window closed, in ISO 8601 UTC.
        - `result` (string): The side that won the window: `yes` or `no`.
      - `yesWon` (integer): The number of windows that Yes won.
      - `noWon` (integer): The number of windows that No won.
  - `trades` (object[]): The newest 40 whale buys, when you ask for `include=trades`.
    - `id` (string): The trade's id. It never changes, so the same trade has the same id in every listing and on the stream.
    - `time` (string): When the trade happened on the venue, in ISO 8601 UTC.
    - `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 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`.
    - `action` (string): Whether the trader bought or sold: `buy` or `sell`.
    - `entry` (string 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.
    - `price` (number or null): The price paid for each contract, from 0 to 1.
    - `usd` (number or null): The dollars traded.
    - `contracts` (number or null): The number of contracts traded.
    - `trader` (object 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`.
      - `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`.
    - `agreement` (object): The other whale trades on this market in the 24 hours before this one.
      - `sameSide` (object): Trades that bought the same side.
        - `trades` (integer): The number of whale trades.
        - `usd` (number): The dollars those trades spent.
      - `otherSide` (object): Trades that bought the other side.
        - `trades` (integer): The number of whale trades.
        - `usd` (number): The dollars those trades spent.
    - `result` (string): The trade's result. It is `open` until the market settles, then `win`, `loss` or `void`.
    - `profit` (number 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. |