# Rivo API

> A REST API and Server-Sent Events stream for prediction markets on Kalshi, Polymarket, Polymarket US and Gemini: markets, prices, order books, trades, market moves, trader records, backtests, paper trading and paper bots.

Base URL: https://api.rivo.markets/v2. Every page is linked as Markdown. Before writing code against the API, read the instructions below or load https://rivo.markets/docs/llms-full.txt.

## Instructions for coding agents

Use the Rivo API v2. Full docs: https://rivo.markets/docs/llms-full.txt (one file) or https://rivo.markets/docs/llms.txt (an index of Markdown pages).

- Base URL: https://api.rivo.markets/v2. Send `Authorization: Bearer $RIVO_API_KEY`. Read the key from the environment; never write it into code.
- A success is `{ "data": ... }`, plus `nextCursor` on a list. A failure is `{ "success": false, "error", "code" }` with an HTTP status. Branch on `code`, never on `error`.
- Markets and traders are named by refs. Take refs from responses and send them back unchanged. A market ref is opaque; never build or parse one. A trader ref is `platform:traderId`, such as `kalshi:apexnyc`.
- Page with `limit` (up to 200) and `cursor` = the last response's `nextCursor`, with the same filters. Stop when `nextCursor` is null. There are no offsets.
- Pass several values by repeating the key: `?venue=kalshi&venue=polymarket`. Unknown parameters are refused, so use only the names in the docs.
- Prices are 0 to 1, money is USD, times are ISO 8601 UTC. Win rates are null under 10 settled bets.
- `outcome` filters need exactly one `market`. Paper orders and market bots take a contract ref (`outcomes[].ref` of `GET /v2/markets/{ref}`), not an event ref.
- Limits per key: 120 requests a minute (each `include` and each sweep value counts), 50,000 trades a day, 3 streams, trades from the last 30 days. Read `x-ratelimit-remaining`; on 429 wait `retry-after` seconds.
- For anything live use `GET /v2/stream` (Server-Sent Events, events `trade` and `move`) instead of polling. After a reconnect, fill the gap with `GET /v2/trades?since=<last seen time>` and dedupe by `id`.
- Send an `Idempotency-Key` header with `POST /v2/paper-orders` and reuse it on retries.
- Do not use /v1: it is deprecated and stops answering on December 14, 2026.
- Use only fields the docs list. If a field you need is not there, it does not exist.

## Get started

- [rivomarkets API](https://rivo.markets/docs/index.md): A REST API and live stream for prediction markets on Kalshi, Polymarket, Polymarket US and Gemini.
- [Quickstart](https://rivo.markets/docs/quickstart.md): Create an API key, then list trades, open a market and backtest an idea in three calls.
- [Authentication](https://rivo.markets/docs/authentication.md): Send your key as a bearer token. Scopes decide what it can change, and the account's subscription decides whether it works.

## Essentials

- [Core concepts](https://rivo.markets/docs/concepts.md): Every v2 route follows the same rules for responses, refs, cursors, filters, includes and units.
- [Venues](https://rivo.markets/docs/venues.md): The four venues the API covers, the value you pass for each, and which ones name their traders.
- [Errors](https://rivo.markets/docs/errors.md): Every failure returns an HTTP status and a stable error code to check.
- [Rate limits](https://rivo.markets/docs/rate-limits.md): Each key can make 120 requests a minute, read 50,000 trades a day and hold three streams open at once.
- [Streaming](https://rivo.markets/docs/streaming.md): The stream sends you trades and market moves the moment they land, over Server-Sent Events, with the same filters as the list routes.

## Guides

- [Build with AI](https://rivo.markets/docs/build-with-ai.md): Give Claude, Cursor, Codex or any agent the whole API in one file, every page as Markdown, and a set of instructions to follow.
- [Migrate from v1](https://rivo.markets/docs/migrate-from-v1.md): v1 is deprecated and stops answering on December 14, 2026. This guide shows where each v1 route went and what to change.

## API reference

- [GET /v2/trades](https://rivo.markets/docs/reference/list-trades.md): Lists whale trades from the last 30 days, newest or biggest first, with each trader's record and what other whales did.
- [GET /v2/positions](https://rivo.markets/docs/reference/list-positions.md): Lists what winning traders hold right now on markets that are still trading, biggest first.
- [GET /v2/moves](https://rivo.markets/docs/reference/list-moves.md): Lists what markets did over the last 24 hours: sharp price moves, changes of favorite and whales piling in.
- [GET /v2/stream](https://rivo.markets/docs/reference/stream.md): Pushes trades and market moves to you over one server-sent events connection, with the same filters as the listings.
- [GET /v2/markets](https://rivo.markets/docs/reference/list-markets.md): Searches and browses markets on every venue. It returns open markets by default, or the markets that settled in the last 30 days.
- [GET /v2/markets/{ref}](https://rivo.markets/docs/reference/get-market.md): 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.
- [GET /v2/traders](https://rivo.markets/docs/reference/list-traders.md): Searches and ranks traders who were active in the last 30 days, over all time or over today, this week or this month.
- [GET /v2/traders/{ref}](https://rivo.markets/docs/reference/get-trader.md): Reads one trader's record overall, by category and by kind of market. On request it adds their positions, profit curve, habits and similar traders.
- [POST /v2/backtest](https://rivo.markets/docs/reference/backtest.md): Scores a signal or one trader on settled history at a sizing you choose. You can add a holdout check, a sweep or a breakdown.
- [POST /v2/paper-orders](https://rivo.markets/docs/reference/place-paper-order.md): Buys or sells one side of a market on paper. Rivo fills the order against the venue's live order book at the venue's real fee.
- [GET /v2/paper](https://rivo.markets/docs/reference/get-paper-account.md): Reads the paper account's totals and positions, from both hand trades and bots. On request it adds the paper orders you placed by hand.
- [GET /v2/bots](https://rivo.markets/docs/reference/list-bots.md): Lists every bot on the account: trader, signal and market bots, on paper and live.
- [POST /v2/bots](https://rivo.markets/docs/reference/create-bot.md): Starts a paper bot that copies a trader, runs a signal, or runs a price rule on one market.
- [GET /v2/bots/{id}](https://rivo.markets/docs/reference/get-bot.md): Reads one bot's settings, record and profit curve. On request it adds the bot's trades and how busy its trigger has been.
- [PATCH /v2/bots/{id}](https://rivo.markets/docs/reference/update-bot.md): Changes a paper bot's sizing, signal, rule, alerts or status.
- [DELETE /v2/bots/{id}](https://rivo.markets/docs/reference/delete-bot.md): Stops and removes a paper bot. Its open paper positions stay until they settle.

## Optional

- [Everything in one file](https://rivo.markets/docs/llms-full.txt): every page above, in full
- [MCP server](https://rivo.markets/docs/mcp)
- [v1 reference (deprecated)](https://rivo.markets/docs/api/universe): kept until v1 is switched off; do not build on it
- [Rivo product, markets and traders](https://rivo.markets/llms.txt)