# List Moves

> Lists what markets did over the last 24 hours: sharp price moves, changes of favorite and whales piling in.

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

`GET /v2/moves`

Scope: `read`

This route returns market moves from the last 24 hours, newest first. There are three types:

- `move` means the Yes price moved sharply within a few minutes and held there.
- `flip` means the favorite changed.
- `whales` means several different whales bought one side within a few minutes.

Moves do not count toward the daily trade allowance.

## Example request

curl:

```bash
curl "https://api.rivo.markets/v2/moves?category=crypto&minPoints=10&limit=2" \
  -H "Authorization: Bearer rivo_live_..."
```

Python:

```python
import requests

url = "https://api.rivo.markets/v2/moves"
headers = {
    "Authorization": "Bearer rivo_live_...",
}
params = [
    ("category", "crypto"),
    ("minPoints", "10"),
    ("limit", "2"),
]

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

TypeScript:

```typescript
const params = new URLSearchParams([
  ["category", "crypto"],
  ["minPoints", "10"],
  ["limit", "2"],
]);

const res = await fetch(`https://api.rivo.markets/v2/moves?${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.
- `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.
- `type` (string, optional): Returns moves of these types: `move`, `flip` or `whales`. Repeat the key to pass several.
- `minPoints` (number, optional): Returns `move` rows whose price changed by at least this many points, from 0 to 100. Flips and whales have no price change, so they always pass.
- `priceMin` (number, optional): Returns moves where the Yes price ended at or above this, from 0 to 1. Use it to leave out markets that are all but decided.
- `priceMax` (number, optional): Returns moves where the Yes price ended at or below this, from 0 to 1.
- `q` (string, optional): Returns moves on markets whose name contains every one of these words, up to 200 characters.
- `since` (string, optional): Returns moves at or after this time, in ISO 8601 with an offset.
- `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": [
    {
      "id": "flip:kalshi:market:KXBTCD-26OCT1423-T80799.99:1792031312711",
      "time": "2026-10-15T02:28:32.711Z",
      "type": "flip",
      "market": {
        "ref": "a2Fsc2hpOm1hcmtldDpLWEJUQ0QtMjZPQ1QxNDIzLVQ4MDc5OS45OQ",
        "contract": "a2Fsc2hpOm1hcmtldDpLWEJUQ0QtMjZPQ1QxNDIzLVQ4MDc5OS45OQ",
        "title": "Bitcoin price on Oct 14, 2026?",
        "venue": "kalshi",
        "category": "crypto",
        "kind": "bitcoin"
      },
      "outcome": "No",
      "priceBefore": null,
      "priceAfter": 0.36,
      "minutes": null,
      "traders": null,
      "usd": null
    },
    {
      "id": "price_move:polymarket:market:btc-updown-5m-1792031100:1792031230000",
      "time": "2026-10-15T02:27:10.000Z",
      "type": "move",
      "market": {
        "ref": "cG9seW1hcmtldDptYXJrZXQ6YnRjLXVwZG93bi01bS0xNzkyMDMxMTAw",
        "contract": "cG9seW1hcmtldDptYXJrZXQ6YnRjLXVwZG93bi01bS0xNzkyMDMxMTAw",
        "title": "Bitcoin Up or Down - October 14, 10:25PM-10:30PM ET",
        "venue": "polymarket",
        "category": "crypto",
        "kind": "bitcoin"
      },
      "outcome": "Yes",
      "priceBefore": 0.5,
      "priceAfter": 0.89,
      "minutes": 5,
      "traders": null,
      "usd": null
    }
  ],
  "nextCursor": "eyJ0IjoxNzkyMDMxMjMwMDAwLCJpZCI6InByaWNlX21vdmU6cG9seW1hcmtldDptYXJrZXQ6YnRjLXVwZG93bi01bS0xNzkyMDMxMTAwOjE3OTIwMzEyMzAwMDAifQ"
}
```

## Response fields

- `data` (object[]): The moves on this page.
  - `id` (string): The move's id. It never changes, so the listing and the stream use the same id.
  - `time` (string): When Rivo recorded the move, in ISO 8601 UTC.
  - `type` (string): What happened. `move` means the Yes price moved sharply. `flip` means the favorite changed. `whales` means several whales bought one side within minutes.
  - `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 move is about. On a `move` it is `Yes`, the side whose price moved. On a `flip` it is the new favorite. On `whales` it is the side the whales bought.
  - `priceBefore` (number or null): On a `move`, the Yes price before the move. On other types it is `null`.
  - `priceAfter` (number or null): The Yes price when Rivo recorded the move. It is `null` on a `whales` move when Rivo has no price yet.
  - `minutes` (integer or null): On a `move`, the number of minutes the move took. On other types it is `null`.
  - `traders` (integer or null): On `whales`, the number of whales who bought. On other types it is `null`.
  - `usd` (number or null): On `whales`, the dollars those whales spent between them. On other types it is `null`.
- `nextCursor` (string or null): Pass this as `cursor` to read the next page. It is `null` on the last page.

## Errors

| Code | When |
| --- | --- |
| `VALIDATION` | A parameter is out of range or unknown, or the cursor came from another listing. |