# Get Paper Account > 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. Source: https://rivo.markets/docs/reference/get-paper-account `GET /v2/paper` Scope: `read` This route returns the paper account: totals for the whole account, and its positions. It shows open positions by default. It lists positions you placed by hand and positions held by paper bots together, and tags each one with its `source`. `include=orders` adds every paper order you placed by hand, newest first. The orders page with their own cursor, `ordersCursor`. Each sale carries `profit`, measured against the average cost of what you held. Market bots keep their trades on the bot itself. You can find them in [Get Bot](https://rivo.markets/docs/reference/get-bot), not here. ## Example request curl: ```bash curl "https://api.rivo.markets/v2/paper?status=open&include=orders" \ -H "Authorization: Bearer rivo_live_..." ``` Python: ```python import requests url = "https://api.rivo.markets/v2/paper" headers = { "Authorization": "Bearer rivo_live_...", } params = [ ("status", "open"), ("include", "orders"), ] res = requests.get(url, headers=headers, params=params) res.raise_for_status() print(res.json()) ``` TypeScript: ```typescript const params = new URLSearchParams([ ["status", "open"], ["include", "orders"], ]); const res = await fetch(`https://api.rivo.markets/v2/paper?${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 - `status` (string, optional, default `open`): Which positions to return: `open`, `settled` or `all`. - `source` (string, optional, default `all`): Which positions to return by where they came from: `hand`, `bot` or `all`. - `bot` (string, optional): Returns only one bot's positions. Pass its id, such as `trader:` or `signal:`. - `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. - `market` (market ref, optional): Returns positions on this contract. Pass the contract's `ref`. Repeat the key to pass several, up to 50. - `include` (string, optional): Set to `orders` to add your hand-placed paper orders. - `since` (string, optional): With `include=orders`, returns orders at or after this time, in ISO 8601 with an offset. - `ordersCursor` (string, optional): With `include=orders`, pass the `orders.nextCursor` from the previous page to read the next one. - `limit` (integer, optional, default `50`): The number of rows on each page, from 1 to 200. It applies to both positions and orders. - `cursor` (string, optional): Pass the `positions.nextCursor` from the previous page to read the next one. ## Example response ```json { "data": { "totals": { "openUsd": 1842.6, "unrealized": 63.18, "realized": 412.95, "winRate": 0.5833 }, "positions": { "data": [ { "market": { "ref": "a2Fsc2hpOm1hcmtldDpLWE1MQkdBTUUtMjZPQ1QxNDIwMDBNSUxMQUQtTUlM", "contract": "a2Fsc2hpOm1hcmtldDpLWE1MQkdBTUUtMjZPQ1QxNDIwMDBNSUxMQUQtTUlM", "title": "Milwaukee wins", "venue": "kalshi", "category": "sports", "kind": "mlb" }, "outcome": "Yes", "contracts": 284, "entryPrice": 0.8796, "price": 0.89, "cost": 249.81, "value": 252.76, "profit": 2.95, "status": "open", "result": null, "source": "hand", "bot": null, "openedAt": "2026-10-15T02:31:07.412Z", "settledAt": null }, { "market": { "ref": "a2Fsc2hpOm1hcmtldDpLWE5GTE5GQ05PUlRILTI3LUNISQ", "contract": "a2Fsc2hpOm1hcmtldDpLWE5GTE5GQ05PUlRILTI3LUNISQ", "title": "Will Chicago win the Pro Football NFC North Division?", "venue": "kalshi", "category": "sports", "kind": "nfl" }, "outcome": "Yes", "contracts": 500, "entryPrice": 0.2, "price": 0.2, "cost": 100, "value": 100, "profit": 0, "status": "open", "result": null, "source": "bot", "bot": { "id": "trader:8d3f2a61-0c4e-4b7a-9f15-2e6a1c9b4d70", "name": "avidsmores" }, "openedAt": "2026-10-12T05:13:31.000Z", "settledAt": null } ], "nextCursor": null }, "orders": { "data": [ { "id": "5b7e0c1a-2f4d-4c8e-9a61-3d2f7b9e0a14", "market": { "ref": "a2Fsc2hpOm1hcmtldDpLWE1MQkdBTUUtMjZPQ1QxNDIwMDBNSUxMQUQtTUlM", "contract": "a2Fsc2hpOm1hcmtldDpLWE1MQkdBTUUtMjZPQ1QxNDIwMDBNSUxMQUQtTUlM", "title": "Milwaukee wins", "venue": "kalshi", "category": "sports", "kind": "mlb" }, "outcome": "Yes", "action": "buy", "contracts": 284, "avgPrice": 0.8796, "cost": 249.81, "unfilledContracts": 0, "filledAt": "2026-10-15T02:31:07.412Z" } ], "nextCursor": null } } } ``` ## Response fields - `data` (object): The paper account. - `totals` (object): Totals for the whole account. Filters do not change them. - `openUsd` (number): What your open holdings are worth now, in USD. - `unrealized` (number): The profit on your open holdings, in USD. - `realized` (number): The profit from settled holdings and sales, in USD. - `winRate` (number or null): The share of settled holdings that won, from 0 to 1. It is `null` until a holding settles. - `positions` (object): One page of positions. - `data` (object[]): The positions on this page. - `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 holding is on. - `contracts` (number): The number of contracts held. - `entryPrice` (number): The average price paid, from 0 to 1. - `price` (number): The side's price now, or its payout once the market settles. - `cost` (number): The contracts multiplied by `entryPrice`, in USD. - `value` (number): What the holding is worth now, in USD. - `profit` (number): The profit in USD, which is `value` minus `cost`. - `status` (string): Whether the holding is `open` or `settled`. - `result` (string or null): The result once the market settles: `win`, `loss` or `void`. - `source` (string): Where the holding came from. `hand` means you placed it with a paper order, and `bot` means a paper bot holds it. - `bot` (object or null): The bot that holds this position. It is `null` for a holding you placed by hand. - `id` (string): The bot's id, as [List Bots](https://rivo.markets/docs/reference/list-bots) returns it. - `name` (string): The bot's name. - `openedAt` (string): When the holding opened, in ISO 8601 UTC. - `settledAt` (string or null): When the holding settled, in ISO 8601 UTC. - `nextCursor` (string or null): Pass this as `cursor` to read the next page. It is `null` on the last page. - `orders` (object): One page of the paper orders you placed by hand, when you ask for `include=orders`. - `data` (object[]): The orders on this page, newest first. - `id` (string): The paper order's id. - `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 traded, using the name that [Get Market](https://rivo.markets/docs/reference/get-market) gives it. - `action` (string): Whether the order bought or sold: `buy` or `sell`. - `contracts` (number): The number of contracts that filled. - `avgPrice` (number): The average price for each contract, from 0 to 1, with the venue's fee included. - `cost` (number): What the buy cost, or what the sale brought in, in USD with the fee included. - `unfilledContracts` (number): The contracts the book could not fill right away. Paper orders never rest on the book, so Rivo drops this part. - `filledAt` (string): When the order filled, in ISO 8601 UTC. - `profit` (number or null): On a sale, the profit measured against the average cost of what you held. - `nextCursor` (string or null): Pass this as `ordersCursor` to read the next page. It is `null` on the last page. Rivo prices open holdings from the prices it already holds for each market. A holding settles once Rivo records the market's result. ## Errors | Code | When | | --- | --- | | `VALIDATION` | A parameter is out of range or unknown, or a cursor came from another listing. |