# Build with AI

> Give Claude, Cursor, Codex or any agent the whole API in one file, every page as Markdown, and a set of instructions to follow.

Source: https://rivo.markets/docs/build-with-ai

We wrote these docs for both people and AI models. Every page has a Markdown version, and the whole reference fits in one file. You can also paste a set of instructions into your agent so the code it writes uses the API correctly.

## llms.txt

| File | Holds |
| --- | --- |
| [/docs/llms.txt](https://rivo.markets/docs/llms.txt) | This file indexes every docs page, with a one-line summary and a link to the page's Markdown. Point an agent here if it can fetch pages as it needs them. |
| [/docs/llms-full.txt](https://rivo.markets/docs/llms-full.txt) | This file holds every page in one Markdown file, including the guides and every endpoint with its parameters, fields and examples. Load it into your agent's context once. |

These files cover only the developer docs. The site's main [/llms.txt](https://rivo.markets/llms.txt) covers the rest of Rivo, including its markets and traders.

## Every page as Markdown

Add `.md` to any docs URL to get the page as Markdown, for example [/docs/reference/list-trades.md](https://rivo.markets/docs/reference/list-trades.md). The overview lives at [/docs/index.md](https://rivo.markets/docs/index.md). Every page also has a **Copy page** button, which copies the page as Markdown or opens it in Claude or ChatGPT.

## Instructions for your agent

Paste this into your agent's project instructions: `CLAUDE.md` for Claude Code, `AGENTS.md` for Codex, `.cursor/rules` for Cursor, or the system prompt of your own agent.

AGENTS.md:

```
# Rivo API: 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.
```

## A good first prompt

```
Read https://rivo.markets/docs/llms-full.txt. Then write a TypeScript script that opens the Rivo
v2 stream for Kalshi trades by traders with a win rate of at least 0.6, prints each
trade's market title, outcome, price and dollars, and reconnects with a gap fill from
/v2/trades when the connection drops. Read the API key from RIVO_API_KEY.
```

## MCP

If you want an assistant to call Rivo directly instead of writing code against it, connect the [MCP server](https://rivo.markets/docs/mcp). It uses the same API keys.