GET/v2/paperread scope

Get Paper Account

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, not here.

Example request

GET /v2/paper

curl "https://api.rivo.markets/v2/paper?status=open&include=orders" \
  -H "Authorization: Bearer rivo_live_..."

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())

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

statusstringdefault open
Which positions to return: open, settled or all.
sourcestringdefault all
Which positions to return by where they came from: hand, bot or all.
botstring
Returns only one bot's positions. Pass its id, such as trader:<id> or signal:<id>.
venuestring
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.
marketmarket ref
Returns positions on this contract. Pass the contract's ref. Repeat the key to pass several, up to 50.
includestring
Set to orders to add your hand-placed paper orders.
sincestring
With include=orders, returns orders at or after this time, in ISO 8601 with an offset.
ordersCursorstring
With include=orders, pass the orders.nextCursor from the previous page to read the next one.
limitintegerdefault 50
The number of rows on each page, from 1 to 200. It applies to both positions and orders.
cursorstring
Pass the positions.nextCursor from the previous page to read the next one.

Example response

Response

{
  "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

dataobject
The paper account.
Show 3 data fields
- totalsobject
  Totals for the whole account. Filters do not change them.
  Show 4 totals fields
  - openUsdnumber
    What your open holdings are worth now, in USD.
  - unrealizednumber
    The profit on your open holdings, in USD.
  - realizednumber
    The profit from settled holdings and sales, in USD.
  - winRatenumber or null
    The share of settled holdings that won, from 0 to 1. It is null until a holding settles.
- positionsobject
  One page of positions.
  Show 2 positions fields
  - dataobject[]
    The positions on this page.
    Show 14 data fields
    marketobject
    The market this row is about.
    Show 6 market fields
    refmarket ref
    The market's ref. You can pass it to any market filter or to Get Market. On a market of several outcomes, it names the whole event.
    contractmarket 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 or a market bot.
    titlestring
    The market's title, as the venue writes it.
    venuestring
    The venue that lists the market: one of kalshi, polymarket, polymarket_us or gemini.
    categorystring or null
    The market's category: one of sports, politics, crypto, finance, culture. It is null when Rivo has not classified the market.
    kindstring or null
    The kind of market, such as nfl or bitcoin. It is null when Rivo has not classified the market yet.
    outcomestring
    The side the holding is on.
    contractsnumber
    The number of contracts held.
    entryPricenumber
    The average price paid, from 0 to 1.
    pricenumber
    The side's price now, or its payout once the market settles.
    costnumber
    The contracts multiplied by entryPrice, in USD.
    valuenumber
    What the holding is worth now, in USD.
    profitnumber
    The profit in USD, which is value minus cost.
    statusstring
    Whether the holding is open or settled.
    resultstring or null
    The result once the market settles: win, loss or void.
    sourcestring
    Where the holding came from. hand means you placed it with a paper order, and bot means a paper bot holds it.
    botobject or null
    The bot that holds this position. It is null for a holding you placed by hand.
    Show 2 bot fields
    idstring
    The bot's id, as List Bots returns it.
    namestring
    The bot's name.
    openedAtstring
    When the holding opened, in ISO 8601 UTC.
    settledAtstring or null
    When the holding settled, in ISO 8601 UTC.
  - nextCursorstring or null
    Pass this as cursor to read the next page. It is null on the last page.
- ordersobject
  One page of the paper orders you placed by hand, when you ask for include=orders.
  Show 2 orders fields
  - dataobject[]
    The orders on this page, newest first.
    Show 10 data fields
    idstring
    The paper order's id.
    marketobject
    The market this row is about.
    Show 6 market fields
    refmarket ref
    The market's ref. You can pass it to any market filter or to Get Market. On a market of several outcomes, it names the whole event.
    contractmarket 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 or a market bot.
    titlestring
    The market's title, as the venue writes it.
    venuestring
    The venue that lists the market: one of kalshi, polymarket, polymarket_us or gemini.
    categorystring or null
    The market's category: one of sports, politics, crypto, finance, culture. It is null when Rivo has not classified the market.
    kindstring or null
    The kind of market, such as nfl or bitcoin. It is null when Rivo has not classified the market yet.
    outcomestring
    The side traded, using the name that Get Market gives it.
    actionstring
    Whether the order bought or sold: buy or sell.
    contractsnumber
    The number of contracts that filled.
    avgPricenumber
    The average price for each contract, from 0 to 1, with the venue's fee included.
    costnumber
    What the buy cost, or what the sale brought in, in USD with the fee included.
    unfilledContractsnumber
    The contracts the book could not fill right away. Paper orders never rest on the book, so Rivo drops this part.
    filledAtstring
    When the order filled, in ISO 8601 UTC.
    profitnumber or null
    On a sale, the profit measured against the average cost of what you held.
  - nextCursorstring 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.

Example request

GET /v2/paper

curl "https://api.rivo.markets/v2/paper?status=open&include=orders" \
  -H "Authorization: Bearer rivo_live_..."

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())

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

