> ## Documentation Index
> Fetch the complete documentation index at: https://docs.novig.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Catalog

> The events and markets you can trade, and how to find one game

export const PAGE_LIMIT_RANGE = "1\u20135000";

export const PAGE_LIMIT_DEFAULT = 500;

Model: [Universe model](/api/concepts/universe-model) · [Event lifecycle](/api/concepts/event-lifecycle).

| Route | Key | Throttle | Reply |
| - | - | - | - |
| `GET /v3/catalog/events` `GET /v3/catalog/markets` | `trading` `trading::read` | `read` | <span className="st st-ok">200</span> |
| `GET /v3/catalog/{events,markets}/{id}` | `trading` `trading::read` | `read` | <span className="st st-ok">200</span> <span className="st st-warn">404</span> |
| `GET /v3/catalog/markets/{id}/book` `GET /v3/catalog/markets/{id}/trades` | `trading` `trading::read` | `read` | <span className="st st-ok">200</span> <span className="st st-warn">404</span> |
| `GET /v3/types/{leagues,sports,markets,event-statuses}` | `trading` `trading::read` | `read` | <span className="st st-ok">200</span> |
| `GET /v3/history/markets` | `trading` `trading::read` | `history` | <span className="st st-ok">200</span> |
| `GET /v3/history/markets/{id}` | `trading` `trading::read` | `history` | <span className="st st-ok">200</span> <span className="st st-warn">404</span> |
| `GET /v3/history/events` | `trading` `trading::read` | `history` | <span className="st st-ok">200</span> |
| `GET /v3/history/events/{id}` | `trading` `trading::read` | `history` | <span className="st st-ok">200</span> <span className="st st-warn">404</span> |

<Tabs>
  <Tab title="Request">
    ```bash theme={"dark"}
    curl -s "$NOVIG_HOST/v3/catalog/markets?league=NFL&limit=5" \
      -H "Novig-Key-Id: $TRADING_KEY_ID" \
      -H "Novig-Timestamp: $TS" \
      -H "Novig-Signature: $SIG"
    ```
  </Tab>

  <Tab title="200">
    ```json theme={"dark"}
    {
    "items": [
    {
      "marketId":    "6f9619ff-…",
      "eventId":     "110e8400-…",
      "marketType":  "MONEY",
      "status":      "OPEN",
      "description": "Kansas City Chiefs at Buffalo Bills — Moneyline",
      "startsTs":    1758400800000,
      "fee": { "coefficient": "0.03", "makerCredit": "0.5",
               "charged": "WHEN_LIVE" },
      "outcomes": [
        { "outcomeId": "3f2504e0-…", "name": "Kansas City Chiefs",
          "status": "TBD" },
        { "outcomeId": "5a1c9e73-…", "name": "Buffalo Bills",
          "status": "TBD" }
      ]
    }
    ],
    "next": "eyJvIjoxNzU4NDAwODAwMDAwfQ"
    }
    ```
  </Tab>
</Tabs>

A market with a line carries `strike`, a decimal string. A spread's line is the home side's handicap, so `"-3.5"` makes the home side a 3.5-point favorite. A moneyline has no line and omits `strike`.

## Filters

| Query | Type | |
| - | - | - |
| `league` | `string` | From `GET /v3/types/leagues`. Comma-separated. |
| `marketType` | `string` | From `GET /v3/types/markets`. Comma-separated. |
| `eventStatus` | `string` | From `GET /v3/types/event-statuses`. |
| `event` | `uuid` | Every market of one event. |
| `startsAfter` | `int64 ms` | Exclusive lower bound on the event's start. |
| `startsBefore` | `int64 ms` | Exclusive upper bound. |
| `limit` | <code>{PAGE_LIMIT_RANGE}</code> | Defaults to <code>{PAGE_LIMIT_DEFAULT}</code>, not the maximum. Outside the range → <span className="st st-warn">400</span>. |
| `after` | `string` | The previous page's `next`. Opaque. Do not build or parse one. |

## Market history

A market leaves the catalog when it closes. The history routes return every market of any age and status, so you can still read its grade.

* [List market history](/api-reference/history/list-market-history) pages through every market, newest first. It takes `limit` and `after`, like the catalog.
* [Get a market from history](/api-reference/history/get-a-market-from-history) returns one market by ID.

A graded outcome carries its grade in `status`. Both routes spend the `history` throttle, and a larger page costs more.

## Event history

An event leaves the catalog when its last market closes. The event history routes return every event of any age and status.

* [List event history](/api-reference/history/list-event-history) pages through every event, newest first. It takes `limit` and `after`, like the catalog.
* [Get an event from history](/api-reference/history/get-an-event-from-history) returns one event by ID.

A history market's `eventId` names its event here. Both routes spend the `history` throttle, and a larger page costs more.

## Finding one game

<Steps>
  <Step title="Narrow by league and start window">
    `?league=NFL&startsAfter=1758326400000&startsBefore=1758412800000` — a day of one league.
  </Step>

  <Step title="Match description client-side, once, at start-up" />

  <Step title="Cache the outcome IDs and trade on them" />
</Steps>

<Note>
  Build on IDs, not on `description`. `description` is unversioned prose, and it changes. An outcome ID stays stable for the life of its market.
</Note>

## Depth and tape

| Route | Returns | Live alternative |
| - | - | - |
| `GET /v3/catalog/markets/{id}/book` | Resting orders by outcome, priority order | [Book channel](/api/streaming/book) |
| `GET /v3/catalog/markets/{id}/trades` | Executions, newest first | [Tape channel](/api/streaming/tape) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.