# Quickstart

> Create an API key, then list trades, open a market and backtest an idea in three calls.

Source: https://rivo.markets/docs/quickstart

## 1. Create a key

Create an API key in [Settings](https://rivo.markets/settings?tab=developer). Choose the `read` scope to read data, and add `write` to place paper orders or change bots. Rivo shows the key only once, so copy it into an environment variable. Never commit it to source control.

```bash
export RIVO_API_KEY=rivo_live_...
```

## 2. List recent trades

This call lists the newest large buys on Kalshi from traders who win at least 60% of their bets in that kind of market.

curl:

```bash
curl "https://api.rivo.markets/v2/trades?venue=kalshi&minWinRate=0.6&limit=10" \
  -H "Authorization: Bearer $RIVO_API_KEY"
```

Python:

```python
import os
import requests

res = requests.get(
    "https://api.rivo.markets/v2/trades",
    headers={"Authorization": f"Bearer {os.environ['RIVO_API_KEY']}"},
    params={"venue": "kalshi", "minWinRate": 0.6, "limit": 10},
)
res.raise_for_status()
for trade in res.json()["data"]:
    print(trade["market"]["title"], trade["outcome"], trade["usd"])
```

TypeScript:

```typescript
const res = await fetch(
  "https://api.rivo.markets/v2/trades?venue=kalshi&minWinRate=0.6&limit=10",
  { headers: { Authorization: `Bearer ${process.env.RIVO_API_KEY}` } },
);
const { data } = await res.json();
for (const trade of data) console.log(trade.market.title, trade.outcome, trade.usd);
```

Response:

```json
{
  "data": [
    {
      "id": "f1c6b941-64bf-5911-88ef-1b5de17e9d76",
      "time": "2026-10-15T02:25:20.514Z",
      "market": {
        "ref": "a2Fsc2hpOm1hcmtldDpLWEJUQzE1TS0yNk9DVDE0MjIzMC0zMA",
        "contract": "a2Fsc2hpOm1hcmtldDpLWEJUQzE1TS0yNk9DVDE0MjIzMC0zMA",
        "title": "BTC price up in next 15 mins?",
        "venue": "kalshi",
        "category": "crypto",
        "kind": "bitcoin"
      },
      "outcome": "No",
      "action": "buy",
      "entry": null,
      "price": 0.992,
      "usd": 1008.86,
      "contracts": 1017,
      "trader": {
        "ref": "kalshi:prokingpriest",
        "name": "prokingpriest",
        "winRate": 0.974,
        "profit": 14118.88,
        "settled": 16521
      },
      "agreement": {
        "sameSide": {
          "trades": 9,
          "usd": 13130.67
        },
        "otherSide": {
          "trades": 2,
          "usd": 2501.92
        }
      },
      "result": "open",
      "profit": null
    }
  ],
  "nextCursor": "eyJ0IjoiMjAyNi0..."
}
```

Every trade includes a `ref` for its market. Routes use refs to name markets and traders. Copy a ref from one response and send it unchanged in your next call.

## 3. Open the market

Pass a market's ref to read that market. Add `include=whales` to see who bought each side, and `include=call` to see the call Rivo makes on it. Each include counts as one request toward your limit of 120 a minute, so this call uses three: one for the market and one for each include.

```bash
curl "https://api.rivo.markets/v2/markets/<ref>?include=whales&include=call" \
  -H "Authorization: Bearer $RIVO_API_KEY"
```

## 4. Backtest an idea

This backtest scores a signal against 90 days of settled trades. The signal picks large buys on sports markets priced between 40 and 70 cents and stakes $100 on each one.

```bash
curl -X POST "https://api.rivo.markets/v2/backtest" \
  -H "Authorization: Bearer $RIVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signal": { "category": ["sports"], "priceMin": 0.4, "priceMax": 0.7 },
    "sizing": { "usd": 100 },
    "days": 90
  }'
```

If you like the result, send the same signal to [Create Bot](https://rivo.markets/docs/reference/create-bot). The bot starts paper trading on the next matching trade.

## Next

- [Core concepts](https://rivo.markets/docs/concepts): Learn how refs, paging and filters work on every route.
- [Stream](https://rivo.markets/docs/streaming): Receive trades and moves as they happen instead of polling.
- [Build with AI](https://rivo.markets/docs/build-with-ai): Hand these docs to Claude, Cursor or any agent.