statusstringdefault open

Which positions to return: open, settled or all.

sourcestringdefault all

Which positions to return by where they came from: hand, bot or all.

botstring

Returns only one bot's positions. Pass its id, such as trader:<id> or signal:<id>.

venuestring

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.

marketmarket ref

Returns positions on this contract. Pass the contract's ref. Repeat the key to pass several, up to 50.

includestring

Set to orders to add your hand-placed paper orders.

sincestring

With include=orders, returns orders at or after this time, in ISO 8601 with an offset.

ordersCursorstring

With include=orders, pass the orders.nextCursor from the previous page to read the next one.

limitintegerdefault 50

The number of rows on each page, from 1 to 200. It applies to both positions and orders.

cursorstring

Pass the positions.nextCursor from the previous page to read the next one.

Example response

Response

{
  "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

dataobject

The paper account.

Show 3 data fields

totalsobject
Totals for the whole account. Filters do not change them.
Show 4 totals fields
- openUsdnumber
  What your open holdings are worth now, in USD.
- unrealizednumber
  The profit on your open holdings, in USD.
- realizednumber
  The profit from settled holdings and sales, in USD.
- winRatenumber or null
  The share of settled holdings that won, from 0 to 1. It is null until a holding settles.
positionsobject
One page of positions.
Show 2 positions fields
- dataobject[]
  The positions on this page.
  Show 14 data fields
  - marketobject
    The market this row is about.
    Show 6 market fields
    refmarket ref
    The market's ref. You can pass it to any market filter or to Get Market. On a market of several outcomes, it names the whole event.
    contractmarket 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 or a market bot.
    titlestring
    The market's title, as the venue writes it.
    venuestring
    The venue that lists the market: one of kalshi, polymarket, polymarket_us or gemini.
    categorystring or null
    The market's category: one of sports, politics, crypto, finance, culture. It is null when Rivo has not classified the market.
    kindstring or null
    The kind of market, such as nfl or bitcoin. It is null when Rivo has not classified the market yet.
  - outcomestring
    The side the holding is on.
  - contractsnumber
    The number of contracts held.
  - entryPricenumber
    The average price paid, from 0 to 1.
  - pricenumber
    The side's price now, or its payout once the market settles.
  - costnumber
    The contracts multiplied by entryPrice, in USD.
  - valuenumber
    What the holding is worth now, in USD.
  - profitnumber
    The profit in USD, which is value minus cost.
  - statusstring
    Whether the holding is open or settled.
  - resultstring or null
    The result once the market settles: win, loss or void.
  - sourcestring
    Where the holding came from. hand means you placed it with a paper order, and bot means a paper bot holds it.
  - botobject or null
    The bot that holds this position. It is null for a holding you placed by hand.
    Show 2 bot fields
    idstring
    The bot's id, as List Bots returns it.
    namestring
    The bot's name.
  - openedAtstring
    When the holding opened, in ISO 8601 UTC.
  - settledAtstring or null
    When the holding settled, in ISO 8601 UTC.
- nextCursorstring or null
  Pass this as cursor to read the next page. It is null on the last page.
ordersobject
One page of the paper orders you placed by hand, when you ask for include=orders.
Show 2 orders fields
- dataobject[]
  The orders on this page, newest first.
  Show 10 data fields
  - idstring
    The paper order's id.
  - marketobject
    The market this row is about.
    Show 6 market fields
    refmarket ref
    The market's ref. You can pass it to any market filter or to Get Market. On a market of several outcomes, it names the whole event.
    contractmarket 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 or a market bot.
    titlestring
    The market's title, as the venue writes it.
    venuestring
    The venue that lists the market: one of kalshi, polymarket, polymarket_us or gemini.
    categorystring or null
    The market's category: one of sports, politics, crypto, finance, culture. It is null when Rivo has not classified the market.
    kindstring or null
    The kind of market, such as nfl or bitcoin. It is null when Rivo has not classified the market yet.
  - outcomestring
    The side traded, using the name that Get Market gives it.
  - actionstring
    Whether the order bought or sold: buy or sell.
  - contractsnumber
    The number of contracts that filled.
  - avgPricenumber
    The average price for each contract, from 0 to 1, with the venue's fee included.
  - costnumber
    What the buy cost, or what the sale brought in, in USD with the fee included.
  - unfilledContractsnumber
    The contracts the book could not fill right away. Paper orders never rest on the book, so Rivo drops this part.
  - filledAtstring
    When the order filled, in ISO 8601 UTC.
  - profitnumber or null
    On a sale, the profit measured against the average cost of what you held.
- nextCursorstring or null
  Pass this as ordersCursor to read the next page. It is null on the last page.

Code

When

VALIDATION

A parameter is out of range or unknown, or a cursor came from another listing.