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

# Catalog

> Discover venue coverage, valid market identifiers, and historical bounds before you query data.

Use catalog to discover venue and market availability before you build data requests.

`GET /catalog` is a public endpoint. You do not need an `Authorization` header for standard catalog lookups.

## Base URL

All examples use `https://api.polaris.supply`.

## `GET /catalog`

Returns flattened market coverage rows with per-market UTC bounds, dataset categories, access metadata, and normalized instrument metadata.

* Optional: `source`, `market`, `q`
* `market` requires `source`

## Parameters

<ParamField query="source" type="string">
  Source ID for the venue to inspect, for example `hyperliquid` or `lighter`.
</ParamField>

<ParamField query="market" type="string">
  Exact market identifier to filter within the selected source. Requires `source`.
</ParamField>

<ParamField query="q" type="string">
  Optional free-text filter across catalog rows. Useful when you know part of a venue market name or symbol but not the exact Polaris market ID.
</ParamField>

## Response fields

<ResponseField name="markets" type="object[]" required>
  Market rows that match the query.
</ResponseField>

<ResponseField name="markets.source" type="string" required>
  Source identifier for the venue, such as `hyperliquid`.
</ResponseField>

<ResponseField name="markets.market" type="string" required>
  Exact Polaris market ID to use in requests.
</ResponseField>

<ResponseField name="markets.start" type="string" required>
  Earliest available UTC timestamp for the market.
</ResponseField>

<ResponseField name="markets.end" type="string" required>
  Latest available UTC timestamp for the market.
</ResponseField>

<ResponseField name="markets.categories" type="string[]" required>
  Dataset categories available for the market.
</ResponseField>

<ResponseField name="markets.access.status" type="string" required>
  Access state for the market, such as `open`, `preview`, or `restricted`.
</ResponseField>

<ResponseField name="markets.access.public_cutoff_date" type="string">
  Latest UTC date available without gated access when a public cutoff exists.
</ResponseField>

<ResponseField name="markets.instrument" type="object" required>
  Normalized instrument metadata for the market row. The object is always present, and missing values are returned as `null`.
</ResponseField>

<ResponseField name="markets.instrument.base" type="string">
  Base asset or instrument code when available, such as `BTC`.
</ResponseField>

<ResponseField name="markets.instrument.quote" type="string">
  Quote asset or settlement code when available, such as `USD`.
</ResponseField>

<ResponseField name="markets.instrument.tick_size" type="string | number">
  Minimum price increment when available. Numeric values may be returned as strings or numbers depending on source normalization.
</ResponseField>

<ResponseField name="markets.instrument.lot_size" type="string | number">
  Minimum quantity increment when available. Numeric values may be returned as strings or numbers depending on source normalization.
</ResponseField>

<ResponseField name="markets.instrument.min_notional" type="string | number">
  Minimum notional trade size when available. Numeric values may be returned as strings or numbers depending on source normalization.
</ResponseField>

<ResponseField name="updatedAt" type="string" required>
  UTC timestamp for the catalog snapshot.
</ResponseField>

Example:

```bash theme={null}
curl "https://api.polaris.supply/catalog?source=hyperliquid&market=BTC-USD"
```

Response shape:

```json theme={null}
{
  "updatedAt": "2026-06-03T12:00:00.000Z",
  "markets": [
    {
      "source": "hyperliquid",
      "market": "BTC-USD",
      "start": "2026-05-01T00:15:00.000Z",
      "end": "2026-05-07T23:45:00.000Z",
      "categories": ["perp", "crypto"],
      "access": {
        "status": "open",
        "public_cutoff_date": null
      },
      "instrument": {
        "base": "BTC",
        "quote": "USD",
        "tick_size": "0.1",
        "lot_size": "0.001",
        "min_notional": "10"
      }
    }
  ]
}
```

When Polaris does not have instrument metadata for a market, the `instrument` object is still present and its fields are set to `null`.

## When to use catalog

* Confirm that a `source`/`market` pair is valid before making data requests.
* Check the earliest and latest available timestamps for a market.
* Inspect dataset category coverage for a market before you design downstream jobs.
* Send bearer auth only when you want catalog visibility that matches your account tier. Unauthenticated requests use the public catalog view.

## Use exact Polaris market IDs

Catalog returns the exact market IDs you should pass to the API and SDK. Treat those IDs as canonical.

* Do not assume every venue uses the same symbol format.
* Do not assume a user-facing market name matches the Polaris market ID.
* Filter with the exact `market` value returned in each catalog row.

For example, on Hyperliquid you might search for a market described as "SpaceX", but the Polaris market ID is `SPX`.

## Python example

Use catalog first when you are building a notebook or script.

```python theme={null}
from polaris_data import PolarisClient

with PolarisClient() as client:
    catalog = client.catalog(source="hyperliquid")
    markets = [row["market"] for row in catalog["markets"]]
    print(markets[:20])
```

If you already know the likely market name, you can also query the exact pair directly:

```python theme={null}
from polaris_data import PolarisClient

with PolarisClient() as client:
    market = client.catalog(source="hyperliquid", market="SPX")
    print(market)
```

## Next steps

* Read [Example Notebooks](/guides/jupyter-notebook-quickstart) if you want a notebook workflow that starts from catalog and ends with a chart.
* Read [Snapshots](/reference/snapshots) if you want bulk historical files for a market you just validated.
* Read [Trades](/sdks/trades) if you want to query recent normalized events directly.
* Read [Market coverage](/markets/market-coverage) if you want a broader view of supported venue categories.