# Equities, commodities, indices & crypto

- Method: `GET`
- Path: `/assets`
- Tier: Free
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-assets/
- Interactive docs: https://docs.hiddensystems.ai/nebula/api/#endpoint=get-assets

## Description

Discovers equities, commodities, indices, and crypto assets and returns the identifiers accepted by asset-scoped endpoints. Commodity and index instruments use asset_class=equity and expose asset_category for classification. Filter them with asset_category without asset_class. With no filter, results preserve the documented asset-class order: equity, then crypto. Supply query for search or asset_id for exact resolution; asset_id always requires asset_class. Parameter rules: asset_class and asset_category cannot be combined. asset_id and query cannot be combined. asset_id requires asset_class.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/assets' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

No path parameters for this endpoint.

## Query Parameters

- `asset_id` (string, optional): Canonical identifier returned by /assets. Stock, commodity, and index IDs are normally ticker or market symbols and use asset_class=equity; crypto IDs are canonical crypto slugs. asset_class is mandatory whenever asset_id is present.
- `asset_class` (string, optional, allowed: equity, crypto): Namespace of asset_id, or the market class for endpoints with a class-scoped global view. Stocks, commodities, and indices use equity. Equity is the documented default only where the endpoint description states a default.
- `asset_category` (string, optional, allowed: commodity, index): Equity category filter. Commodity and index instruments retain asset_class=equity in results and downstream selectors.
- `query` (string, optional): Case-insensitive search across public identifiers and names.
- `limit` (integer, optional, default: 50): Maximum results returned.
- `offset` (integer, optional, default: 0): Number of results skipped.

## Response

OK

- `assets` (array<object>, required): Assets matching the supplied discovery filters.
- `assets[].asset_category` (string, enum: commodity, index): Optional equity classification. Commodity and index instruments use commodity or index; ordinary equities omit this field.
- `assets[].asset_class` (string, required): Market class that namespaces the asset identifier.
- `assets[].asset_id` (string, required): Canonical public asset identifier. Equity identifiers are ticker symbols; crypto identifiers are canonical crypto IDs.
- `assets[].handle` (string): Primary social handle when available.
- `assets[].market_cap_usd` (number (double)): Latest market capitalisation in US dollars.
- `assets[].name` (string, required): Human-readable name.
- `assets[].price_change_24h_pct` (number (double)): Raw market-price change over 24 hours, in percentage points.
- `assets[].price_usd` (number (double)): Latest or observed market price in US dollars.
- `assets[].symbol` (string, required): Display ticker or market symbol.
- `has_more` (boolean, required): True when another page is available after the returned records.
- `limit` (integer, required): Maximum records requested.
- `offset` (integer, required): Number of matching records skipped.

Media type: `application/json`

## JSON Response

```json
{
  "assets": [
    {
      "asset_class": "equity",
      "asset_id": "NVDA",
      "market_cap_usd": 4450000000000,
      "name": "NVIDIA Corporation",
      "price_change_24h_pct": 2.37,
      "price_usd": 182.41,
      "symbol": "NVDA"
    },
    {
      "asset_category": "commodity",
      "asset_class": "equity",
      "asset_id": "GLD",
      "name": "SPDR Gold Shares",
      "symbol": "GLD"
    },
    {
      "asset_category": "index",
      "asset_class": "equity",
      "asset_id": "SPX",
      "name": "S&P 500",
      "symbol": "SPX"
    }
  ],
  "has_more": false,
  "limit": 50,
  "offset": 0
}
```